Metadata-Version: 2.2
Name: mujofil
Version: 0.1.6
Summary: MuJoCo + Google Filament — high-fidelity, faster-than-OpenGL PBR rendering for MuJoCo
Keywords: mujoco,filament,rendering,pbr,robotics,simulation
Author: MuJoFil Contributors
License: Apache-2.0
Project-URL: Homepage, https://github.com/tau-intelligence/MuJoCo-Filament
Project-URL: Source, https://github.com/tau-intelligence/MuJoCo-Filament
Project-URL: Issues, https://github.com/tau-intelligence/MuJoCo-Filament/issues
Requires-Python: >=3.10
Requires-Dist: mujoco>=3.0
Requires-Dist: numpy>=1.24
Provides-Extra: gym
Requires-Dist: gymnasium>=0.29; extra == "gym"
Provides-Extra: examples
Requires-Dist: imageio; extra == "examples"
Requires-Dist: pillow; extra == "examples"
Provides-Extra: warp
Requires-Dist: mujofil-warp>=0.1.0; extra == "warp"
Provides-Extra: usd
Requires-Dist: mujofil==0.1.6; extra == "usd"
Requires-Dist: usd-core>=23.0; extra == "usd"
Requires-Dist: trimesh>=4.0; extra == "usd"
Requires-Dist: pillow; extra == "usd"
Requires-Dist: numpy>=1.24; extra == "usd"
Description-Content-Type: text/markdown

# MuJoFil — MuJoCo + Google Filament

High-fidelity, **physically-based** rendering for [MuJoCo](https://mujoco.org),
powered by [Google Filament](https://google.github.io/filament/) instead of the
legacy fixed-function OpenGL path — sharper materials, real image-based lighting,
and faster frames on modern GPUs.

```bash
pip install mujofil
```

To install the GPU/warp edition together with the base package:

```bash
pip install "mujofil[warp]"
```

This keeps `mujofil` as the main package while pulling in `mujofil-warp` as an
optional extra dependency.

> 📖 **Full documentation:** [docs/](docs/) — [getting started](docs/getting-started.md),
> [API guide](docs/guide.md), [feature reference](docs/features.md),
> [cookbook & troubleshooting](docs/cookbook.md).
>
> 🚀 **Running physics on the GPU?** For MJWarp (thousands of GPU worlds) with
> zero-copy `torch.cuda` observations, use the GPU edition,
> [`mujofil-warp`](https://github.com/tau-intelligence/mujofil-warp).


That's it. The Filament engine is **statically compiled into the wheel** and the
material packages ship inside it, so there's no separate SDK, no compiler, and no
`PYTHONPATH` setup. MuJoCo itself comes from its own pip wheel (a dependency).

> ## ⚠️ One thing pip can't install for you: a **Vulkan GPU driver**
> MuJoFil renders on the GPU via Vulkan (with an OpenGL fallback). That driver is
> part of your operating system and **cannot** be bundled in a wheel. MuJoFil
> detects this for you — if it's missing you'll see a clear message on first
> `import mujofil`, and `mujofil-doctor` prints exactly what to install:
>
> | OS | Install command |
> |----|-----------------|
> | Ubuntu/Debian | `sudo apt install libvulkan1 mesa-vulkan-drivers vulkan-tools` |
> | Fedora | `sudo dnf install vulkan-loader mesa-vulkan-drivers vulkan-tools` |
> | Arch | `sudo pacman -S vulkan-icd-loader vulkan-tools <gpu-vulkan-driver>` |
> | macOS | LunarG Vulkan SDK (MoltenVK): https://vulkan.lunarg.com/sdk/home#mac |
> | Windows | Latest GPU driver, or LunarG SDK: https://vulkan.lunarg.com |
>
> NVIDIA GPUs also need the proprietary driver. Headless/no-GPU machines can use
> the software rasterizer (`mesa-vulkan-drivers`, "lavapipe"). After installing,
> run **`mujofil-doctor`** to confirm.

## Verify your setup

```bash
mujofil-doctor      # prints a GPU/Vulkan diagnostic; exit 0 = ready to render
```

## Quick start

```python
import mujoco
from mujofil import VFRenderer, RenderConfig

model = mujoco.MjModel.from_xml_path("scene.xml")
data = mujoco.MjData(model)

r = VFRenderer(model, RenderConfig(width=1920, height=1080))
mujoco.mj_step(model, data)
rgb = r.render(data)        # (H, W, 3) uint8
```

It's a **drop-in renderer swap** — same `model` / `data` / `mj_step` as plain
MuJoCo, you just build a `VFRenderer` instead of `mujoco.Renderer`. A neutral
studio HDR is loaded automatically, so even a bare `.xml` renders photoreal with
no lighting setup.

### Parallel vision-RL (one call for N environments)

For batched pixel observations, `BatchRenderer` renders **N environments with a
single GPU sync** — faster than, and simpler than, looping MuJoCo's renderer:

```python
from mujofil import BatchRenderer

datas = [mujoco.MjData(model) for _ in range(32)]
br = BatchRenderer(model, n_envs=32, width=128, height=128, camera_id=0)
obs = br.render(datas)      # (32, 128, 128, 3) uint8 — one call
```

More runnable scripts in [examples/](examples/).

## What ships in the wheel

* `mujofil/_vf_mujoco_native.*.so` — the Filament renderer (Filament linked
  statically; only `libc++`/`libunwind` bundled alongside via `auditwheel`).
* `mujofil/materials/*.filamat` — precompiled Filament material packages.
* Pure-Python API (`VFRenderer`, `RenderConfig`, `VFRenderWrapper`).

MuJoCo is **not** bundled — the bindings read `mjModel`/`mjData` through pointers
and call no MuJoCo functions, so the `mujoco` pip package satisfies it at runtime.

## Optional: USD / GLB asset tooling

`pip install "mujofil[usd]"` adds converters that turn a USD or GLB environment
into a visual GLB **plus** a MuJoCo collision MJCF — so you can drop a robot into
a photoreal scene and have it actually collide with the geometry:

```bash
python -m mujofil.tools.usd_to_assets scene.usd --name kitchen
```

The heavy `usd-core` / `trimesh` deps are only pulled by the `[usd]` extra; the
base `import mujofil` never loads them.

## Requirements

* A GPU with a working **Vulkan** (preferred) or OpenGL driver — same as any
  realtime renderer. For headless CI, a software Vulkan (e.g. lavapipe) works.
* Linux x86-64 (manylinux wheels). macOS / Windows wheels are produced by the
  same `cibuildwheel` config.

## Building from source

```bash
export FILAMENT_DIR=/path/to/filament      # a Filament release
pip install .                              # scikit-build-core + CMake
```

Multi-platform release wheels are built in CI with `cibuildwheel`.

## License

Apache 2.0 License
