Quality Assurance

Quality Assurance#

Review every recording before publishing or converting it. Start with visual replay, then run automated validation and inspect the captured signals.

1. Replay and Inspect#

For local recordings, pass the local root as DATASET; no dataset is downloaded:

JAX_PLATFORMS=cpu handumi replay \
  outputs/20260714_224135 \
  --robot openarmv1 \
  --episode 0

See Replay a Local Recording in Simulation for the current OpenArm v1 and TRLC-DK1 commands, calibration semantics, measured IK results, and Viser mesh troubleshooting.

Choose the target robot explicitly. Piper is a currently available example:

TARGET_ROBOT=piper
handumi replay \
  your-name/handumi-demo \
  --robot "$TARGET_ROBOT"

In Viser, check the bimanual geometry, table alignment, motion continuity, and unreachable poses. Use --headless for automated checks and --strict-ik to fail when IK error exceeds the configured limits. Add --hide-trajectories to show only the robot and scene without the target and achieved TCP paths.

Table-calibrated datasets preserve recorded bimanual geometry automatically.

Absolute-table replay and calibration precedence

For an explicit geometry-preserving replay:

handumi replay your-name/handumi-demo \
  --robot "$TARGET_ROBOT" \
  --retarget-mode absolute-table \
  --deployment-profile sim

absolute-table applies robot_from_table to both TCP trajectories, preserving their bimanual separation. By default, replay aligns each tool orientation on the first frame and preserves subsequent wrist rotations. Use --absolute-orientation table-absolute only when the HandUMI and robot TCP frames were externally calibrated.

Controller-to-TCP calibration is selected in this order:

  1. Explicit --controller-tcp-calibration.

  2. Identity-bound snapshot stored in the dataset.

  3. Robot/device calibration from configs/robots/*.yaml.

  4. Device fallback for legacy data.

Replay prints the calibration source and hash, TCP distances, minimum height, bimanual separation and workspace bounds, the resolved deployment profile, table-to-robot transform, and IK errors. auto selects the laboratory-local file from configs/rig.yaml when configured and otherwise selects configs/calibration/table/sim/<robot>.yaml; use sim in portable QA so a machine-local rig cannot change the result.

Offline playback of a dataset on physical arms is not currently exposed. handumi teleop-real consumes live HandUMI motion and is not a recorded-dataset replay command.

2. Run Automated Validation#

handumi validate \
  outputs/datasets/handumi-demo --strict

The report is written to meta/handumi_quality.json. Review rejected episodes for tracking loss, stale sensors, synchronization errors, frozen poses, motion jumps, or invalid duration. Rejected episodes are excluded automatically during conversion.

3. Inspect Captured Signals#

Raw datasets preserve the information needed to validate, recalibrate, or retarget a capture:

observation.images.left_wrist
observation.images.right_wrist
observation.images.workspace
observation.state                  # controller poses + gripper widths
observation.feetech.*              # ticks, width, time, health
observation.tracking.*             # device poses, validity, aligned time
observation.sync.*                 # shared target and record times
observation.camera.<name>.*        # sample time and health

observation.state[14:16] stores left/right gripper widths in meters. Tool, controller mount, calibration hashes, source enablement, and coordinate layout are stored in metadata. Raw controller poses remain unchanged so the same capture can be checked against another supported robot.

4. Convert and Check Target Motion#

Conversion creates a target-specific dataset while preserving the raw source. --retarget-mode defaults to auto and is resolved with the exact same rule handumi replay uses, identically for every embodiment: when the source dataset declares a calibrated table workspace, conversion runs the same absolute-table solver as replay (validating the selected local or configs/calibration/table/sim/<embodiment>.yaml deployment) for exact qpos parity; otherwise it falls back to local-relative. For Piper, use the validated --robot piper profile to convert the replay result to physical Piper commands:

JAX_PLATFORMS=cpu handumi convert \
  outputs/datasets/handumi-demo \
  --robot piper \
  --output your-name/handumi-demo-piper

The Piper state has 14 physical commands: six replay arm joints in radians plus one gripper opening in meters per side. Its pairs are observation.state[t] = command[t] and action[t] = command[t+1]. The two mirrored URDF finger joints are reconstructed from the single opening only when rendering simulation. Other embodiments use the same --robot <name> interface; absolute-table support requires their corresponding simulation file or lab-local deployment, and an explicit --retarget-mode can override auto detection for any of them. Use --deployment-profile sim for a portable converted dataset and record the resulting deployment metadata.

Replay and validate the converted motion before using it with a robot-specific integration. See Add a New Robot Embodiment when adding another simulation model or hardware backend.

5. Curate Rejected or Incomplete Data#

When a dataset contains rejected or incomplete episodes, create a separate curated derivative before conversion or publication. The analysis and curation steps are intentionally separate so statistical outliers can be reviewed before any data is removed. See Analyze and Curate Datasets.

6. Publish Accepted Data#

Upload only after the replay and validation checks pass:

hf auth login
huggingface-cli upload your-name/handumi-demo \
  outputs/datasets/handumi-demo --repo-type dataset