Metadata-Version: 2.4
Name: animasim
Version: 0.2.0
Summary: Animal models and animations for robotics simulators (esmini, MuJoCo, Isaac Sim, CARLA).
Project-URL: Homepage, https://github.com/danwahl/animasim
Project-URL: Repository, https://github.com/danwahl/animasim
Author-email: Dan Wahl <hi@danwahl.net>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: typer>=0.25.1
Provides-Extra: mujoco
Requires-Dist: mujoco>=3.8.1; extra == 'mujoco'
Provides-Extra: pipeline
Requires-Dist: lxml>=6.1.1; extra == 'pipeline'
Requires-Dist: mujoco>=3.8.1; extra == 'pipeline'
Requires-Dist: obj2mjcf>=0.0.25; extra == 'pipeline'
Requires-Dist: pillow>=12.2.0; extra == 'pipeline'
Requires-Dist: pygltflib>=1.16.5; extra == 'pipeline'
Requires-Dist: usd-core>=26.5; extra == 'pipeline'
Description-Content-Type: text/markdown

# AnimaSim

A standard set of animal models and animations for robotics/AV simulators (**esmini**, **MuJoCo**, **Isaac Sim**, and **CARLA**) which today ship almost no animal assets. When animals are missing from the asset libraries, they tend to be left out of the algorithms engineers build and the scenarios regulators design, even though real-world deer-on-highway and dog-in-driveway interactions are common. AnimaSim ports an open animal pack into these platforms with a small, dockerized conversion pipeline plus a runnable example per platform.

All 12 animals are ported to every platform and spawn through each one's idiomatic mechanism (esmini catalog, MuJoCo include, Isaac USD, CARLA blueprint). **Deer** is the worked example with a runnable scene per platform; the rest are discoverable and render together as a menagerie (see the gallery).

## Install

`pip install animasim` ships the asset-locator API and CLI, with every generated artifact
bundled in the wheel — resolve a path and hand it to your simulator:

```python
from animasim import get_mjcf, get_usd, get_osgb, get_glb, list_animals
import mujoco

model = mujoco.MjModel.from_xml_path(str(get_mjcf("deer")))   # MuJoCo
# get_usd("deer") -> Isaac Sim/USD   get_osgb("deer") -> esmini   get_glb("deer") -> Blender/glTF
```

From the shell: `animasim path deer -f usd`. The CARLA cooked package is distributed
separately as a release asset (see [`platforms/carla`](platforms/carla)).

## Quickstart (from source)

```bash
git lfs install && git lfs pull     # fetch vendored + generated assets (Git LFS)
uv sync --extra pipeline            # environment + conversion/validation toolchain
uv run animasim list                # the 12 animals and their rigs
uv run animasim validate deer       # check the generated artifacts
```

Regenerate the assets (needs Docker for the `osgconv` step):

```bash
uv run animasim convert deer        # -> assets/generated/{glb,osgb,mjcf,metadata}/deer.*
```

## Platform support

| Platform | Status | How it runs | Example |
|----------|--------|-------------|---------|
| **MuJoCo** | ✅ verified (runs + renders) | uv (Python lib) | deer on a ground plane; all 12 as `<include>` models — [`platforms/mujoco`](platforms/mujoco) |
| **esmini** | ✅ verified (headless run + offscreen recording) | esmini container | deer crosses a highway, ego brakes (OpenSCENARIO); all 12 in the catalog — [`platforms/esmini`](platforms/esmini) |
| **Isaac Sim** | ✅ verified (GPU: convert + spawn + pilot) | Isaac Sim container (NGC) | spawn + pilot the deer; all 12 as UsdSkel — [`platforms/isaacsim`](platforms/isaacsim) |
| **CARLA** | ✅ verified (GPU: drop-in cooked package + spawn) | prebuilt CARLA container | all 12 as `static.prop.<animal>` — [`platforms/carla`](platforms/carla) |

Sim **engines run in Docker** (esmini, Isaac, CARLA); Python (the `animasim` CLI, validators, MuJoCo) runs in the **uv** environment.

## Gallery

| Simulator | Menagerie |
|:---------:|:-----|
| **Isaac Sim** | ![12 animals marching in Isaac Sim](docs/images/isaac_menagerie.gif) |
| **CARLA** | ![12 animals in CARLA](docs/images/carla_menagerie.png) |
| **MuJoCo** | ![12 animals in MuJoCo](docs/images/mujoco_menagerie.png) |
| **esmini** | ![Deer crossing in esmini](docs/images/esmini_deer.gif) |

Isaac Sim and MuJoCo show all 12 animals together; esmini shows the deer crossing a road. Each platform's README has the commands to reproduce its clip.

## Animation fidelity

The source models share one skeleton and carry ~13 animation clips each (Idle, Walk, Gallop, Eating, …). Clips are preserved where the target supports skeletal animation:

| Target | Skinned animation | Clips |
|--------|-------------------|-------|
| `glb` (interchange) | yes | **all** (native) |
| Isaac Sim / USD | yes (UsdSkel) | **all** — one `SkelAnimation` prim per clip, CI-validated |
| esmini (`.osgb`) | no (static scene-graph model) | n/a |
| MuJoCo (mesh) | no (physics engine) | n/a |
| CARLA (`.fbx` prop) | no (static prop) | n/a |

## How it fits together

```
assets/source/      vendored source (glTF/OBJ/FBX, Git LFS)
assets/generated/   derived artifacts grouped by format (glb, osgb, usd, mjcf, fbx, carla, metadata)
src/animasim/       CLI + animal registry (config.py) + pipeline + validators
platforms/<name>/   per-platform assets, example scene, and runner
docker/             pipeline (osgconv) and esmini images
```

## Adding an animal

The pipeline is data-driven: add an entry to the registry in [`src/animasim/config.py`](src/animasim/config.py) (name, source file, height, bbox, rig variant) and run `uv run animasim convert <animal>`. No code changes required. All 12 animals ship with their source files vendored; importing a *new* animal beyond them is the only step that needs the original pack — point `ANIMASIM_SOURCE_PACK` at it (or pass `--source`) and `convert` vendors its source on the way.

## License & assets

Project code: MIT (see [`LICENSE`](LICENSE)). The bundled animal models are from the Quaternius "Ultimate Animated Animals" [pack](https://quaternius.com/packs/ultimateanimatedanimals.html), released under CC0 (public domain); they are vendored and redistributed here under those terms.
