استخدام أدوات مجموعات البيانات

يُبيّن هذا الدليل كيفية استكشاف مجموعة بيانات LeRobot، سواءً عبر الإنترنت أو محليًا، ثم يتناول الأدوات التي يوفرها LeRobot لتعديل مجموعات البيانات الموجودة وتحريرها.

استكشاف مجموعة بيانات في المتصفح

أسرع طريقة لمعرفة ما يحتويه مجموعة بيانات LeRobot هي LeRobot Dataset Visualizer، وهي مساحة على Hugging Face تشغّل أي مجموعة بيانات LeRobot على Hub دون الحاجة إلى تثبيت أي شيء. تُدفع مجموعات البيانات التي تسجّلها باستخدام lerobot إلى Hub ما لم تختار عدم ذلك، لذا يمكن فتح تسجيلاتك الخاصة هناك أيضًا.

لمحاولة ذلك على مجموعة بيانات حقيقية، افتح الحلقة 0 من lerobot/svla_so101_pickplace، وهي ذراع SO-101 تضع طوبة لего في صندوق، واتبع الخطوات:

1. اختر مجموعة بيانات. في الصفحة الرئيسية للأداة البصرية، أدخل معرف مستودع مثل lerobot/svla_so101_pickplace، أو اختر أحد الأمثلة. سجّل الدخول لفتح مجموعات البيانات الخاصة بك.

   

2. اختر حلقة. يعرض الشريط الجانبي كل حلقة، تحت إجمالي إطارات مجموعة البيانات، وعدد الحلقات، ومعدل الإطارات في الثانية. انقر على حلقة لفتحها، أو استخدم ↑ / ↓ للتنقل بينها.

3. شاهد التسجيلات. كل كاميرا في مجموعة البيانات تعمل بشكل متزامن. كبّر واحدة منها، أو أخفِ تلك التي لا تحتاجها. يُعرض مهمة الحلقة، أي تعليماتها اللغوية، أسفل مقاطع الفيديو.

4. اقرأ البيانات جنبًا إلى جنب. أسفل مقاطع الفيديو، تُرسم حالة الروبوت وأفعاله على مدى الحلقة كاملة، بخط واحد لكل مفصل. يتبع مؤشر التشغيل، وتُظهر القائمة كل قيمة في الإطار الحالي (أو تحت المؤشر أثناء التحويم). اضغط Space للتشغيل أو الإيقاف المؤقت، أو اسحب شريط التمرير، أو انقر على مخطط للانتقال إلى تلك اللحظة.

   

5. اذهب أبعد من ذلك. 3D Replay يُحرّك الروبوت من مواضع المفاصل المسجّلة (SO-100/SO-101، وOpenArm، وUnitree G1، على مجموعات بيانات v3.0). ويحتوي Advanced على إحصاءات المجموعة، وتصفية لتمييز الحلقاتproblematic، ومراجعات للإطار الأول/الأخير، ورؤى حول الإجراءات.

الربط مباشرةً إلى حلقة باستخدام https://huggingface.co/spaces/lerobot/visualize_dataset?path=/<repo_id>/episode_<index>، على سبيل المثال لمشاركة حالة فشل مع فريقك.

تصوير مجموعة بيانات محليًا

يمكنك أيضًا عرض الحلقات من مجموعة بيانات محليًا باستخدام أداة سطر الأوامر الخاصة بنا.

من Hugging Face Hub:

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:

lerobot-dataset-viz \
    --repo-id lerobot/pusht \
    --root ./my_local_data_dir/lerobot/pusht \
    --mode local \
    --episode-index 0

بمجرد التنفيذ، يفتح الأداة rerun.io ويعرض تدفقات الكاميرا وحالات الروبوتات والإجراءات الخاصة بالحلقة المحددة.

للاستخدام Foxglove بدلاً من Rerun، ثبّت الإضافة viz (تتضمن foxglove-sdk) وأضف --display-mode foxglove. يبدأ هذا خادم WebSocket (اربط تطبيق Foxglove بـ ws://127.0.0.1:8765) الذي يقدّم الحلقة كخط زمني قابل للتنقل يمكنك تشغيله/إيقافه مؤقتاً والتنقل فيه.

للاستخدام المتقدم — بما في ذلك تصور مجموعات البيانات المخزنة على خادم بعيد — قم بتشغيل:

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 للحصول على مزيد من المعلومات حول تكوين كل عملية.

أمثلة على الاستخدام

حذف الحلقات

إزالة حلقات محددة من مجموعة بيانات. وهذا مفيد لاستبعاد البيانات غير المرغوب فيها.

# 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]"

تقسيم مجموعة البيانات

قسّم مجموعة بيانات إلى عدة مجموعات فرعية.

# 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.

دمج مجموعات البيانات

دمج مجموعات بيانات متعددة في مجموعة بيانات واحدة.

# 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']"

إزالة الميزات

إزالة الميزات من مجموعة بيانات.

# Remove a camera feature
lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --operation.type remove_feature \
    --operation.feature_names "['observation.images.top']"

تعديل المهام

غيّر أوصاف المهام بلغة طبيعية المرتبطة بالحلقات. هذا مفيد لتصحيح الأخطاء الإملائية، أو توحيد الصياغة، أو إعادة تسمية الحلقات.

يعمل modify_tasks على تعديل مجموعة البيانات في مكانها (حيث يُحدَّث meta/tasks.parquet، وعمود task_index في ملفات البيانات، وعمود tasks في بيانات وصفية الحلقات، وtotal_tasks في meta/info.json). يتم تجاهل المعاملين --new_repo_id و--new_root في هذه العملية.

# 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 المناسبة.

# 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.<field>. راجع معلمات ترميز الفيديو لمزيد من التفاصيل.
• depth_encoder: إعدادات مُشفِّر الفيديو المطبَّقة على كاميرات خرائط العمق (مثل تلك القادمة من Intel RealSense). بالإضافة إلى حقول المُشفِّر القياسية، يكشف عن مقابض تكميم العمق (depth_min، depth_max، shift، use_log)، ويمكن الوصول إليها عبر --operation.depth_encoder.<field>. يتم حفظ إعدادات التكميم هذه في بيانات وصفية مجموعة البيانات بحيث يمكن عكس تكميم العمق إلى وحدات فيزيائية عند التحميل. راجع قسم تدفقات العمق للتفاصيل.
• episode_indices: قائمة بالحلقات المحددة للتحويل (الافتراضي: جميع الحلقات)
• num_workers: عدد العمال المتوازيين للمعالجة (الافتراضي: 4)

ملاحظة: ستكون مجموعة البيانات الناتجة مجموعة بيانات LeRobotDataset صحيحة، حيث تُرمَّز جميع الكاميرات كفيديوهات في المجلد videos/، مع ملفات parquet تحتوي على البيانات الوصفية فقط (بدون بيانات صور خام). يتم اكتشاف كاميرات خرائط العمق تلقائيًا وتوجيهها إلى depth_encoder، بينما تستخدم كاميرات RGB المُرمِّز rgb_encoder. يتم الحفاظ على جميع الحلقات والإحصاءات والمهام.

إعادة ترميز مقاطع الفيديو

أعد ترميز مقاطع فيديو مجموعة بيانات فيديو موجودة باستخدام إعدادات مُرمِّز مختلفة، دون الحاجة إلى الرجوع إلى الإطارات الخام. تستخدم مقاطع الفيديو RGB المُرمِّز rgb_encoder بينما تستخدم مقاطع الفيديو العمق المُرمِّز depth_encoder. على سطر الأوامر، يكون لكل مُرمِّضين دائمًا إعدادات (الإعدادات الافتراضية، ما لم تُغيّرها)، لذا فإن نوع التدفق الذي لا تُهيّئه يُعاد ترميزه بالإعدادات الافتراضية ما لم يكن يستخدمها بالفعل.

# 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: عدد العمال المتوازيين للمعالجة.

عند إعادة ترميز مقاطع فيديو العمق، تُحفظ معاملات تكميم العمق الموجودة مسبقًا (depth_min، depth_max، shift، use_log) وعلامة is_depth_map — إذ لا تغيّر عملية إعادة الترميز سوى مُرمّز/جودة البث المخزّن، دون التأثير على كيفية إلغاء تكميم العمق عند التحميل.

عرض معلومات مجموعات البيانات

عرض معلومات مجموعات البيانات مثل عدد الحلقات وعدد الإطارات وحجم الملف وما إلى ذلك. لن يتم إجراء أي تغيير على مجموعة البيانات

# 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:

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.