> 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/detect-reference.md).

# Detect Reference

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

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

`Image` الصورة التي سيتم البحث داخلها (المشهد الرئيسي). هذا مقبس إدخال.

`Reference` صورة الكائن المرجعي الذي تريد إيجادها داخل الصورة الرئيسية. هذا مقبس إدخال.

`Mask` قناع اختياري لتحديد منطقة البحث أو تجاهل أجزاء من المرجع. هذا مقبس إدخال.

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

`Image Any` صورة ناتجة مع تعليقات مرئية تُظهر المطابقات المكتشفة (إذا كان الرسم مُمكَّناً). هذا مقبس إخراج.

`Object Positions` إحداثيات مراكز كل حالة مكتشفة. هذا مقبس إخراج.

`Object Count` العدد الإجمالي للحالات المكتشفة. هذا مقبس إخراج.

`Rectangle Coordinates` إحداثيات المستطيلات المحيطة بكل كشف. هذا مقبس إخراج.

`Match Percentage` درجات الثقة أو نسبة المطابقة لكل كشف. هذا مقبس إخراج.

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

* `Match Threshold %` شريط تمرير لإقصاء المطابقات ذات الثقة المنخفضة. القيم الأعلى تقلل الإيجابيات الكاذبة.
* `Down-size` شريط لتقليل حجم الصورة لتسريع المعالجة. الصور الأصغر تعمل أسرع لكن قد تفقد تفاصيل دقيقة.
* `Rotations` شريط لتحديد عدد شرائح الزاوية التي ستُجرى عليها الاختبارات (المزيد يعني تحمل أكبر للدوران لكنه يزيد زمن المعالجة).
* `Sweep Angle` محدد نطاق يضبط زاوية المسح (البداية والنهاية) لاختبار الدوران.
* `Include Flipped` خانة اختيار لتضمين نسخة مقلوبة أفقياً من المرجع أثناء البحث (مفيد للأجسام المعكوسة).
* `Method` قائمة منسدلة لاختيار طريقة تقدير المطابقة؛ كل خيار يقدّم توازناً مختلفاً بين الدقة والسلوك.
* `Color Mode` قائمة منسدلة للتبديل بين المقارنة بتدرج الرمادي أو باللون الكامل (BGR). وضع BGR عادةً أدق للمراجع الملونة أو الملمسية.

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

* مطابقة متسامحة مع الدوران: يبحث عبر نطاق زوايا للعثور على الحالات المدورة.
* تحكم في الحجم/الأداء: يتيح `Down-size` موازنة بين الدقة والسرعة.
* بحث اختياري بالانعكاس: العثور على المظاهر المعكوسة بتفعيل `Include Flipped`.
* دعم القناع: استخدم `Mask` لتجاهل أجزاء من المرجع أو المشهد.
* وضع حسّاس للون: اختر بين تدرج الرمادي وBGR لتحسين النتائج على المراجع الملونة.
* مخرجات مرئية وعددية: صورة مع التعليقات، نقاط المركز، المستطيلات المحيطة، الأعداد ونسب المطابقة.

## ⚙️ كيف يعمل <a href="#how-it-works" id="how-it-works"></a>

* يمكن للبلوك تقليل أحجام الصور عندما يتم ضبط `Down-size` لتسريع المعالجة.
* يتم اختبار المرجع عبر عدة شرائح دوران تُحدد بـ`Rotations` و`Sweep Angle`.
* إذا كان `Include Flipped` مفعلاً، فسيُختبر أيضاً المرجع المقلوب.
* تحدد `Method` و`Color Mode` كيفية احتساب درجة كل مطابقة مرشحة.
* المطابقات التي تبلغ أو تتجاوز قيمة `Match Threshold %` تُبلغ عنها وقد تُرسم على الصورة الناتجة.
* تُعاد النتائج على شكل صورة مشروحة، قائمة بإحداثيات المراكز، عدد الكشوف، إحداثيات المستطيلات ونسب المطابقة.

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

1. زوّد الصورة المشهدية في `Image` والعينات المرجعية في `Reference`. اختياريًا قدّم `Mask` لتقييد مناطق البحث.
2. ابدأ بإعدادات متوسطة: ضع `Match Threshold %` حول 50–70 واحتفظ بـ`Rotations` و`Down-size` منخفضين.
3. راجع النتائج عبر `Image Any` المشروحة و`Object Positions` / `Object Count`.
4. عدّل عناصر التحكم: زد `Rotations` للأجسام ذات الدوران الكبير، قلّل `Down-size` لتحسين الدقة، أو اختر `Color Mode` = BGR للمطابقات الحساسة للون.
5. استخدم `Mask` لتقليل الإيجابيات الكاذبة عندما يحتوي المرجع على خلفية أو أنماط متكررة.

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

* إذا كانت صور الإدخال كبيرة جداً، أضف `Image Resize` أو `Image Resizer` قبل هذا البلوك لتسريع المعالجة مع الحفاظ على التفاصيل اللازمة.
* اقتطِ المنطقة ذات الاهتمام باستخدام `Image ROI Select` لتقليل مساحة البحث والإيجابيات الكاذبة.
* عالج المدخلات مسبقاً بـ`Blur`, `Denoising` أو `Contrast Optimization` لتقليل ضوضاء المستشعر وتحسين ثبات المطابقة.
* استخدم `Image Threshold` أو `Background Removal (RMBG-1.4)` عندما يكون للمرجع فصل واضح بين المقدمة والخلفية لتبسيط المطابقة.
* عاين الكشوف باستخدام `Show Image` لفتح عارض صورة أكبر.
* أضف مستطيلات أو تسميات عبر `Draw Detections` إذا رغبت في عرض مخصص للتقارير أو للمعالجة اللاحقة.
* سجّل أمثلة للكشوف باستخدام `Image Logger` لحفظ بيانات العينة أو لأغراض التصحيح.

(تلميح: الجمع بين هذه البلوكات يمكن أن يسرّع المطابقة ويقلل الإيجابيات الكاذبة — مثلاً اقتطع بـ`Image ROI Select`, حسّن التباين بـ`Contrast Optimization`, ثم نفّذ هذا البلوك.)

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

* لم تُعثر أي مطابقات: جرّب خفض `Match Threshold %`, زد `Rotations` إذا كان الكائن قد يكون دورانياً، أو غيّر `Color Mode` إلى BGR.
* عدد كبير من الإيجابيات الكاذبة: زد قيمة `Match Threshold %`, قدّم `Mask` أدق، أو اقتطع الإدخال باستخدام `Image ROI Select`.
* أداء بطيء: قلّل `Rotations` أو زد قيمة `Down-size`. فعّل `Include Flipped` فقط عند الحاجة.
* مطابقة جزئية أو غير مستقرة: استخدم مرجعاً بجودة أعلى (واضح، ذو تباين جيد)، عالج الصورة باستخدام `Blur` أو `Contrast Optimization`، أو جرّب وضع اللون BGR.

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