feat: data quality check via episode boundary frame export (#13)

* feat: add episode boundary frame export script

* feat: add boundary frame export hints after recording and in dataset report

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: print scp hint when running in SSH session

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: address review findings — deduplicate utils, fix CHW handling, fix --json output

- Replace duplicated resolve_dataset_root/load_info/HF_LEROBOT_HOME with imports from existing modules
- Replace custom tensor_to_pil_image with torchvision.transforms.functional.to_pil_image
- Fix select_camera_key to use names field for CHW/HWC shape disambiguation
- Move dataset report tip inside text-only branch to preserve --json output
- Move prepare_output_dir after dataset construction to avoid premature deletion
- Fix resolve_repo_id to always derive from resolved dataset_root
- Remove unnecessary scripts/__init__.py
- Fix episode spec display in README.txt for non-contiguous selections
- Use episodes.column_names for column containment check

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: shuyuan <shuyuan@shuyuandeMac-mini.local>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
这个提交包含在:
Shuyuan
2026-04-01 19:12:21 +08:00
提交者 GitHub
父节点 7e4e6701d7
当前提交 80fa8bf47a
共有 5 个文件被更改,包括 406 次插入 和 0 次删除

查看文件

@ -216,6 +216,7 @@ lerobot-human-inloop-record="lerobot.scripts.lerobot_human_inloop_record:main"
lerobot-value-train="lerobot.scripts.lerobot_value_train:main"
lerobot-value-infer="lerobot.scripts.lerobot_value_infer:main"
lerobot-dataset-report="lerobot.scripts.lerobot_dataset_report:main"
lerobot-export-boundary-frames="lerobot.scripts.lerobot_export_boundary_frames:main"
# ---------------- Tool Configurations ----------------
[tool.setuptools.packages.find]

查看文件

@ -350,6 +350,10 @@ def main():
print(json.dumps(report, indent=2, ensure_ascii=False))
else:
print(format_text_report(report))
print(
"\nTip: To visually inspect episode boundaries, run:\n"
f" lerobot-export-boundary-frames --dataset {args.dataset} --episodes all --output-dir <output_dir>"
)
if __name__ == "__main__":

查看文件

@ -0,0 +1,319 @@
#!/usr/bin/env python
# Copyright 2026 The HuggingFace Inc. team. All rights reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""
Export the first and last frame of selected episodes from a LeRobot dataset.
Examples:
```bash
lerobot-export-boundary-frames \
--dataset ~/.cache/huggingface/lerobot/javadcc/evorl_0 \
--episodes 0-99 \
--camera-key observation.images.right_front \
--output-dir outputs/evorl_0_right_front_first_last_ep000_099
```
```bash
lerobot-export-boundary-frames \
--dataset local/my_dataset \
--episodes all \
--output-dir outputs/my_dataset_boundaries
```
"""
from __future__ import annotations
import argparse
import csv
import os
import shutil
from pathlib import Path
from typing import TYPE_CHECKING, Any
from torchvision.transforms.functional import to_pil_image
from lerobot.datasets.utils import load_info
from lerobot.scripts.lerobot_dataset_report import resolve_dataset_root
from lerobot.utils.constants import HF_LEROBOT_HOME
if TYPE_CHECKING:
from lerobot.datasets.lerobot_dataset import LeRobotDataset
def resolve_repo_id(dataset_root: Path, root: Path | None) -> str:
base_root = root.expanduser().resolve() if root is not None else HF_LEROBOT_HOME.resolve()
if dataset_root.is_relative_to(base_root):
return dataset_root.relative_to(base_root).as_posix()
return f"local/{dataset_root.name}"
def get_camera_keys(info: dict) -> list[str]:
features = info.get("features", {})
return [
key
for key, value in sorted(features.items())
if key.startswith("observation.images.") and value.get("dtype") in {"image", "video"}
]
def _get_pixel_count(feature: dict) -> int:
shape = feature.get("shape", (0, 0, 0))
names = feature.get("names", [])
if names:
name_list = list(names)
h_idx = name_list.index("height") if "height" in name_list else None
w_idx = name_list.index("width") if "width" in name_list else None
if h_idx is not None and w_idx is not None:
return int(shape[h_idx]) * int(shape[w_idx])
# Fallback: assume HWC if no names
return int(shape[0]) * int(shape[1]) if len(shape) >= 2 else 0
def select_camera_key(info: dict, camera_key: str | None) -> str:
camera_keys = get_camera_keys(info)
if not camera_keys:
raise ValueError("Dataset does not contain any image or video observation keys.")
if camera_key is not None:
if camera_key not in camera_keys:
available = "\n".join(f"- {key}" for key in camera_keys)
raise ValueError(f"Unknown camera key: {camera_key}\nAvailable cameras:\n{available}")
return camera_key
features = info["features"]
def sort_key(key: str) -> tuple[int, int, str]:
is_front = 0 if "front" in key else 1
pixel_count = _get_pixel_count(features[key])
return (is_front, -pixel_count, key)
return sorted(camera_keys, key=sort_key)[0]
def parse_episode_indices(spec: str, total_episodes: int) -> list[int]:
cleaned = spec.strip().lower()
if total_episodes <= 0:
raise ValueError("Dataset has no episodes to export.")
if cleaned == "all":
return list(range(total_episodes))
episode_indices: list[int] = []
seen: set[int] = set()
for chunk in spec.split(","):
part = chunk.strip()
if not part:
continue
if "-" in part:
start_str, end_str = part.split("-", maxsplit=1)
start = int(start_str)
end = int(end_str)
if end < start:
raise ValueError(f"Invalid episode range: {part}")
values = range(start, end + 1)
else:
values = [int(part)]
for episode_index in values:
if episode_index < 0 or episode_index >= total_episodes:
raise ValueError(
f"Episode index {episode_index} is out of range for dataset with {total_episodes} episodes."
)
if episode_index not in seen:
episode_indices.append(episode_index)
seen.add(episode_index)
if not episode_indices:
raise ValueError("No episodes were selected.")
return episode_indices
def prepare_output_dir(output_dir: Path, overwrite: bool) -> None:
if output_dir.exists() and overwrite:
shutil.rmtree(output_dir)
if output_dir.exists() and any(output_dir.iterdir()):
raise FileExistsError(f"Output directory already exists and is not empty: {output_dir}")
output_dir.mkdir(parents=True, exist_ok=True)
def _format_episode_spec(episode_indices: list[int]) -> str:
if not episode_indices:
return ""
groups: list[str] = []
start = episode_indices[0]
prev = start
for idx in episode_indices[1:]:
if idx == prev + 1:
prev = idx
else:
groups.append(str(start) if start == prev else f"{start}-{prev}")
start = idx
prev = idx
groups.append(str(start) if start == prev else f"{start}-{prev}")
return ",".join(groups)
def export_episode_boundary_frames(
dataset: "LeRobotDataset",
output_dir: Path,
episode_indices: list[int],
camera_key: str,
) -> Path:
pad_width = max(3, len(str(max(episode_indices))))
episodes = dataset.meta.episodes
manifest_rows: list[dict[str, Any]] = []
for episode_index in episode_indices:
from_idx = int(episodes["dataset_from_index"][episode_index])
to_idx = int(episodes["dataset_to_index"][episode_index])
length = int(episodes["length"][episode_index])
success = str(episodes["episode_success"][episode_index]) if "episode_success" in episodes.column_names else ""
first_name = f"episode_{episode_index:0{pad_width}d}_first.png"
last_name = f"episode_{episode_index:0{pad_width}d}_last.png"
to_pil_image(dataset[from_idx][camera_key]).save(output_dir / first_name)
to_pil_image(dataset[to_idx - 1][camera_key]).save(output_dir / last_name)
manifest_rows.append(
{
"episode_index": episode_index,
"length": length,
"episode_success": success,
"first_dataset_index": from_idx,
"last_dataset_index": to_idx - 1,
"first_file": first_name,
"last_file": last_name,
}
)
manifest_path = output_dir / "manifest.csv"
with manifest_path.open("w", newline="") as f:
writer = csv.DictWriter(
f,
fieldnames=[
"episode_index",
"length",
"episode_success",
"first_dataset_index",
"last_dataset_index",
"first_file",
"last_file",
],
)
writer.writeheader()
writer.writerows(manifest_rows)
episode_spec = _format_episode_spec(episode_indices)
(output_dir / "README.txt").write_text(
f"Dataset root: {dataset.root}\n"
f"Dataset repo_id: {dataset.repo_id}\n"
f"Camera: {camera_key}\n"
f"Episodes exported: {episode_spec} ({len(episode_indices)} total)\n"
"Files per episode: episode_XXX_first.png, episode_XXX_last.png\n"
)
return manifest_path
def build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser()
parser.add_argument(
"--dataset",
type=str,
required=True,
help="Dataset repo id or local dataset path.",
)
parser.add_argument(
"--root",
type=Path,
default=None,
help="Optional local dataset root to search under when --dataset is not an existing path.",
)
parser.add_argument(
"--episodes",
type=str,
default="all",
help="Episode selection like 'all', '0-99', or '0-9,12,20-25'.",
)
parser.add_argument(
"--camera-key",
type=str,
default=None,
help="Camera key to export. Defaults to the front camera when available, otherwise the largest image key.",
)
parser.add_argument(
"--output-dir",
type=Path,
required=True,
help="Directory where boundary frames and manifest.csv will be written.",
)
parser.add_argument(
"--overwrite",
action="store_true",
help="Delete --output-dir first if it already exists.",
)
return parser
def main() -> None:
args = build_parser().parse_args()
dataset_root = resolve_dataset_root(args.dataset, args.root)
repo_id = resolve_repo_id(dataset_root, args.root)
info = load_info(dataset_root)
camera_key = select_camera_key(info, args.camera_key)
episode_indices = parse_episode_indices(args.episodes, int(info["total_episodes"]))
from lerobot.datasets.lerobot_dataset import LeRobotDataset
dataset = LeRobotDataset(repo_id=repo_id, root=dataset_root)
prepare_output_dir(args.output_dir, args.overwrite)
manifest_path = export_episode_boundary_frames(
dataset=dataset,
output_dir=args.output_dir,
episode_indices=episode_indices,
camera_key=camera_key,
)
print(f"dataset_root={dataset_root}")
print(f"repo_id={repo_id}")
print(f"camera_key={camera_key}")
print(f"episodes_exported={len(episode_indices)}")
print(f"manifest={manifest_path}")
ssh_connection = os.environ.get("SSH_CONNECTION")
if ssh_connection:
parts = ssh_connection.split()
client_ip = parts[0]
abs_output = args.output_dir.resolve()
hostname = os.uname().nodename
print(
f"\nTip: You are in an SSH session (client {client_ip}).\n"
f"To pull these files to your local machine, run on your local terminal:\n"
f" scp -r {hostname}:{abs_output} ~/Downloads/"
)
if __name__ == "__main__":
main()

查看文件

@ -546,6 +546,11 @@ def record(cfg: RecordConfig) -> LeRobotDataset:
if dataset:
dataset.finalize()
logging.info(
"To visually inspect episode boundaries, run:\n"
" lerobot-export-boundary-frames --dataset %s --episodes all --output-dir <output_dir>",
dataset.repo_id,
)
if policy_sync_executor is not None:
policy_sync_executor.shutdown()

查看文件

@ -0,0 +1,77 @@
#!/usr/bin/env python
# Copyright 2026 The HuggingFace Inc. team. All rights reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
import pytest
from lerobot.scripts.lerobot_export_boundary_frames import (
parse_episode_indices,
select_camera_key,
)
def test_parse_episode_indices_supports_ranges_and_deduplicates():
assert parse_episode_indices("0-2,4,2,6-7", total_episodes=10) == [0, 1, 2, 4, 6, 7]
def test_parse_episode_indices_supports_all_keyword():
assert parse_episode_indices("all", total_episodes=4) == [0, 1, 2, 3]
def test_parse_episode_indices_rejects_out_of_range_indices():
with pytest.raises(ValueError, match="out of range"):
parse_episode_indices("0-5", total_episodes=5)
def test_select_camera_key_prefers_front_camera():
info = {
"features": {
"observation.images.left_wrist": {"dtype": "video", "shape": [480, 640, 3]},
"observation.images.right_front": {"dtype": "video", "shape": [320, 320, 3]},
"observation.images.right_wrist": {"dtype": "video", "shape": [720, 1280, 3]},
}
}
assert select_camera_key(info, None) == "observation.images.right_front"
def test_select_camera_key_falls_back_to_largest_resolution():
info = {
"features": {
"observation.images.left_wrist": {"dtype": "video", "shape": [480, 640, 3]},
"observation.images.right_wrist": {"dtype": "video", "shape": [720, 1280, 3]},
}
}
assert select_camera_key(info, None) == "observation.images.right_wrist"
def test_select_camera_key_handles_chw_shape_with_names():
info = {
"features": {
"observation.images.small": {
"dtype": "image",
"shape": [3, 240, 320],
"names": ["channels", "height", "width"],
},
"observation.images.large": {
"dtype": "image",
"shape": [3, 720, 1280],
"names": ["channels", "height", "width"],
},
}
}
assert select_camera_key(info, None) == "observation.images.large"