Skip to content
Antoine Boucher

Options

Profiles

Table of contents

MistubaVideo

MistubaVideo renders simulation exports with Mitsuba 3, under ETSim. The batch command processes OBJ sequences; the mitsuba-video helper reads recorded body poses and surface fields through manifest and TextureFriction source adapters. Facts below come from the repository documentation as read for the project introduction.

  • Updated
View sourceREADMEMarkdown

1. Overview

Why it exists. A simulation computes motion and surface change; rendering a recording shows where bodies moved and how material appearance evolved, and lets you change camera or lighting without repeating the simulation.

Best fit. Turning recorded poses and wear fields into frames, heatmaps, atlas panels and video for reports and talks.

2. Use cases

Mitsuba 3 tools from ETSim that path-trace OBJ sequences and wear-field recordings into frames, MP4 videos and GIFs.

Use-case diagram for MistubaVideo: Render an OBJ sequence; Render several camera views; Denoise and split AOVs; Make a field video; Render a wear recording; Write and check a manifestMistubaVideoRender an OBJ sequenceRender several camera viewsDenoise and split AOVsMake a field videoRender a wear recordingWrite and check a manifestSimulation researcher«system»Mitsuba 3 and FFmpeg«system»TextureFriction runs
People on the left, external systems on the right; each oval is a use case backed by the files cited below.
Render an OBJ sequence
Simulation researcherMitsuba 3 and FFmpeg

python main.py multi --folder exports --regex "\d+\.obj" builds a scene XML per matching OBJ, renders it on CPU or CUDA at the chosen spp and resolution, then encodes MP4 and GIF with FFmpeg.

Render several camera views
Simulation researcher

--view front --view top or --all-views renders each frame from the front, back, left, right, top, bottom or perspective camera defined in src/mitsuba/camera.py, with the view name in the file name.

Denoise and split AOVs
Simulation researcherMitsuba 3 and FFmpeg

python main.py denoise <path> runs the OptiX denoiser from src/mitsuba/denoising.py on rendered images, and python main.py aov <file.exr> extracts the AOV layers of an EXR into separate files.

Make a field video
Simulation researcherMitsuba 3 and FFmpeg

mitsuba-video render <manifest.json> -q paper path-traces rigid bodies at their recorded poses with a field-driven material blend and heatmap, adds a UV atlas panel and a covered-area chart, and encodes an MP4.

Render a wear recording
Simulation researcherTextureFriction runs

python main.py wear render simulation_<ts> or tf-render reads a TextureFriction --record folder or .h5 file through the texturefriction source.

Write and check a manifest
Simulation researcher

Any project can emit a versioned manifest.json with ManifestWriter; mitsuba-video validate checks it against manifest-v1.schema.json, and mitsuba-video fixture creates a small synthetic example.

2.1. Scenario: Render the demo field video

  1. Install FFmpeg and Mitsuba 3, then run pip install -e "packages/mitsuba_video[texturefriction]" to get mitsuba-video and tf-render.
  2. Create a synthetic input with mitsuba-video fixture demo.
  3. Check the framing quickly with mitsuba-video preview demo.
  4. Run mitsuba-video render demo -q preview to path-trace the frames and encode the MP4.
  5. For real data, point python main.py wear render at a TextureFriction simulation_<ts> folder with -q paper.

Files readREADME.mdmain.pyconfig.jsonrequirements.txtpackages/mitsuba_video/README.mdpackages/mitsuba_video/src/mitsuba_video/cli.pysrc/mitsuba/camera.py.github/workflows/mitsuba-video.yml

3. Getting started

python main.py multi --folder exports          # batch-render an OBJ sequence
mitsuba-video inspect path/to/manifest.json    # check the input data
mitsuba-video preview path/to/manifest.json    # check camera and framing
mitsuba-video render path/to/manifest.json -q preview

Quality presets: preview, draft, paper. encode reassembles existing frames into video; FFmpeg does the encoding.

4. Features and components

StageData
InputMeshes, materials, recorded poses and surface fields; a versioned manifest (bodies, meshes, materials, poses, field images) or a TextureFriction recording through a source adapter; ManifestWriter lets another simulator export the format
ProcessingApply recorded poses, blend base and affected materials using the surface field, Mitsuba 3 path tracing; optional heatmap, UV-atlas panel and covered-area chart
OutputBeauty and composite frames, field-area CSV, render_config.json with settings and timings, MP4; optional linear EXR frames

5. Architecture

flowchart TD
  subgraph Inputs[Simulation output]
    R[TextureFriction recording]
    M[Manifest: meshes, poses and fields]
  end
  subgraph Helper[mitsuba-video helper]
    A[Source adapter]
    B[Apply poses and blend materials]
    C[Mitsuba 3 path tracing]
    D[Atlas panel and area chart]
  end
  R --> A
  M --> A
  A --> B --> C --> D
  D --> E[Frame images and MP4]

6. Constraints and checks

  • The area chart measures the recorded field’s covered area, not the visible area of the rendered object.
  • Keep display settings with the render: changing the heatmap range makes the same field look different.
  • The package documents pytest tests for transforms, material blending, OBJ/MTL readers and the manifest schema and writer; no measured coverage percentage is quoted here.

8. CI/CD pipeline

1 GitHub Actions workflow, 2 jobs. Each box is a job; double-bordered boxes publish or deploy, and arrows follow needs.

Mermaid Pipeline flow
flowchart LR
  subgraph wf0["mitsuba-video"]
    direction LR
    wf0_linux[["linux<br/>ubuntu-latest"]]
    wf0_windows["windows<br/>windows-latest"]
  end
  t0(["push · pull request · manual run"])
  t0 --> wf0_linux
  t0 --> wf0_windows
Workflows, triggers, jobs and targets
WorkflowTriggersJobsPublishes to
mitsuba-video
.github/workflows/mitsuba-video.yml		push, pull request, manual run
  • linux ubuntu-latest
    actions/checkout · actions/setup-python · System packages · Install · Tests · Smoke renders
  • windows windows-latest
    actions/checkout · actions/setup-python · Install · Tests · Scalar smoke render
—

Generated from the source at commit 87b180b.

9. Deployment diagram

Mermaid Deployment diagram
flowchart LR
  repo[("GitHub repository")]
  ci[["GitHub Actions<br/>1 workflow"]]
  image["Docker image<br/>FROM nvidia/cuda:12.0.1-cudnn8-devel-ubuntu22.04"]
  subgraph compose["Docker Compose"]
    svc_mitsuba_renderer["mitsuba-renderer"]
  end
  repo -->|"push or pull request"| ci
  ci -->|"docker build"| image
  image -->|"docker compose up"| compose

10. External dependencies

16 declared packages (14 runtime, 2 development) in pyproject.toml, requirements.txt, packages/mitsuba_video/pyproject.toml.

Package table 16
External dependencies
PackageVersionScopePurposeRegistry
typer—runtimeCommand linepypi.org
rich—runtimeCommand linepypi.org
python-dotenv—runtimeConfigurationpypi.org
jsonschema—runtimeData validationpypi.org
mitsuba—runtimeGraphics, imaging and 3Dpypi.org
rpds—runtime—pypi.org
xmltodict—runtimeMakes working with XML feel like you are working with JSONpypi.org
xmlschema—runtimeAn XML Schema validator and decoderpypi.org
numpy—runtimeData analysispypi.org
tqdm—runtimeCommand linepypi.org
gradio—runtimeUser interfacepypi.org
imageio>=2.30.0runtimeGraphics, imaging and 3Dpypi.org
pillow>=10.0.0runtimeGraphics, imaging and 3Dpypi.org
coverage—runtimeTestingpypi.org
h5py>=3developmentRead and write HDF5 files from Pythonpypi.org
pytest>=7developmentTestingpypi.org

11. Glossary

Repository

The versioned source files, configuration, and history of a project.

README

The repository’s entry document, usually covering its purpose and initial setup.

Dependency

A library, tool, or service that another component needs to build or run.

HTTP

A request-and-response protocol used by browsers and web services. A method, path, headers, and optional body describe a request.

Published port

A host port mapped to a service’s container port. Publishing a port can expose that service beyond its container network.

CLI

A text interface in which commands and arguments select operations. Exit codes let scripts detect success or failure.

Mermaid

A text-based diagram language. Nodes and connections describe a model; the diagram itself does not execute the project.

GPU

A processor designed for parallel workloads, including graphics rendering and many numerical operations.

Mesh

A surface represented by vertices and connected elements, often triangles. Its geometry is distinct from its material or texture.

Video decoder

A component that reconstructs video frames from a compressed stream. Decoding and displaying a frame are separate stages.

12. References

  1. ETSim. (2026, November 5). [Web page] github.com.
  2. ETSim. (2026, November 5). MistubaVideo. [Software repository] github.com.
  3. ETSim. (2026, November 5). Render helper package. [Source file or documentation] github.com.

Sources without a publication date show the date they were last checked, November 5, 2026. File links retain the inspected revision where available.