چگونه با Aspose.Imaging FOSS Core API در .NET کار کنیم

Aspose.Imaging FOSS برای سطح عمومی .NET از سه کلاس تشکیل شده است: ImageProbe، ImageInfo و ImageFormat. این راهنما نصب بسته و استفاده همزمان از هر سه را برای تشخیص یک فرمت و خواندن متادیتای هدر از یک فایل، یک جریان و یک آرایه بایت توضیح می‌دهد.

راهنمای گام به گام

مرحله 1: نصب بسته

git clone https://github.com/aspose-imaging-foss/Aspose.Imaging-FOSS-for-.NET.git
cd Aspose.Imaging-FOSS-for-.NET
dotnet build

این بسته هدف net8.0 و netstandard2.0 را دارد و هیچ وابستگی زمان اجرا خارجی ندارد.

مرحله 2: وارد کردن فضای نام

یک دستور using اضافه کنید — این ImageProbe، ImageInfo و ImageFormat را در اختیار می‌گذارد، کل سطح API، به‌طوری‌که دیگر نیازی به وارد کردن چیزی نیست:

using Aspose.Imaging.Foss;

مرحله ۳: بررسی یک فایل بر اساس مسیر

ImageProbe.ProbeFile به اندازه کافی از هدر فایل می‌خواند تا نتیجه‌ای از نوع ImageInfo پر کند — هرگز داده‌های پیکسل را رمزگشایی نمی‌کند:

var info = ImageProbe.ProbeFile("photo.jpg");
Console.WriteLine($"{info.Format}: {info.Width}x{info.Height}, {info.BitDepth}-bit");

مرحله ۴: بررسی یک جریان یا آرایه بایت

زمانی که تصویر هم‌اکنون در حافظه است یا از یک جریان (بارگذاری، پاسخ شبکه) آمده است، به‌جای نوشتن در یک فایل موقت ابتدا، از overloadهایی استفاده کنید که آن‌ها را به‌صورت مستقیم می‌پذیرند:

byte[] bytes = File.ReadAllBytes("photo.jpg");
var infoFromBytes = ImageProbe.Probe(bytes);

using var stream = File.OpenRead("photo.jpg");
var infoFromStream = ImageProbe.Probe(stream);

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

مرحله ۵: استفاده از DetectFormat وقتی فقط به فرمت نیاز دارید

اگر فقط نیاز دارید بر اساس فرمت تصمیم بگیرید و به ابعاد، عمق بیت یا تعداد فریم‌ها نیازی ندارید، DetectFormat بقیه تجزیه هدر را نادیده می‌گیرد:

var format = ImageProbe.DetectFormat(bytes);
if (format == ImageFormat.Dicom)
{
    // route to DICOM-specific handling
}

گام 6: فیلدهای ImageInfo قابل نال را به‌صورت ایمن بخوانید

Width، Height، BitDepth و FrameCount قابل نال هستند — فقط زمانی مقداردهی می‌شوند که هدر فرمت تشخیص داده‌شده واقعاً آن مقدار را داشته باشد. Format تنها فیلدی است که همیشه پس از شناسایی هدر تنظیم می‌شود:

var info = ImageProbe.ProbeFile("scan.dcm");
if (info.Width.HasValue && info.Height.HasValue)
{
    Console.WriteLine($"{info.Format}: {info.Width}x{info.Height}");
}
else
{
    Console.WriteLine($"{info.Format}: dimensions not available in this header");
}

مشکلات رایج و راه‌حل‌ها

قالب به این شکل نشان داده می‌شود ImageFormat.Unknown. سرآیند فایل با هیچ‌یک از ۱۱ قالب شناسایی‌شده (PNG، JPEG، GIF، BMP، WebP، ICO، TIFF، PSD، EMF، WMF، DICOM) مطابقت ندارد. تأیید کنید که فایل واقعاً یکی از این قالب‌ها است — ImageProbe هرگز برای سرآیند ناشناخته خطا نمی‌اندازد، بلکه گزارش می‌دهد Unknown در عوض.

Width/Height are null اگرچه Format تنظیم شده است. هر سرآیند قالب تمام فیلدها را شامل نمی‌شود، و یک فایل بریده‌شده ممکن است قبل از بایت‌های یک فیلد قطع شود. بررسی کنید Format ابتدا، سپس بقیه را به‌عنوان اختیاری در نظر بگیرید.

Calling Probe when DetectFormat کافی است. Probe and ProbeFile سرتیتر کامل را تجزیه می‌کند؛ DetectFormat فقط به اندازهٔ کافی می‌خواند تا قالب را شناسایی کند. استفاده کنید DetectFormat اگر هرگز نخوانید Width/Height/BitDepth/FrameCount.

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

سوالات متداول

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

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

آیا ImageProbe thread-safe است؟

بله. ImageProbe استاتیک است و بین فراخوانی‌ها هیچ وضعیت قابل تغییر نگه نمی‌دارد، بنابراین فراخوانی‌های همزمان از چندین رشته ایمن هستند.

آیا می‌توانم یک ImageInfo را به‌طور مستقیم بسازم، بدون اینکه فایل واقعی را بررسی کنم؟

بله. سازندهٔ ImageInfo عمومی است و فقط format مورد نیاز است — برای ساختن شبیه‌سازهای تست مفید است: new ImageInfo(ImageFormat.Png, width: 64, height: 48).

آیا لازم است کاری برای dispose کردن انجام دهم؟

شماره ImageProbe هیچ منبع IDisposable خود را ندارد. اگر یک Stream که خودتان باز کرده‌اید را پاس بدهید، همچنان مسئول حذف آن خواهید بود.