> 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/image-transformations/transformation-filters/alignment.md).

# Alignment

هذا البلوك يقوم بمحاذاة صورة المشهد باستخدام مجموعة مرتبة من قوالب المراجع (ROIs) ومربعات الإحاطة المقابلة لها. استخدم هذا البلوك لتصحيح أخطاء الإزاحة والدوران بحيث تتطابق صورة المشهد مع تخطيط مرجعي معروف.

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

`Scene Image` الصورة التي سيتم محاذاتها. قدّم صورة واحدة غير فارغة.

`Reference ROIs` واحد أو أكثر من صور القوالب المرجعية المرتبة المستخدمة للمطابقة (قدّمها كقائمة). الترتيب يحدد التطابق مع مربعات الإحاطة.

`Reference BBoxes` واحد أو أكثر من مربعات الإحاطة المرتبة التي تُقرَن مع `Reference ROIs` (قدّمها كقائمة). يجب أن يتطابق الترتيب مع ROIs.

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

`Aligned Image` صورة المشهد بعد تطبيق تصحيح المحاذاة المحسوب.

`Translation` تصحيح الإزاحة المطبق على شكل زوج (x, y).

`Angle` تصحيح الدوران المطبق بالدرجات.

## 🕹️ الضوابط <a href="#controls" id="controls"></a>

`Mode` اختر بين المحاذاة باستخدام الإزاحة فقط (centroid shift) أو الإزاحة مع الزاوية (rotation + translation). استخدم `Translation` عند الحاجة إلى تحريك فقط و`Translation + Angle` عندما تكون تصحيحات الدوران مطلوبة.

`Match Threshold %` حد أدنى لدرجة التطابق المطلوبة لكل ROI مرجعي. القيم الأعلى تتطلب تطابقًا أقوى.

`Include Flipped` تبديل يسمح بالأخذ بعين الاعتبار نُسخ قلابه أفقيًا من قوالب ROI أثناء المطابقة (مفيد عند احتمال ظهور العناصر معكوسة).

`Method` اختر طريقة مطابقة القالب. قد تكون بعض الطرق أسرع أو تعطي نتائج أفضل اعتمادًا على نسيج وتباين المراجع.

`Color Mode` اختر بين `Gray` (أسرع) و`BGR` (قد تحسن الدقة للقوالب الملونة).

`Tolerance (+/- px)` اضبط سماحية البكسل للمتبقي المسموح بعد المحاذاة. استخدم قيمًا أكبر لقبول مطابقة أوسع، وقيمًا أصغر لطلب محاذاة أدق.

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

* المطابقة المرجعية المرتبة: ترتيب `ROI` و`bbox` يحدد الارتباط المستخدم لحساب المحاذاة.
* وضعيتا تشغيل: إزاحة فقط أو إزاحة + زاوية لتصحيح الدوران.
* مطابقة القوالب المقلوبة اختياريًا للتعامل مع الظهور المعكوس.
* طرق مطابقة ووضعيات ألوان متعددة لتحقيق توازن بين السرعة والدقة.
* عناصر تحكم عددية مع تحقق فوري لتقليل أخطاء التكوين.

## 📊 كيف تعمل <a href="#evaluation" id="evaluation"></a>

* يتطلب البلوك وجود `Scene Image` صالح وقوائم مطابقة لـ `Reference ROIs` و`Reference BBoxes`.
* يتم مطابقة كل ROI مع المشهد بالترتيب المقدم؛ المربع المقابل يحدد الموقع المتوقع.
* إذا استوفت التطابقات حد `Match Threshold %`، يقوم البلوك بحساب الإزاحة اللازمة (وبالزاوية عند اختيارها) لمحاذاة المشهد.
* يُرجع البلوك `Aligned Image` المصححة بالإضافة إلى قيم `Translation` و`Angle` المطبقة.
* إذا كانت المدخلات مفقودة أو فارغة، أو لم تتطابق أعداد ROIs وBBoxes، سيعرض البلوك رسالة خطأ وسيتوقف حتى يتم التصحيح.

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

1. جهز مجموعة مراجع واضحة: أنشئ قوالب ROI صغيرة تحدد معالم ثابتة في المشهد بوضوح.
2. قدّم تعريفات `bbox` المتطابقة بنفس ترتيب الـ ROIs.
3. اختر `Mode` بناءً على ما إذا كنت بحاجة لتصحيح الدوران.
4. عيّن `Match Threshold %` لقيمة تقبل التطابقات الحقيقية وترفض التشابه العرضي.
5. اختياريًا فعّل `Include Flipped` إذا كانت النسخ المعكوسة قد تظهر.
6. شغّل البلوك وافحص `Aligned Image` والمخرجات الرقمية للتحقق من النتائج.

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

* استخدم `Image ROI` أو `Image ROI Select` لإنشاء قوالب مرجعية دقيقة من صورة عيّنة قبل إدخالها في `Reference ROIs`.
* عندما تحتاج لتعريف عدة مناطق تفاعليًا، استخدم `Image ROI Polygon Multi` لحفظ عدة ROIs مرجعية.
* إذا أردت التحقق بصريًا من نتائج المحاذاة، وصل مخرج `Aligned Image` إلى `Show Image` لمعاينة التصحيحات.
* للمطابقة القوية في المشاهد الغنية بالنسيج، جرّب تغيير `Color Mode` إلى `BGR` وجرب طرق `Method` المختلفة.
* إذا احتجت لاستخراج قوالب تلقائيًا، استخدم `Find Object` لتحديد الحالات ثم استخرج ROIs من الإحداثيات المبلغ عنها.
* احفظ المخرجات المحاذاة باستخدام `Image Logger` أو `Image Write` عندما ترغب في الاحتفاظ بسجلات الإطارات المصححة.

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

* عدم تطابق بين ROIs وBBoxes\
  تأكد من أن عدد وترتيب `Reference ROIs` و`Reference BBoxes` متطابقان. يعتمد البلوك على الترتيب لتحديد الارتباط.
* عدد مراجع غير كافٍ لوضع الدوران\
  إذا اخترت `Translation + Angle` تأكد من تزويدك بمرجعين مميزين على الأقل؛ وإلا فلن يمكن حل التصحيح الدوراني بشكل موثوق.
* انخفاض عدد التطابقات أو فشل التطابق\
  زِد قيمة `Match Threshold %` إذا كانت لديك إيجابيات كاذبة، أو خفّضها قليلًا إذا كانت المراجع الحقيقية مفقودة. جرّب تغيير `Method` أو `Color Mode` لتحسين النتائج.
* بقايا غير متوقعة بعد المحاذاة\
  زِد `Tolerance (+/- px)` إذا كانت أخطاء التموضع الصغيرة مقبولة، أو حسّن ROIs المرجعية لتكون أكثر تمييزًا للحصول على دقة أعلى.
* التحقق البصري\
  إذا بدت المحاذاة غير صحيحة، عاين القوالب الوسيطة و`Aligned Image` باستخدام `Show Image` لتشخيص أي مرجع فشل في المطابقة.