Add compressed depth sidecar video for LeRobot datasets - #434
Merged
Conversation
Add an EmbodiChain-owned depth writer that stores camera depth as gray12le/HEVC sidecar videos alongside LeRobot datasets on Python 3.10/3.11 with lerobot 0.4.4 (issue DexForce#424 Path A), without requiring the Python 3.12 / lerobot 0.6.0 upgrade. Depth quantization math is vendored from lerobot v0.6.0 (no py3.12-only syntax); sidecar schema is aligned with the official 0.6.0 reader for a future seamless migration (issue DexForce#424 Path B). - data_pipeline/depth_video: depth_utils (quantize/dequantize), codec detection, DepthVideoWriter + DepthSidecarManager (per-episode gray12le/libx265 lossless or CRF MP4s + depth_meta.json), DepthVideoReader + load_depth_dataset (decode + dequantize to m/mm). - LeRobotRecorder: depth_video cfg; offload depth to sidecar and drop it from lerobot's RGB-only pipeline; keep mask numeric; auto-fallback to numeric depth (PR DexForce#422) when no HEVC encoder is available. - libx265 bframes=0 to make the encoder flush deterministic for short episodes (default B-frame/lookahead buffering races on 1-3 frame videos). - Tests (35) + docs + benchmark script comparing storage size. Co-Authored-By: Claude <noreply@anthropic.com>
yuecideng
added
enhancement
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This PR implements issue #424 Path A: an EmbodiChain-owned depth writer that stores camera depth as compressed
gray12le/HEVC sidecar videos alongside LeRobot datasets, on Python 3.10/3.11 with lerobot 0.4.4 — without the Python 3.12 / lerobot 0.6.0 upgrade.Built on top of the merged PR #422 (numeric depth/mask features). Depth quantization math is vendored from lerobot v0.6.0 (
depth_utils.py), which has no py3.12-only syntax —requires-python>=3.12is a project policy, not a technical barrier of the depth code. The sidecar metadata schema is aligned with the official 0.6.0 reader for a seamless future migration (Path B).What's added
embodichain/data_pipeline/depth_video/—depth_utils(quantize/dequantize, vendored),codec(libx265/hevc detection),DepthVideoWriter+DepthSidecarManager(per-episodegray12le/libx265 lossless-or-CRF MP4s +depth_meta.json),DepthVideoReader+load_depth_dataset(decode + dequantize to m/mm).LeRobotRecorder—depth_videoconfig; when enabled, depth is offloaded to the sidecar writer and dropped from lerobot's RGB-only image/video pipeline. Mask stays numeric. Auto-fallback to numeric depth (feat(dataset): preserve depth and mask camera frames #422) when no HEVC encoder is available. Works for both sync and async recorders.scripts/benchmark/data_pipeline/benchmark_depth_size.py).Storage size (benchmark, 480x640 x 100 frames @ 30fps)
Lossless sidecar is ~6x smaller than the numeric float32 Parquet from #422, and the 12-bit codes survive the encode/decode round-trip bit-exactly (verified; max error 0.6 mm over 0.1-3.0 m).
Key technical note
libx265's default B-frame/lookahead buffering races on the flush of 1-3 frame videos (
PatchWelcomeError). Settingbframes=0makes the flush deterministic (0/24 failures after the fix vs 7/24 before).Dependencies: none new (uses already-installed
av/pyav, numpy, torch).Fixes #424
Type of change
Non-breaking:
depth_videodefaults toenable=False, so existing recordings are unchanged.Screenshots
Not applicable; affects structured dataset output.
Checklist
black .command to format the code base.av/numpy/torch.)🤖 Generated with Claude Code