كيفية العمل مع Aspose.Imaging FOSS Core API في .NET

Aspose.Imaging FOSS لـ .NET’s public surface يتكون من ثلاث فئات: 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;

الخطوة 3: فحص ملف بواسطة المسار

ImageProbe.ProbeFile يقرأ ما يكفي فقط من رأس الملف لملء نتيجة ImageInfo — لا يقوم أبدًا بفك تشفير بيانات البكسل:

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

الخطوة 4: فحص تدفق أو مصفوفة بايت

عندما تكون الصورة موجودة بالفعل في الذاكرة أو جاءت من تدفق (تحميل، استجابة شبكة)، استخدم الدوال المتجاوزة التي تقبلها مباشرةً بدلاً من كتابة ملف مؤقت أولاً:

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) يعمل مع التدفقات القابلة للتمرير وغير القابلة للتمرير.

الخطوة 5: استخدم 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. رأس الملف لا يتطابق مع أي من الصياغات الـ11 المعروفة (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 لا يفك تشفير أبداً، ولا يعرض، ولا يحول محتوى الصورة — فهو يقرأ فقط بيانات تعريف الرأس. فك التشفير والعمليات على مستوى البكسل تتطلب مجموعة تطوير البرمجيات التجارية Aspose.Imaging SDK.

الأسئلة المتكررة

ماذا يحدث إذا قمت بفحص ملف مقطوع أو تالف؟

ImageProbe لا يطرح استثناءً أبداً عند مدخلات غير صحيحة أو مقطوعة. إنه يُعيد ImageInfo جزئي — يتم تعيين Format كلما تم التعرف على علامة تنسيق الرأس، حتى إذا تم قطع بقية الملف.

هل ImageProbe آمن من حيث تعدد الخيوط؟

نعم. ImageProbe ثابت ولا يحتفظ بأي حالة قابلة للتغيير بين الاستدعاءات، لذا فإن الاستدعاءات المتزامنة من خيوط متعددة آمنة.

هل يمكنني إنشاء ImageInfo مباشرةً، دون فحص ملف فعلي؟

نعم. مُنشئ ImageInfo عام ولا يتطلب سوى format — وهو مفيد لإنشاء نسخ اختبارية: new ImageInfo(ImageFormat.Png, width: 64, height: 48).

هل أحتاج إلى تحرير أي شيء؟

لا. ImageProbe لا يحتوي على أي موارد IDisposable خاصة به. إذا قمت بتمرير Stream الذي فتحته بنفسك، فإنك تظل مسؤولاً عن التخلص منه.