# continuumroboticslab/opencr-mujoco architecture

> Architecture diagram of the GitHub repository continuumroboticslab/opencr-mujoco, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/continuumroboticslab/opencr-mujoco
- Repository: https://github.com/continuumroboticslab/opencr-mujoco

## Overview

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.

Main entry points: [`tests`](https://github.com/continuumroboticslab/opencr-mujoco/tree/main/tests) (Tests), [`opencr_mujoco/sysid`](https://github.com/continuumroboticslab/opencr-mujoco/tree/main/opencr_mujoco/sysid) (SysID), [`opencr_mujoco/generators`](https://github.com/continuumroboticslab/opencr-mujoco/tree/main/opencr_mujoco/generators) (Generators), [`opencr_mujoco/controllers`](https://github.com/continuumroboticslab/opencr-mujoco/tree/main/opencr_mujoco/controllers) (Controllers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrypoints["Entry Points"]
  node_generate_py["generate.py<br/>CLI generator<br/>[generate.py]"]
  node_teleop_py["teleop.py<br/>CLI teleop<br/>[teleop.py]"]
  node_viewer_py["viewer.py<br/>CLI viewer<br/>[viewer.py]"]
  node_sysid_pipeline_py["sysid_pipeline.py<br/>CLI sysid<br/>[sysid_pipeline.py]"]
  node_trace_tip_demo_py["trace_tip_demo.py<br/>Demo script<br/>[trace_tip_demo.py]"]
end

subgraph group_core["Core Package"]
  node_generators_pkg["Generators<br/>Scene synthesis"]
  node_tdcr_kinematics_pkg["Kinematics<br/>TDCR math"]
  node_controllers_pkg["Controllers<br/>Control stack"]
  node_utils_pkg["Utilities<br/>Input/config"]
  node_dynamixel_bridge_pkg["Dynamixel bridge<br/>Hardware bridge"]
  node_sysid_pkg["SysID<br/>Calibration pipeline"]
end

subgraph group_data["Assets & Data"]
  node_assets_dir[("Assets<br/>MuJoCo scenes")]
  node_configs_dir["Configs<br/>Control plane"]
  node_reference_data[("Reference data<br/>Benchmark data")]
  node_sysid_data[("SysID data<br/>Recorded runs")]
end

subgraph group_validation["Validation"]
  node_evaluation_pkg["Evaluation<br/>Metrics/plots"]
  node_paper_results_dir["Paper results<br/>Repro scripts"]
  node_tests_dir["Tests<br/>Verification"]
end

subgraph group_docs["Web Demo"]
  node_docs_site["Docs site<br/>Web demo"]
end

node_generate_py -->|"invokes"| node_generators_pkg
node_generate_py -->|"reads"| node_configs_dir
node_generators_pkg -->|"writes scenes"| node_assets_dir
node_generators_pkg -->|"uses math"| node_tdcr_kinematics_pkg
node_teleop_py -->|"drives"| node_controllers_pkg
node_teleop_py -->|"uses inputs"| node_utils_pkg
node_teleop_py -->|"reads"| node_configs_dir
node_controllers_pkg -->|"commands"| node_tdcr_kinematics_pkg
node_controllers_pkg -.->|"can bridge"| node_dynamixel_bridge_pkg
node_viewer_py -->|"loads"| node_assets_dir
node_viewer_py -->|"reads"| node_configs_dir
node_trace_tip_demo_py -->|"assembles"| node_generators_pkg
node_trace_tip_demo_py -->|"runs"| node_controllers_pkg
node_sysid_pipeline_py -->|"orchestrates"| node_sysid_pkg
node_sysid_pkg -->|"ingests"| node_sysid_data
node_sysid_pkg -->|"reads"| node_configs_dir
node_sysid_pkg -->|"evaluates"| node_evaluation_pkg
node_evaluation_pkg -->|"loads"| node_reference_data
node_paper_results_dir -->|"reuses"| node_evaluation_pkg
node_paper_results_dir -->|"compares"| node_reference_data
node_docs_site -->|"bundles"| node_assets_dir
node_docs_site -->|"reuses"| node_utils_pkg
node_tests_dir -->|"covers"| node_generators_pkg
node_tests_dir -->|"covers"| node_controllers_pkg
node_tests_dir -->|"covers"| node_evaluation_pkg
node_tests_dir -->|"covers"| node_sysid_pkg
node_tests_dir -->|"covers"| node_viewer_py

click node_generate_py "https://github.com/continuumroboticslab/opencr-mujoco/blob/main/generate.py"
click node_teleop_py "https://github.com/continuumroboticslab/opencr-mujoco/blob/main/teleop.py"
click node_viewer_py "https://github.com/continuumroboticslab/opencr-mujoco/blob/main/viewer.py"
click node_sysid_pipeline_py "https://github.com/continuumroboticslab/opencr-mujoco/blob/main/sysid_pipeline.py"
click node_trace_tip_demo_py "https://github.com/continuumroboticslab/opencr-mujoco/blob/main/examples/trace_tip_demo.py"
click node_generators_pkg "https://github.com/continuumroboticslab/opencr-mujoco/tree/main/opencr_mujoco/generators"
click node_tdcr_kinematics_pkg "https://github.com/continuumroboticslab/opencr-mujoco/tree/main/opencr_mujoco/tdcr_kinematics"
click node_controllers_pkg "https://github.com/continuumroboticslab/opencr-mujoco/tree/main/opencr_mujoco/controllers"
click node_utils_pkg "https://github.com/continuumroboticslab/opencr-mujoco/tree/main/opencr_mujoco/utils"
click node_dynamixel_bridge_pkg "https://github.com/continuumroboticslab/opencr-mujoco/tree/main/opencr_mujoco/dynamixel_bridge"
click node_evaluation_pkg "https://github.com/continuumroboticslab/opencr-mujoco/tree/main/opencr_mujoco/evaluation"
click node_sysid_pkg "https://github.com/continuumroboticslab/opencr-mujoco/tree/main/opencr_mujoco/sysid"
click node_paper_results_dir "https://github.com/continuumroboticslab/opencr-mujoco/tree/main/paper_results"
click node_assets_dir "https://github.com/continuumroboticslab/opencr-mujoco/tree/main/assets"
click node_configs_dir "https://github.com/continuumroboticslab/opencr-mujoco/tree/main/configs"
click node_reference_data "https://github.com/continuumroboticslab/opencr-mujoco/tree/main/data/reference/sorosim"
click node_sysid_data "https://github.com/continuumroboticslab/opencr-mujoco/tree/main/data/sysid"
click node_docs_site "https://github.com/continuumroboticslab/opencr-mujoco/tree/main/docs"
click node_tests_dir "https://github.com/continuumroboticslab/opencr-mujoco/tree/main/tests"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_generate_py,node_teleop_py,node_viewer_py,node_sysid_pipeline_py,node_trace_tip_demo_py toneBlue
class node_generators_pkg,node_tdcr_kinematics_pkg,node_controllers_pkg,node_utils_pkg,node_dynamixel_bridge_pkg,node_sysid_pkg toneAmber
class node_assets_dir,node_configs_dir,node_reference_data,node_sysid_data toneMint
class node_evaluation_pkg,node_paper_results_dir,node_tests_dir toneRose
class node_docs_site toneIndigo
```

## Components

### Entry Points

Thin scripts that assemble the package into workflows

- [generate.py](https://github.com/continuumroboticslab/opencr-mujoco/blob/main/generate.py): CLI generator · Top-level scene generation entry point · `generate.py`
- [teleop.py](https://github.com/continuumroboticslab/opencr-mujoco/blob/main/teleop.py): CLI teleop · Interactive control entry point · `teleop.py`
- [viewer.py](https://github.com/continuumroboticslab/opencr-mujoco/blob/main/viewer.py): CLI viewer · Passive MuJoCo scene viewer · `viewer.py`
- [sysid_pipeline.py](https://github.com/continuumroboticslab/opencr-mujoco/blob/main/sysid_pipeline.py): CLI sysid · System identification pipeline entry point · `sysid_pipeline.py`
- [trace_tip_demo.py](https://github.com/continuumroboticslab/opencr-mujoco/blob/main/examples/trace_tip_demo.py): Demo script · Example runtime demo · `examples/trace_tip_demo.py`

### Core Package

Primary library code for modeling, control, and analysis

- [Generators](https://github.com/continuumroboticslab/opencr-mujoco/tree/main/opencr_mujoco/generators): Scene synthesis · Builds TDCR MuJoCo scenes from configuration · `opencr_mujoco/generators`
- [Kinematics](https://github.com/continuumroboticslab/opencr-mujoco/tree/main/opencr_mujoco/tdcr_kinematics): TDCR math · Continuum-robot kinematics used by controllers and generation · `opencr_mujoco/tdcr_kinematics`
- [Controllers](https://github.com/continuumroboticslab/opencr-mujoco/tree/main/opencr_mujoco/controllers): Control stack · Joint, task-space, IK, and combined control logic · `opencr_mujoco/controllers`
- [Utilities](https://github.com/continuumroboticslab/opencr-mujoco/tree/main/opencr_mujoco/utils): Input/config · Shared config loading and input-device adapters · `opencr_mujoco/utils`
- [Dynamixel bridge](https://github.com/continuumroboticslab/opencr-mujoco/tree/main/opencr_mujoco/dynamixel_bridge): Hardware bridge · Optional bridge from teleop commands to physical actuators · `opencr_mujoco/dynamixel_bridge`
- [SysID](https://github.com/continuumroboticslab/opencr-mujoco/tree/main/opencr_mujoco/sysid): Calibration pipeline · Parameter estimation, optimization, and model validation · `opencr_mujoco/sysid`

### Assets & Data

Static MuJoCo assets, configs, and reference datasets

- [Assets](https://github.com/continuumroboticslab/opencr-mujoco/tree/main/assets): MuJoCo scenes · Static Franka and TDCR scene assets plus meshes · `assets`
- [Configs](https://github.com/continuumroboticslab/opencr-mujoco/tree/main/configs): Control plane · Named configuration sets for generation, teleop, viewer, evaluation, and sysid · `configs`
- [Reference data](https://github.com/continuumroboticslab/opencr-mujoco/tree/main/data/reference/sorosim): Benchmark data · Bundled SoRoSim reference statics and dynamics datasets · `data/reference/sorosim`
- [SysID data](https://github.com/continuumroboticslab/opencr-mujoco/tree/main/data/sysid): Recorded runs · Motion-capture and derived analysis CSVs for calibration · `data/sysid`

### Validation

Tests and paper-result workflows that exercise the stack

- [Evaluation](https://github.com/continuumroboticslab/opencr-mujoco/tree/main/opencr_mujoco/evaluation): Metrics/plots · Reference-data loading, metrics, and visualization · `opencr_mujoco/evaluation`
- [Paper results](https://github.com/continuumroboticslab/opencr-mujoco/tree/main/paper_results): Repro scripts · Batch workflows for statics, dynamics, and sysid figures · `paper_results`
- [Tests](https://github.com/continuumroboticslab/opencr-mujoco/tree/main/tests): Verification · CLI, generator, teleop, viewer, evaluation, and sysid checks · `tests`

### Web Demo

Browser deployment and supporting runtime files

- [Docs site](https://github.com/continuumroboticslab/opencr-mujoco/tree/main/docs): Web demo · Browser-based MuJoCo deployment and served scenes · `docs`

## Connections

- generate.py → Generators: invokes · CLI drives scene synthesis
- generate.py → Configs: reads · Uses generation configs and overrides
- Generators → Assets: writes scenes · Emits generated XML under robot assets
- Generators → Kinematics: uses math · Shares continuum formulations for layout and routing
- teleop.py → Controllers: drives · Interactive runtime control
- teleop.py → Utilities: uses inputs · Keyboard and DualSense adapters
- teleop.py → Configs: reads · Teleop modes and bindings
- Controllers → Kinematics: commands · Maps targets to tendon/joint commands
- Controllers → Dynamixel bridge: can bridge · Optional hardware actuation path
- viewer.py → Assets: loads · Opens static or generated MuJoCo scenes
- viewer.py → Configs: reads · Viewer presets
- trace_tip_demo.py → Generators: assembles · Demo uses generated TDCR scenes
- trace_tip_demo.py → Controllers: runs · Demo control loop
- sysid_pipeline.py → SysID: orchestrates · Multi-stage calibration flow
- SysID → SysID data: ingests · Consumes recorded motion-capture CSVs
- SysID → Configs: reads · Pipeline and parameter configs
- SysID → Evaluation: evaluates · Compares simulated and observed trajectories
- Evaluation → Reference data: loads · Benchmarks against SoRoSim data
- Paper results → Evaluation: reuses · Publication-style analysis and plots
- Paper results → Reference data: compares · Static and dynamic reference comparisons
- Docs site → Assets: bundles · Tracks scene copies and meshes for browser demo
- Docs site → Utilities: reuses · Browser input/runtime glue mirrors desktop tooling
- Tests → Generators: covers · Scene generation behavior
- Tests → Controllers: covers · Teleop and controller behavior
- Tests → Evaluation: covers · Metrics and validation correctness
- Tests → SysID: covers · Pipeline and CLI behavior
- Tests → viewer.py: covers · Viewer correctness checks