> 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/ai-blocks/hand-pose-estimation.md).

# Hand Pose Estimation

تقوم هذه الدالة باكتشاف وتقدير نقاط المفاتيح لليد (21 نقطة لكل يد) في الصور وتوفر كل من تغطية بصرية وبيانات كشف منظمة. تم تصميمها للاستخدام في الزمن الحقيقي وتوفر عناصر تحكم لحساسية الكشف، ظهور نقاط المفاتيح، نمط هيكل العظم (skeleton) وعدد الأيدي الأقصى للمعالجة.

## 📥 المدخلات

`Image` أدخل صورة (إطار كاميرا، صورة محملة، أو صورة بعد المعالجة) لتحليلها بحثًا عن الأيدي.

## 📤 المخرجات

`Visualization` صورة مشروحة تظهر نقاط المفاتيح، الهيكل العظمي (skeleton) وصناديق الإحاطة.

`Hands` بيانات كشف منظمة (قائمة/قاموس) تتضمن صناديق الإحاطة، إحداثيات كل نقطة مفتاحية، درجات الثقة وعلامات الظهور (visibility).

`Model Info` معلومات وقت التشغيل الأساسية مثل نمط الهيكل المختار وإعدادات العتبات.

`Hand Count` عدد الأيدي المكتشفة (بعد تطبيق الحدود المكوّنة).

## 🕹️ Controls

`Skeleton Style` اختر كيف يتم تنسيق نقاط المفاتيح/الهيكل العظمي للعرض (على سبيل المثال MMPose أو OpenPose style).

`Det Threshold` ضبط الثقة الدنيا المطلوبة لكي يُعتبر كشف اليد صالحًا (مقياس 0–100).

`Keypoint Threshold` ضبط الثقة الدنيا التي تجعل النقطة المفتاحية الفردية مرئية (مقياس 0–100).

`Max Hands` تحديد عدد الأيدي التي سيتم إرجاعها ورسمها (مفيد لتقليل حجم المخرجات والمعالجة في المشاهد المزدحمة).

## 🎨 Features

* تراكب بصري يعرض نقاط المفاتيح، وصلات الهيكل العظمي وصناديق الإحاطة لكل يد مكتشفة.
* مخرجات منظمة على شكل شبيهة بـ JSON للاستخدام في المنطق اللاحق: صناديق الإحاطة، إحداثيات كل نقطة (x,y)، الثقة والظهور.
* عتبات قابلة للتعديل من قبل المستخدم للموازنة بين الحساسية والنتائج الخاطئة الإيجابية.
* تحديد عدد الأيدي المعالجة عبر `Max Hands` لسلوك متوقع في المراحل اللاحقة.
* يستخدم تلقائيًا العتاد المتاح لتحسين السرعة (يفضل GPU إذا كان متاحًا).

## 📝 إرشادات الاستخدام

1. زوّد مصدر صورة إلى مدخل `Image` (كاميرا مباشرة، بث أو ملف صورة).
2. اختر `Skeleton Style` المفضل للعرض ولتنسيق المخرجات.
3. اضبط `Det Threshold` للتحكم فيما إذا كانت الاكتشافات الضعيفة ستتجاهل أم لا.
4. اضبط `Keypoint Threshold` للتحكم في النقاط المفتاحية التي تُعتبر مرئية.
5. اضبط `Max Hands` إذا أردت تتبّع عدد محدود من الأيدي.
6. اطلع على المخرجات: استخدم `Visualization` للمعاينة، و`Hands` / `Hand Count` للمنطق، واجهة المستخدم أو السجلات.

## 📊 كيف يعمل

عند تزويده بصورة، يحلل البلوك الصورة لاكتشاف الأيدي، يطبق عتبات الثقة للكشف ونقاط المفاتيح، يقيّد النتائج بواسطة `Max Hands`، ثم يُخرج: صورة مرئية مع التراكبات، قائمة منظمة بالأيدي المكتشفة مع صناديق الإحاطة وتفاصيل كل نقطة، ملخص صغير لمعلومات النموذج، وعدد الأيدي المكتشفة.

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

* للمداخل الحية، اجمعه مع `Camera USB`, `Camera IP (ONVIF)`, أو `Stream Reader` لتغذية إطارات مستمرة.
* استخدم `Show Image` لمعاينة مخرج `Visualization` في نافذة أكبر أثناء ضبط العتبات.
* قم بعمليات ما قبل المعالجة للصور المشوشة باستخدام `Blur`, `Denoising` أو `Image Resize` لتحسين استقرار الكشف.
* إذا بدت الأيدي مقطوعة أو أردت تحليل منطقة محددة فقط، ضع `Image ROI Select` أو `Image ROI` قبل هذا البلوك.
* لتعليقات للعرض أو التقارير، ادمج `Visualization` مع `Write Text On Image` أو `Draw Result On Image` ثم احفظ باستخدام `Image Logger`, `Image Write` أو `Record Video`.
* استخدم `Object Detection` أو `Object Detection - Custom` قبل هذا البلوك عندما تريد أولًا تحديد الأشخاص ثم تحليل مناطق الأشخاص فقط للأيدي — هذا يقلل الإيجابيات الكاذبة ويسرّع المعالجة.
* إذا كنت بحاجة إلى نقاط مفاتيح للجسم بالكامل بالإضافة إلى نقاط يد، فكّر في الاقتران مع `Skeleton Estimation` ودمج النتائج في خطوات المعالجة اللاحقة.

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

* لا توجد اكتشافات: جرّب خفض `Det Threshold` و`Keypoint Threshold` قليلاً، أو حسّن وضوح الصورة باستخدام `Image Resizer`.
* إيجابيات كاذبة / نقاط مفتاحية مشوشة: زد العتبات و/أو قم بقص منطقة الاهتمام باستخدام `Image ROI Select` لإزالة الفوضى.
* بطيء جدًا: قلل دقة الصورة عبر `Image Resize`, خفّض `Max Hands`, أو استخدم مصدر صورة أسرع. استخدام نظام مزود بـ GPU سيعجّل المعالجة.
* تبعيات مفقودة أو عدم توفر النموذج: يتطلب البلوك توفر نموذج hand-pose. إذا لم يكن النموذج أو مكونات وقت التشغيل موجودة، اتبع مثبت الوحدات / محمّل الوحدات في التطبيق لإضافة حزم النموذج ووقت التشغيل المطلوبة.

إذا كنت تحتاج أمثلة لتجميعات مقترحة أو خط أنابيب صغير موصى به للتتبع الحي لليد (كاميرا → معالجة مسبقة → hand pose → عرض / حفظ)، اطلب سلسلة بلوكات مقترحة وشرح قصير.