ویژگی‌ها و قابلیت‌ها

ویژگی‌ها و عملکردها

این صفحه تمام حوزه‌های ویژگی Aspose.Imaging FOSS برای .NET را که مربوط به تشخیص قالب و بررسی سرآیند API است، همراه با مثال‌های کاری C# پوشش می‌دهد. این کتابخانه هرگز داده‌های پیکسل را رمزگشایی نمی‌کند — هر متد فقط سرآیند فایل را می‌خواند.

تشخیص قالب

ImageProbe نقطه ورودی ایستا است. سه overload مسیر فایل، یک جریان، و یک آرایه بایت خام را پوشش می‌دهند:

using Aspose.Imaging.Foss;

var fromPath   = ImageProbe.ProbeFile("photo.jpg");
var fromBytes  = ImageProbe.Probe(byteArray);
var fromStream = ImageProbe.Probe(stream);

var formatOnly = ImageProbe.DetectFormat(byteArray); // ImageFormat only, no header parse

از DetectFormat زمانی استفاده کنید که فقط نیاز به تصمیم‌گیری بر اساس قالب دارید؛ از Probe/ProbeFile زمانی استفاده کنید که علاوه بر آن به ابعاد، عمق بیت یا تعداد فریم‌ها نیز نیاز دارید.

خواندن فراداده‌های سرآیند

ProbeFile/Probe یک ImageInfo با Width، Height، BitDepth و FrameCount قابل مقداردهی بازگشت می‌دهند — که هر کدام تنها زمانی پر می‌شوند که سرآیند قالب شناسایی‌شده واقعاً آن مقدار را داشته باشد:

var info = ImageProbe.ProbeFile("scan.dcm");
if (info.Width.HasValue && info.Height.HasValue)
{
    Console.WriteLine($"{info.Format}: {info.Width}x{info.Height}");
}

Format (یک مقدار enum ImageFormat) همیشه پس از شناسایی هدر تنظیم می‌شود — این تنها فیلدی است که تضمین می‌شود مقداردهی شود.

یادداشت‌های مربوط به هر قالب

چند قالب دارای نکات خاص هدر هستند که ImageInfo آنها را نرمال‌سازی یا به‌صورت مستقیم نمایش می‌دهد:

// DICOM: rows -> Height, columns -> Width, bitsAllocated -> BitDepth,
// across any of the three common transfer syntaxes
var dicomInfo = ImageProbe.Probe(dicomBytes);
Console.WriteLine($"{dicomInfo.Width}x{dicomInfo.Height}, {dicomInfo.BitDepth}-bit");

قالب‌های پشتیبانی‌شده

تمام ۱۱ قالب به‌یک‌روش شناسایی می‌شوند — ImageProbe قالب را شناسایی کرده و متادیتای هدر را می‌خواند؛ هرگز داده‌های پیکسل را برای هیچ‌یک از آن‌ها رمزگشایی یا دوباره‌کدگذاری نمی‌کند. پر شدن فیلدها به‌طور واقعی بسته به قالب متفاوت است — هر قالب Format را تنظیم می‌کند، اما تنها برخی عمق بیت یا تعداد فریم را در هدر خود دارند:

یک هدر ناشناخته به ImageFormat.Unknown تبدیل می‌شود نه اینکه خطا بدهد. چند جزئیات قابل توجه درباره پر شدن فیلدها: FrameCount در PNG همیشه 1 است (یک مقدار ثابت، نه تشخیص واقعی فریم‌های PNG انیمیشنی)؛ FrameCount در ICO شمارش واقعی اندازه‌های آیکون‌های جاسازی‌شده در دایرکتوری است، و یک بایت بعدی 0 در ورودی دایرکتوری ICO به معنای ۲۵۶ پیکسل طبق مشخصات قالب است؛ FrameCount در TIFF بازتاب یک پیمایش محدود زنجیره IFDهای فایل است (هر IFD یک صفحه است)؛ WMF غیرقابل قرارگیری همچنان به‌درستی به عنوان ImageFormat.Wmf شناسایی می‌شود اما فقط Format را برمی‌گرداند — ابعاد فقط برای WMF قابل قرارگیری پر می‌شوند، از طریق تبدیل ثابت ۹۶ DPI از مرزهای واحد اینچ هدر؛ EMF اصلاً فیلد عرض/ارتفاع صریحی ندارد، بنابراین ابعاد آن از مستطیل فضای دستگاه rclBounds استخراج می‌شود.

قابلیت تحمل به‌صورت طراحی‌شده

ImageProbe هرگز در مواجهه با ورودی خراب یا ناقص خطا نمی‌اندازد. به‌جای پرتاب استثنا، یک ImageInfo جزئی باز می‌گرداند — Format هر زمان که نشانگر قالب هدر شناسایی شود تنظیم می‌شود، حتی اگر بقیه فایل کوتاه یا خراب باشد:

byte[] truncated = fullFileBytes[..^3];
var info = ImageProbe.Probe(truncated);
// info.Format is still populated; other fields may be null

این باعث می‌شود که بدون نیاز به try/catch برای هر فراخوانی، بتوانید بر روی دانلودهای ناشناخته، جزئی یا در حال انتقال به‌صورت ایمن اجرا کنید.

نکات و بهترین شیوه‌ها

• از DetectFormat به‌جای Probe استفاده کنید وقتی فقط به فرمت نیاز دارید، نه به ابعاد
• قبل از استفاده، Width/Height/BitDepth/FrameCount را برای null بررسی کنید — این مقادیر برای هر فرمت پر نمی‌شوند
• در کار با فایل‌های بزرگ، به‌جای خواندن کل فایل به‌صورت آرایه بایت، از Probe(stream) استفاده کنید
• ImageProbe کاملاً استاتیک است — هیچ نمونه‌ای نیست، IDisposable نیست، شیء پیکربندی نیز وجود ندارد

مشکلات رایج

FAQ

آیا ImageProbe داده‌های پیکسل را رمزگشایی می‌کند؟

نه. هر متد فقط هدر فایل را می‌خواند — ابعاد، عمق بیت، و تعداد فریم‌ها — و هرگز محتوای پیکسل را نمی‌خواند. رمزگشایی و رندر کردن خارج از دامنه این کتابخانه است.

اگر یک فایل خراب یا قطع‌شده را بررسی کنم چه اتفاقی می‌افتد؟

ImageProbe هرگز برای ورودی خراب یا قطع‌شده استثنا نمی‌اندازد. یک ImageInfo برمی‌گرداند که شامل هر فیلدی است که می‌توانست از بایت‌های هدر موجود تعیین کند — Format هر زمان که نشانگر قالب خودش شناسایی می‌شود تنظیم می‌شود.

آیا می‌توانم یک جریان که قابل جستجو نیست را بررسی کنم؟

بله. Probe(stream) هر دو نوع جریان قابل جستجو و غیرقابل جستجو را می‌پذیرد.

API Reference خلاصه

همچنین ببینید:

• Aspose.Imaging — Enterprise Documentation