A C++ library bridging MuJoCo physics simulation with KDL for robot kinematics and dynamics.
Screenshots
 ex_gravity_comp — Single arm, KDL gravity compensation |  ex_table_scene — Arm + table + scene objects |
 ex_pick — Pick-and-place with Robotiq 2F-85 |  ex_dual_arm — Dual arm + grippers |
Features
- Scene builder – compose MJCF robots, grippers, objects, and cameras into one MuJoCo scene via mjSpec, with ordered attachment chains and relative placement.
- Multi-robot – multiple robots with independent KDL chains in one simulation.
- KDL from the model – builds the KDL chain directly from the compiled MuJoCo model.
- Control – POSITION / TORQUE ports plus KDL FK, IK, RNEA, and ACHD solvers.
- Runtime environments – Env with reset hooks for task setup and replay.
- Interactive viewer – MuJoCo simulate UI with Frames / Trace / Perturb panels and overlay lines.
- Recording – interactive and headless EGL + ffmpeg MP4 capture.
- Python bindings – the same API from Python via pip install, returning PyKDL types.
Install
Ubuntu/Debian. Requires MuJoCo 3.9.0 (auto-downloaded), CMake >= 3.16, a C++20 compiler, and (for Python) Python >= 3.10. The secorolab Orocos KDL fork is built from source; the system KDL is never used.
Full details and every flag are in the installation guides:
- Standalone Installation Guide – C++ and Python, no ROS
- ROS 2 Installation Guide – colcon, C++ and Python
System packages
C++ (CMake)
To share one KDL across several projects, set up a ws/ folder, build the fork once into ws/install, and point the wrapper (and any sibling) at it instead of bundling its own:
The standalone guide covers tests, custom MuJoCo/KDL, sharing one KDL across projects, and all CMake options.
Python
Installing without a @tag tracks the main branch, which only advances at releases - so the default command above already installs the latest release.
Bundles MuJoCo, the KDL fork, and PyKDL. See the standalone guide for editable installs, Menagerie models, and build options.
The example scripts ship in the wheel. Copy them out, populate the cache, and run one (the scripts resolve models and bundled assets from the cache, so they run from anywhere):
ROS 2 (colcon)
Tested on ROS 2 Jazzy and Lyrical. Build the secorolab KDL as its own workspace package, then the wrapper against it so the overlay shares one liborocos-kdl:
The ROS 2 guide covers the Python venv, the shared-KDL rationale, build ordering, and consuming it from your own nodes.
API
- C++ API guide
- Python Bindings API Guide
- Generated C++ and Python API reference: build/docs/html/index.html (build with cmake -B build -DBUILD_DOCS=ON && cmake --build build --target docs)
Examples
The example catalog lives in docs/examples.md. Every C++ src/examples/ex_*.cpp example has a same-name Python counterpart in python/examples/, including the named force-torque admittance demos: ex_admittance_ft, ex_admittance_ft_rnea, and ex_admittance_ft_achd.
Tests
Tests resolve the Menagerie models and bundled assets from the user cache (~/.cache/mj_kdl_wrapper); -DMJ_KDL_FETCH_MENAGERIE=ON at configure populates it, and tests self-skip when it is empty. See test/README.md for the full list.
More Documentation
Assets
These ship in the repo and the wheel, and are copied into the user cache (~/.cache/mj_kdl_wrapper/assets) by -DMJ_KDL_FETCH_MENAGERIE=ON or mj-kdl-fetch-menagerie. Examples and tests resolve them from the cache via mj_kdl_examples::asset(...) (C++) and menagerie.asset_path(...) (Python).
| Path | Description |
|---|---|
| assets/robotiq_2f85/2f85.xml | Local Robotiq 2F-85 gripper asset used by examples/tests |
| assets/ft_sensor.xml | Local 6-axis force-torque sensor asset used by FT examples/tests |
| assets/table.xml | Table asset with authored table_top site |
| assets/mug.xml, assets/mug_table.xml | Pouring example assets |
