> 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/input-output/image-inputs/play-folder.md).

# Play Folder

تعمل هذه الوحدة على تشغيل الصور الموجودة في مجلد محدد، وتعيد ملفًا واحدًا في كل تقييــم. استخدمها للتنقّل خلال مجموعات الصور، معاينة التسلسلات، أو توجيه الصور إلى معالجة لاحقة. يمكنك اختيار مجلد افتراضي باستخدام زر اختيار المجلد، تجاوزه عبر مدخل `Folder Path`, فلترة الملفات بنمط glob، والتحكم في التشغيل عبر عناصر التحكم `Mode` و`Order`.

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

`Folder Path` نص اختياري يجاوز المجلد الافتراضي المُختار بزر المجلد. قدّم مسار مجلد كامل لتغيير المصدر أثناء التشغيل.

`Restart` مدخل منطقي اختياري. عند إرساله بقيمة True، تعيد الوحدة إعادة ضبط التشغيل وفقًا لـ `Mode` الحالي وتعيد الصورة الحافة (edge) بعد إعادة الضبط في ذلك التقييم.

ملاحظة: هذه مآخذ إدخال.

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

`Image` الصورة الحالية المقروءة من المجلد. هذا مخرج صورة.

`File Path` المسار المطلق لملف الصورة الحالي. هذا مخرج سلسلة نصية.

`Restarted` منطقي يكون True عندما تعيد الوحدة صورة ملففة أو صورة حافة مُعادة في هذا التقييم. هذا مخرج منطقي.

ملاحظة: هذه مآخذ إخراج.

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

`Select folder` زر لاختيار المجلد الافتراضي المستخدم عندما تكون قيمة `Folder Path` فارغة.

`Glob pattern` حقل نص لفلترة الملفات باستخدام صياغة Python glob (أمثلة: `*`, `*.png`, `**/*`).

`Mode` قائمة منسدلة للتحكم باتجاه التشغيل: `Forward`, `Backward`, أو `Stop`.

`Order` قائمة منسدلة لاختيار ترتيب الملفات: `Name` (فرز أسماء الملفات طبيعياً) أو `Time` (زمن تعديل الملف).

ملاحظة: هذه عناصر واجهة مرئية تؤثر على كيفية اختيار الوحدة للملفات وإرجاعها.

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

* إدارة قائمة التشغيل: تنشئ وتخزّن قائمة بالملفات المطابقة للمجلد، نمط glob، والترتيب المحدد.
* تشغيل مرن: يدعم أوضاع الأمام، الخلف، والإيقاف مع سلوك التفاف (wrap-around).
* تجاوز المجلد أثناء التشغيل: عبر مدخل `Folder Path` دون تغيير الإعداد الافتراضي المحفوظ.
* معالجة إعادة التشغيل: مدخل `Restart` يعيد ضبط التشغيل ويعيد صورة الحافة في التقييم المطلوب.
* مخرجات بيانات الملف: يعيد المسار المطلق لتسهيل السجلات أو المعالجة اللاحقة.
* رفع إطارات غير متزامن اختياري: إذا كان متاحًا، يمكن رفع الإطارات في الخلفية للتسجيل البعيد.

## ⚙️ آلية العمل <a href="#running-mechanism" id="running-mechanism"></a>

في كل تقييــم تحدد الوحدة المجلد الفعّال (الافتراضي أو المتجاوز)، تفحص نمط glob والترتيب، وتحدّث قائمة التشغيل الداخلية عند الحاجة. تتتبّع الفهرس الحالي وتُعيد الصورة عند ذلك الفهرس مع مسار الملف وعلم `Restarted`. بعد إعادة الصورة الحالية، تجهّز الوحدة الفهرس التالي وفقًا لـ `Mode` المختار (forward/backward/stop)، مع التفاف إلى البداية أو النهاية عند الضرورة.

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

1. اضغط زر `Select folder` لاختيار مجلد افتراضي، أو اتركه فارغًا وقدّم المسار أثناء التشغيل عبر مدخل `Folder Path`.
2. أدخل `Glob pattern` لفلترة الملفات (استخدم `*` للجميع أو `*.jpg` / `**/*.png` لأنواع محددة).
3. اختر `Mode` للتقدّم، التراجع، أو تثبيت الصورة الحالية بين التقييمات.
4. اختر `Order` لفرز الملفات حسب الاسم أو وقت التعديل.
5. اختياريًا أرسل `Restart` = True لإعادة ضبط التشغيل وإرجاع صورة الحافة وفقًا لوضع `Mode`.

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

* استعرض الصور في نافذة أكبر بربط مخرج `Image` مع وحدة `Show Image` للمعاينة التفاعلية أثناء التنقّل عبر المجلد.
* احفظ الإطارات المثيرة للاهتمام باستخدام `Image Write` أو صدّر دفعات عبر `Image Logger` المتصل بمخرج `Image`.
* إذا كانت الصور كبيرة جدًا بالنسبة لوحدات الذكاء الاصطناعي اللاحقة، اربط `Image Resize` أو `Image Resizer` بعد مخرج `Image` لتقليل زمن المعالجة.
* للتركيز على منطقة محددة من كل صورة قبل التحليل، ضع `Image ROI Select` (أو `Image ROI`) بعد هذه الوحدة ومرّر النتيجة المقصوصة إلى كاشفات مثل `Find Object` أو `Mask Detection`.
* لإنشاء تقارير مرئية أو عرض مركب، اجمع إطارات متعددة مرّرها إلى `Collage Images` أو `Image Concatenate`.
* عند بناء سير عمل قائم على مجموعات بيانات، استخدم مخرج `File Path` لإنشاء سجلات أو CSV مرافقة لبيانات الصور عبر وحدات تصدير البيانات.

(hint: only combine with the listed function blocks available in the environment.)

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

* لا توجد ملفات: تأكّد أن المجلد المحدد يحتوي امتدادات صور مدعومة وأن `Glob pattern` يطابق أسماء الملفات.
* تجاوز المجلد غير صالح: تأكّد أن مدخل `Folder Path` هو نص غير فارغ ويشير إلى دليل موجود.
* ترتيب غير متوقع: استخدم `Order` = `Time` لفرز حسب طابع التعديل؛ استخدم `Name` للفرز التنبؤي بأسماء الملفات (الفرز الطبيعي يتعامل مع الأجزاء الرقمية).
* التشغيل لا يتقدّم: تحقّق من أن إعداد `Mode` ليس `Stop` وأن الوحدة تتلقى تقييمات (بعض أوضاع التشغيل تعمل فقط عند تنفيذ السيناريو).