EmbodiK
EmbodiK is a high-performance prioritized numerical inverse kinematics library for cross-embodiment robotics and VLA/AI applications. It pairs a C++ core with Python bindings, exposes robot-model utilities without requiring the Python pin package at runtime, and includes interactive examples for collision-aware IK, CoM constraints, teleop, whole-body robots, GPU batch solving, and dual-arm coordination.
✨ Overview
EmbodiK is designed for bringing up IK behavior across different robot bodies without rewriting the solver stack for each model. The public examples focus on a practical path:
- 🧭 start with the smallest fixed-base IK loop.
- 🛡️ add collision, joint-limit, and CoM constraints.
- 🎮 connect the same prioritized IK solver path to teleop input.
- 🤖 scale to bimanual, humanoid, and Spot whole-body examples.
- 🧪 use richer clone-only examples for development, stress testing, and policy rollout.
The intent is to keep Python examples lean: visualization and target plumbing stay in Python, while constraint handling and recovery policy stay in the C++ solver.
The detailed installation notes, API reference, and example walkthroughs live in the official documentation:
https://robodreamer.github.io/embodik/
🚀 Quick Start
Fastest path for most users is the wheel-only PyPI install inside a virtual environment:
python -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install --only-binary=:all: embodik
python -c "import embodik; print(embodik.__version__)"
If that import works, the core package is installed.
If pip cannot find a compatible wheel, use the one-shot source installer for your platform from the Installation Guide. It creates the venv, installs native dependencies, builds EmbodiK, and runs an import smoke test.
To run copied examples from the same venv:
python -m pip install "embodik[examples]"
embodik-examples --copy
cd embodik_examples
python 01_basic_ik_simple.py
Published repaired wheels do not require the Python pin package at runtime.
Source builds use pin or a system Pinocchio install as the native library
provider; keep that provider installed in the environment used to import
EmbodiK.
🎮 Examples
The pip-facing examples are intentionally split by purpose:
| Script | Purpose |
|---|---|
01_basic_ik_simple.py |
Minimal fixed-base IK bring-up for a robot preset or new URDF. |
02_collision_aware_IK.py |
Collision-aware IK behavior demo and advanced tuning surface. |
03_teleop_ik.py |
Small adapter showing how teleop input drives the same IK solver path. |
04_com_constraint_example.py |
CoM support-polygon constraint visualization. |
05_dual_arm_ects.py |
Dual-arm ECTS and orthogonal coordination modes. |
06_bimanual_whole_body_ik.py |
Bimanual whole-body teleop, defaulting to AI Worker and optionally supporting RB-Y1, with CoM, collision handling, torso gizmo control, torso/arm contribution controls, adaptive tuning, and optional Seer input. |
07_unitree_g1_retargeting_ik.py |
Unitree G1 whole-body retargeting IK with CoM and optional collision handling. |
08_spot_full_body_ik_viser.py |
Spot full-body IK in regular Viser with arm+torso, torso-only, full-body, and two-stage modes. |
09_spot_locomanip_mjviser.py |
Spot locomanipulation ONNX policy rollout in MuJoCo through mjviser. |
Run them from a copied example directory:
python 02_collision_aware_IK.py
python 03_teleop_ik.py
python 06_bimanual_whole_body_ik.py
python 07_unitree_g1_retargeting_ik.py
python 08_spot_full_body_ik_viser.py
For Seer/xvisio controller input in the public teleop examples, install the teleop extra and pass the controller port:
python -m pip install "embodik[examples,teleop]"
python 06_bimanual_whole_body_ik.py --controller-port /dev/ttyUSB0
The regular Viser Spot full-body IK example uses the standard example
dependencies and includes a bundled Spot-with-arm URDF. The
MuJoCo/mjviser locomanipulation example needs the optional mjviser stack and
includes a bundled public MuJoCo Menagerie Spot-with-arm MJCF scene.
mjviser is the MuJoCo-backed web viewer environment for policy rollout and
interactive simulation. mjviser-teleop is the same viewer stack plus the
optional Seer/xvisio controller dependencies, so use it only when running
--enable-teleop:
python -m pip install "embodik[mjviser]"
embodik-examples --copy
cd embodik_examples
python 09_spot_locomanip_mjviser.py --policy locomanip
python 09_spot_locomanip_mjviser.py --policy locomanip-stationary
# add the optional Seer controller extra when needed:
python -m pip install "embodik[mjviser,teleop]"
python 09_spot_locomanip_mjviser.py --enable-teleop --policy locomanip
From a repository checkout, run the same example from the repository root with the matching Pixi environment and task:
pixi run -e mjviser spot-locomanip-mjviser --policy locomanip
pixi run -e mjviser-teleop spot-locomanip-mjviser --enable-teleop --policy locomanip
Use the spot-locomanip-mjviser Pixi task from a checkout, not raw
pixi run -e mjviser-teleop python examples/09_spot_locomanip_mjviser.py, on
a fresh environment. The task depends on install, so it builds/installs the
native EmbodiK extension before launching the example.
See the Spot locomanipulation guide for mjviser, Seer teleop, solver tuning, and headless validation details.
Most examples default to the Panda preset. Use --robot <key> when a script supports alternate robot presets. See the Examples Guide for the full catalog, helper conventions, and clone-only development examples.
🎬 Preview
Franka Panda collision-free IK
ROBOTIS AI Worker constraint teleop
RB-Y1 bimanual whole-body IK
Unitree G1 retargeting IK
Spot full-body IK
Spot locomanipulation mjviser
🧰 Core Capabilities
- ⚙️ C++ IK core with Nanobind Python bindings.
- 🎯 Hierarchical velocity IK tasks for frames, posture, CoM, and dual-arm coordination.
- 🧮 Fixed-base acceleration eSNS with compatible position, velocity, acceleration, effort, contact-kinematics, and geometry constraints.
- 🛡️ Joint-limit, self-collision, and CoM support-polygon constraints.
- 📈 Solver diagnostics for timing, task scaling, and Jacobian condition-number logging.
- 🧭 Lie-group-aware configuration operations for floating-base, quaternion, and continuous joints.
- 🤖 Native Pinocchio-backed robot model utilities exposed through EmbodiK bindings.
- 👁️ Optional Viser visualization for interactive IK demos.
- ⚡ Experimental GPU batch IK and collision tooling for high-throughput research workflows.
📚 Documentation
- Installation - platform setup, source builds, and troubleshooting.
- Quickstart - first IK calls and solver concepts.
- Acceleration Solver - fixed-base scope, state-box semantics, and collision certification boundaries.
- Working with Transforms - transform helpers and SE(3) operations.
- Examples - public scripts and development-only demos.
- API Reference - Python API generated from docstrings.
- GPU Solvers - FI-PeSNS and PPH-SNS batch solver notes.
- Development - local build, tests, and contributor workflow.
🛠️ Development
Use Pixi from a repository clone:
pixi run build
pixi run test
pixi run docs-build
Run examples from the clone:
pixi run python examples/01_basic_ik_simple.py
pixi run python examples/02_collision_aware_IK.py
pixi run python examples/03_teleop_ik.py
🗂️ Repository Layout
embodik/
|-- README.md
|-- cpp_core/
| |-- include/embodik/
| `-- src/
|-- python_bindings/
| `-- src/
|-- python/embodik/
|-- examples/
|-- docs/
|-- scripts/
`-- test/
⭐ Star History
📄 License
EmbodiK is released under the Apache License 2.0. See LICENSE for details. Binary wheels may bundle permissively licensed native dependencies; see THIRD_PARTY_NOTICES.md.
Developer: Andy Park andypark.purdue@gmail.com
1 maintainer
Release files for embodik 0.22.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| embodik-0.22.0.tar.gz | 37.4 MB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| embodik-0.22.0-cp312-cp312-manylinux_2_28_x86_64.whl | CPython 3.12 | CPython 3.12 | Linux glibc 2.28+ x86-64 | Details |
| embodik-0.22.0-cp312-cp312-macosx_14_0_arm64.whl | CPython 3.12 | CPython 3.12 | macOS 14.0+ ARM64 | Details |
| embodik-0.22.0-cp311-cp311-manylinux_2_28_x86_64.whl | CPython 3.11 | CPython 3.11 | Linux glibc 2.28+ x86-64 | Details |
| embodik-0.22.0-cp311-cp311-macosx_14_0_arm64.whl | CPython 3.11 | CPython 3.11 | macOS 14.0+ ARM64 | Details |
| embodik-0.22.0-cp310-cp310-manylinux_2_28_x86_64.whl | CPython 3.10 | CPython 3.10 | Linux glibc 2.28+ x86-64 | Details |
| embodik-0.22.0-cp310-cp310-macosx_14_0_arm64.whl | CPython 3.10 | CPython 3.10 | macOS 14.0+ ARM64 | Details |
Total release size: 259.4 MB
Release files / embodik-0.22.0.tar.gz
| Download URL | embodik-0.22.0.tar.gz |
|---|---|
| Size | 37.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ae08f01585430530d01244dd9afde521480d9dd719716a6fef0ec9fa1238ae13
|
|
BLAKE2b-256 checksum How to use checksums |
ae5c0771b8a416b5a26d0635dbb24c1fe91d80f9442e53695b051d8cc238544b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency logRelease files / embodik-0.22.0-cp312-cp312-manylinux_2_28_x86_64.whl
| Download URL | embodik-0.22.0-cp312-cp312-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 28.8 MB |
| Tags | CPython 3.12 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
56c6568feb67294fdc371d42514207dc70975672419d391ff8a9f31a7d7ce81c
|
|
BLAKE2b-256 checksum How to use checksums |
53776ded9ed6c0360964e17ba1d3e8adbb3b58f59dc308285946125b628b6535
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency logRelease files / embodik-0.22.0-cp312-cp312-macosx_14_0_arm64.whl
| Download URL | embodik-0.22.0-cp312-cp312-macosx_14_0_arm64.whl |
|---|---|
| Size | 45.2 MB |
| Tags | CPython 3.12 macOS 14.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
c2a2f9e65be827217f748c4e03d821f470d138b32c8d5835339ea8c75e16b435
|
|
BLAKE2b-256 checksum How to use checksums |
1a0a89812807987edb44e6de9470bd69ce3d9e185691e0ca7e700a854db0fab7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency logRelease files / embodik-0.22.0-cp311-cp311-manylinux_2_28_x86_64.whl
| Download URL | embodik-0.22.0-cp311-cp311-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 28.8 MB |
| Tags | CPython 3.11 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
dda6cb6555cc09742cfe3ca19dc07e0090288a1b3913f8130b848192c50e67f4
|
|
BLAKE2b-256 checksum How to use checksums |
377e276a3f3b2a2c9bcaddefceca1016ac0ac9c7956533a66f88954845fcf710
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency logRelease files / embodik-0.22.0-cp311-cp311-macosx_14_0_arm64.whl
| Download URL | embodik-0.22.0-cp311-cp311-macosx_14_0_arm64.whl |
|---|---|
| Size | 45.2 MB |
| Tags | CPython 3.11 macOS 14.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
4574692452107590fa902e1a73a089c600783f3937b7bd88cb503d1fa26958ab
|
|
BLAKE2b-256 checksum How to use checksums |
f2e41fdfc8c1be841012837765bb159bbb12352f5a57050a6216a683c3241d12
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency logRelease files / embodik-0.22.0-cp310-cp310-manylinux_2_28_x86_64.whl
| Download URL | embodik-0.22.0-cp310-cp310-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 28.8 MB |
| Tags | CPython 3.10 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
01f8bc02803f080ed711b59589e2b935d200832ab91ab2154e1b973d0f7743d3
|
|
BLAKE2b-256 checksum How to use checksums |
225cf638abc1aefc11bbfd3bd8a1319b63e7914c9d31392375df000892386548
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency logRelease files / embodik-0.22.0-cp310-cp310-macosx_14_0_arm64.whl
| Download URL | embodik-0.22.0-cp310-cp310-macosx_14_0_arm64.whl |
|---|---|
| Size | 45.2 MB |
| Tags | CPython 3.10 macOS 14.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
35c33030e034207dc28b4cbcc87b9b8ede79c93f650a4e1990aee95f43a171e1
|
|
BLAKE2b-256 checksum How to use checksums |
7d9900e822eeec64dd94c24b1b02da455c5f74ef088fbbbb3adba93138f67072
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency log
