> For the complete documentation index, see [llms.txt](https://docs.augelab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.augelab.com/arabic/alblwkat-alwzyfyh/blocks-reference/detections-shapes/draw/write-text-on-image.md).

# Write Text On Image

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

## 📥 المدخلات <a href="#inputs" id="inputs"></a>

`Image Any` يستقبل الصورة التي سيتم كتابة النص عليها.

`String` إدخال نصي اختياري. إذا تُرك فارغًا، سيُرسم نص فارغ (لا يظهر نص مرئي).

## 📤 المخرجات <a href="#outputs" id="outputs"></a>

`Image Any` الصورة مع طبقة النص المطبقة.

## 🕹️ عناصر التحكم <a href="#controls" id="controls"></a>

`Text Position Horizontal` تحريك النص لليسار/لليمين باستخدام قيمة مقيسة (0.0 = اليسار، 1.0 = اليمين).

`Text Position Vertical` تحريك النص للأعلى/للأسفل باستخدام قيمة مقيسة (0.0 = الأعلى، 1.0 = الأسفل).

`Font Scale` ضبط حجم النص العام نسبةً إلى الصورة.

`Font Thickness` ضبط سماكة خط النص (Stroke).

`Font` اختر نمط الخط من الخيارات المتاحة.

`Color` اختر لون النص.

`Background Enabled` تفعيل/تعطيل مستطيل خلفي شبه شفاف خلف النص لزيادة التباين.

## 🎨 الميزات <a href="#features" id="features"></a>

* تكبير/تصغير تلقائي بحيث يتناسب حجم النص مع أبعاد الصورة لضمان مظهر متناسق عبر دقات مختلفة.
* تحديد موضع مقيّس يسهل وضع النص بشكل نسبي مستقلاً عن حجم الصورة.
* خيار خلفية شبه شفافة يحسن قابلية القراءة على الصور المعقدة.
* يعمل مع مدخلات نصية ديناميكية بحيث يمكن عرض محتوى متغير (مثل معرّفات، تسميات، قراءات حساسات).

## 📊 كيفية التشغيل <a href="#evaluation" id="evaluation"></a>

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

## 📝 تعليمات الاستخدام <a href="#usage" id="usage"></a>

1. وصل مصدرًا يوفر الصورة إلى مدخل `Image Any`.
2. أدخل النص في مدخل `String` أو اتركه فارغًا لاستخدام نص البلوك الداخلي.
3. اضبط `Font`, `Color`, `Font Scale` و`Font Thickness` للشكل المرغوب.
4. استخدم `Text Position Horizontal` و`Text Position Vertical` لوضع النص في المكان المطلوب.
5. فعّل `Background Enabled` إذا احتجت إلى تباين أعلى على صور معقدة.
6. عاين النتيجة بتوصيل هذا البلوك إلى بلوك عرض مثل `Show Image` أو احفظ النتيجة باستخدام `Image Write` / `Image Logger`.

## 💡 نصائح وحيل <a href="#tips-and-tricks" id="tips-and-tricks"></a>

* لطباعة طابع زمني متجدد، وجه خرج التاريخ من بلوك `Date-Time` أو `Date-Time List` إلى مدخل `String` بعد تنسيقه بواسطة بلوك `String Merge`.
* للمعاينة الحية أثناء ضبط الموقع والمقياس، وصل الخروج إلى بلوك `Show Image`.
* إذا أردت كتابة تسميات داخل منطقة محددة فقط، قم أولاً بقص الصورة باستخدام `Image ROI` أو `Image ROI Select` ثم طبّق هذا البلوك.
* استخدم `Image Resize` قبل الكتابة إن أردت حجم نص نهائي متسق عبر صور ذات دقات مختلفة.
* لحفظ الإطارات المشروحة، وصل الخروج إلى `Image Logger` أو `Image Write`.
* لعرض نتائج اكتشافات، ادمج مع بلوكات الكشف مثل `Find Object` أو `Object Detection` ووجه التسميات أو الأعداد المكتشفة إلى مدخل `String`.
* عند رسم نص حالة شرطية (مثل OK / NOK)، استخدم بلوكات منطقية (مثل `Logic Input` أو بلوكات المقارنة) و`String Merge` لتجميع النص قبل إرساله إلى هذا البلوك.

## 🛠️ استكشاف الأخطاء وإصلاحها <a href="#troubleshooting" id="troubleshooting"></a>

* النص صغير جدًا أو كبير جدًا: اضبط `Font Scale` أو غيّر حجم الصورة بواسطة `Image Resize` للحصول على نتائج متناسقة.
* النص غير مقروء على خلفيات مزدحمة: فعّل `Background Enabled` أو غيّر `Color` إلى قيمة عالية التباين.
* موضع النص يختلف بين الصور: استخدم القيم المقيسة في `Text Position Horizontal` و`Text Position Vertical` وتحقق من موضعه على صورة ممثلة باستخدام `Show Image`.