إدراك لحساب أبعاد الصور — Idraaak Image Fit

Idraaak Image Fit مكتبة صغيرة بلغة Rust تساعد المبرمج على حساب أبعاد الصورة عند إدخالها داخل مساحة محددة أو ملء هذه المساحة مع قص الأطراف. تحسب المكتبة الأرقام فقط ولا تفتح الصور أو تضغطها أو تغيّر ملفاتها.

ماذا تفعل المكتبة؟

لنفترض أن لديك صورة وتريد عرضها داخل بطاقة في موقع أو تطبيق. إذا غيّرت العرض والارتفاع بشكل مستقل قد تبدو الصورة ممدودة. هذه المكتبة تختار معامل تصغير أو تكبير واحدًا ثم تعطيك الأبعاد المناسبة، مع تقريب واضح إلى عدد صحيح من البكسلات.

يمكنك اختيار إظهار الصورة كاملة داخل المساحة باستخدام contain أو تغطية المساحة كلها باستخدام cover. في الخيار الثاني تُرجع المكتبة أبعاد الصورة بعد تغيير حجمها ومكان المستطيل الذي يجب الاحتفاظ به عند القص.

مثال عملي: صورة بعرض ١٢٠٠ وارتفاع ٨٠٠ بكسل

نريد وضع هذه الصورة داخل مساحة بعرض ٥٠٠ وارتفاع ٣٧٥ بكسل. النتيجة تختلف بحسب ما إذا أردنا رؤية الصورة كاملة أو ملء الإطار بالكامل.

طريقة العرض	النتيجة	ما الذي تعنيه؟
إظهار الصورة كاملة	٥٠٠ × ٣٣٣ بكسل	تظهر الصورة كلها ويبقى جزء من ارتفاع الإطار فارغًا. المكتبة لا تضيف خلفية أو حواف بنفسها.
ملء الإطار مع القص	تغيير الحجم إلى ٥٦٣ × ٣٧٥ ثم قص مستطيل ٥٠٠ × ٣٧٥	يبدأ القص بعد ٣١ بكسل من اليسار دون إزاحة من الأعلى، فتُزال ٣١ بكسل من اليسار و٣٢ من اليمين.

إحداثيات القص تخص الصورة بعد تغيير حجمها وليست الصورة الأصلية. يجب على البرنامج الذي يستخدم المكتبة تنفيذ تغيير الحجم والقص فعليًا عبر مكتبة معالجة صور مناسبة.

كيف يستخدمها المبرمج؟

يمكن تجربة الكود من مستودع Idraaak Image Fit على GitHub. يستخدم المثال التالي أبعاد المصدر والمساحة المطلوبة، ثم يطبع النتيجة. القيمة false تمنع تكبير الصورة.

use idraaak_image_fit::{contain, cover, FitError, Size};

fn main() -> Result<(), FitError> {
    let source = Size::new(1200, 800)?;
    let target = Size::new(500, 375)?;
    let output = contain(source, target, false)?;
    let plan = cover(source, target, false)?;

    println!("{} x {}", output.width(), output.height());
    println!("{:?}", plan.crop);
    Ok(())
}

ماذا يحدث عند منع التكبير؟

إذا كانت الصورة صغيرة وتدخل بالكامل داخل المساحة، فإن contain يحافظ على أبعادها الأصلية عند منع التكبير. أما cover فيُرجع الخطأ UpscalingRequired إذا كان ملء الإطار يحتاج تكبيرًا، حتى يختار البرنامج طريقة عرض مناسبة بدل استلام خطة لا تغطي المساحة فعلًا.

التقريب والمقاسات غير الصالحة

أبعاد الصور أعداد صحيحة، ولهذا قد تختلف النسبة النهائية قليلًا بسبب تقريب البكسل. عند إظهار الصورة كاملة تُقرّب الأبعاد إلى الأسفل حتى تدخل داخل الإطار. وعند تغطية الإطار تُقرّب إلى الأعلى حتى لا تبقى مساحة غير مغطاة.

ترفض المكتبة العرض أو الارتفاع الصفري. وإذا أدى التصغير المتناسب لصورة شديدة النحافة إلى بُعد أقل من بكسل واحد، تُرجع خطأ بدل إجبار الصورة على أبعاد قد تشوهها. كما تكشف نتائج التكبير التي تتجاوز الحد المسموح لأبعاد u32. الأرقام السالبة والكسور يجب رفضها في البرنامج قبل تحويلها إلى هذا النوع.

الترخيص وحالة المشروع

الكود متاح برخصة MIT ولا يعتمد على مكتبات خارجية. أُعد بمساعدة الذكاء الاصطناعي وخضع لاختبارات آلية للحسابات والأخطاء والتوثيق. تتوفر النسخة 0.1.0 على crates.io، ويمكن الاطلاع على الكود والأمثلة في مستودع المشروع على GitHub. ويمكن قراءة توثيق المكتبة وأمثلتها على docs.rs.