الميزات والوظائف

الميزات والوظائف

تغطي هذه الصفحة كل مجال من مجالات الميزات في Aspose.Imaging FOSS لـ .NET اكتشاف الصيغ واستكشاف رؤوس API، مع أمثلة C# تعمل. لا تقوم المكتبة أبدًا بفك تشفير بيانات البكسل — كل طريقة تقرأ فقط رأس الملف.

اكتشاف الصيغة

ImageProbe هو نقطة الدخول الثابتة. تغطي ثلاث عمليات تحميل مسار ملف، تدفق، ومصفوفة بايتات خام:

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 (قيمة تعداد 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");

الصيغ المدعومة

جميع الصيغ الـ 11 يتم اكتشافها بنفس الطريقة — ImageProbe يحدد الصيغة ويقرأ بيانات الرأس الوصفية؛ لا يقوم أبدًا بفك تشفير أو إعادة ترميز بيانات البكسل لأي منها. ومع ذلك، يتفاوت تعبئة الحقول فعليًا حسب الصيغة — كل صيغة تعيين Format، لكن فقط بعضها يحمل عمق اللون أو عدد الإطارات في رأسها:

رأس غير معروف يُحل إلى ImageFormat.Unknown بدلاً من إلقاء استثناء. بعض تفاصيل تعبئة الحقول الملحوظة: FrameCount الخاص بـ PNG هو دائمًا 1 (ثابت، وليس اكتشافًا حقيقيًا لإطارات PNG المتحركة)؛ FrameCount الخاص بـ ICO هو عدد حقيقي لأحجام الأيقونات المدمجة في الدليل، و0 بايت البُعد في إدخال دليل ICO يعني 256 بكسل وفقًا لمواصفة الصيغة؛ FrameCount الخاص بـ TIFF يعكس مسارًا محدودًا لسلسلة IFD في الملف (كل IFD يمثل صفحة واحدة)؛ WMF غير القابل للموضع لا يزال يُحدد بشكل صحيح كـ ImageFormat.Wmf لكنه يُعيد فقط Format — تُملأ الأبعاد لـ WMF القابل للموضع فقط، عبر تحويل ثابت 96 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