> 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/detectors/shape-detector.md).

# Shape Detector

هذا الدالة البلوكية تبحث عن شكل مميز في صورة ملونة عبر التصفية، الت threshol딩 (العَتْبة) وتحليل المنحنيات. تعيد نتيجة مرئية ووصفات شكل رقمية يمكن استخدامها في البلوكات التالية.

## 📥 المدخلات

`Image`\
مقبس الإدخال الذي يقبل صورة ملونة للتحليل.

## 📤 المخرجات

`Filtered Image`\
مخرج يقدم الصورة الثنائية أو المصفاة المستخدمة لاستخراج الكنتور (تغذية بصرية لخطوات المعالجة المسبقة).

`Contoured Image`\
مخرج يقدم الصورة الأصلية مع رسم الكنتور المكتشف عليها.

`Shape Image`\
مخرج يقدم صورة الشكل المقتص أو المعزول لعرضه.

`Border Coordinate`\
مخرج يوفر إحداثيات/نقاط الكنتور التي تشكل الحد المكتشف.

`Shape Width`\
مخرج يعيد عرض الشكل المكتشف.

`Shape Height`\
مخرج يعيد ارتفاع الشكل المكتشف.

`Shape Position`\
مخرج يعيد موقع مركز الشكل المكتشف.

`Shape Rotation`\
مخرج يعيد زاوية دوران الشكل المكتشف.

## 🕹️ عناصر التحكم

`Blur coefficient`\
شريط منزلق لضبط شدة الـ median blur قبل العتبة. يُستخدم لتقليل الضوضاء مع الحفاظ على الحواف.

`Clear spots parameter`\
شريط منزلق لتحديد حجم الإغلاق المورفولوجي (morphological closing). يُستخدم لإزالة الثقوب الصغيرة أو لربط أجزاء الكائن.

`Auto threshold ?`\
مربع اختيار لتفعيل العتبة التلقائية (Otsu). عند التفعيل، نطاق العتبة اليدوي يصبح معطلاً.

`Threshold range`\
شريط منزلق ثنائي النهاية لتعيين قيم العتبة اليدوية (من/إلى). فعّال عندما يكون `Auto threshold ?` غير مفعل.

`Shape area range %`\
شريط منزلق ثنائي النهاية لحدّ الكنتورات المكتشفة حسب المساحة النسبية (نسبة مئوية من الصورة). استخدمه لتجاهل الكائنات الصغيرة جداً أو الكبيرة جداً.

## ⚙️ آلية العمل

* عند وصل صورة إلى مقبس `Image`، يطبّق البلوك الـ blur المحدد، ثم العتبة (تلقائية أو يدوية) ثم الإغلاق المورفولوجي.
* تُستخرج الكنتورات من الصورة المصفاة. يختار البلوك الكنتورات التي تقع ضمن `Shape area range %` ويعيد أكبر كنتور صالح والمخرجات ذات الصلة.
* المخرجات المرئية تعرض الصورة المصفاة والكنتور المرسوم على الصورة الأصلية لتتمكن من التحقق من النتائج في الواجهة.
* تبديل `Auto threshold ?` يفعل أو يعطل فوراً تحكم `Threshold range` اليدوي ليسمح بالتجربة السريعة.

## ✨ الميزات

* مخرجات تصحيح مرئي لكل من الصورة بعد العتبة وتراكب الكنتور.
* معالجة مسبقة مرنة: `Blur` و`Clear spots parameter`.
* ترشيح بالمساحة لتجنّب كنتورات خاطئة الناتجة عن الضوضاء أو الحواف.
* ينتج مخرجات مرئية ووصفات رقمية (الحجم، الموقع، الدوران) لاستخدامها في المنطق التالي أو التسجيل.

## 📝 تعليمات الاستخدام

1. وصل صورة ملونة إلى مقبس `Image`.
2. ابدأ بقيمة متوسطة لـ `Blur coefficient` ومعامل صغير لـ `Clear spots parameter`.
3. جرّب `Auto threshold ?` أولاً. إذا كانت النتائج مشوشة، أوقفه وضبط `Threshold range` يدوياً.
4. عدّل `Shape area range %` حتى يقع الكائن المطلوب ضمن نافذة المساحة المسموح بها.
5. راجع `Filtered Image` و`Contoured Image` لتأكيد الاكتشاف. استخدم البلوكات اللاحقة للتعامل مع `Shape Position` أو `Shape Rotation`.

## 💡 نصائح وحيل

* إذا كانت الصورة تحتوي ضوضاء لونية أو تفاوت إضاءة، ضع سلسلة معالجة مسبقة قبل هذا البلوك مثل `HSV Filter` أو `Adjust Colors` لتحسين فصل الكائن عن الخلفية.
* استخدم `Blur` أو `Denoising` قبل هذا البلوك لتقليل النمش قبل العتبة للحصول على كنتورات أكثر ثباتاً.
* لتحليل منطقة فرعية فقط، اقتطع أولاً باستخدام `Image ROI Select` أو `Image ROI` ومرّر الصورة المقتصة إلى هذا البلوك.
* لتحويل مشهد ملون مشوش إلى مدخل ثنائي أوضح، اجمع مع `Image Adaptive Threshold` أو `Image Threshold` قبل هذا البلوك.
* للمعالجة الهندسية الإضافية أو استخراج الميزات، وصل المخارج إلى بلوكات تحليل الشكل ذات الصلة مثل `Approximate Contour`، `Minimum Rectangle`، `Minimum Rotated Rectangle` أو `Translate Shape`.
* اعرض النتائج مباشرة باستخدام `Show Image` واحفظ أمثلة أو سجلات بواسطة `Image Logger` أو `Image Write` للمراجعة لاحقاً.

## 🛠️ استكشاف الأخطاء وإصلاحها

* لا يوجد كنتور: زِد الحد الأعلى في `Shape area range %` أو خفّض الحد الأدنى؛ راجع `Filtered Image` للتحقق من ظهور الكائن بعد العتبة.
* الكثير من الكنتورات الصغيرة: زِد `Clear spots parameter` (الإغلاق المورفولوجي) أو شدّد الحد الأدنى في `Shape area range %`.
* انقسام الكائن إلى كنتورات متعددة: قلّل الـ blur أو خفّض الإغلاق المورفولوجي، أو اقتطع المنطقة باستخدام `Image ROI Select` لعزل الكائن.
* العتبة لا تعمل: جرّب تفعيل `Auto threshold ?` للسماح للبلوك باختيار عتبة مناسبة تلقائياً، ثم عدّل `Threshold range` يدوياً إن لزم.