SnapOtter/apps/docs/ar/api/ai.md

---
description: "مرجع محرك الذكاء الاصطناعي مع جميع أدوات التعلم الآلي المحلية. إزالة الخلفية، وتحسين الدقة، وقراءة النصوص (OCR)، واكتشاف الوجوه، وترميم الصور، والمزيد."
i18n_output_hash: 778d92965216
i18n_source_hash: aa9a56cdddc7
i18n_provenance: human
---

# مرجع محرك الذكاء الاصطناعي {#ai-engine-reference}

تقوم حزمة `@snapotter/ai` بتنسيق الأدوات الأصلية وأوقات تشغيل Python لعمليات ML المحلية. تستخدم معظم أدوات ML Python sidecar المستمر لبدء التشغيل الدافئ السريع. OCR منفصل عمدا: يستدعي `fast` ثنائي Tesseract الأصلي، بينما يستخدم `balanced` و`best` JSONL dispatcher المستمر المخصص والمثبت على جيل RapidOCR النشط غير القابل للتغيير ضمن `/data/ai/v3`. يحمل كل طلب generation lease. أثناء الترقية، يقوم SnapOtter بتشغيل smoke test على المرشح قبل التنشيط، ويتحول تلقائيًا إلى dispatcher الجديد، ثم يستنزف الجيل القديم قبل garbage collection.

يتم اكتشاف NVIDIA CUDA تلقائيًا ويتم استخدامه في أوقات التشغيل التي تدعمه. يستخدم OCR CPU على كل مضيف، بما في ذلك الأنظمة التي تحتوي على وحدات معالجة الرسومات NVIDIA، مع تجنب CUDA واقتران برنامج التشغيل لهذه الأداة.

تسريع وحدة معالجة الرسومات المدمجة من Intel/AMD عبر VA-API أو Quick Sync أو OpenCL غير مدعوم لاستدلال الذكاء الاصطناعي حاليًا. تعيين `/dev/dri` داخل حاوية لا يسرّع أدوات Python الجانبية هذه ما لم تتوفر وحدة معالجة رسومات NVIDIA قادرة على تشغيل CUDA.

19 أداة ذكاء اصطناعي تعمل عبر Python الجانبية موزّعة على أربع طرائق (صورة، وصوت، وفيديو، ومستند)، بالإضافة إلى أداتين ذواتَي قدرات ذكاء اصطناعي اختيارية. تعمل جميع النماذج محليًا، ولا حاجة للإنترنت بعد التنزيل الأولي للنموذج.


<!-- korean-ocr-contract:start -->
::: info توافق OCR الكوري
يدعم Fast OCR اللغات `auto` و`en` و`de` و`es` و`fr` و`zh` و`ja`، لكنه لا يدعم الكورية (`ko`). تتطلب الكورية حزمة OCR الدقيقة ومستوى `balanced` أو `best`. تعمل الحزمة على حاويات Linux amd64 وarm64 الرسمية، بما في ذلك مضيفات NVIDIA حيث يبقى OCR على CPU. تُرجع الأنظمة غير المدعومة خطأ توافق صريحاً ولا تعود بصمت إلى `fast`. كما يُرفض طلب Korean مع `fast` أو الاسم القديم `tesseract` قبل وضعه في قائمة الانتظار، مع `FEATURE_INCOMPATIBLE` والسبب `fast-korean-unsupported`.
:::
<!-- korean-ocr-contract:end -->
## البنية المعمارية {#architecture}

```
Node.js Tool Route
      |
      v
 @snapotter/ai bridge.ts
      | (stdin/stdout JSON + stderr progress events)
      v
 +-- Native Tesseract + Ghostscript (fast image/PDF OCR)
 |
 +-- Isolated OCR runtime (persistent JSONL dispatcher)
 |     `-- RapidOCR + ONNX Runtime CPU + pinned PP-OCR models
 |
 `-- Python dispatcher (persistent process, "ai" profile)
      |
      |-- remove_bg.py        (rembg / BiRefNet)
      |-- upscale.py          (RealESRGAN)
      |-- inpaint.py          (LaMa ONNX)
      |-- outpaint.py         (LaMa canvas expansion)
      |-- detect_faces.py     (MediaPipe)
      |-- face_landmarks.py   (MediaPipe landmarks)
      |-- enhance_faces.py    (GFPGAN / CodeFormer)
      |-- colorize.py         (DDColor)
      |-- noise_removal.py    (SCUNet / tiered denoising)
      |-- red_eye_removal.py  (landmark + color analysis)
      |-- restore.py          (scratch repair + enhancement + denoising)
      |-- transcribe.py       (faster-whisper speech-to-text)
      +-- install_feature.py  (on-demand bundle installer)
```

يستبدل ملف تعريف موزّع "docs" منفصل قائمةَ السماح الخاصة بالذكاء الاصطناعي بنصوص معالجة المستندات (`doc_pagecount`، `doc_health`، `doc_flatten`، `doc_redact`، `doc_text`، `doc_to_word`، `doc_metadata`، `doc_html_pdf`) ويتجاوز عمليات استيراد التعلم الآلي الثقيلة.

**المهل الزمنية:** 300 ثانية افتراضيًا؛ وتحصل قراءة النصوص (OCR) وإزالة الخلفية بـ BiRefNet على 600 ثانية.

## حزم الميزات {#feature-bundles}

تُحزَّم نماذج الذكاء الاصطناعي حسب حزمة التبعيات المشتركة، وليس أرشيفًا واحدًا لكل أداة. يمكن لحزمة الميزات أن تُفعّل عدة أدوات عندما تستخدم العائلة نفسها من النماذج، أو حزم Python (wheels)، أو المكتبات الأصلية. يبقي هذا صورة Docker الخاصة بالإصدار أصغر ويتجنب تخزين نسخ مكررة من نماذج تنعيم الخلفية، واكتشاف الوجوه، وقراءة النصوص، والترميم، والكلام نفسها.

تشحن صورة Docker التطبيقَ إضافةً إلى وقت التشغيل المشترك. تُنزَّل أرشيفات النماذج الكبيرة عند الطلب إلى وحدة التخزين الدائمة `/data/ai`، ثم تُعاد استخدامها من قِبل كل أداة تحتاجها. إذا كانت الحزمة مثبّتة بالفعل لأن أداة أخرى احتاجتها، فإن تفعيل أداة جديدة معتمدة عليها لا يُعيد تنزيل تلك الحزمة.

تتطلب معظم أدوات الذكاء الاصطناعي حزمة ميزات واحدة أو أكثر قبل أن تتمكن من التشغيل. تقوم واجهة المستخدم الإدارية بتثبيت تلك عن طريق الأداة من خلال `POST /api/v1/admin/tools/:toolId/features/install`، الذي يحل قائمة الحزم الكاملة، ويتخطى الحزم المثبتة بالفعل، ويضع التنزيلات المفقودة فقط في قائمة الانتظار. على سبيل المثال، تمكين صورة جواز السفر في قائمة انتظار المثيلات الجديدة `background-removal` و`face-detection`؛ تمكينه بعد تثبيت بالفعل قوائم الانتظار إزالة الخلفية فقط `face-detection`. OCR هو الاستثناء لأن `fast` لا يحتاج إلى حزمة؛ قم بتثبيت وقت التشغيل الدقيق الاختياري من خلال واجهة المستخدم أو `POST /api/v1/admin/features/ocr/install`.

| الحزمة | الحجم | مجموعة التبعيات المشتركة | الأدوات التي تستخدمها |
|--------|------|-------------------------|-------------------|
| `background-removal` | 4-5 GB | تنعيم الخلفية rembg / BiRefNet | remove-background, passport-photo, transparency-fixer, background-replace, blur-background |
| `face-detection` | 200-300 MB | اكتشاف الوجوه والمعالم في MediaPipe | blur-faces, red-eye-removal, smart-crop |
| `object-eraser-colorize` | 1-2 GB | الرسم الداخلي/الخارجي بـ LaMa و DDColor | erase-object, colorize, ai-canvas-expand |
| `upscale-enhance` | 5-6 GB | RealESRGAN و GFPGAN / CodeFormer وإزالة التشويش | upscale, enhance-faces, noise-removal |
| `photo-restoration` | 4-5 GB | مسار إصلاح الخدوش والترميم | restore-photo |
| `ocr` | ~208-234 MiB تنزيل / ~409-488 MiB مثبتة | اختياري RapidOCR 3.9.1، ONNX Runtime 1.20.1، ونماذج PP-OCR المثبتة | ocr وocr-pdf (`balanced` و`best` فقط) |
| `transcription` | ~600 MB | نماذج تحويل الكلام إلى نص faster-whisper | transcribe-audio, auto-subtitles |

أدوات ذات تبعيات عبر عدة حزم:

| الأداة | الحزم المطلوبة | السبب |
|------|------------------|-----|
| `passport-photo` | `background-removal`، `face-detection` | يزيل الخلفية، ثم يستخدم معالم الوجه لتأطير القص وفق قواعد صور جواز السفر والهوية. |
| `enhance-faces` | `upscale-enhance`، `face-detection` | يكتشف الوجوه قبل تشغيل تحسين GFPGAN أو CodeFormer على مناطق الوجه المحددة. |

تتوفر الأداة فقط عند تثبيت جميع الحزم المطلوبة، باستثناء OCR: تظل طبقة `fast` المضمنة متاحة بدون حزمة OCR الاختيارية. عمليات التثبيت الجزئية صالحة ويتم التعامل معها بشكل متزايد: تتم إعادة استخدام الحزم المثبتة، وتظهر الحزم المفقودة كتنزيلات، ويتم تشغيل عمليات التثبيت الموضوعة في قائمة الانتظار واحدًا تلو الآخر حتى لا يتم تعديل بيئة Python المشتركة بشكل متزامن.

### التثبيت الدقيق لوقت تشغيل OCR {#accurate-ocr-runtime-installation}

تعد حزمة OCR الدقيقة بمثابة وقت تشغيل خاص بالمنصة لحاوية Linux amd64 أو Linux arm64 الرسمية. يستخدم الإصدار amd64 Python 3.12؛ يستخدم الإصدار arm64 Python 3.11. يعمل كلا الإصدارين على تشغيل RapidOCR من خلال ONNX Runtime's `CPUExecutionProvider`، لذا فإن نفس الحزمة تعمل على وحدة المعالجة المركزية (CPU) فقط ومضيفي NVIDIA Docker. يتطلب وقت التشغيل الدقيق ما لا يقل عن 4 GiB من الذاكرة الفعالة: الحد الأقصى للحاوية التي تم تكوينها cgroup، خلاف ذلك الذاكرة المضيفة. يتم رفض النظام الموجود أسفل الحد الأدنى من التوافق الموقع قبل التنزيل. لا ينطبق هذا المتطلب على Fast OCR المدمج. تم رفض إصدارات Bare-metal لأنه لا يمكن استنتاج libc و Python ABI بشكل آمن؛ يظل OCR السريع متاحًا عندما يوفر المضيف Tesseract و Ghostscript.

يكون المنتج الاختياري حوالي 208-234 MiB مضغوطًا و409-488 MiB مستخرجًا، اعتمادًا على البنية. يربط الفهرس الموقع عدد البايتات المضغوطة والمستخرجة بدقة والذي يفرضه المثبت. يضيف Tesseract المدمج حوالي 25 MiB إلى الصورة الرسمية ولا يحتاج إلى ملفات في `/data/ai`.

يجلب التثبيت عبر الإنترنت فهرس الإصدار الموقع والمحتوى المحدد الذي يتناوله النظام الأساسي الحالي. يتحقق SnapOtter من توقيع فهرس Ed25519، وحجم القطعة الأثرية، وملخص SHA-256، وملخصات النموذج، والمسارات، وأوضاع الملفات، و smoke test المرحلي قبل تنشيط الجيل الجديد ذريًا. يؤدي التثبيت الفاشل إلى ترك الجيل السليم السابق نشطًا.

للتثبيت الهوائي، قم بتحميل كل من `ocr-runtime-index.json` الخاص بالإصدار وأرشيف وقت تشغيل OCR المطابق إلى `POST /api/v1/admin/features/import` باستخدام حقول متعددة الأجزاء تسمى `index` و`archive`. يطبق الاستيراد دون اتصال نفس عمليات التحقق من التوقيع والتجزئة والاستخراج والتوافق واختبار الدخان مثل التثبيت عبر الإنترنت؛ يتم رفض الأرشيف الذي لا يحتوي على الفهرس الموقع الموثوق به.

---

## إزالة الخلفية {#background-removal}

**مسار الأداة:** `remove-background`  
**النموذج:** rembg مع BiRefNet (الافتراضي) أو متغيرات U2-Net

| المعامل | النوع | الافتراضي | الوصف |
|-----------|------|---------|-------------|
| `model` | نص | - | متغير النموذج (تجاوز اختياري) |
| `backgroundType` | نص | `"transparent"` | أحد: `transparent`، `color`، `gradient`، `blur`، `image` |
| `backgroundColor` | نص | - | لون سداسي عشري لخلفية موحّدة |
| `gradientColor1` | نص | - | لون التدرّج الأول |
| `gradientColor2` | نص | - | لون التدرّج الثاني |
| `gradientAngle` | رقم | - | زاوية التدرّج بالدرجات |
| `blurEnabled` | منطقي | - | تفعيل تأثير طمس الخلفية |
| `blurIntensity` | رقم (0-100) | - | شدة الطمس |
| `shadowEnabled` | منطقي | - | تفعيل الظل المُسقَط على الموضوع |
| `shadowOpacity` | رقم (0-100) | - | تعتيم الظل |
| `outputFormat` | نص | - | تنسيق الإخراج: `png` أو `webp` أو `avif` |
| `edgeRefine` | عدد صحيح (0-3) | - | مستوى تنقيح الحواف |
| `decontaminate` | منطقي | - | إزالة تسرّب الألوان من الحواف |

## استبدال الخلفية {#background-replace}

**مسار الأداة:** `background-replace`  
**النموذج:** rembg / BiRefNet (مشترك مع remove-background)

يزيل الخلفية ويستبدلها بلون موحّد أو تدرّج لوني.

| المعامل | النوع | الافتراضي | الوصف |
|-----------|------|---------|-------------|
| `backgroundType` | `"color"` \| `"gradient"` | `"color"` | وضع الخلفية |
| `color` | نص | `"#ffffff"` | لون الخلفية السداسي العشري (عندما يكون `backgroundType` هو `color`) |
| `gradientColor1` | نص | - | لون التدرّج السداسي العشري الأول |
| `gradientColor2` | نص | - | لون التدرّج السداسي العشري الثاني |
| `gradientAngle` | عدد صحيح (0-360) | `180` | زاوية التدرّج بالدرجات |
| `feather` | عدد صحيح (0-20) | `0` | نصف قطر تنعيم الحواف |
| `format` | `"png"` \| `"webp"` | `"png"` | تنسيق الإخراج |

## طمس الخلفية {#blur-background}

**مسار الأداة:** `blur-background`  
**النموذج:** rembg / BiRefNet (مشترك مع remove-background)

يطمس الخلفية مع إبقاء الموضوع حادًا.

| المعامل | النوع | الافتراضي | الوصف |
|-----------|------|---------|-------------|
| `intensity` | عدد صحيح (1-100) | `50` | شدة الطمس |
| `feather` | عدد صحيح (0-20) | `0` | نصف قطر تنعيم الحواف |
| `format` | `"png"` \| `"webp"` | `"png"` | تنسيق الإخراج |

## تحسين دقة الصورة {#image-upscaling}

**مسار الأداة:** `upscale`  
**النموذج:** RealESRGAN (مع الرجوع إلى Lanczos عند عدم التوفر)

| المعامل | النوع | الافتراضي | الوصف |
|-----------|------|---------|-------------|
| `scale` | رقم | `2` | عامل تحسين الدقة |
| `model` | نص | `"auto"` | متغير النموذج |
| `faceEnhance` | منطقي | `false` | تطبيق مرور تحسين الوجه بـ GFPGAN |
| `denoise` | رقم | `0` | قوة إزالة التشويش |
| `format` | نص | `"auto"` | تجاوز تنسيق الإخراج |
| `quality` | رقم | `95` | جودة الإخراج (1-100) |

## قراءة النصوص (OCR) / استخراج النص {#ocr-text-extraction}

**مسار الأداة:** `ocr`  
**النماذج:** Tesseract (`fast`)؛ RapidOCR مع نماذج PP-OCRv6 الصغيرة (`balanced`)؛ الطرازات المتوسطة PP-OCRv6 مع تسجيل متغير مُعاير (`best`)

| المعامل | النوع | الافتراضي | الوصف |
|-----------|------|---------|-------------|
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | متحرك | عند حذف `quality` و`engine`، يختار SnapOtter أعلى مستوى متاح بالترتيب: `best` ثم `balanced` ثم `fast`. لا تختار اللغة الكورية `fast` أبداً؛ بل تستخدم `best` ثم `balanced`، أو تُرجع خطأ تثبيت أو توافق لوقت التشغيل الدقيق. |
| `language` | نص | `"auto"` | اللغة: `auto`، `en`، `de`، `fr`، `es`، `zh`، `ja`، `ko` |
| `enhance` | منطقية | تعتمد على الطبقة | تحسين التباين المحلي. سريع يطبقه مباشرة؛ تحافظ الطبقات الدقيقة على المتغير فقط عندما يؤدي تسجيل المعايرة إلى تحسين OCR. الإعدادات الافتراضية للأفضل |
| `engine` | خيط | - | الاسم المستعار للتوافق مهمل. تعيين `tesseract` إلى `fast` وقيمة `paddleocr` القديمة إلى `balanced`؛ لا يتم تحميل PaddlePaddle |

إرجاع النص المستخرج بالإضافة إلى بيانات تعريف المصدر: المحرك، والجودة المطلوبة والفعلية، والجهاز، والموفر، وحالة التدهور، والتحذيرات، وإصدارات وقت التشغيل/الطراز الدقيقة عند الاقتضاء. طلبات الجودة الصريحة لا تعود أبدًا إلى مستوى آخر. في حالة عدم توفر `balanced` أو `best`، تقوم API بإرجاع `FEATURE_NOT_INSTALLED` أو `FEATURE_INCOMPATIBLE` بدلاً من تشغيل `fast` بصمت.

## قراءة نصوص PDF {#pdf-ocr}

**مسار الأداة:** `ocr-pdf`  
**النماذج:** نظام الطبقات نفسه المستخدم في قراءة نصوص الصور

يستخرج النص من مستندات PDF الممسوحة ضوئيًا باستخدام قراءة النصوص المدعومة بالذكاء الاصطناعي، صفحة بصفحة.

| المعامل | النوع | الافتراضي | الوصف |
|-----------|------|---------|-------------|
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | متحرك | عند حذف `quality` و`engine`، يختار SnapOtter أعلى مستوى متاح بالترتيب: `best` ثم `balanced` ثم `fast`. لا تختار اللغة الكورية `fast` أبداً؛ بل تستخدم `best` ثم `balanced`، أو تُرجع خطأ تثبيت أو توافق لوقت التشغيل الدقيق. |
| `language` | نص | `"auto"` | اللغة: `auto`، `en`، `de`، `fr`، `es`، `zh`، `ja`، `ko` |
| `pages` | نص | `"all"` | تحديد الصفحات: `"all"`، `"1-3"`، `"1,3,5"` |
| `enhance` | منطقية | تعتمد على الطبقة | تحسين التباين المحلي. سريع يطبقه مباشرة؛ تحافظ الطبقات الدقيقة على المتغير فقط عندما يؤدي تسجيل المعايرة إلى تحسين OCR. الإعدادات الافتراضية للأفضل |
| `engine` | خيط | - | الاسم المستعار للتوافق مهمل. تعيين `tesseract` إلى `fast` وقيمة `paddleocr` القديمة إلى `balanced`؛ لا يتم تحميل PaddlePaddle |

تنطبق نفس قاعدة عدم الرجوع إلى الإصدار السابق على PDF OCR. يتم تنقيط صفحات PDF قبل التعرف عليها، ويمكن لطلب واحد تحديد 50 صفحة على الأكثر.

## طمس الوجوه / المعلومات الشخصية {#face-pii-blur}

**مسار الأداة:** `blur-faces`  
**النموذج:** اكتشاف الوجوه بـ MediaPipe

| المعامل | النوع | الافتراضي | الوصف |
|-----------|------|---------|-------------|
| `blurRadius` | رقم (1-100) | `30` | نصف قطر طمس غاوس |
| `sensitivity` | رقم (0-1) | `0.5` | عتبة ثقة الاكتشاف |

## تحسين الوجه {#face-enhancement}

**مسار الأداة:** `enhance-faces`  
**النماذج:** GFPGAN، CodeFormer

| المعامل | النوع | الافتراضي | الوصف |
|-----------|------|---------|-------------|
| `model` | `"auto"` \| `"gfpgan"` \| `"codeformer"` | `"auto"` | نموذج التحسين |
| `strength` | رقم (0-1) | `0.8` | قوة التحسين |
| `sensitivity` | رقم (0-1) | `0.5` | عتبة اكتشاف الوجه |
| `onlyCenterFace` | منطقي | `false` | تحسين الوجه الأكثر مركزية فقط |

## التلوين بالذكاء الاصطناعي {#ai-colorization}

**مسار الأداة:** `colorize`  
**النموذج:** DDColor (مع الرجوع إلى OpenCV DNN)

يحوّل الصور بالأبيض والأسود أو ذات التدرّج الرمادي إلى ألوان كاملة.

| المعامل | النوع | الافتراضي | الوصف |
|-----------|------|---------|-------------|
| `intensity` | رقم (0-1) | `1.0` | قوة تشبّع الألوان |
| `model` | `"auto"` \| `"ddcolor"` \| `"opencv"` | `"auto"` | متغير النموذج |

## إزالة التشويش {#noise-removal}

**مسار الأداة:** `noise-removal`  
**النموذج:** SCUNet (مسار إزالة تشويش متدرّج)

| المعامل | النوع | الافتراضي | الوصف |
|-----------|------|---------|-------------|
| `tier` | `"quick"` \| `"balanced"` \| `"quality"` \| `"maximum"` | `"balanced"` | طبقة المعالجة |
| `strength` | رقم (0-100) | `50` | قوة إزالة التشويش |
| `detailPreservation` | رقم (0-100) | `50` | مقدار التفاصيل المراد الحفاظ عليها؛ القيمة الأعلى تُبقي نسيجًا أكثر |
| `colorNoise` | رقم (0-100) | `30` | قوة تقليل تشويش الألوان |
| `format` | نص | `"original"` | تنسيق الإخراج: `original`، `png`، `jpeg`، `webp`، `avif`، `jxl` |
| `quality` | رقم (1-100) | `90` | جودة ترميز الإخراج |

## إزالة العين الحمراء {#red-eye-removal}

**مسار الأداة:** `red-eye-removal`

يكتشف معالم الوجه، ويحدد مناطق العينين، ويصحح فرط تشبّع القناة الحمراء.

| المعامل | النوع | الافتراضي | الوصف |
|-----------|------|---------|-------------|
| `sensitivity` | رقم (0-100) | `50` | عتبة اكتشاف البكسل الأحمر |
| `strength` | رقم (0-100) | `70` | قوة التصحيح |
| `format` | نص | - | تجاوز تنسيق الإخراج (اختياري) |
| `quality` | رقم (1-100) | `90` | جودة الإخراج |

## ترميم الصور {#photo-restoration}

**مسار الأداة:** `restore-photo`

مسار متعدد الخطوات للصور القديمة أو التالفة: اكتشاف الخدوش/التمزقات وإصلاحها، وتحسين الوجه، وإزالة التشويش، والتلوين الاختياري.

| المعامل | النوع | الافتراضي | الوصف |
|-----------|------|---------|-------------|
| `scratchRemoval` | منطقي | `true` | اكتشاف الخدوش والتمزقات وإصلاحها |
| `faceEnhancement` | منطقي | `true` | تطبيق مرور تحسين الوجه |
| `fidelity` | رقم (0-1) | `0.7` | قوة تحسين الوجه (الأعلى = أكثر تحفظًا) |
| `denoise` | منطقي | `true` | تطبيق مرور إزالة التشويش |
| `denoiseStrength` | رقم (0-100) | `25` | قوة إزالة التشويش |
| `colorize` | منطقي | `false` | التلوين بعد الترميم |
| `colorizeStrength` | رقم (0-100) | `85` | شدة التلوين |

## صورة جواز السفر {#passport-photo}

**مسار الأداة:** `passport-photo`  
**النماذج:** معالم الوجه بـ MediaPipe + إزالة الخلفية بـ BiRefNet

سير عمل من مرحلتين: التحليل (اكتشاف الوجه + إزالة الخلفية) ثم التوليد (القص، وتغيير الحجم، والتبليط). يدعم أكثر من 37 دولة عبر 6 مناطق.

### المرحلة 1: التحليل {#phase-1-analyze}

`POST /api/v1/tools/image/passport-photo/analyze`

يقبل ملف صورة (متعدد الأجزاء). يُرجِع بيانات معالم الوجه، ومعاينة بترميز base64، وأبعاد الصورة.

### المرحلة 2: التوليد {#phase-2-generate}

`POST /api/v1/tools/image/passport-photo/generate`

يقبل جسم JSON يحتوي على نتائج المرحلة 1 إضافةً إلى إعدادات التوليد:

| المعامل | النوع | الافتراضي | الوصف |
|-----------|------|---------|-------------|
| `jobId` | نص | (مطلوب) | معرّف المهمة من المرحلة 1 |
| `filename` | نص | (مطلوب) | اسم الملف الأصلي من المرحلة 1 |
| `countryCode` | نص | (مطلوب) | رمز الدولة ISO (مثل `US`، `GB`، `IN`) |
| `documentType` | نص | `"passport"` | نوع المستند |
| `bgColor` | نص | `"#FFFFFF"` | لون الخلفية السداسي العشري |
| `printLayout` | نص | `"none"` | تخطيط الطباعة: `none`، `4x6`، `a4`، `letter` |
| `maxFileSizeKb` | رقم | `0` | الحد الأقصى لحجم الملف بالكيلوبايت (0 = بلا حد) |
| `dpi` | رقم (72-1200) | `300` | دقة الإخراج DPI |
| `customWidthMm` | رقم | - | عرض مخصص بالمليمتر (يتجاوز مواصفات الدولة) |
| `customHeightMm` | رقم | - | ارتفاع مخصص بالمليمتر (يتجاوز مواصفات الدولة) |
| `zoom` | رقم (0.5-3) | `1` | عامل التكبير |
| `adjustX` | رقم | `0` | تعديل الموضع الأفقي |
| `adjustY` | رقم | `0` | تعديل الموضع الرأسي |
| `landmarks` | كائن | (مطلوب) | المعالم من المرحلة 1 |
| `imageWidth` | رقم | (مطلوب) | عرض الصورة من المرحلة 1 |
| `imageHeight` | رقم | (مطلوب) | ارتفاع الصورة من المرحلة 1 |

## محو الأجسام (الرسم الداخلي) {#object-erasing-inpainting}

**مسار الأداة:** `erase-object`  
**النموذج:** LaMa عبر ONNX Runtime

يُرسَل القناع كـ**جزء ملف ثانٍ** (اسم الحقل `mask`)، وليس بترميز base64. تشير البكسلات البيضاء في القناع إلى المناطق المراد محوها. يُرسَل الإعدادان `format` و`quality` كحقول نموذج علوية المستوى.

| المعامل | النوع | الافتراضي | الوصف |
|-----------|------|---------|-------------|
| `file` | ملف | (مطلوب) | الصورة المصدر (متعددة الأجزاء) |
| `mask` | ملف | (مطلوب) | صورة القناع (متعددة الأجزاء، اسم الحقل `mask`، الأبيض = محو) |
| `format` | نص | `"auto"` | تنسيق الإخراج: `auto`، `png`، `jpg`، `jpeg`، `webp`، `tiff`، `gif`، `avif`، `heic`، `heif`، `jxl` |
| `quality` | عدد صحيح (1-100) | `95` | جودة الإخراج |

مُسرَّع بـ CUDA عند توفر وحدة معالجة رسومات NVIDIA.

## توسيع اللوحة بالذكاء الاصطناعي {#ai-canvas-expand}

**مسار الأداة:** `ai-canvas-expand`  
**النموذج:** الرسم الخارجي القائم على LaMa

يوسّع لوحة الصورة في أي اتجاه ويملأ المناطق الجديدة بمحتوى مولّد بالذكاء الاصطناعي يطابق الصورة الموجودة.

| المعامل | النوع | الافتراضي | الوصف |
|-----------|------|---------|-------------|
| `extendTop` | عدد صحيح | `0` | البكسلات المراد تمديدها في الأعلى |
| `extendRight` | عدد صحيح | `0` | البكسلات المراد تمديدها على اليمين |
| `extendBottom` | عدد صحيح | `0` | البكسلات المراد تمديدها في الأسفل |
| `extendLeft` | عدد صحيح | `0` | البكسلات المراد تمديدها على اليسار |
| `tier` | `"fast"` \| `"balanced"` \| `"high"` | `"balanced"` | طبقة الجودة |
| `format` | نص | `"auto"` | تنسيق الإخراج: `auto`، `png`، `jpg`، `jpeg`، `webp`، `tiff`، `gif`، `avif`، `heic`، `heif`، `jxl` |
| `quality` | عدد صحيح (1-100) | `95` | جودة الإخراج |

يجب أن يكون اتجاه تمديد واحد على الأقل أكبر من 0.

## القص الذكي {#smart-crop}

**مسار الأداة:** `smart-crop`  
**النموذج:** اكتشاف الوجوه بـ MediaPipe (وضع الوجه فقط)

| المعامل | النوع | الافتراضي | الوصف |
|-----------|------|---------|-------------|
| `mode` | نص | `"subject"` | استراتيجية القص: `subject`، `face`، `trim` |
| `strategy` | `"attention"` \| `"entropy"` | `"attention"` | استراتيجية وضع الموضوع |
| `width` | عدد صحيح | - | عرض الإخراج |
| `height` | عدد صحيح | - | ارتفاع الإخراج |
| `padding` | عدد صحيح (0-50) | `0` | نسبة الحشو حول الموضوع |
| `facePreset` | نص | `"head-shoulders"` | التأطير المُعَدّ مسبقًا عند `mode=face` |
| `sensitivity` | رقم (0-1) | `0.5` | عتبة اكتشاف الوجه |
| `threshold` | عدد صحيح (0-255) | `30` | عتبة اكتشاف الخلفية (وضع التشذيب) |
| `padToSquare` | منطقي | `false` | حشو النتيجة المُشذَّبة إلى مربع |
| `padColor` | نص | `"#ffffff"` | لون الخلفية للحشو المربّع |
| `targetSize` | عدد صحيح | - | الحجم المستهدف للإخراج المحشو (بالبكسل) |
| `quality` | عدد صحيح (1-100) | - | جودة الإخراج |

تُقبَل القيم القديمة `mode` وهي `attention` و`content` وتُعيَّن إلى `subject` و`trim` على التوالي.

**الإعدادات المسبقة للوجه:**

| الإعداد المسبق | الأفضل لِـ |
|--------|---------|
| `closeup` | لقطات الرأس |
| `head-shoulders` | صور الملف الشخصي |
| `upper-body` | LinkedIn / رسمي |
| `half-body` | الجزء العلوي الكامل من الجسم |

## نسخ الصوت {#transcribe-audio}

**مسار الأداة:** `transcribe-audio`  
**النموذج:** faster-whisper

يحوّل الكلام إلى نص. يدعم تنسيقات إخراج النص العادي و SRT و VTT.

| المعامل | النوع | الافتراضي | الوصف |
|-----------|------|---------|-------------|
| `language` | نص | `"auto"` | اللغة: `auto`، `en`، `de`، `fr`، `es`، `zh`، `ja`، `ko`، `id`، `th`، `vi` |
| `outputFormat` | `"txt"` \| `"srt"` \| `"vtt"` | `"txt"` | تنسيق الإخراج |

## الترجمات التلقائية {#auto-subtitles}

**مسار الأداة:** `auto-subtitles`  
**النموذج:** faster-whisper (يستخرج الصوت من الفيديو، ثم ينسخه)

يولّد ملفات ترجمة من مسار الصوت في الفيديو.

| المعامل | النوع | الافتراضي | الوصف |
|-----------|------|---------|-------------|
| `language` | نص | `"auto"` | اللغة: `auto`، `en`، `de`، `fr`، `es`، `zh`، `ja`، `ko`، `id`، `th`، `vi` |
| `format` | `"srt"` \| `"vtt"` | `"srt"` | تنسيق ملف الترجمة للإخراج |

## مُصلِح شفافية PNG {#png-transparency-fixer}

**مسار الأداة:** `transparency-fixer`  
**النموذج:** تنعيم BiRefNet عالي الدقة (بدقة 2048x2048)

يصلح ملفات PNG "الشفافة الزائفة" حيث أُزيلت الخلفية لكنها تركت وراءها هُدبًا، أو هالات، أو عيوبًا شبه شفافة. يستخدم نموذج التنعيم عالي الدقة من BiRefNet لإنتاج قناة ألفا نظيفة، ثم يطبّق معالجة إزالة هُدب قابلة للتهيئة لإزالة تلوث الألوان على طول الحواف.

**سلسلة الرجوع عند نفاد الذاكرة (OOM):** إذا تجاوز تنعيم BiRefNet عالي الدقة الذاكرة المتاحة، ترجع الأداة تلقائيًا إلى `birefnet-general`، ثم إلى `u2net`.

| المعامل | النوع | الافتراضي | الوصف |
|-----------|------|---------|-------------|
| `defringe` | رقم (0-100) | `30` | قوة إزالة هُدب الحواف لإزالة تلوث الألوان |
| `outputFormat` | `"png"` \| `"webp"` | `"png"` | تنسيق صورة الإخراج |
| `removeWatermark` | منطقي | `false` | تطبيق معالجة مسبقة لإزالة العلامة المائية (مرشّح وسيط) |

```bash
curl -X POST http://localhost:1349/api/v1/tools/image/transparency-fixer \
  -H "Authorization: Bearer <token>" \
  -F "file=@fake-transparent.png" \
  -F 'settings={"defringe":30,"outputFormat":"png"}'
```

---

## أدوات ذات قدرات ذكاء اصطناعي اختيارية {#tools-with-optional-ai-capabilities}

الأدوات التالية ليست أدوات Python جانبية لكنها تستخدم ميزات الذكاء الاصطناعي عند تفعيل خيارات معينة.

### تحسين الصورة {#image-enhancement}

**مسار الأداة:** `image-enhancement`  
**المحرك:** قائم على التحليل (المدرج التكراري والإحصاءات في Sharp)

يحلّل الصورة ويطبّق تصحيحات تلقائية للتعريض، والتباين، وتوازن الأبيض، والتشبّع، والحدة، والتشويش. يدعم أوضاعًا خاصة بالمشهد.

| المعامل | النوع | الافتراضي | الوصف |
|-----------|------|---------|-------------|
| `mode` | `"auto"` \| `"portrait"` \| `"landscape"` \| `"low-light"` \| `"food"` \| `"document"` | `"auto"` | وضع المشهد لضبط التصحيحات |
| `intensity` | رقم (0-100) | `50` | قوة التصحيح الإجمالية |
| `corrections.exposure` | منطقي | `true` | تطبيق تصحيح التعريض |
| `corrections.contrast` | منطقي | `true` | تطبيق تصحيح التباين |
| `corrections.whiteBalance` | منطقي | `true` | تطبيق تصحيح توازن الأبيض |
| `corrections.saturation` | منطقي | `true` | تطبيق تصحيح التشبّع |
| `corrections.sharpness` | منطقي | `true` | تطبيق تصحيح الحدة |
| `corrections.denoise` | منطقي | `true` | تطبيق إزالة التشويش |
| `deepEnhance` | منطقي | `false` | تفعيل إزالة التشويش بالذكاء الاصطناعي عبر SCUNet (يتطلب حزمة `upscale-enhance`) |

تتوفر نقطة نهاية تحليل إضافية عند `POST /api/v1/tools/image/image-enhancement/analyze` تُرجِع التصحيحات المكتشفة دون تطبيقها.

### تغيير الحجم المدرك للمحتوى (نحت الأطراف) {#content-aware-resize-seam-carving}

**مسار الأداة:** `content-aware-resize`  
**المحرك:** ثنائي `caire` بلغة Go (ليس Python، لا فائدة من وحدة معالجة الرسومات)

يغيّر حجم الصور بذكاء عن طريق إزالة الأطراف منخفضة الطاقة، مع الحفاظ على المحتوى المهم.

| المعامل | النوع | الافتراضي | الوصف |
|-----------|------|---------|-------------|
| `width` | رقم | - | العرض المستهدف |
| `height` | رقم | - | الارتفاع المستهدف |
| `protectFaces` | منطقي | `false` | حماية مناطق الوجه المكتشفة (يتطلب حزمة `face-detection`) |
| `blurRadius` | رقم (0-20) | `4` | طمس مسبق لحساب الطاقة |
| `sobelThreshold` | رقم (1-20) | `2` | عتبة حساسية الحواف |
| `square` | منطقي | `false` | فرض إخراج مربّع |