react-manip 0.1.0__py3-none-any.whl

scripts/piperx_assets.lock.json

@@ -0,0 +1,181 @@
+{
+  "sources": {
+    "arm": {
+      "repository": "https://github.com/agilexrobotics/agx_arm_urdf",
+      "revision": "983788b58d7eae76511177f768d85877534917fe",
+      "license": "MIT"
+    },
+    "mobile": {
+      "repository": "https://github.com/agilexrobotics/mobile_aloha_sim",
+      "revision": "f799ae0192c0c2bbd502ec4d9bbec8c2633acd1a",
+      "license": "package.xml declares BSD; no top-level LICENSE in pinned source",
+      "use": "Tracer chassis and support frame only; no legacy arms or grippers"
+    }
+  },
+  "files": {
+    "arm/LICENSE": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/agx_arm_urdf/983788b58d7eae76511177f768d85877534917fe/LICENSE",
+      "sha256": "247944c63de1573653722ba784f96123da267105b7b48577e0c8826a24b809f6"
+    },
+    "arm/agx_gripper/meshes/gripper_base.stl": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/agx_arm_urdf/983788b58d7eae76511177f768d85877534917fe/agx_gripper/meshes/gripper_base.stl",
+      "sha256": "0b839dc0bcb7d94e3422c74f6396b54a0441ba4836448ab5586e7f372d1bdbf3"
+    },
+    "arm/agx_gripper/meshes/gripper_link1.stl": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/agx_arm_urdf/983788b58d7eae76511177f768d85877534917fe/agx_gripper/meshes/gripper_link1.stl",
+      "sha256": "475a7d8db056524d7659fadf5a2c307d62791047b6214d733dfc7846ed1c613d"
+    },
+    "arm/agx_gripper/meshes/gripper_link2.stl": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/agx_arm_urdf/983788b58d7eae76511177f768d85877534917fe/agx_gripper/meshes/gripper_link2.stl",
+      "sha256": "3f88d534a85e28a33ef7d2061adacbd1d25214aa9325f9e464aad0f9e4b74606"
+    },
+    "arm/agx_gripper/meshes/dae/gripper_link1.dae": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/agx_arm_urdf/983788b58d7eae76511177f768d85877534917fe/agx_gripper/meshes/dae/gripper_link1.dae",
+      "sha256": "b4aaf0e024d09eb0454e70e0c5092638edcf7da7c253d1effdeeaec46f76427b"
+    },
+    "arm/agx_gripper/meshes/dae/gripper_link2.dae": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/agx_arm_urdf/983788b58d7eae76511177f768d85877534917fe/agx_gripper/meshes/dae/gripper_link2.dae",
+      "sha256": "0da1350898b2787b76b84698253aeb1efd2ddb6360b2fa2ae03ecff389883af8"
+    },
+    "arm/agx_gripper/meshes/dae/gripper_base.dae": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/agx_arm_urdf/983788b58d7eae76511177f768d85877534917fe/agx_gripper/meshes/dae/gripper_base.dae",
+      "sha256": "aaea10ec06709d6a3343dd3378553eee3df40b43ee276df10c5b68ac7f61bae2"
+    },
+    "arm/piper_x/urdf/piper_x_description.urdf": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/agx_arm_urdf/983788b58d7eae76511177f768d85877534917fe/piper_x/urdf/piper_x_description.urdf",
+      "sha256": "8786fa7d01c81358b446e8d5121ae2b8e7a9fc770513373f270f29a9d5a3a2f1"
+    },
+    "arm/piper_x/urdf/piper_x_with_gripper_description.xacro": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/agx_arm_urdf/983788b58d7eae76511177f768d85877534917fe/piper_x/urdf/piper_x_with_gripper_description.xacro",
+      "sha256": "88561fe45a3f4e639c7a233b13574d88d7707b545110cb30b983e360cdb57420"
+    },
+    "arm/piper_x/meshes/flange.stl": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/agx_arm_urdf/983788b58d7eae76511177f768d85877534917fe/piper_x/meshes/flange.stl",
+      "sha256": "f9ce752f93a6598858a779e3d8755a09e466b588efcffc3a1c3953773753a22b"
+    },
+    "arm/piper_x/meshes/link3.stl": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/agx_arm_urdf/983788b58d7eae76511177f768d85877534917fe/piper_x/meshes/link3.stl",
+      "sha256": "c51994fa4ca6a0577cfc65fe5a666ad47ad6af8dc98fbe81b71c4a7fe8ad09a5"
+    },
+    "arm/piper_x/meshes/base_link.stl": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/agx_arm_urdf/983788b58d7eae76511177f768d85877534917fe/piper_x/meshes/base_link.stl",
+      "sha256": "b732cf8a1f8435f51e3ec860f11189c3ec63744d3df008b7d3e9b6505dfc483d"
+    },
+    "arm/piper_x/meshes/link2.stl": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/agx_arm_urdf/983788b58d7eae76511177f768d85877534917fe/piper_x/meshes/link2.stl",
+      "sha256": "0316b881cd0bae6c9f8f794fabdee7fbf041f83f2f75980d34b67555fe8a3561"
+    },
+    "arm/piper_x/meshes/link1.stl": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/agx_arm_urdf/983788b58d7eae76511177f768d85877534917fe/piper_x/meshes/link1.stl",
+      "sha256": "60c53c4d5d20c5b663cc4ced2f5e322d2a857baa6e79cef04a33b5f9f7c1e985"
+    },
+    "arm/piper_x/meshes/link5.stl": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/agx_arm_urdf/983788b58d7eae76511177f768d85877534917fe/piper_x/meshes/link5.stl",
+      "sha256": "fb7ab27270e6b5fa0b2e6df9fa37722062f4ff397cd4f89883d23551bedd0801"
+    },
+    "arm/piper_x/meshes/link4.stl": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/agx_arm_urdf/983788b58d7eae76511177f768d85877534917fe/piper_x/meshes/link4.stl",
+      "sha256": "10b69bde5305c53fbb4a6dc4e910e8604d54d250a969e6cda8128d8244989831"
+    },
+    "arm/piper_x/meshes/link6.stl": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/agx_arm_urdf/983788b58d7eae76511177f768d85877534917fe/piper_x/meshes/link6.stl",
+      "sha256": "8c391520fd963fe4f9b46afcde82ceeab2a93b73c01fc5debe039fe632f597e6"
+    },
+    "arm/piper_x/meshes/dae/link4.dae": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/agx_arm_urdf/983788b58d7eae76511177f768d85877534917fe/piper_x/meshes/dae/link4.dae",
+      "sha256": "cda6aab6dfefb13d5409a691d7486c4253737f114cca9ada67da36a10fb08123"
+    },
+    "arm/piper_x/meshes/dae/link5.dae": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/agx_arm_urdf/983788b58d7eae76511177f768d85877534917fe/piper_x/meshes/dae/link5.dae",
+      "sha256": "8c2a2da46dfe9d13fc8841a990694c77106c27be292fac4fc42a86cd78a2dee1"
+    },
+    "arm/piper_x/meshes/dae/link6.dae": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/agx_arm_urdf/983788b58d7eae76511177f768d85877534917fe/piper_x/meshes/dae/link6.dae",
+      "sha256": "7e6076e2574f042f5067dd431e96486249cffbc8ab292fb66cb68848ad5bab9a"
+    },
+    "arm/piper_x/meshes/dae/link2.dae": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/agx_arm_urdf/983788b58d7eae76511177f768d85877534917fe/piper_x/meshes/dae/link2.dae",
+      "sha256": "05ad1975346a330129dbce02131405dba6f51d74d0e5f3a70ec154ef219d9163"
+    },
+    "arm/piper_x/meshes/dae/base_link.dae": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/agx_arm_urdf/983788b58d7eae76511177f768d85877534917fe/piper_x/meshes/dae/base_link.dae",
+      "sha256": "706008b1e425227d42fb490febb6a54a2a294a39911b8cf4e9ca4b8c61eb42bd"
+    },
+    "arm/piper_x/meshes/dae/link3.dae": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/agx_arm_urdf/983788b58d7eae76511177f768d85877534917fe/piper_x/meshes/dae/link3.dae",
+      "sha256": "001b0b97dd514a9f8e6b321e12a8005d17198eb8b60ec443b9bd67251a3790ce"
+    },
+    "arm/piper_x/meshes/dae/link1.dae": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/agx_arm_urdf/983788b58d7eae76511177f768d85877534917fe/piper_x/meshes/dae/link1.dae",
+      "sha256": "6448c874d7106738d20cdd044e0e88f86262935f0bc3bdc072c5025bcf47ecfd"
+    },
+    "arm/piper_x/meshes/dae/flange.dae": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/agx_arm_urdf/983788b58d7eae76511177f768d85877534917fe/piper_x/meshes/dae/flange.dae",
+      "sha256": "421c3e20c6109df3c96c5ce18ff0b2609b6604135ff790e4bfc1d9a281b0701a"
+    },
+    "mobile/aloha_new_description/urdf/aloha_new.urdf": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/mobile_aloha_sim/f799ae0192c0c2bbd502ec4d9bbec8c2633acd1a/aloha_new_description/urdf/aloha_new.urdf",
+      "sha256": "d4a115493af6a67ef969cfb8686b54f2970225b617ec6dd99cf682c0c4c7b6e9"
+    },
+    "mobile/aloha_new_description/package.xml": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/mobile_aloha_sim/f799ae0192c0c2bbd502ec4d9bbec8c2633acd1a/aloha_new_description/package.xml",
+      "sha256": "8b7aa5c8b34c8854ad4e033132ff1f8a406f5bb8c32260a8e14b337cf570dba4"
+    },
+    "mobile/aloha_new_description/meshes/base_link.STL": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/mobile_aloha_sim/f799ae0192c0c2bbd502ec4d9bbec8c2633acd1a/aloha_new_description/meshes/base_link.STL",
+      "sha256": "fd9c5c5816513cae313b6bee70f95474faadd136eb3ea19c68ffa451dfcd962a"
+    },
+    "mobile/aloha_new_description/meshes/link1.STL": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/mobile_aloha_sim/f799ae0192c0c2bbd502ec4d9bbec8c2633acd1a/aloha_new_description/meshes/link1.STL",
+      "sha256": "2288b210ac2a4a0a6150cbe024870e6d1eee21dea320d5d6d19d17eb3099b8ea"
+    },
+    "mobile/aloha_new_description/meshes/link2.STL": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/mobile_aloha_sim/f799ae0192c0c2bbd502ec4d9bbec8c2633acd1a/aloha_new_description/meshes/link2.STL",
+      "sha256": "09f46d7c93dccf8073491fb4ef6fb89dbe5ec9b5e82ad2c383b96a50dd6fe81f"
+    },
+    "mobile/aloha_new_description/meshes/link3.STL": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/mobile_aloha_sim/f799ae0192c0c2bbd502ec4d9bbec8c2633acd1a/aloha_new_description/meshes/link3.STL",
+      "sha256": "80077a3cb2fd4bf4a7f65920c8f3e2f3a590c6059146dc08731a536244114210"
+    },
+    "mobile/aloha_new_description/meshes/link4.STL": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/mobile_aloha_sim/f799ae0192c0c2bbd502ec4d9bbec8c2633acd1a/aloha_new_description/meshes/link4.STL",
+      "sha256": "e9963ce55b0796a61e4f9eb3445d81f4d40b67dcfd43eafcf2619c637f341cfe"
+    },
+    "mobile/aloha_new_description/meshes/link5.STL": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/mobile_aloha_sim/f799ae0192c0c2bbd502ec4d9bbec8c2633acd1a/aloha_new_description/meshes/link5.STL",
+      "sha256": "ab9877b96fe2b69622011049735f0fd244b1e30ada2dc65840364c07a5154323"
+    },
+    "mobile/aloha_new_description/meshes/piper_slave_meshes/link6.STL": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/mobile_aloha_sim/f799ae0192c0c2bbd502ec4d9bbec8c2633acd1a/aloha_new_description/meshes/piper_slave_meshes/link6.STL",
+      "sha256": "227f63feb64d17c397c76ebb96a8720476345a3bba36e0d6d7c9d938db8ce677"
+    },
+    "mobile/aloha_new_description/meshes/tracer_base_link_no_wheel.dae": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/mobile_aloha_sim/f799ae0192c0c2bbd502ec4d9bbec8c2633acd1a/aloha_new_description/meshes/tracer_base_link_no_wheel.dae",
+      "sha256": "d3a1ee3b34dbc418e888d68148d04fccda589e00d5100fbd3cbc2f17154e0a08"
+    },
+    "mobile/aloha_new_description/meshes/tracer_wheel.dae": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/mobile_aloha_sim/f799ae0192c0c2bbd502ec4d9bbec8c2633acd1a/aloha_new_description/meshes/tracer_wheel.dae",
+      "sha256": "42784402bca05e9f406f4e08d8ea1cc7ff57db9fee0e0b0b557670d0ee1d10c1"
+    },
+    "mobile/aloha_new_description/meshes/castor_joint.dae": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/mobile_aloha_sim/f799ae0192c0c2bbd502ec4d9bbec8c2633acd1a/aloha_new_description/meshes/castor_joint.dae",
+      "sha256": "901cad2da533c8fd0f3e3ce25a4d5b5d1c689d5f852640cd7dab041dc647d629"
+    },
+    "mobile/aloha_new_description/meshes/castor.dae": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/mobile_aloha_sim/f799ae0192c0c2bbd502ec4d9bbec8c2633acd1a/aloha_new_description/meshes/castor.dae",
+      "sha256": "0a61bca6839f37ebebd89021474821abfd908d2b50867f221e3504db4d84a06a"
+    },
+    "mobile/aloha_new_description/meshes/body.dae": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/mobile_aloha_sim/f799ae0192c0c2bbd502ec4d9bbec8c2633acd1a/aloha_new_description/meshes/body.dae",
+      "sha256": "2bad2557aad93a83adad913da6ee30f32d4414602f9f7be138c377a0543be659"
+    },
+    "mobile/aloha_new_description/meshes/piper_slave_meshes/link7.STL": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/mobile_aloha_sim/f799ae0192c0c2bbd502ec4d9bbec8c2633acd1a/aloha_new_description/meshes/piper_slave_meshes/link7.STL",
+      "sha256": "63d89c3e9d5aba6c230f21a1e8ad5724f3818a1dba7e3493c58de4bee8d44cac"
+    },
+    "mobile/aloha_new_description/meshes/piper_slave_meshes/link8.STL": {
+      "url": "https://raw.githubusercontent.com/agilexrobotics/mobile_aloha_sim/f799ae0192c0c2bbd502ec4d9bbec8c2633acd1a/aloha_new_description/meshes/piper_slave_meshes/link8.STL",
+      "sha256": "8ff0fa31925c2339f8c64171e47c91410b671530d6613e33472b710cc4968ece"
+    }
+  }
+}

scripts/pygame_demo.py

@@ -0,0 +1,360 @@
+#!/usr/bin/env python3
+"""Manual replay viewer for the shipped fixed Instance/Episode task bank.
+
+This script never samples a task. It loads the candidate bank, validates
+the manifest and replays the saved initial state of
+one of its 48 Instances and 720 Episodes through ``ReplayEnv``.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+import numpy as np
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+DEFAULT_BANK = ROOT / "react_manip" / "suites" / "piperx_candidates_v1" / "bank.json"
+
+
+class KeyboardPoseControl:
+    """Manual-only physical speed scaling and persistent stop targets."""
+
+    def __init__(self, robot, dt, fast_speed=1.0):
+        self.robot, self.dt = robot, float(dt)
+        self.fast_speed = float(fast_speed)
+        if not np.isfinite(self.fast_speed) or not 0 < self.fast_speed <= 2:
+            raise ValueError("fast speed must be in (0, 2] m/s")
+        self.previous = {arm: np.zeros(6) for arm in robot.arms}
+        for arm in robot.arms:
+            c = robot.part_controllers[arm]
+            if c.input_type != 'delta' or c.impedance_mode != 'fixed':
+                raise ValueError('Keyboard control requires fixed-impedance delta OSC_POSE')
+            c.update(force=True)
+            c.reset_goal(goal_update_mode='desired')
+            c.goal_pos, c.goal_ori = self.current_pose(c)
+
+    @staticmethod
+    def current_pose(c):
+        if c.input_ref_frame == 'world':
+            return c.ref_pos.copy(), c.ref_ori_mat.copy()
+        return c.world_to_origin_frame(c.ref_pos), c.goal_origin_to_eef_pose()[:3, :3]
+
+    def stop(self):
+        for arm in self.robot.arms:
+            c = self.robot.part_controllers[arm]
+            c.update(force=True)
+            c.goal_pos, c.goal_ori = self.current_pose(c)
+            self.previous[arm].fill(0)
+
+    def action(self, action_dim, layout, active, direction, grippers, fast=False):
+        from scipy.spatial.transform import Rotation
+        from react_manip.robots.arm_actions import arm_action
+        direction = np.asarray(direction, dtype=float).copy()
+        # Normalize diagonal input to preserve the requested translation speed.
+        for part in (slice(0, 3), slice(3, 6)):
+            direction[part] /= max(1., np.linalg.norm(direction[part]))
+        c = self.robot.part_controllers[active]
+        c.update(force=True)
+        position, orientation = self.current_pose(c)
+        previous = self.previous[active]
+        released = (direction[:3] == 0) & (previous[:3] != 0)
+        c.goal_pos[released] = position[released]
+        if not np.any(direction[3:]) and np.any(previous[3:]):
+            c.goal_ori = orientation.copy()
+        # Bound target lead when blocked by contact or a workspace limit.
+        moving = direction[:3] != 0
+        limit = .10 if fast else .02
+        c.goal_pos[moving] = position[moving] + np.clip(c.goal_pos[moving] - position[moving], -limit, limit)
+        if np.any(direction[3:]):
+            rotation = Rotation.from_matrix(c.goal_ori @ orientation.T).as_rotvec()
+            rotation *= min(1., .3 / max(np.linalg.norm(rotation), 1e-12))
+            c.goal_ori = Rotation.from_rotvec(rotation).as_matrix() @ orientation
+        delta = direction * np.array([self.fast_speed if fast else .06] * 3 + [1.2 if fast else .3] * 3) * self.dt
+        output_mid = (c.output_max + c.output_min) / 2
+        output_half = (c.output_max - c.output_min) / 2
+        pose = (delta - output_mid) / output_half
+        pose = pose * (c.input_max - c.input_min) / 2 + (c.input_max + c.input_min) / 2
+        self.previous[active] = direction.copy()
+        return arm_action(action_dim, layout, active, pose, grippers)
+
+
+def _records(bank_path):
+    """Load and flatten the validated bank in stable task/instance order."""
+    from react_manip.instances.candidate_bank import load_bank
+
+    bank, manifest_path, manifest, choices = load_bank(bank_path)
+    groups = []
+    for task_id in sorted(choices):
+        for instance, episodes in sorted(choices[task_id],
+                                         key=lambda item: item[0]["task_instance_id"]):
+            groups.append((instance, episodes))
+    return bank, manifest_path, manifest, groups
+
+
+def _select(groups, instance_id=None, episode_id=None, task_id=None):
+    """Resolve a single Instance/Episode, rejecting ambiguous combinations."""
+    if task_id is not None:
+        groups = [item for item in groups if item[0]["task_id"] == task_id]
+    if not groups:
+        raise ValueError("no Instances match the requested task")
+
+    if instance_id is not None:
+        groups = [item for item in groups if item[0]["task_instance_id"] == instance_id]
+        if not groups:
+            raise ValueError(f"unknown task Instance {instance_id!r}")
+    if episode_id is not None:
+        matches = [(instance, episodes) for instance, episodes in groups
+                   if any(ep["episode_id"] == episode_id for ep in episodes)]
+        if not matches:
+            raise ValueError(f"unknown Episode {episode_id!r}")
+        if instance_id is not None and len(matches) != 1:
+            raise ValueError(f"Episode {episode_id!r} does not belong to Instance {instance_id!r}")
+        groups = matches
+
+    instance, episodes = groups[0]
+    if episode_id is None:
+        episode_index = 0
+    else:
+        episode_index = next(i for i, ep in enumerate(episodes)
+                             if ep["episode_id"] == episode_id)
+    return instance, episodes, episode_index
+
+
+def _print_instances(groups, task_id=None):
+    rows = [(instance, episodes) for instance, episodes in groups
+            if task_id is None or instance["task_id"] == task_id]
+    for index, (instance, episodes) in enumerate(rows, 1):
+        print(f"{index:02d}. {instance['task_instance_id']}  "
+              f"task={instance['task_id']}  episodes={len(episodes)}")
+    print(f"{len(rows)} instance(s), {sum(len(es) for _, es in rows)} episode(s)")
+
+
+def _print_episodes(instance, episodes):
+    for index, episode in enumerate(episodes, 1):
+        print(f"{index:02d}. {episode['episode_id']}")
+    print(f"Instance {instance['task_instance_id']}: {len(episodes)} episode(s)")
+
+
+def _parser():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--bank', type=Path, default=DEFAULT_BANK,
+                        help='candidate bank JSON (default: shipped piperx bank)')
+    parser.add_argument('--task', help='restrict listing/selection to one task')
+    parser.add_argument('--instance', help='Task Instance ID, for example tilte_maze_001')
+    parser.add_argument('--episode', help='Episode ID, for example tilte_maze_001_e000')
+    parser.add_argument('--list-instances', action='store_true',
+                        help='print all Instances and exit without opening pygame')
+    parser.add_argument('--list-episodes', action='store_true',
+                        help='print Episodes for --instance and exit without opening pygame')
+    parser.add_argument('--hz', type=float, default=20,
+                        help='display pacing; task physics timing stays unchanged')
+    parser.add_argument('--camera', help='initial camera name')
+    parser.add_argument('--fast-speed', type=float, default=1.0,
+                        help='fast target speed in m/s, (0, 2]; default 1.0')
+    return parser
+
+
+def main(argv=None):
+    parser = _parser()
+    args = parser.parse_args(argv)
+    if args.hz <= 0 or not np.isfinite(args.hz):
+        parser.error('hz must be positive')
+    if not np.isfinite(args.fast_speed) or not 0 < args.fast_speed <= 2:
+        parser.error('fast-speed must be in (0, 2] m/s')
+    if args.list_episodes and args.instance is None:
+        parser.error('--list-episodes requires --instance')
+    if not args.bank.is_file():
+        parser.error(f'bank file does not exist: {args.bank}')
+
+    try:
+        bank, manifest_path, manifest, groups = _records(args.bank)
+        if args.task is not None:
+            groups = [item for item in groups if item[0]['task_id'] == args.task]
+        if args.list_instances:
+            _print_instances(groups, args.task)
+            return 0
+        if args.list_episodes:
+            instance, episodes, _ = _select(groups, args.instance, args.episode, args.task)
+            _print_episodes(instance, episodes)
+            return 0
+        instance, episodes, episode_index = _select(
+            groups, args.instance, args.episode, args.task)
+    except (OSError, TypeError, ValueError, KeyError, ImportError, json.JSONDecodeError) as exc:
+        parser.error(str(exc))
+
+    # Import pygame and the simulator only after list-only commands have run.
+    try:
+        import pygame
+    except ImportError:
+        parser.error('install dependencies: python -m pip install -r requirements.txt')
+    from react_manip.instances.runtime import ReplayEnv
+    from react_manip.rendering import NativeRGBRenderer
+    from react_manip.cameras import display_camera_names
+
+    env = renderer = None
+    try:
+        pygame.init()
+        screen = pygame.display.set_mode((1120, 720))
+        pygame.display.set_caption('ReAct-Manip fixed task bank')
+        font = pygame.font.Font(None, 24)
+        clock = pygame.time.Clock()
+        renderer = NativeRGBRenderer()
+        keys = set()
+        active = 0
+        camera_index = 0
+        fast_latched = False
+        raw = arms = layout = grippers = manual = cameras = None
+        done, info = False, {}
+        group_index = next(i for i, (item, _) in enumerate(groups)
+                           if item["task_instance_id"] == instance["task_instance_id"])
+
+        def load_episode(new_group_index, new_episode_index):
+            """Close/recreate on Instance changes; bind/reset on Episode changes."""
+            nonlocal env, instance, episodes, episode_index, group_index
+            nonlocal raw, arms, layout, grippers, manual, done, info, cameras
+            nonlocal active, camera_index, fast_latched
+            new_instance, new_episodes = groups[new_group_index]
+            instance_changed = (env is None or
+                                instance["task_instance_id"] != new_instance["task_instance_id"])
+            instance, episodes = new_instance, new_episodes
+            episode_index = new_episode_index % len(episodes)
+            group_index = new_group_index
+            if instance_changed:
+                if env is not None:
+                    env.close()
+                env = ReplayEnv(instance, cameras=True)
+            env.bind(episodes[episode_index])
+            reset_result = env.reset()
+            info = reset_result[1] if isinstance(reset_result, tuple) and len(reset_result) == 2 else {}
+            raw = getattr(env, 'env', env)
+            robot = raw.robots[0]
+            arms = tuple(robot.arms)
+            layout = robot.composite_controller._action_split_indexes
+            grippers = {arm: -1.0 for arm in arms}
+            manual = KeyboardPoseControl(robot, raw.control_timestep, args.fast_speed)
+            fast_latched = False
+            done = False
+            active = 0
+            keys.clear()
+            cameras = list(display_camera_names(raw, include_legacy=True))
+            if not cameras:
+                cameras = ['__free__']
+            camera_index = cameras.index(args.camera) if args.camera in cameras else 0
+
+        def reset_episode():
+            load_episode(group_index, episode_index)
+
+        load_episode(group_index, episode_index)
+        running = True
+        while running:
+            for event in pygame.event.get():
+                if event.type == pygame.QUIT:
+                    running = False
+                elif event.type == pygame.KEYDOWN:
+                    if event.key == pygame.K_ESCAPE:
+                        running = False
+                    elif event.key == pygame.K_BACKSPACE:
+                        reset_episode()
+                    elif event.key == pygame.K_n:
+                        load_episode(group_index, episode_index + 1)
+                    elif event.key == pygame.K_p:
+                        load_episode(group_index, episode_index - 1)
+                    elif event.key == pygame.K_i:
+                        load_episode((group_index + 1) % len(groups), 0)
+                    elif event.key == pygame.K_o:
+                        load_episode((group_index - 1) % len(groups), 0)
+                    elif event.key == pygame.K_TAB:
+                        manual.stop()
+                        fast_latched = False
+                        active = (active + 1) % len(arms)
+                        keys.clear()
+                    elif event.key == pygame.K_f:
+                        fast_latched = not fast_latched
+                    elif event.key in (pygame.K_EQUALS, pygame.K_KP_PLUS, pygame.K_MINUS, pygame.K_KP_MINUS):
+                        sign = 1 if event.key in (pygame.K_EQUALS, pygame.K_KP_PLUS) else -1
+                        manual.fast_speed = float(np.clip(round(manual.fast_speed + sign * .05, 2), .05, 2.))
+                    elif event.key == pygame.K_SPACE:
+                        arm = arms[active]
+                        grippers[arm] = -grippers[arm]
+                    elif pygame.K_1 <= event.key <= pygame.K_9:
+                        index = event.key - pygame.K_1
+                        if index < len(cameras):
+                            camera_index = index
+                    elif event.key in (pygame.K_LEFTBRACKET, pygame.K_RIGHTBRACKET):
+                        camera_index = (camera_index + (1 if event.key == pygame.K_RIGHTBRACKET else -1)) % len(cameras)
+                    else:
+                        keys.add(event.key)
+                elif event.type == pygame.WINDOWFOCUSLOST:
+                    fast_latched = False
+                    keys.clear()
+                    manual.stop()
+                elif event.type == pygame.KEYUP:
+                    keys.discard(event.key)
+            if not running:
+                break
+
+            def axis(positive, negative):
+                return float((positive in keys) - (negative in keys))
+
+            target = np.array([
+                axis(pygame.K_RIGHT, pygame.K_LEFT), axis(pygame.K_UP, pygame.K_DOWN),
+                axis(pygame.K_PAGEUP, pygame.K_PAGEDOWN), axis(pygame.K_d, pygame.K_a),
+                axis(pygame.K_w, pygame.K_s), axis(pygame.K_e, pygame.K_q)])
+            fast = fast_latched or bool(keys & {pygame.K_LSHIFT, pygame.K_RSHIFT})
+            if not done:
+                action = manual.action(env.action_dim, layout, arms[active], target, grippers, fast=fast)
+                _, reward, terminated, truncated, info = env.step(action)
+                done = bool(terminated or truncated)
+
+            frame = renderer.render(raw.sim, cameras[camera_index])
+            screen.fill((20, 24, 30))
+            screen.blit(pygame.surfarray.make_surface(frame.transpose(1, 0, 2)), (0, 0))
+            score = next((info[k] for k in ('task_score', 'total_score', 'score', 'S') if k in info), '--')
+            lines = [
+                f"Task: {instance['task_id']}",
+                f"Instance: {instance['task_instance_id']} ({group_index + 1}/{len(groups)})",
+                f"Episode: {episodes[episode_index]['episode_id']} ({episode_index + 1}/{len(episodes)})",
+                f'Robot: {instance["robot_id"]}  Arm: {arms[active]}',
+                f'Camera: {cameras[camera_index]}', f'Score: {score}',
+                f"Mode: {'FAST' if fast else 'FINE'}  Target: {manual.fast_speed if fast else .06:.2f} m/s",
+                'Arrows / PgUp PgDn: translation', 'A D / W S / Q E: rotation',
+                'F: toggle fast; Shift: hold fast', f'+/-: fast target {manual.fast_speed:.2f} m/s',
+                'Space: gripper    Tab: switch arm', '1-9 / [ ]: cameras',
+                'N/P: next/previous Episode    I/O: next/previous Instance',
+                'Backspace: reset    Esc: quit',
+                'Episode ended. N/P or Backspace to continue.' if done else 'Manual control',
+            ]
+            for index, line in enumerate(lines):
+                screen.blit(font.render(line, True, (235, 235, 235)), (650, 20 + index * 29))
+            prompt = str(info.get('language_prompt', ''))
+            words = prompt.split()
+            line, rows = '', []
+            for word in words:
+                candidate = (line + ' ' + word).strip()
+                if font.size(candidate)[0] > 1080 and line:
+                    rows.append(line)
+                    line = word
+                else:
+                    line = candidate
+            if line:
+                rows.append(line)
+            for index, line in enumerate(rows[:6]):
+                screen.blit(font.render(line, True, (235, 235, 235)), (20, 510 + index * 28))
+            pygame.display.flip()
+            clock.tick(args.hz)
+        return 0
+    finally:
+        if renderer is not None:
+            renderer.close()
+        if env is not None:
+            env.close()
+        pygame.quit()
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())