#!/usr/bin/env python3 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 # # 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. """ Download a small DROID sample dataset from HuggingFace and convert it to GR00T LeRobot v2 format suitable for inference with the base model. The full DROID dataset (lerobot/droid_1.0.1) is ~358 GB with 95k+ episodes in LeRobot v3.0 format. This script downloads only the first data/video chunks, then extracts a handful of episodes into the v2.0 per-episode format. Prerequisites: uv pip install jsonlines # if not already installed Usage: python scripts/download_droid_sample.py python scripts/download_droid_sample.py --num-episodes 5 --output-dir demo_data/droid_sample After running, test with: uv run python scripts/deployment/standalone_inference_script.py \\ --model-path nvidia/GR00T-N1.7-3B \\ --dataset-path demo_data/droid_sample \\ --embodiment-tag OXE_DROID_RELATIVE_EEF_RELATIVE_JOINT \\ --traj-ids 0 1 --inference-mode pytorch --action-horizon 8 """ from __future__ import annotations import argparse import json import logging from pathlib import Path import shutil import subprocess import jsonlines import numpy as np import pyarrow.parquet as pq from scipy.spatial.transform import Rotation logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s") logger = logging.getLogger(__name__) # Egocentric frame correction applied after euler-to-matrix conversion. # Matches the OXE DROID training pipeline (TFG convention). DROID_EEF_ROTATION_CORRECT = np.array( [[0, 0, -1], [-1, 0, 0], [0, 1, 0]], dtype=np.float64, ) def euler_to_rot6d(euler_angles: np.ndarray) -> np.ndarray: """Convert euler angles (3D) to rotation 6D representation. Uses extrinsic XYZ Euler convention (scipy ``"XYZ"``, equivalent to ``tfg.rotation_matrix_3d.from_euler``) and post-multiplies by ``DROID_EEF_ROTATION_CORRECT`` to match the pretrained model. Args: euler_angles: (..., 3) array of euler angles Returns: (..., 6) array of rot6d representation """ shape = euler_angles.shape[:-1] flat = euler_angles.reshape(-1, 3) rot_matrices = Rotation.from_euler("XYZ", flat).as_matrix() # (N, 3, 3) rot_matrices = rot_matrices @ DROID_EEF_ROTATION_CORRECT rot6d = rot_matrices[:, :2, :].reshape(-1, 6) # (N, 6) return rot6d.reshape(*shape, 6) def compute_eef_9d(cartesian_position: np.ndarray) -> np.ndarray: """Convert cartesian_position (XYZ + euler 3D) to eef_9d (XYZ + rot6d). Args: cartesian_position: (..., 6) array [x, y, z, euler_x, euler_y, euler_z] Returns: (..., 9) array [x, y, z, rot6d_0..5] """ xyz = cartesian_position[..., :3] euler = cartesian_position[..., 3:] rot6d = euler_to_rot6d(euler) return np.concatenate([xyz, rot6d], axis=-1) REPO_ID = "lerobot/droid_1.0.1" DEFAULT_OUTPUT_DIR = "demo_data/droid_sample" DEFAULT_NUM_EPISODES = 3 # The 2 cameras used by the OXE_DROID model config. # (The dataset also has exterior_2_left, but the model only uses 2 cameras.) VIDEO_KEYS = [ "observation.images.exterior_1_left", "observation.images.wrist_left", ] def download_droid_files(cache_dir: Path) -> None: """Download minimal files from the DROID v3.0 dataset.""" from huggingface_hub import hf_hub_download logger.info("Downloading DROID v3.0 metadata and first chunks...") files_to_download = [ "meta/info.json", "meta/stats.json", "meta/tasks.parquet", "meta/episodes/chunk-000/file-000.parquet", "data/chunk-000/file-000.parquet", ] # Download video file-000 for each camera we need for video_key in VIDEO_KEYS: files_to_download.append(f"videos/{video_key}/chunk-000/file-000.mp4") for fname in files_to_download: logger.info(f" {fname}...") hf_hub_download( repo_id=REPO_ID, repo_type="dataset", filename=fname, local_dir=str(cache_dir), ) def extract_episodes(cache_dir: Path, output_dir: Path, num_episodes: int) -> None: """Convert downloaded v3.0 data to GR00T LeRobot v2.0 format.""" output_dir.mkdir(parents=True, exist_ok=True) meta_dir = output_dir / "meta" meta_dir.mkdir(exist_ok=True) # Load source info with open(cache_dir / "meta" / "info.json") as f: source_info = json.load(f) fps = source_info.get("fps", 15) # ── Load episodes metadata (v3.0 parquet format) ── episodes_pq = cache_dir / "meta" / "episodes" / "chunk-000" / "file-000.parquet" episodes_df = pq.read_table(episodes_pq).to_pandas() # Only take episodes from file-000 (the chunk we downloaded) episodes = [] for _, row in episodes_df.iterrows(): if len(episodes) >= num_episodes: break # Skip episodes whose data is in a different file if int(row["data/file_index"]) != 0: continue episodes.append(row) if not episodes: raise RuntimeError("No episodes found in first data chunk") # ── Load tasks (v3.0: parquet with task text as index, task_index as column) ── tasks_df = pq.read_table(cache_dir / "meta" / "tasks.parquet").to_pandas() tasks_df_reset = tasks_df.reset_index() # columns after reset: ['index' (= task text), 'task_index'] task_text_col = tasks_df_reset.columns[0] # the task text column logger.info(f"Extracting {len(episodes)} episodes (fps={fps})") # ── Read the consolidated data parquet ── data_path = cache_dir / "data" / "chunk-000" / "file-000.parquet" table = pq.read_table(data_path) df = table.to_pandas() # ── Create per-episode parquet files ── data_chunk_dir = output_dir / "data" / "chunk-000" data_chunk_dir.mkdir(parents=True, exist_ok=True) episode_records = [] task_indices_used = set() for ep_row in episodes: ep_idx = int(ep_row["episode_index"]) ep_df = df[df["episode_index"] == ep_idx].copy() if len(ep_df) == 0: logger.warning(f"Episode {ep_idx} has no data rows, skipping") continue ep_length = len(ep_df) new_ep_idx = len(episode_records) lang = ( str(ep_df["language_instruction"].iloc[0]) if "language_instruction" in ep_df.columns else "" ) logger.info(f" Episode {ep_idx} -> {new_ep_idx}: {ep_length} frames, task={lang[:60]!r}") if "task_index" in ep_df.columns: task_indices_used.update(ep_df["task_index"].unique().tolist()) ep_df = ep_df.copy() ep_df["episode_index"] = new_ep_idx ep_df["index"] = range(len(ep_df)) # Compute eef_9d (XYZ + rot6d) from cartesian_position (XYZ + euler) # for both state and action, as the model expects 17D = eef_9d(9) + gripper(1) + joints(7) for prefix in ["observation.state", "action"]: cart_col = f"{prefix}.cartesian_position" if cart_col in ep_df.columns: cart = np.stack(ep_df[cart_col].values) # (T, 6) eef_9d = compute_eef_9d(cart) # (T, 9) ep_df[f"{prefix}.eef_9d"] = list(eef_9d) # Rebuild concatenated observation.state = [eef_9d(9), gripper(1), joint(7)] = 17D state_parts = [] for col in [ "observation.state.eef_9d", "observation.state.gripper_position", "observation.state.joint_position", ]: if col in ep_df.columns: vals = ep_df[col].values arr = np.stack([np.atleast_1d(v) for v in vals]) state_parts.append(arr) if state_parts: new_state = np.concatenate(state_parts, axis=-1) # (T, 17) ep_df["observation.state"] = list(new_state) # Rebuild concatenated action = [eef_9d(9), gripper(1), joint(7)] = 17D action_parts = [] for col in ["action.eef_9d", "action.gripper_position", "action.joint_position"]: if col in ep_df.columns: vals = ep_df[col].values arr = np.stack([np.atleast_1d(v) for v in vals]) action_parts.append(arr) if action_parts: new_action = np.concatenate(action_parts, axis=-1) # (T, 17) ep_df["action"] = list(new_action) ep_parquet = data_chunk_dir / f"episode_{new_ep_idx:06d}.parquet" ep_df.to_parquet(ep_parquet, index=False) episode_records.append( { "episode_index": new_ep_idx, "tasks": list(ep_row["tasks"]) if "tasks" in ep_row.index else [], "length": ep_length, "_src_row": ep_row, # keep for video timestamp lookup } ) if not episode_records: raise RuntimeError("No episodes could be extracted") # ── Extract per-episode video segments using timestamps from episodes metadata ── for video_key in VIDEO_KEYS: video_chunk_dir = output_dir / "videos" / "chunk-000" / video_key video_chunk_dir.mkdir(parents=True, exist_ok=True) source_video = cache_dir / "videos" / video_key / "chunk-000" / "file-000.mp4" if not source_video.exists(): logger.warning(f"Video not found: {source_video}, skipping") continue for rec in episode_records: new_ep_idx = rec["episode_index"] ep_row = rec["_src_row"] from_ts = float(ep_row[f"videos/{video_key}/from_timestamp"]) to_ts = float(ep_row[f"videos/{video_key}/to_timestamp"]) duration = to_ts - from_ts out_video = video_chunk_dir / f"episode_{new_ep_idx:06d}.mp4" # Try stream copy first (fast), fall back to re-encode for AV1 cmd = [ "ffmpeg", "-y", "-loglevel", "error", "-ss", f"{from_ts:.6f}", "-i", str(source_video), "-t", f"{duration:.6f}", "-c", "copy", str(out_video), ] result = subprocess.run(cmd, capture_output=True, text=True) if result.returncode != 0: cmd_reencode = [ "ffmpeg", "-y", "-loglevel", "error", "-ss", f"{from_ts:.6f}", "-i", str(source_video), "-t", f"{duration:.6f}", "-c:v", "libx264", "-crf", "23", "-preset", "fast", str(out_video), ] subprocess.run(cmd_reencode, check=True) logger.info( f" {video_key} ep{new_ep_idx}: re-encoded ({rec['length']} frames, {from_ts:.1f}s-{to_ts:.1f}s)" ) else: logger.info( f" {video_key} ep{new_ep_idx}: copied ({rec['length']} frames, {from_ts:.1f}s-{to_ts:.1f}s)" ) # ── Write meta files ── # Clean up internal fields before writing for rec in episode_records: del rec["_src_row"] # meta/stats.json — copy from source dataset (used for normalization) src_stats = cache_dir / "meta" / "stats.json" if src_stats.exists(): shutil.copy2(src_stats, meta_dir / "stats.json") logger.info(" Copied stats.json from source dataset") else: logger.warning( " stats.json not found in source. Generate it with:\n" f" python gr00t/data/stats.py --dataset-path {output_dir} --embodiment-tag OXE_DROID_RELATIVE_EEF_RELATIVE_JOINT" ) # meta/episodes.jsonl with jsonlines.open(meta_dir / "episodes.jsonl", mode="w") as writer: for rec in episode_records: writer.write(rec) # meta/tasks.jsonl with jsonlines.open(meta_dir / "tasks.jsonl", mode="w") as writer: for _, row in tasks_df_reset.iterrows(): tidx = int(row["task_index"]) if tidx in task_indices_used: writer.write({"task_index": tidx, "task": str(row[task_text_col])}) # meta/info.json info = { "codebase_version": "v2.1", "robot_type": "droid", "total_episodes": len(episode_records), "total_frames": sum(r["length"] for r in episode_records), "fps": fps, "data_path": "data/chunk-{episode_chunk:03d}/episode_{episode_index:06d}.parquet", "video_path": "videos/chunk-{episode_chunk:03d}/{video_key}/episode_{episode_index:06d}.mp4", "chunks_size": 1000, "splits": {"train": f"0:{len(episode_records)}"}, "features": { "observation.images.exterior_1_left": { "dtype": "video", "shape": [180, 320, 3], }, "observation.images.wrist_left": { "dtype": "video", "shape": [180, 320, 3], }, "observation.state": {"dtype": "float32", "shape": [17]}, "action": {"dtype": "float32", "shape": [17]}, "task_index": {"dtype": "int64", "shape": [1]}, }, } with open(meta_dir / "info.json", "w") as f: json.dump(info, f, indent=2) # meta/modality.json modality = { "state": { "eef_9d": {"start": 0, "end": 9}, "gripper_position": {"start": 9, "end": 10}, "joint_position": {"start": 10, "end": 17}, }, "action": { "eef_9d": {"start": 0, "end": 9}, "gripper_position": {"start": 9, "end": 10}, "joint_position": {"start": 10, "end": 17}, }, "video": { "exterior_1_left": {"original_key": "observation.images.exterior_1_left"}, "wrist_left": {"original_key": "observation.images.wrist_left"}, }, "annotation": { "language.language_instruction": {"original_key": "task_index"}, }, } with open(meta_dir / "modality.json", "w") as f: json.dump(modality, f, indent=2) logger.info(f"\nDataset created at: {output_dir}") logger.info(f" Episodes: {len(episode_records)}") logger.info(f" Total frames: {sum(r['length'] for r in episode_records)}") def main(): parser = argparse.ArgumentParser( description="Download a small DROID sample dataset for GR00T inference testing.", ) parser.add_argument("--output-dir", default=DEFAULT_OUTPUT_DIR) parser.add_argument("--num-episodes", type=int, default=DEFAULT_NUM_EPISODES) parser.add_argument("--cache-dir", default=None) args = parser.parse_args() cache_dir = Path(args.cache_dir or "/tmp/droid_download_cache") output_dir = Path(args.output_dir) if output_dir.exists(): logger.info(f"Output already exists: {output_dir} — delete it to regenerate.") return download_droid_files(cache_dir) extract_episodes(cache_dir, output_dir, args.num_episodes) logger.info("\nTo run inference:") logger.info( f" uv run python scripts/deployment/standalone_inference_script.py \\\n" f" --model-path nvidia/GR00T-N1.7-3B \\\n" f" --dataset-path {output_dir} \\\n" f" --embodiment-tag OXE_DROID_RELATIVE_EEF_RELATIVE_JOINT \\\n" f" --traj-ids 1 2 --inference-mode pytorch --action-horizon 8" ) if __name__ == "__main__": main()