continuumroboticslab/opencr-mujoco

1. Repository shape

This is a Python/MuJoCo robotics repository centered on tendon-driven continuum robots (TDCRs). The core package is opencr_mujoco, and the top-level scripts (generate.py, teleop.py, viewer.py, sysid_pipeline.py, examples/trace_tip_demo.py, and paper_results/*) are thin application entry points that assemble the package into different workflows.

2. Core simulation model

The main architecture is a discretized continuum backbone: each TDCR is represented as a serial chain of rigid links with elastic hinge joints, while tendons are routed through MuJoCo tendon elements. This is the fundamental simulation boundary: geometry, stiffness, and tendon routing are encoded in MuJoCo XML scenes and executed by MuJoCo at runtime.

3. Model generation pipeline

opencr_mujoco/generators plus configs/generation/* define how robot scenes are synthesized from configuration. Generated TDCR scene XMLs are written under assets/tdcr/ on demand, and the generator supports multiple segment counts, modular heterogeneous segments, tendon routing variants, pretension keyframes, and collision exclusions.

4. Shared configuration layer

Most user-facing tools use the same config convention: CLI arguments override named config files, which override built-in defaults. The config namespaces under configs/generation, configs/teleop, configs/viewer, configs/evaluation, and configs/sysid are the control plane that keeps the scripts consistent across generation, simulation, teleoperation, and analysis.

5. Control and teleoperation subsystem

teleop.py is the runtime control front-end. It connects input devices from opencr_mujoco/utils and opencr_mujoco/controllers to robot commands, supporting keyboard and DualSense inputs, TDCR joint/task-space control, IK-based control, multi-point task-space control, homing, and combined Franka + TDCR operation.

6. Kinematics boundary

opencr_mujoco/tdcr_kinematics provides the continuum-robot math used by controllers and some generation logic. It contains multi-segment formulations, tension-aware variants, and wrappers for common robot layouts, bridging high-level target commands to tendon/joint commands that MuJoCo can apply.

7. Scene composition and assets

The repository ships reusable MuJoCo assets for the Franka Panda arm and several TDCR scene definitions in assets/. These XML and mesh assets are the static simulation boundary; higher-level tools select or generate scenes from them, while viewer.py and teleop/demo scripts load them directly.

8. Evaluation and validation against reference physics

opencr_mujoco/evaluation and paper_results/ form the validation layer. They compare MuJoCo simulations against bundled SoRoSim reference data in data/reference/sorosim, covering statics and tip-release dynamics, computing shape/trajectory metrics, and generating publication-style plots and reports.

9. System identification pipeline

opencr_mujoco/sysid and sysid_pipeline.py implement a multi-stage calibration flow for hardware-backed models. The pipeline ingests motion-capture CSVs from data/sysid, estimates geometry and tendon-related parameters, runs trajectory simulation and optimization, and produces refined parameter sets plus analysis artifacts.

10. Hardware bridge

opencr_mujoco/dynamixel_bridge is an optional boundary to real actuators. It mirrors teleoperation outputs to a physical TDCR through the Dynamixel SDK, keeping the simulation/control stack separate from the hardware actuation layer.

11. Interactive viewing and browser deployment

viewer.py is the passive MuJoCo scene viewer for inspecting any model, while docs/ packages a browser-based version of the same simulator. The docs site uses bundled Python extras, Pyodide/WASM glue, and tracked scene copies under docs/scenes/ so GitHub Pages can serve a runnable demo without the full desktop environment.

12. Validation and developer harness

The tests/ directory exercises generation, scene creation, evaluation, teleop, sysid CLI behavior, and viewer correctness. CI and local test scripts are part of the repo’s architectural boundary: they protect the generator, control, and analysis layers from diverging as the MuJoCo models evolve.