mujofil 0.1.5

MuJoCo + Google Filament — high-fidelity, faster-than-OpenGL PBR rendering for MuJoCo

MuJoFil — MuJoCo + Google Filament

High-fidelity, physically-based rendering for MuJoCo, powered by Google Filament instead of the legacy fixed-function OpenGL path — sharper materials, real image-based lighting, and faster frames on modern GPUs.

pip install mujofil

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

pip install "mujofil[warp]"

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

📖 Full documentation: docs/ — getting started, API guide, feature reference, cookbook & troubleshooting.

🚀 Running physics on the GPU? For MJWarp (thousands of GPU worlds) with zero-copy torch.cuda observations, use the GPU edition, 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

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

Quick start

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:

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

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:

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

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