Closed-loop figure-8 tip tracing · station-keeping
against arm motion · an elastic whip kick into the
goal — all from
examples/trace_tip_demo.py
(HQ · HQ · HQ)
Native MuJoCo simulation of tendon-driven continuum robots (TDCRs) by discretizing the continuum backbone into a serial chain of rigid links with elastic joints.
The backbone rod is split into N links bounded by half-links, joined by
hinge pairs (or triples, adding torsion) whose stiffness comes from beam
theory (N·EI/L per joint, G·J for torsion), with tendons routed through
per-link sites and actuated natively by MuJoCo's tendon model. The approach is
validated against SoRoSim
Cosserat-rod solutions (statics and dynamics) and supports system
identification against hardware motion-capture data.
- Unified TDCR generator — single config-driven generator for 1–5 segment TDCRs with 3–4+ tendons per segment, material-based (Young's modulus) or direct stiffness, coupled / independent / tension tendon routing, pretension keyframes, and collision exclusions
- Modular (heterogeneous) TDCRs — compose robots from reusable modules with independent materials and geometry (e.g. stiff base, soft tip)
- Evaluation framework — statics and tip-release dynamics compared against bundled SoRoSim reference data, with arc-length-correct shape errors and publication-quality figures
- Teleoperation — keyboard and PlayStation DualSense control of the TDCR, a Franka Panda arm, or both combined (joint-space, task-space IK, and multi-point task-space modes)
- System identification — 3-step pipeline (geometry → tendon parameters → refinement) calibrating simulation parameters against hardware mocap data (bundled for two hardware TDCRs)
- Hardware bridge — optional Dynamixel bridge mirroring teleop commands to a real TDCR
git clone https://github.com/ContinuumRoboticsLab/opencr-mujoco.git
cd opencr-mujoco
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e . # editable install
pip install -e ".[dev]" # + pytest/black/flake8
pip install -e ".[hardware]" # + Dynamixel SDK (real-robot bridge)Requires Python 3.10+ and MuJoCo ≥ 3.0 (installed automatically from pip).
macOS: run the GUI commands below (
teleop.py,viewer.py, and the live demo) withmjpythoninstead ofpython— MuJoCo's passive viewer requires it. Plainpythonis fine for--list-configs,--headless, and--record.
# Drive a TDCR (hold LSHIFT, then T/F/G/H to bend, Z/X/C to switch segment).
# Scene XMLs are generated automatically on first use — no setup step.
python teleop.py --config tdcr_keyboard
# ...or watch the gallery demos live (--record <name> re-renders the clips)
python examples/trace_tip_demo.py --demo kick
# Look at any model in the passive viewer
python viewer.py --scene assets/tdcr/example_three_segment_franka.xml
# Reproduce the validation against SoRoSim
python paper_results/evaluate.py --config spring_steel_statics --n-values 50 --early-stop 20Every script documents itself — start with --help and the usage block at
the top of the file. The scripts share a JSON config system with precedence
CLI args > config file > built-in defaults; all expose --list-configs
and --config NAME, and viewer.py/teleop.py additionally support
--show-config and --save-config NAME.
| Topic | Start here |
|---|---|
| Model generation & config options | generate.py · configs/generation/README.md |
| Teleoperation, keyboard/DualSense controls | teleop.py (control tables in the docstring) |
| Scene viewer | viewer.py |
| Demos (the GIFs above) | examples/trace_tip_demo.py |
| SoRoSim validation & paper figures | paper_results/README.md |
| System identification | opencr_mujoco/sysid/README.md |
| Controllers & Clark-coordinate control | opencr_mujoco/controllers/README.md |
| Bundled reference / mocap data formats | data/reference/sorosim/README.md |
| Tests & development tooling | tests/README.md — python run_tests.py |
Install the development extra before working on the code:
pip install -e ".[dev]"Useful checks:
black .
flake8 . --count --statistics
python run_tests.py --quick
pytest tests/unit -qThe browser demo is generated from the same Python sources used by the desktop tools. Rebuild and serve it locally with:
python docs/build_site.py
python docs/serve.py 8000Generated TDCR scene XMLs under assets/tdcr/ are intentionally not tracked;
the command-line tools regenerate them from configs/generation/ on first use.
The small web-demo scene copies under docs/scenes/ are tracked so GitHub
Pages can serve the browser simulator. Large policy-rollout videos are hosted
as GitHub Release assets and should not be committed.
opencr-mujoco is an open academic project, and we welcome contributions from
the community, including:
- Pull requests for new features, bug fixes, examples, or documentation.
- Bug reports through GitHub Issues.
- Suggestions that make the simulator easier to install, reproduce, or extend.
- New CR configurations, validation cases, or controller/evaluation tests.
See our contribution guide for development setup, testing, and repository hygiene notes.
MIT License — see LICENSE. The bundled Franka Panda meshes under
assets/franka_assets/ are from franka_ros (Apache 2.0 — see
assets/franka_assets/LICENSE.md).
- Franka robot assets from franka_ros
- SoRoSim reference data generated with SoRoSim


