Replay & merge

Step A — Merge trajectory shards

Recording (especially with --num-procs or multiple runs) leaves several trajectory.h5 shards. utils/merge_trajectory.py gathers everything matching a filename pattern and writes one combined HDF5.

$ python utils/merge_trajectory.py \
    -i demos/grasp_part/100221 \
    -o demos/grasp_part/100221/trajectory.h5 \
    -p trajectory.h5

-i takes one or more input dirs; -p is the filename pattern to collect (default trajectory.h5); -s True (default) keeps only successful trajectories.

Step B — Replay (render observations)

utils/replay_trajectory.py re-runs the merged trajectory in SAPIEN and renders observations. The output filename encodes the obs / control / backend: merged.<obs>.<control>.<backend>.h5.

Match the recording's control mode. Each env records in its own control mode — check trajectory.json → env_kwargs.control_mode (e.g. grasp_part records pd_joint_pos). Pass that same mode to -c and use --use-env-states for a deterministic, faithful replay. Converting to a different control mode is allowed but falls back to action-replay (--use-env-states is rejected for cross-control-mode) and markedly lowers reproduction success.

$ python utils/replay_trajectory.py \
    --traj-path demos/grasp_part/merged.h5 \
    -o rgb \
    -c pd_joint_pos # ← same mode the recording used \
    -b physx_cpu \
    --use-env-states \
    --save-traj \
    --save-video \
    --shader default
# → demos/grasp_part/merged.rgb.pd_joint_pos.physx_cpu.h5

--save-traj writes the observation-augmented HDF5 (required for conversion); --save-video dumps MP4s for QA. For task-graph data add --allow-failure: replay can't re-evaluate the task-graph goal predicate, so success is decided at record time — replay must not re-filter on its own success check, or every task-graph demo is dropped.

$ python utils/replay_trajectory.py --traj-path demos/<tg-env>/merged.h5 \
    -o rgb -c pd_joint_pos -b physx_cpu --use-env-states --allow-failure --save-traj

Common flags

Tool / flag	Notes
merge_trajectory.py -i	Input dir(s) to scan
merge_trajectory.py -o	Output merged .h5 path
merge_trajectory.py -p	Filename pattern (default trajectory.h5)
merge_trajectory.py -s	Only merge successful trajectories (default True; -s False keeps all)
replay_trajectory.py --traj-path	Trajectory .h5 to replay
-o / --obs-mode	e.g. rgb, rgbd, state
-c / --target-control-mode	Match the recording's control mode (see trajectory.json)
-b / --sim-backend	e.g. physx_cpu
--save-traj / --save-video	Write the replayed .h5 / MP4s
--use-env-states	Deterministic state replay (requires matching control mode)
--allow-failure	Keep all replayed episodes — required for task-graph data

Canonical source: python utils/merge_trajectory.py --help · python utils/replay_trajectory.py --help.