انتقل إلى المحتوى
كل الأعمال

مفتوح المصدرمباشر

imgkit

معالجة صور سريعة لـ Bun وNode.js، بنواة مكتوبة بـ Rust وواجهة منمّطة.

الحالة
مباشر
السنة
2025
الدور
مؤلّف

غيّر حجم الصور وقصّها وحوّلها وضع عليها علامات مائية وحلّلها من JavaScript، والعمل كله في Rust أصلي. ملفات ثنائية جاهزة لسبع منصات، وبديل WebAssembly لما سواها، وقراءة صور HEIC من iPhone على macOS ARM64، وأسرع من sharp في اختبارات الأداء الخاصة بالمشروع.

ما هو

  • Rust أصلي عبر napi-rs: ترميز JPEG بتعليمات SIMD عبر libjpeg-turbo، وفكّ الترميز بنصف الحجم أو ربعه أو ثُمنه حين يكون الهدف صغيرًا، وكائنات Buffer تعبر إلى Rust دون نسخ
  • أكثر من تغيير الحجم: قصّ ذكي، وعلامات مائية بأنماط مزج، والألوان الغالبة، وبصمات إدراكية، وصور مؤقتة ThumbHash وBlurHash، وبيانات EXIF، وموتّرات جاهزة لتعلّم الآلة
  • كل نداء غير متزامن يعمل خارج حلقة الأحداث ويقبل مهلة زمنية وAbortSignal، ولكل دالة معالجة نظيرة متزامنة
  • ملفات جاهزة لـ macOS وLinux وWindows على x64 وARM64؛ وعلى أي منصة أخرى يرجع Node إلى نسخة WebAssembly من كود Rust نفسه

كيف يعمل

ما الذي يفعله، ومسار نداء واحد من JavaScript إلى Rust والعودة، ومن أين تأتي السرعة، والبديل WebAssembly، وما لم يكتمل بعد.

#ما الذي يفعله

imgkit مكتبة لمعالجة الصور في Bun وNode.js. يجري العمل في Rust، مُترجَمًا إلى إضافة أصلية عبر napi-rs، وتحصل JavaScript على واجهة منمّطة فوقه. بدأت باسم bun-image-turbo ثم صارت imgkit في الإصدار 2.0.0، بالواجهة نفسها ومسار استيراد جديد.

كل ما يلي متاح في الإصدار 2.4.0.

  • القراءة والتحويل. JPEG وPNG وWebP وGIF وBMP قراءةً وكتابةً، وTIFF قراءةً. ويُفكّ ترميز HEIC/HEIF وAVIF في نسخة macOS ARM64.
  • تغيير الحجم والقصّ والمصغّرات. تغيير الحجم بمرشّحات تتكيّف تلقائيًا، والقصّ بالإحداثيات أو بنسبة العرض إلى الارتفاع أو بالاتجاه، والقصّ الذكي حسب المحتوى، ومسار للمصغّرات يفكّ الترميز بحجم مصغّر.
  • التركيب. طبقات وعلامات مائية بسبعة أنماط مزج، مع شفافية وتغيير حجم وتكرار لكل طبقة.
  • وصف الصورة. بيانات وصفية من الترويسة وحدها، والألوان الغالبة، وبصمات إدراكية (pHash وdHash وaHash وBlockHash) لكشف الصور المكرّرة، وصور مؤقتة بتقنية ThumbHash أو BlurHash.
  • تغذية النماذج. تحوّل toTensor() الصورة إلى موتّر Float32 أو Uint8 بتطبيع ImageNet أو CLIP، بترتيب CHW أو HWC، جاهز لـ ONNX Runtime أو PyTorch أو TensorFlow.js.
  • EXIF. كتابة بيانات EXIF وحذفها في JPEG وWebP.
  • التحكّم. لكل دالة معالجة صيغة غير متزامنة وأخرى متزامنة. وكل نداء غير متزامن يقبل timeoutMs وAbortSignal.

#عمليًا

ts
import { metadata, transform, thumbhash } from 'imgkit';

const buf = Buffer.from(await Bun.file('photo.jpg').arrayBuffer());

const info = await metadata(buf);           // يقرأ الترويسة فقط

const webp = await transform(buf, {         // فكّ ترميز واحد وترميز واحد
  crop: { aspectRatio: '16:9' },
  resize: { width: 1280 },
  output: { format: 'webp', webp: { quality: 85 } },
}, { timeoutMs: 5000 });

const { dataUrl } = await thumbhash(buf);   // صورة مؤقتة صغيرة ضبابية لوسم <img>

#نداء واحد، من JavaScript إلى Rust والعودة

تحوّل طبقة TypeScript الخيارات المقروءة إلى ما يتوقّعه Rust (gravity: 'southEast' تصبح SouthEast) وتربط AbortSignal. يمرّر napi-rs كائن Buffer إلى Rust كشريحة دون نسخه. ينتقل العمل الثقيل إلى مجموعة خيوط معالجة، فتبقى حلقة الأحداث حرّة. يتعرّف Rust على الصيغة من بايتاتها السحرية (magic bytes)، ويفكّ الترميز بأصغر حجم ممكن، ثم يقصّ، ويغيّر الحجم، ويطبّق المؤثرات، ويرمّز، ويعيد Buffer، دون نسخ مرة أخرى.

يُرسم المخطط

#القواعد التي يلمسها المستدعي

  • النداء غير المتزامن لا يحجز حلقة الأحداث أبدًا. معالجة الصور تجري على مجموعة خيوط. والصيغ المتزامنة موجودة للسكربتات وأدوات سطر الأوامر.
  • نداء transform() واحد أفضل من سلسلة نداءات. كل نداء منفصل يفكّ ترميز الصورة ويعيد ترميزها. أما خط المعالجة فيفكّ الترميز مرة ويرمّز مرة.
  • القصّ أولًا. داخل خط المعالجة يُطبَّق القصّ قبل تغيير الحجم، فتلمس كل خطوة بعده بكسلات أقل. والقصّ نفسه نافذة على الصورة المفكوكة لا نسخة منها.
  • الصور الضخمة تُرفض ولا تُبتلع. كل ما يتجاوز 100 ميغابكسل يُرفض قبل فكّ الترميز، كي لا يستنفد ملف خبيث واحد ذاكرة الخادم.
  • المهلة والإلغاء مدمجان. يرفض timeoutMs الـ Promise من جهة Rust بعد المدة المحدّدة. ويتيح AbortSignal لـ JavaScript أن تلغي.
  • المكتبة تخبرك بما تستطيعه. تُبلغ codecBackend() هل المحمّل هو النسخة الأصلية أم نسخة WebAssembly، وهل التصغير عند التحميل وWebP بفقد وHEIC متاحة. يتفرّع الكود حسب القدرات لا حسب أسماء المنصات.

#من أين تأتي السرعة

  • بيانات وصفية من الترويسة وحدها. العرض والارتفاع والصيغة تُؤخذ من مؤشرات JPEG أو مقطع IHDR في PNG أو مقاطع VP8 في WebP. لا يُفكّ ترميز أي بكسل.
  • JPEG بتعليمات SIMD. تختار libjpeg-turbo بين SSE2 وAVX2 وNEON أثناء التشغيل.
  • التصغير عند التحميل (shrink-on-load). حين يكون الهدف أصغر بكثير، يُطلب من مفكّك الترميز صورة بنصف الحجم أو ربعه أو ثُمنه: تحجيم TurboJPEG لـ JPEG، وتحجيم libwebp لـ WebP، وlibheif لـ HEIC. صورة بعرض 4000 بكسل وجهتها 200 بكسل تُفكّ بعرض 500 بكسل.
  • تغيير الحجم على مراحل. في التصغير بأكثر من 75%، تُنصَّف الصورة بمرشّح Box حتى تصبح ضمن ضعفي الهدف، ثم تُختم بمرشّح Bilinear.
  • مرشّحات متكيّفة. إن لم يُحدَّد مرشّح: Box بعد تصغير 4×، وBilinear بين 2× و4×، وCatmullRom بين 1.33× و2×، وLanczos3 دون ذلك.
  • مساران منفصلان لـ RGB وRGBA. الصورة بلا قناة شفافية تنقل 3 بايتات لكل بكسل بدل 4.
  • صفر نسخ عند الحدود. تُقرأ كائنات Buffer الداخلة في مكانها، وتصبح المتجهات الخارجة كائنات Buffer دون نسخ.

#القياس مقارنةً بـ sharp

Apple M1 Pro وBun 1.3.3، من مجموعة اختبارات الأداء في المستودع (bun run benchmarks/final_comparison.ts).

العمليةimgkitsharpالنسبة
بيانات WebP الوصفية0.004 ms3.4 ms950×
بيانات JPEG الوصفية0.003 ms0.1 ms38×
50 عملية متوازية62 ms160 ms2.6×
خط تحويل كامل12.2 ms19.1 ms1.6×
JPEG بحجم 1 MB إلى 800 بكسل12.6 ms20.3 ms1.6×
مصغّرة بعرض 200 بكسل8.8 ms10.7 ms1.2×

كيف تُقرأ: النسب الكبيرة جدًا تخصّ البيانات الوصفية، حيث لا تقرأ imgkit إلا الترويسة. أما في العمل على البكسلات فالتقدّم بين 1.2× و1.6×، ويضيق كلما كبرت الصور. صورة WebP بأبعاد 4000×3000 تُصغَّر إلى 400 بكسل في 32.4 ms مقابل 33.1 ms.

#HEIC مباشرة من iPhone

تحفظ أجهزة iPhone صورها بصيغة HEIC، والنسخ الجاهزة القياسية من sharp لا تقرؤها. تفكّ imgkit ترميز HEIC/HEIF عبر libheif مع التصغير أثناء فكّ الترميز: البيانات الوصفية من الترويسة في 0.1 ms، والتحويل الكامل من HEIC إلى JPEG في 169 ms، وتغيير الحجم إلى 800 بكسل في 138 ms.

دعم HEIC موجود في نسخة macOS ARM64 فقط. منذ الإصدار 2.2.1 تُترجَم libheif وترميزاتها من المصدر وتُربط ربطًا ساكنًا، بعد أن فشل تحميل الربط على أجهزة Mac لا تحتوي libheif.1.dylib. لا Homebrew ولا مكتبة نظام.

#تعمل حيث لا يوجد ملف ثنائي

تغطي الملفات الثنائية الجاهزة سبعة أهداف: macOS على ARM64 وx64، وLinux على x64 (glibc وmusl) وARM64، وWindows على x64 وARM64. تُثبَّت كاعتماديات اختيارية، فلا يترجم أحد شيئًا. ومنذ الإصدار 2.4.0، أي منصة أخرى تحت Node، مثل FreeBSD أو Linux ARMv7، ترجع إلى WebAssembly بدل أن ترمي خطأ عند الاستيراد.

يُرسم المخطط

تُترجَم نسخة WebAssembly من كود Rust نفسه، فلا يوجد تنفيذ ثانٍ ينحرف عن الأول. إيقاف ميزة cargo المسمّاة native-codecs يستبدل libjpeg-turbo وlibwebp بترميزات مكتوبة بـ Rust خالص، ما يعني أيضًا أن الحزمة تُبنى دون أي أدوات C: لا nasm ولا cmake.

الأصليةWebAssembly
ترميز JPEGlibjpeg-turbo بتعليمات SIMDzune-jpeg بـ Rust خالص
التصغير عند التحميلنعملا، فكّ كامل ثم تغيير الحجم
WebP بفقد (quality)نعمدون فقد فقط
HEIC/HEIFmacOS ARM64لا
العمل غير المتزامنمجموعة خيوطالخيط المستدعي
timeoutMsمُطبَّقمرفوض مع رسالة خطأ

مرشّحات تغيير الحجم والقصّ والقصّ الذكي والتركيب والبصمات والصور المؤقتة والألوان والموتّرات وEXIF تتصرّف بالطريقة نفسها في النسختين، لأنها الكود نفسه.

#ثلاثة قرارات في البديل

  • المهلة التي لا يمكن احترامها تُرفض. تحت WebAssembly يكون العمل متزامنًا في العمق، فلا تستطيع المهلة مقاطعته. ترفض النسخة timeoutMs برسالة خطأ صريحة بدل تجاهله بصمت، لأن المهلة المتجاهَلة تعطي المستدعي ضمانًا لا يملكه.
  • النداءات غير المتزامنة تعمل رغم ذلك. يشغّل napi-rs الدوال غير المتزامنة على بيئة Tokio لا تعمل على هدف WebAssembly هذا. طبقة صغيرة تعيد تنفيذ كل دالة غير متزامنة فوق نظيرتها المتزامنة، فيُحلّ await resize() بالطريقة نفسها.
  • لا مدخل للمتصفح، عن قصد. وحدة .wasm والمحمّلان موجودة في الحزمة، لكن مدخل المتصفح الذي يولّده napi-rs كان سيعيد تصدير حزمة غير منشورة ويتجاوز طبقة TypeScript، فلا تُحوَّل الخيارات أبدًا. بدل الإعلان عن تصدير browser يقود إلى شيء معطوب، يبقى غائبًا حتى يُبنى مدخل حقيقي.

#كيف تُختبر

  • نمت مجموعة الاختبارات مع الميزات. 64 اختبارًا في 1.6.0، و111 في 1.8.0، و150 في 1.9.0، و176 في 2.0.0، إضافة إلى مجموعة منفصلة لـ WebAssembly.
  • اختبارات Rust تعمل تحت نوعي الترميزات، الأصلية وRust الخالص، فيُتحقَّق من البديل عند المصدر.
  • مجموعة WebAssembly معزولة تمامًا. تُولَّد ملفات الاختبار في الذاكرة بمُرمِّز PNG صغير: لا شبكة، ولا ملفات ثنائية في المستودع، وملفات .mjs بسيطة تعمل على أي Node بإصدار 18 أو أحدث.
  • التثبيت يُختبر كما يثبّت المستخدم. جرى التحقّق من البديل بتثبيت الحزمة المجمّعة في مشروع فارغ، وفُحصت إصدارات سابقة مع Bun وnpm وyarn وpnpm.

#أخطاء علّمت شيئًا

  • Bun يتسامح وNode لا. كانت thumbhash() معطوبة في نسخة ESM تحت Node بسبب require("zlib") داخل وحدة ES. يتسامح Bun مع ذلك، فنجحت مجموعة اختبارات لا تعمل إلا تحت Bun بينما تلقّى مستخدمو Node خطأ.
  • المسار المختبَر ليس كل المسارات. فشلت صور WebP بلا قناة شفافية في أحد مفكّكات الترميز، لأن كل اختبارات WebP كانت تمرّر أبعادًا مستهدفة فتسلك مفكّكًا آخر.
  • الربط الديناميكي ينكسر على أجهزة الآخرين. مشكلة libheif المذكورة أعلاه انتهت بالربط الساكن.
  • الأسماء مهمّة على npm. أُعيدت تسمية حزم Windows إلى imgkit-windows-x64 وimgkit-windows-arm64 بعد أن اصطدمت الأسماء الأصلية بكشف الرسائل المزعجة في npm.

#لماذا هذه التقنيات

  • Rust للنواة. أمان الذاكرة دون جامع نفايات، ووصول مباشر إلى أفضل الترميزات: libjpeg-turbo وlibwebp وlibheif.
  • napi-rs للربط. ملف ثنائي جاهز لكل منصة، وكائنات Buffer تعبر الحدود دون نسخ، والأدوات نفسها تبني هدف WebAssembly عبر emnapi.
  • fast_image_resize مع Rayon. تغيير حجم بتعليمات SIMD موزّع على الأنوية، والمرشّحات المتكيّفة فوقه.
  • طبقة TypeScript رقيقة. الأنواع ومحوّلات الخيارات والمحمّل وطبقة WebAssembly. كل ما يخصّ راحة JavaScript يبقى خارج Rust.
  • Bun لسير العمل وNode هدفًا. يتولّى Bun التثبيت والبناء والاختبارات وقياس الأداء. تعمل الحزمة في البيئتين، ويتولّى bunx imgkit-build الإضافة الأصلية في الملفات التنفيذية المبنية بـ bun build --compile.

#ليس بعد

  • المتصفحات وبيئات الحافة. ملفات WebAssembly منشورة، لكن مدخل المتصفح غير مبني، وCloudflare Workers وDeno Deploy غير مختبرة.
  • فكّ ترميز HEIC/HEIF موجود في نسخة macOS ARM64 فقط، وHEIC وAVIF للقراءة فقط.
  • نسخة WebAssembly أبطأ: لا تصغير عند التحميل، وJPEG دون SIMD، ولا عمل خارج الخيط الرئيسي. ولا يستطيع Bun تحميلها لأن node:wasi فيه بلا initialize()؛ ومستخدمو Bun يحصلون على الإضافة الأصلية على أي حال.
  • بناء هدف WebAssembly يحتاج emnapi 2.0 alpha، مثبّتًا حتى تستقر سلسلة 2.x.

#للمزيد

التوثيق الكامل يغطي كل دالة، ومقايضات WebAssembly، والبنية بتفصيل أكبر.

هل أفادك هذا؟

النقاش