معلمات ترميز الفيديو

عند تمكين تخزين الفيديو، يخزّن LeRobot كل تدفق كاميرا كملف MP4 بدلاً من حفظ ملف صورة واحد لكل خطوة زمنية. يعمل ترميز الفيديو على الضغط عبر الزمن، مما يقلل عادةً من حجم مجموعة البيانات ومدخلات/مخرجات الإدخال/الإخراج مقارنةً بكمية كبيرة من ملفات PNG، مع الحفاظ على MP4 — وهو صيغة تفهمها كل مشغّل وكل محمّل.

تحويل الإطارات إلى ملف MP4 هو خط أنابيب كامل لـ FFmpeg: اختيار المُشفِّر، وصيغة البكسل، ومجموعات GOP/الإطارات المفتاحية، والجودة مقابل السرعة، وأعلام المُشفِّر الإضافية الاختيارية. معظم هذه الإعدادات قابلة للضبط من قِبل المستخدم عبر rgb_encoder، وهو RGBEncoderConfig متداخل (lerobot.configs.video.RGBEncoderConfig) يُمرَّر عبر PyAV.

يمكنك ضبط هذه المعلمات من سطر الأوامر باستخدام --dataset.rgb_encoder.<field> (على سبيل المثال باستخدام lerobot-record أو lerobot-rollout). ينطبق نفس الكتلة على كل تدفق فيديو كاميرا في تلك الجولة.

يجب أن يكون تخزين الفيديو مفعّلًا حتى يكون لـ rgb_encoder أي تأثير — وذلك عبر use_videos=True في واجهات برمجة التطبيقات بلغة بايثون، أو عبر --dataset.video=true في سطر الأوامر (وهو الافتراضي عند التسجيل). عند إيقاف الفيديو، تبقى المدخلات على شكل صور ويُتجاهل rgb_encoder.

لتفاصيل متى تُكتب الإطارات مقابل ترميزها (بث مباشر مقابل ما بعد الحلقة)، والطوابير، ومفاتيح --dataset.* الأخرى على المستوى الأعلى، راجع ترميز الفيديو البثي. لمقارنة معاملات الترميز والتجارب، راجع مساحة video-benchmark.

مثال

lerobot-record \
    --robot.type=so100_follower \
    --robot.port=/dev/tty.usbmodem58760431541 \
    --robot.cameras="{laptop: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}}" \
    --robot.id=black \
    --teleop.type=so100_leader \
    --teleop.port=/dev/tty.usbmodem58760431551 \
    --teleop.id=blue \
    --dataset.repo_id=<my_username>/<my_dataset_name> \
    --dataset.num_episodes=2 \
    --dataset.single_task="Grab the cube" \
    --dataset.streaming_encoding=true \
    --dataset.encoder_threads=2 \
    --dataset.rgb_encoder.vcodec=h264 \
    --dataset.rgb_encoder.preset=fast \
    --dataset.rgb_encoder.extra_options='{"tune": "film", "profile:v": "high", "bf": 2}' \
    --display_data=true

ضبط المعلمات

تم ضبط القيم الافتراضية لتحقيق التوازن بين نسبة الضغط والجودة البصرية وسرعة فك الترميز/البحث لمجموعات بيانات الروبوتات النموذجية. قد يؤثر تغييرها على كل من التسجيل (حمولة المعالج المركزي، فقدان الإطارات) والتدريب (معدل فك الترميز، جودة الصور).

لا تتجاوز هذه المعلمات إلا إذا كان لديك سبب محدد لذلك، وقِس الأثر على خط أنابيبك قبل الاعتماد على الإعدادات الجديدة.

جميع الأعلام أدناه مُسبوقة بـ --dataset.rgb_encoder. في سطر الأوامر.

تيارات العمق

تُخزَّن خرائط العمق (Intel RealSense، Reachy 2) كـ تدفقات فيديو مستقلة إلى جانب تدفقات RGB. لا يمكن للبيانات الخام للعمق (uint16 بالمليمتر أو float32 بالمتر) أن تنجو عبر مشفر 8-بت، لذا يقوم LeRobot بتكميم كل خريطة إلى رمز 12-بت ([0, 4095]) — بشكل لوغاريتمي افتراضيًا، لمطابقة ملف خطأ 1/depth الخاص بمستشعرات العمق — ثم يعبّئها في تنسيق بكسل عالي العمق البتي (gray12le) ويشفّرها بمشفر 12-بت.

قم بإعداد خط أنابيب العمق عبر كتلة depth_encoder متوازية (DepthEncoderConfig). تشارك جميع حقول RGBEncoderConfig (vcodec، pix_fmt، crf، …) وتضيف أربعة مقابض كمّية، تُضبط عبر --dataset.depth_encoder.<field>:

lerobot-record \
    ... \
    --dataset.depth_encoder.vcodec=hevc \
    --dataset.depth_encoder.depth_min=0.05 \
    --dataset.depth_encoder.depth_max=5.0 \
    --dataset.depth_encoder.use_log=true

يُفسَّر depth_min وdepth_max وshift دائمًا بوحدة المتر، بغض النظر عن وحدة عمق الإدخال. يتم اكتشاف المدخلات تلقائيًا: تُعامل المصفوفات الصحيحة (مثل uint16 بالمليمتر مباشرة من RealSense) كمليمتر، والمصفوفات العائمة كمتر. اختر depth_min / depth_max بحيث يحصران النطاق الفعلي للعمل لحساسك — فالقيم خارج ذلك النطاق تصل إلى حد التشبع، مما قد يُفقد التفاصيل عند الحدود.

تُوسم ميزات العمق بـ "is_depth_map": true في meta/info.json، وتُحفظ إعدادات مُكمِّمها (video.depth_min، video.depth_max، video.shift، video.use_log) — وهذا ما يتيح إلغاء تكميم العمق وإعادته إلى الوحدات الفيزيائية عند التحميل.

وحدة الإخراج عند التحميل

depth_encoder هو أمر يتعلق بـ وقت التسجيل. الوحدة التي تُفكَّ كمّية خرائط العمق إليها عند التحميل (مثلًا أثناء التدريب) تُضبط بشكل منفصل بواسطة علم وقت القراءة --dataset.depth_output_unit:

lerobot-train \
    --dataset.repo_id=<my_username>/<my_dataset_name> \
    --dataset.depth_output_unit=m \
    --policy.type=act

هذا خيار عرض وقت فك الترميز بحت — فهو لا يُغيّر الفيديو المخزّن أو بياناته الوصفية، لذا يمكن قراءة نفس مجموعة البيانات كـmm أو m دون إعادة ترميز. ولا يؤثر على مجموعات البيانات التي لا تحتوي على كاميرات عمق.

الاستمرارية في بيانات وصفية مجموعة البيانات

بعد ترميز الحلقة الأولى من بث الفيديو، يتم حفظ إعدادات المُرمِّز في بيانات وصفية مجموعة البيانات (في meta/info.json) تحت كل ميزة فيديو، إلى جانب القيم المستخرجة من الملف نفسه. لميزة فيديو observation.images.<camera>، يكون الترتيب في info.json كالتالي:

{
  "features": {
    "observation.images.laptop": {
      "dtype": "video",
      "shape": [480, 640, 3],
      "info": {
        "video.height": 480,
        "video.width": 640,
        "video.codec": "h264",
        "video.pix_fmt": "yuv420p",
        "video.fps": 30,
        "video.channels": 3,
        "is_depth_map": false,
        "video.g": 2,
        "video.crf": 30,
        "video.preset": "fast",
        "video.fast_decode": 0,
        "video.video_backend": "pyav",
        "video.extra_options": { "tune": "film", "profile:v": "high", "bf": 2 }
      }
    }
  }
}

تساهم مصدران في كتلة info:

يتم ملء هذا الكتل مرة واحدة، من أول حلقة. يفترض أن كل حلقة في مجموعة البيانات قد تم ترميزها باستخدام rgb_encoder نفسه. لا يتم دعم تغيير إعدادات المرمّز أثناء التسجيل — فملف info.json لن يعكس سوى المعلمات المستخدمة للحلقة الأولى.

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

عند تجميع مجموعات البيانات باستخدام merge_datasets، يتم دمج ملفات الفيديو كما هي (بدون إعادة ترميز)، وتُدمج حقول المُرمِّز في info.json لكل مفتاح: