# mitsuba-renderer/mitsuba3 architecture

> Architecture diagram of the GitHub repository mitsuba-renderer/mitsuba3, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mitsuba-renderer/mitsuba3
- Repository: https://github.com/mitsuba-renderer/mitsuba3

## Overview

Mitsuba 3 is a retargetable renderer for forward and inverse light-transport simulation, exposed through a Python-first API and a plugin-based C++ runtime. The primary workflow is to select a rendering variant, load a scene description, instantiate its objects, render through an algorithm against the scene, and save the resulting image. The repository also includes differentiable rendering algorithms and spectral/polarization-capable models. The README and tree establish these capabilities; sampled source directly supports scene parsing and object instantiation, but does not expose the full render dispatch implementation.

Main entry points: [`src/render/scene.cpp`](https://github.com/mitsuba-renderer/mitsuba3/blob/master/src/render/scene.cpp) (Scene), [`src/integrators`](https://github.com/mitsuba-renderer/mitsuba3/tree/master/src/integrators) (Rendering algorithms), [`src/python/__init__.py`](https://github.com/mitsuba-renderer/mitsuba3/blob/master/src/python/__init__.py) (Python API), [`src/core/parser.cpp`](https://github.com/mitsuba-renderer/mitsuba3/blob/master/src/core/parser.cpp) (Scene parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Python and scenes"]
  node_pyapi["Python API<br/>[__init__.py]"]
  node_sceneparse["Scene parser<br/>[parser.cpp]"]
  node_pyparse["Python parser bindings<br/>[parser.cpp]"]
  node_bindings["Native Python bindings<br/>[main.cpp]"]
end

subgraph group_models["Scene models"]
  node_sceneroot["Scene<br/>[scene.cpp]"]
  node_geometry["Geometry and acceleration<br/>[shape.cpp]"]
  node_materials["Materials and textures"]
  node_lights["Emitters"]
  node_media["Media and phases"]
  node_sensor["Sensors"]
end

subgraph group_render["Rendering and output"]
  node_samplers["Sampling plugins"]
  node_integrators["Rendering algorithms"]
  node_ad["Differentiable algorithms"]
  node_film["Films and image blocks<br/>[film.cpp]"]
  node_filters["Reconstruction filters"]
end

subgraph group_runtime["Core runtime"]
  node_plugins["Plugin registry<br/>[plugin.cpp]"]
  node_bitmap["Bitmap and image output<br/>[bitmap.h]"]
  node_core["Core utilities"]
end

node_user(("Python user"))
node_drjit["Dr.Jit runtime"]
node_filesystem["Image file"]

node_user -->|"calls"| node_pyapi
node_pyapi -->|"loads scenes"| node_sceneparse
node_pyparse -->|"invokes parsing"| node_sceneparse
node_sceneparse -->|"instantiates plugins"| node_plugins
node_sceneparse -->|"builds scene"| node_sceneroot
node_sceneroot -->|"contains shapes"| node_geometry
node_sceneroot -->|"contains materials"| node_materials
node_sceneroot -->|"contains emitters"| node_lights
node_sceneroot -->|"contains media"| node_media
node_sceneroot -->|"contains sensors"| node_sensor
node_pyapi -->|"selects algorithm"| node_integrators
node_integrators -->|"traces scene"| node_sceneroot
node_integrators -->|"uses samples"| node_samplers
node_integrators -->|"produces image blocks"| node_film
node_film -->|"reconstructs samples"| node_filters
node_pyapi -->|"writes image"| node_bitmap
node_bitmap -->|"writes file"| node_filesystem
node_pyapi -.->|"selects differentiable algorithm"| node_ad
node_ad -.->|"uses rendering models"| node_integrators
node_integrators -.->|"JIT execution"| node_drjit
node_ad -.->|"automatic differentiation"| node_drjit
node_bindings -->|"exports runtime"| node_core
node_bindings -->|"registers parser"| node_pyparse
node_plugins -->|"uses core services"| node_core

click node_pyapi "https://github.com/mitsuba-renderer/mitsuba3/blob/master/src/python/__init__.py"
click node_sceneparse "https://github.com/mitsuba-renderer/mitsuba3/blob/master/src/core/parser.cpp"
click node_pyparse "https://github.com/mitsuba-renderer/mitsuba3/blob/master/src/core/python/parser.cpp"
click node_plugins "https://github.com/mitsuba-renderer/mitsuba3/blob/master/src/core/plugin.cpp"
click node_sceneroot "https://github.com/mitsuba-renderer/mitsuba3/blob/master/src/render/scene.cpp"
click node_geometry "https://github.com/mitsuba-renderer/mitsuba3/blob/master/src/render/shape.cpp"
click node_materials "https://github.com/mitsuba-renderer/mitsuba3/tree/master/src/bsdfs"
click node_lights "https://github.com/mitsuba-renderer/mitsuba3/tree/master/src/emitters"
click node_media "https://github.com/mitsuba-renderer/mitsuba3/tree/master/src/media"
click node_sensor "https://github.com/mitsuba-renderer/mitsuba3/tree/master/src/sensors"
click node_samplers "https://github.com/mitsuba-renderer/mitsuba3/tree/master/src/samplers"
click node_integrators "https://github.com/mitsuba-renderer/mitsuba3/tree/master/src/integrators"
click node_ad "https://github.com/mitsuba-renderer/mitsuba3/tree/master/src/python/python/ad/integrators"
click node_film "https://github.com/mitsuba-renderer/mitsuba3/blob/master/src/render/film.cpp"
click node_filters "https://github.com/mitsuba-renderer/mitsuba3/tree/master/src/rfilters"
click node_bitmap "https://github.com/mitsuba-renderer/mitsuba3/blob/master/include/mitsuba/core/bitmap.h"
click node_core "https://github.com/mitsuba-renderer/mitsuba3/tree/master/src/core"
click node_bindings "https://github.com/mitsuba-renderer/mitsuba3/blob/master/src/python/main.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pyapi,node_sceneparse,node_pyparse,node_bindings,node_user toneBlue
class node_sceneroot,node_geometry,node_materials,node_lights,node_media,node_sensor toneAmber
class node_samplers,node_integrators,node_ad,node_film,node_filters toneMint
class node_plugins,node_bitmap,node_core toneRose
class node_drjit,node_filesystem toneIndigo
```

## Components

### Python and scenes

- [Python API](https://github.com/mitsuba-renderer/mitsuba3/blob/master/src/python/__init__.py): `src/python/__init__.py`
- [Scene parser](https://github.com/mitsuba-renderer/mitsuba3/blob/master/src/core/parser.cpp): `src/core/parser.cpp`
- [Python parser bindings](https://github.com/mitsuba-renderer/mitsuba3/blob/master/src/core/python/parser.cpp): `src/core/python/parser.cpp`
- [Native Python bindings](https://github.com/mitsuba-renderer/mitsuba3/blob/master/src/python/main.cpp): `src/python/main.cpp`

### Scene models

- [Scene](https://github.com/mitsuba-renderer/mitsuba3/blob/master/src/render/scene.cpp): `src/render/scene.cpp`
- [Geometry and acceleration](https://github.com/mitsuba-renderer/mitsuba3/blob/master/src/render/shape.cpp): `src/render/shape.cpp`
- [Materials and textures](https://github.com/mitsuba-renderer/mitsuba3/tree/master/src/bsdfs): `src/bsdfs`
- [Emitters](https://github.com/mitsuba-renderer/mitsuba3/tree/master/src/emitters): `src/emitters`
- [Media and phases](https://github.com/mitsuba-renderer/mitsuba3/tree/master/src/media): `src/media`
- [Sensors](https://github.com/mitsuba-renderer/mitsuba3/tree/master/src/sensors): `src/sensors`

### Rendering and output

- [Sampling plugins](https://github.com/mitsuba-renderer/mitsuba3/tree/master/src/samplers): `src/samplers`
- [Rendering algorithms](https://github.com/mitsuba-renderer/mitsuba3/tree/master/src/integrators): `src/integrators`
- [Differentiable algorithms](https://github.com/mitsuba-renderer/mitsuba3/tree/master/src/python/python/ad/integrators): `src/python/python/ad/integrators`
- [Films and image blocks](https://github.com/mitsuba-renderer/mitsuba3/blob/master/src/render/film.cpp): `src/render/film.cpp`
- [Reconstruction filters](https://github.com/mitsuba-renderer/mitsuba3/tree/master/src/rfilters): `src/rfilters`

### Core runtime

- [Plugin registry](https://github.com/mitsuba-renderer/mitsuba3/blob/master/src/core/plugin.cpp): `src/core/plugin.cpp`
- [Bitmap and image output](https://github.com/mitsuba-renderer/mitsuba3/blob/master/include/mitsuba/core/bitmap.h): `include/mitsuba/core/bitmap.h`
- [Core utilities](https://github.com/mitsuba-renderer/mitsuba3/tree/master/src/core): `src/core`

### Other components

- **Python user**
- **Dr.Jit runtime**
- **Image file**

## Connections

- Python user → Python API: calls
- Python API → Scene parser: loads scenes
- Python parser bindings → Scene parser: invokes parsing
- Scene parser → Plugin registry: instantiates plugins
- Scene parser → Scene: builds scene
- Scene → Geometry and acceleration: contains shapes
- Scene → Materials and textures: contains materials
- Scene → Emitters: contains emitters
- Scene → Media and phases: contains media
- Scene → Sensors: contains sensors
- Python API → Rendering algorithms: selects algorithm
- Rendering algorithms → Scene: traces scene
- Rendering algorithms → Sampling plugins: uses samples
- Rendering algorithms → Films and image blocks: produces image blocks
- Films and image blocks → Reconstruction filters: reconstructs samples
- Python API → Bitmap and image output: writes image
- Bitmap and image output → Image file: writes file
- Python API → Differentiable algorithms: selects differentiable algorithm
- Differentiable algorithms → Rendering algorithms: uses rendering models
- Rendering algorithms → Dr.Jit runtime: JIT execution
- Differentiable algorithms → Dr.Jit runtime: automatic differentiation
- Native Python bindings → Core utilities: exports runtime
- Native Python bindings → Python parser bindings: registers parser
- Plugin registry → Core utilities: uses core services
