# استخدام أدوات مجموعات البيانات يُبيّن هذا الدليل كيفية استكشاف مجموعة بيانات LeRobot، سواءً عبر الإنترنت أو محليًا، ثم يتناول الأدوات التي يوفرها LeRobot لتعديل مجموعات البيانات الموجودة وتحريرها. ## استكشاف مجموعة بيانات في المتصفح أسرع طريقة لمعرفة ما يحتويه مجموعة بيانات LeRobot هي [LeRobot Dataset Visualizer](https://huggingface.co/spaces/lerobot/visualize_dataset)، وهي مساحة على Hugging Face تشغّل أي مجموعة بيانات LeRobot على Hub دون الحاجة إلى تثبيت أي شيء. تُدفع مجموعات البيانات التي تسجّلها باستخدام `lerobot` إلى Hub ما لم تختار عدم ذلك، لذا يمكن فتح تسجيلاتك الخاصة هناك أيضًا. The LeRobot Dataset Visualizer showing episode 0 of lerobot/svla_so101_pickplace: the episode list, two synchronized camera recordings, the task, and joint charts لمحاولة ذلك على مجموعة بيانات حقيقية، افتح [الحلقة 0 من `lerobot/svla_so101_pickplace`](https://huggingface.co/spaces/lerobot/visualize_dataset?path=/lerobot/svla_so101_pickplace/episode_0)، وهي ذراع SO-101 تضع طوبة لего في صندوق، واتبع الخطوات: 1. **اختر مجموعة بيانات.** في الصفحة الرئيسية للأداة البصرية، أدخل معرف مستودع مثل `lerobot/svla_so101_pickplace`، أو اختر أحد الأمثلة. سجّل الدخول لفتح مجموعات البيانات الخاصة بك. The visualizer's home page, with a search box for a dataset repo id and example datasets 2. **اختر حلقة.** يعرض الشريط الجانبي كل حلقة، تحت إجمالي إطارات مجموعة البيانات، وعدد الحلقات، ومعدل الإطارات في الثانية. انقر على حلقة لفتحها، أو استخدم `↑` / `↓` للتنقل بينها. 3. **شاهد التسجيلات.** كل كاميرا في مجموعة البيانات تعمل بشكل متزامن. كبّر واحدة منها، أو أخفِ تلك التي لا تحتاجها. يُعرض مهمة الحلقة، أي تعليماتها اللغوية، أسفل مقاطع الفيديو. 4. **اقرأ البيانات جنبًا إلى جنب.** أسفل مقاطع الفيديو، تُرسم حالة الروبوت وأفعاله على مدى الحلقة كاملة، بخط واحد لكل مفصل. يتبع مؤشر التشغيل، وتُظهر القائمة كل قيمة في الإطار الحالي (أو تحت المؤشر أثناء التحويم). اضغط `Space` للتشغيل أو الإيقاف المؤقت، أو اسحب شريط التمرير، أو انقر على مخطط للانتقال إلى تلك اللحظة. Synchronized charts of observation.state and action for each joint, with the playback cursor and current values 5. **اذهب أبعد من ذلك.** **3D Replay** يُحرّك الروبوت من مواضع المفاصل المسجّلة (SO-100/SO-101، وOpenArm، وUnitree G1، على مجموعات بيانات v3.0). ويحتوي **Advanced** على إحصاءات المجموعة، وتصفية لتمييز الحلقاتproblematic، ومراجعات للإطار الأول/الأخير، ورؤى حول الإجراءات. الربط مباشرةً إلى حلقة باستخدام `https://huggingface.co/spaces/lerobot/visualize_dataset?path=//episode_`، على سبيل المثال لمشاركة حالة فشل مع فريقك. ## تصوير مجموعة بيانات محليًا يمكنك أيضًا عرض الحلقات من مجموعة بيانات محليًا باستخدام أداة سطر الأوامر الخاصة بنا. **من Hugging Face Hub:** ```bash lerobot-dataset-viz \ --repo-id lerobot/pusht \ --episode-index 0 ``` للمجموعة الخاصة أو المحمية، قم أولاً بالمصادقة باستخدام `hf auth login`، أو اضبط متغير البيئة `HF_TOKEN`. ثم يكتشف عميل Hub الاعتمادات تلقائياً؛ لا حاجة لحجة رمز. **من مجلد محلي:** أضف الخيار `--root` و اضبط `--mode local`. `--root` هو مجلد مجموعة البيانات نفسه. على سبيل المثال، لمجموعة بيانات مخزنة في `./my_local_data_dir/lerobot/pusht`: ```bash lerobot-dataset-viz \ --repo-id lerobot/pusht \ --root ./my_local_data_dir/lerobot/pusht \ --mode local \ --episode-index 0 ``` بمجرد التنفيذ، يفتح الأداة `rerun.io` ويعرض تدفقات الكاميرا وحالات الروبوتات والإجراءات الخاصة بالحلقة المحددة. للاستخدام [Foxglove](https://foxglove.dev) بدلاً من Rerun، ثبّت الإضافة `viz` (تتضمن `foxglove-sdk`) وأضف `--display-mode foxglove`. يبدأ هذا خادم WebSocket (اربط تطبيق Foxglove بـ `ws://127.0.0.1:8765`) الذي يقدّم الحلقة كخط زمني قابل للتنقل يمكنك تشغيله/إيقافه مؤقتاً والتنقل فيه. للاستخدام المتقدم — بما في ذلك تصور مجموعات البيانات المخزنة على خادم بعيد — قم بتشغيل: ```bash lerobot-dataset-viz --help ``` ## تعديل مجموعات البيانات توفر LeRobot عدة أدوات مساعدة للتعامل مع مجموعات البيانات: 1. **حذف الحلقات** - إزالة حلقات محددة من مجموعة البيانات 2. **تقسيم مجموعة البيانات** - تقسيم مجموعة بيانات إلى مجموعات بيانات أصغر 3. **دمج مجموعات البيانات** - دمج عدة مجموعات بيانات في مجموعة واحدة. يجب أن تكون الميزات متطابقة في جميع المجموعات، وتُربط الحلقات (episodes) بالترتيب المحدد في `repo_ids` 4. **إضافة ميزات** - إضافة ميزات جديدة إلى مجموعة بيانات 5. **إزالة الميزات** - إزالة الميزات من مجموعة البيانات 6. **تعديل المهام** - تغيير أوصاف المهام باللغة الطبيعية المرتبطة بالحلقات 7. **التحويل إلى فيديو** - تحويل مجموعات البيانات القائمة على الصور إلى صيغة فيديو لتخزين فعال (تُرمّز كاميرات RGB والعمق باستخدام مُرمّزين منفصلين) 8. **إعادة ترميز مقاطع الفيديو** - إعادة ترميز تدفقات RGB و/أو العمق لمجموعة بيانات فيديو موجودة بإعدادات مشفّرة جديدة 9. **عرض معلومات مجموعات البيانات** - عرض ملخص لمعلومات مجموعات البيانات مثل عدد الحلقات وما إلى ذلك. توجد التنفيذ الأساسي في `lerobot.datasets.dataset_tools`. يتوفر سكربت مثال يوضح كيفية استخدام واجهة برمجة التطبيقات (API) للأدوات في `examples/dataset/use_dataset_tools.py`. ## أداة سطر الأوامر: lerobot-edit-dataset `lerobot-edit-dataset` هو سطر أوامر لتحرير مجموعات البيانات. يمكن استخدامه لحذف الحلقات، وتقسيم مجموعات البيانات، ودمجها، وإزالة الميزات، وتعديل المهام، وتحويل مجموعات البيانات من الصور إلى صيغة الفيديو، وإعادة ترميز الفيديوهات، وإعادة حساب الإحصاءات، وعرض معلومات مجموعة البيانات. إضافة الميزات متاحة فقط عبر واجهة برمجة التطبيقات بلغة بايثون (`lerobot.datasets.dataset_tools`). شغّل `lerobot-edit-dataset --help` للحصول على مزيد من المعلومات حول تكوين كل عملية. ### أمثلة على الاستخدام #### حذف الحلقات إزالة حلقات محددة من مجموعة بيانات. وهذا مفيد لاستبعاد البيانات غير المرغوب فيها. ```bash # Delete episodes 0, 2, and 5 (modifies original dataset) lerobot-edit-dataset \ --repo_id lerobot/pusht \ --operation.type delete_episodes \ --operation.episode_indices "[0, 2, 5]" # Delete episodes and save to a new dataset (preserves original dataset) lerobot-edit-dataset \ --repo_id lerobot/pusht \ --new_repo_id lerobot/pusht_after_deletion \ --operation.type delete_episodes \ --operation.episode_indices "[0, 2, 5]" ``` #### تقسيم مجموعة البيانات قسّم مجموعة بيانات إلى عدة مجموعات فرعية. ```bash # Split by fractions (e.g. 60% train, 20% val, 20% test) lerobot-edit-dataset \ --repo_id lerobot/pusht \ --operation.type split \ --operation.splits '{"train": 0.6, "val": 0.2, "test": 0.2}' # Split by specific episode indices lerobot-edit-dataset \ --repo_id lerobot/pusht \ --operation.type split \ --operation.splits '{"task1": [0, 1, 2, 3], "task2": [4, 5]}' ``` لا توجد قيود على أسماء التقسيمات، إذ يمكن للمستخدم تحديدها. تُحفظ مجموعات البيانات الناتجة تحت معرّف المستودع مع إضافة اسم التقسيم، مثل `lerobot/pusht_train`، `lerobot/pusht_task1`، `lerobot/pusht_task2`. #### دمج مجموعات البيانات دمج مجموعات بيانات متعددة في مجموعة بيانات واحدة. ```bash # Merge train and validation splits back into one dataset lerobot-edit-dataset \ --new_repo_id lerobot/pusht_merged \ --operation.type merge \ --operation.repo_ids "['lerobot/pusht_train', 'lerobot/pusht_val']" ``` #### إزالة الميزات إزالة الميزات من مجموعة بيانات. ```bash # Remove a camera feature lerobot-edit-dataset \ --repo_id lerobot/pusht \ --operation.type remove_feature \ --operation.feature_names "['observation.images.top']" ``` #### تعديل المهام غيّر أوصاف المهام بلغة طبيعية المرتبطة بالحلقات. هذا مفيد لتصحيح الأخطاء الإملائية، أو توحيد الصياغة، أو إعادة تسمية الحلقات. > [!WARNING] > يعمل `modify_tasks` على تعديل مجموعة البيانات **في مكانها** (حيث يُحدَّث `meta/tasks.parquet`، وعمود `task_index` في ملفات البيانات، وعمود `tasks` في بيانات وصفية الحلقات، و`total_tasks` في `meta/info.json`). يتم تجاهل المعاملين `--new_repo_id` و`--new_root` في هذه العملية. ```bash # Set a single task for all episodes lerobot-edit-dataset \ --repo_id lerobot/pusht \ --operation.type modify_tasks \ --operation.new_task "Pick up the cube and place it" # Set different tasks for specific episodes lerobot-edit-dataset \ --repo_id lerobot/pusht \ --operation.type modify_tasks \ --operation.episode_tasks '{"0": "Task A", "1": "Task B", "2": "Task A"}' # Replace existing task strings wherever they appear lerobot-edit-dataset \ --repo_id lerobot/pusht \ --operation.type modify_tasks \ --operation.task_replacements '{"Pick up the red cube": "Lift the red cube"}' # Combine modes in a single run lerobot-edit-dataset \ --repo_id lerobot/pusht \ --operation.type modify_tasks \ --operation.new_task "Default task" \ --operation.task_replacements '{"Pick up the red cube": "Lift the red cube"}' \ --operation.episode_tasks '{"5": "Special task for episode 5"}' ``` **المعاملات:** - `new_task`: سلسلة مهام واحدة تُستخدم كقيمة افتراضية للحلقات غير المشمولة بشكل آخر. - `episode_tasks`: تعيين من فهرس الحلقة إلى سلسلة المهمة. - `task_replacements`: تعيين من نصوص المهام الموجودة إلى بدائلها، يُطبَّق على الحلقات التي تتطابق مهمتها الحالية مع مفتاح. يجب أن يكون كل مفتاح مهمة موجودة في مجموعة البيانات. يمكن دمج الأوضاع في تشغيل واحد. في كل حلقة، يتم حل المهمة وفق الأولوية التالية: `episode_tasks` > `task_replacements` > `new_task` > المهمة الأصلية يجب تحديد واحد على الأقل من `new_task` أو `episode_tasks` أو `task_replacements`. يثير أي حلقة تنتهي دون مهمة خطأ. #### التحويل إلى فيديو تحويل مجموعة بيانات مبنية على الصور إلى صيغة فيديو، مع إنشاء مجموعة بيانات LeRobotDataset جديدة تُخزَّن فيها الصور على شكل مقاطع فيديو. وهذا مفيد لتقليل متطلبات التخزين وتحسين أداء تحميل البيانات. ستحتفظ المجموعة الجديدة بالبنية نفسها تمامًا كما في الأصل، لكن مع ترميز الصور كمقاطع فيديو بصيغة MP4 في صيغة LeRobot المناسبة. ```bash # Local-only: Save to a custom output directory (no hub push) lerobot-edit-dataset \ --repo_id lerobot/pusht_image \ --operation.type convert_image_to_video \ --operation.output_dir /path/to/output/pusht_video # Save with new repo_id (local storage) lerobot-edit-dataset \ --repo_id lerobot/pusht_image \ --new_repo_id lerobot/pusht_video \ --operation.type convert_image_to_video # Convert and push to Hugging Face Hub lerobot-edit-dataset \ --repo_id lerobot/pusht_image \ --new_repo_id lerobot/pusht_video \ --operation.type convert_image_to_video \ --push_to_hub true # Convert with custom video codec and quality settings lerobot-edit-dataset \ --repo_id lerobot/pusht_image \ --operation.type convert_image_to_video \ --operation.output_dir outputs/pusht_video \ --operation.rgb_encoder.vcodec libsvtav1 \ --operation.rgb_encoder.pix_fmt yuv420p \ --operation.rgb_encoder.g 2 \ --operation.rgb_encoder.crf 30 # Convert a dataset that includes depth maps, customizing the depth encoder lerobot-edit-dataset \ --repo_id lerobot/pusht_image \ --operation.type convert_image_to_video \ --operation.output_dir outputs/pusht_video \ --operation.depth_encoder.depth_min 0.01 \ --operation.depth_encoder.depth_max 10.0 \ --operation.depth_encoder.use_log true # Convert only specific episodes lerobot-edit-dataset \ --repo_id lerobot/pusht_image \ --operation.type convert_image_to_video \ --operation.output_dir outputs/pusht_video \ --operation.episode_indices "[0, 1, 2, 5, 10]" # Convert with multiple workers for parallel processing lerobot-edit-dataset \ --repo_id lerobot/pusht_image \ --operation.type convert_image_to_video \ --operation.output_dir outputs/pusht_video \ --operation.num_workers 8 # For memory-constrained systems, users can now specify limits: lerobot-edit-dataset \ --repo_id lerobot/pusht_image \ --operation.type convert_image_to_video \ --operation.max_episodes_per_batch 50 \ --operation.max_frames_per_batch 10000 ``` **المعاملات:** - `output_dir`: مخرج مخصص (اختياري - يستخدم افتراضيًا `new_repo_id` أو `{repo_id}_video`) - `rgb_encoder`: إعدادات مُشفِّر الفيديو المطبّقة على كاميرات RGB — جميع الحقول الفرعية قابلة للوصول عبر `--operation.rgb_encoder.`. راجع [معلمات ترميز الفيديو](./video_encoding_parameters) لمزيد من التفاصيل. - `depth_encoder`: إعدادات مُشفِّر الفيديو المطبَّقة على كاميرات خرائط العمق (مثل تلك القادمة من Intel RealSense). بالإضافة إلى حقول المُشفِّر القياسية، يكشف عن مقابض تكميم العمق (`depth_min`، `depth_max`، `shift`، `use_log`)، ويمكن الوصول إليها عبر `--operation.depth_encoder.`. يتم حفظ إعدادات التكميم هذه في بيانات وصفية مجموعة البيانات بحيث يمكن عكس تكميم العمق إلى وحدات فيزيائية عند التحميل. راجع قسم [تدفقات العمق](./video_encoding_parameters#depth-streams) للتفاصيل. - `episode_indices`: قائمة بالحلقات المحددة للتحويل (الافتراضي: جميع الحلقات) - `num_workers`: عدد العمال المتوازيين للمعالجة (الافتراضي: 4) **ملاحظة:** ستكون مجموعة البيانات الناتجة مجموعة بيانات LeRobotDataset صحيحة، حيث تُرمَّز جميع الكاميرات كفيديوهات في المجلد `videos/`، مع ملفات parquet تحتوي على البيانات الوصفية فقط (بدون بيانات صور خام). يتم اكتشاف كاميرات خرائط العمق تلقائيًا وتوجيهها إلى `depth_encoder`، بينما تستخدم كاميرات RGB المُرمِّز `rgb_encoder`. يتم الحفاظ على جميع الحلقات والإحصاءات والمهام. #### إعادة ترميز مقاطع الفيديو أعد ترميز مقاطع فيديو مجموعة بيانات فيديو موجودة باستخدام إعدادات مُرمِّز مختلفة، دون الحاجة إلى الرجوع إلى الإطارات الخام. تستخدم مقاطع الفيديو RGB المُرمِّز `rgb_encoder` بينما تستخدم مقاطع الفيديو العمق المُرمِّز `depth_encoder`. على سطر الأوامر، يكون لكل مُرمِّضين دائمًا إعدادات (الإعدادات الافتراضية، ما لم تُغيّرها)، لذا فإن نوع التدفق الذي لا تُهيّئه يُعاد ترميزه بالإعدادات الافتراضية ما لم يكن يستخدمها بالفعل. ```bash # Re-encode all RGB videos with new settings (saves to lerobot/pusht_reencoded by default) lerobot-edit-dataset \ --repo_id lerobot/pusht \ --operation.type reencode_videos \ --operation.rgb_encoder.vcodec h264 \ --operation.rgb_encoder.pix_fmt yuv420p \ --operation.rgb_encoder.crf 23 # Re-encode both RGB and depth videos in a dataset with depth maps lerobot-edit-dataset \ --repo_id lerobot/pusht_depth \ --operation.type reencode_videos \ --operation.rgb_encoder.vcodec h264 \ --operation.depth_encoder.crf 50 ``` **المعاملات:** - `rgb_encoder`: إعدادات المُشفِّر المطبَّقة على كل فيديو RGB. - `depth_encoder`: إعدادات المُشفِّر المطبَّقة على كل فيديو عمق. لإعادة ترميز نوع تدفق واحد فقط وترك الآخر دون تغيير، استخدم واجهة برمجة التطبيقات بلغة بايثون وقم بتمرير `None` للمرمّز الآخر، على سبيل المثال `reencode_dataset(dataset, rgb_encoder=..., depth_encoder=None)`. - `num_workers`: عدد العمال المتوازيين للمعالجة. > [!NOTE] > عند إعادة ترميز مقاطع فيديو العمق، تُحفظ **معاملات تكميم العمق** الموجودة مسبقًا (`depth_min`، `depth_max`، `shift`، `use_log`) وعلامة `is_depth_map` — إذ لا تغيّر عملية إعادة الترميز سوى مُرمّز/جودة البث المخزّن، دون التأثير على كيفية إلغاء تكميم العمق عند التحميل. ### عرض معلومات مجموعات البيانات عرض معلومات مجموعات البيانات مثل عدد الحلقات وعدد الإطارات وحجم الملف وما إلى ذلك. لن يتم إجراء أي تغيير على مجموعة البيانات ```bash # Show dataset information without feature details lerobot-edit-dataset \ --repo_id lerobot/pusht_image \ --operation.type info # Show dataset information with feature details lerobot-edit-dataset \ --repo_id lerobot/pusht_image \ --operation.type info \ --operation.show_features true ``` **المعاملات:** - `show_features`: ما إذا كان يجب عرض تفاصيل الميزات أيضًا (الافتراضي: `false`). ### الرفع إلى المستودع أضِف علم `--push_to_hub true` إلى أي أمر لرفع مجموعة البيانات الناتجة تلقائيًا إلى Hugging Face Hub: ```bash lerobot-edit-dataset \ --repo_id lerobot/pusht \ --new_repo_id lerobot/pusht_after_deletion \ --operation.type delete_episodes \ --operation.episode_indices "[0, 2, 5]" \ --push_to_hub true ``` يوجد أيضاً أداة لإضافة ميزات إلى مجموعة بيانات لم تغطَّ بعد في `lerobot-edit-dataset`.