Metadata-Version: 2.4
Name: truerig
Version: 0.1.1
Summary: Robot-model conversion (URDF/MJCF/USD) you can trust — with a fidelity report of everything it changed.
Author: Sputnikboi
License-Expression: MIT
Project-URL: Homepage, https://truerig.xyz
Project-URL: Repository, https://github.com/Sputnikboi/truerig
Keywords: robotics,urdf,mjcf,mujoco,usd,converter,simulation,ros
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: trimesh
Requires-Dist: mujoco>=3.0
Requires-Dist: yourdfpy
Provides-Extra: usd
Requires-Dist: usd-core; extra == "usd"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: robot_descriptions; extra == "dev"
Requires-Dist: usd-core; extra == "dev"
Dynamic: license-file

# TrueRig

**Robot-model conversion you can trust.** Convert robot descriptions between
**URDF ↔ MJCF ↔ USD** through a lossless canonical IR — and get a **fidelity
report** of everything that changed.

> The thesis is the point: existing converters fail *silently*.
> TrueRig's product is knowing what you lost.

![PyPI](https://img.shields.io/pypi/v/truerig)
![Python](https://img.shields.io/pypi/pyversions/truerig)
![License](https://img.shields.io/pypi/l/truerig)
[![CI](https://github.com/Sputnikboi/truerig/actions/workflows/ci.yml/badge.svg)](https://github.com/Sputnikboi/truerig/actions/workflows/ci.yml)

```bash
pip install truerig
```

## Why

Every open-source URDF→MJCF converter today fails on real robots, silently. We
reproduced this against the current `urdf2mjcf` (MuJoCo 3.10) on two standard
models:

| Defect | Robot | Existing tool behaviour |
|---|---|---|
| Off-diagonal inertia dropped on 32 links (up to **31.5%** of the diagonal) | Unitree G1 | one buried "Warning" line |
| Closed-chain coupling (5 mimic joints → **0** constraints) | Robotiq 2F-85 | **no warning at all** |
| `package://` mesh URIs passed through unresolved / doubled paths | both | hard load error |
| Invalid MJCF emitted (empty-name material) | Robotiq | MuJoCo refuses the file |

Out of the box, **neither converted model even loads in MuJoCo** without manual
fixing — and once you fix the plumbing, the physics is still silently wrong.

3 of the 4 defects are pure engineering diligence. The 4th (closed chains) is
genuinely lossy — so TrueRig's job isn't to pretend loss doesn't happen, it's to
**preserve everything it can and report the rest honestly.**

## How it works

```
 URDF ─┐                          ┌─ MJCF
 MJCF ─┼─► frontend ─► IR ─► backend ─┼─ URDF      + validate(IR)  → physics checks
 USD  ─┘   (parse)   (lossless)  (emit) └─ USD      + report(loss_log) → what changed
```

The **IR is frozen** (`truerig/ir.py`) and is lossless by construction: frontends
record *all* source data; backends drop only what the target can't express and log
a `LossEvent` for each drop. See module docstrings for per-component contracts.

## What works today

- **URDF ↔ MJCF** — full bidirectional conversion
- **URDF / MJCF → USD** — experimental (UsdPhysics articulation, inertia diagonalized
  losslessly); `pip install truerig[usd]`
- **validate · report · simcheck** — physics sanity checks, a fidelity report you can
  gate CI on, and a behavioural round-trip check in simulation

**Field-tested on 12 diverse robots** — Unitree G1/H1/A1/B1/Go2, ANYmal C, Franka
Panda, KUKA iiwa14, Allegro Hand, Cassie, Baxter, Fetch, Solo — plus the
G1/Robotiq/Z1 golden set. All convert and load in MuJoCo with full inertia and
closed-chain coupling preserved; degenerate source inertia is repaired **and
reported**, never silently. 51 tests, CI on Python 3.10–3.12.

## Usage

```bash
truerig convert robot.urdf robot.mjcf --report text --strict   # convert + fidelity report
truerig validate robot.urdf                                    # physics sanity checks
truerig simcheck robot.urdf robot.mjcf                          # behavioural round-trip in sim
```

## Roadmap

Embedding USD mesh geometry (currently referenced by path) and a hosted demo at
[truerig.xyz](https://truerig.xyz). Early and open (MIT) — issues and PRs welcome.
