Metadata-Version: 2.2
Name: mujofil
Version: 0.1.1
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"
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.

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
```

## 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.

## 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
