# BlendGen (/)



BlendGen is a Python rendering pipeline for turning Blender scenes into reproducible machine-learning datasets. Declare the render engine, semantic passes, output formats, frame range, and annotations once; BlendGen renders each frame once and records the resulting files in a dataset index.

<video preload="auto" poster="/media/character-dataset-poster.jpg" aria-label="Animated grid of synthetic scenes and render passes generated with BlendGen" className="not-prose my-8 w-full rounded-xl border object-cover">
  <source src="/media/character-dataset-loop.mp4" type="video/mp4" />

  <img src="/media/character-dataset-poster.jpg" alt="A grid of synthetic scenes and render passes generated with BlendGen" />
</video>

## What it gives you [#what-it-gives-you]

* **Synchronized outputs:** color, alpha, metric depth, normals, optical flow, and material IDs stay aligned frame by frame.
* **Explicit render engines:** configure Cycles for production or Eevee for faster supported workloads.
* **Headless operation:** run the same dataset file locally, in Docker, or on a GPU host without opening Blender's UI.
* **Procedural annotations:** callbacks can move scene objects and attach 2D/3D boxes, poses, camera matrices, or custom metadata.
* **Verified manifests:** a pass is recorded only after its expected file exists.

## The shortest path [#the-shortest-path]

1. [Build the Docker image](/getting-started/installation).
2. [Render your first dataset](/getting-started/first-dataset).
3. Choose [passes and formats](/guides/render-passes).
4. Add [callbacks and annotations](/guides/callbacks-and-attributes).

## Documentation for people and agents [#documentation-for-people-and-agents]

Every page is also available as Markdown by appending `.md` to its documentation URL. The complete site is indexed at [`/llms.txt`](/llms.txt), with all page content at [`/llms-full.txt`](/llms-full.txt).


# Python API reference (/api)



The module pages in this section are generated directly from the Python abstract syntax tree. This avoids importing `bpy` in the Node.js documentation build while keeping function signatures, enum values, source links, and docstrings synchronized with the repository.

Run the generator directly:

```bash
cd docs
npm run generate:api
```

`npm run dev`, `npm run build`, and `npm run types:check` run it automatically. Generated files live under `content/docs/api/generated` and should not be edited by hand.

## Public entry points [#public-entry-points]

* `blendgen.session.Session` coordinates the frame lifecycle.
* `blendgen.renderer.Renderer` and `Background` configure the render.
* `blendgen.renderers` provides Cycles and Eevee backends.
* `blendgen.passes` declares semantic outputs and formats.
* `blendgen.dataset.Dataset` writes the frame index and attributes.
* `blendgen.util` and `blendgen.utils.scene` provide camera, pose, selection, and projection helpers.


# Your first dataset (/getting-started/first-dataset)



Create `dataset.py` beside a `.blend` file. This example produces display color plus lossless metric and semantic channels:

```python
from pathlib import Path

import bpy

from blendgen.dataset import Dataset, DatasetOutputType
from blendgen.passes.alpha import AlphaPass
from blendgen.passes.base import ImageOutputType
from blendgen.passes.color import ColorPass
from blendgen.passes.depth import DepthPass
from blendgen.passes.index import RawMaterialIndexPass
from blendgen.passes.normal import NormalPass
from blendgen.passes.opticalflow import OpticalFlowPass
from blendgen.renderer import Background, Renderer
from blendgen.renderers import CyclesBackend, CyclesDevice
from blendgen.session import Session

OUTPUT = "/data/output/"

if bpy.context.scene.camera is None:
    raise RuntimeError("The scene has no active camera")
Path(OUTPUT).mkdir(parents=True, exist_ok=True)

passes = [
    ColorPass(prefix="color", output_type=ImageOutputType.PNG),
    AlphaPass(prefix="alpha", output_type=ImageOutputType.PNG),
    DepthPass(prefix="depth", output_type=ImageOutputType.EXR),
    NormalPass(prefix="normal", output_type=ImageOutputType.EXR),
    OpticalFlowPass(prefix="flow", output_type=ImageOutputType.EXR),
    RawMaterialIndexPass(prefix="material_index", output_type=ImageOutputType.EXR),
]

renderer = Renderer(
    backend=CyclesBackend(samples=8, device=CyclesDevice.GPU),
    background=Background.ALPHA,
    resolution_x=640,
    resolution_y=360,
    output_base_path=OUTPUT,
    passes=passes,
)

dataset = Dataset(
    prefix="",
    dataset_name="My BlendGen dataset",
    output_dir=OUTPUT,
    filename="blendgen_dataset",
    output_type=DatasetOutputType.JSON,
)

session = Session(
    renderer=renderer,
    dataset=dataset,
    output_dir=OUTPUT,
    frame_start=1,
    frame_length=1,
)

print(session.info)
session.run()
```

Run it against your scene:

```bash
docker run --rm --gpus all \
  -v "$PWD":/data -w /data blendgen:latest \
  blender --background --python-exit-code 1 /data/scene.blend \
  --python /data/dataset.py
```

For CPU or Eevee, remove `--gpus all`. For a CPU Cycles run, change the dataset file to `CyclesDevice.CPU`.

## Expected output [#expected-output]

```text
output/
├── alpha/Image0001.png
├── color/Image0001.png
├── depth/Image0001.exr
├── flow/Image0001.exr
├── material_index/Image0001.exr
├── normal/Image0001.exr
└── blendgen_dataset.json
```

The exact ordering is unimportant. Every path recorded in `blendgen_dataset.json` must point to a real file.


# Getting started (/getting-started)



BlendGen runs inside Blender's Python runtime. The maintained Docker images package Blender 5.1.2 and make the repository importable as `blendgen`, so Docker is the most repeatable route for both development and dataset production.

## Prerequisites [#prerequisites]

* Git and Docker
* A Blender scene with an active camera
* NVIDIA Container Toolkit only when using Cycles on an NVIDIA GPU
* Enough disk space for lossless EXR passes; depth, normals, and flow grow quickly

Continue with [Installation](/getting-started/installation), then render [Your first dataset](/getting-started/first-dataset).

## Before a large run [#before-a-large-run]

Use a low resolution and `frame_length=1`. Verify that every pass file exists and inspect all semantic outputs together. Scale the resolution and frame range only after that smoke test passes.


# Installation (/getting-started/installation)



## Clone and build [#clone-and-build]

```bash
git clone https://github.com/juniorxsound/BlendGen.git
cd BlendGen
make build
```

`make build` chooses the GPU Dockerfile when `nvidia-smi` is available; otherwise it builds the CPU image. Both use the local tag `blendgen:latest` by default.

Build a specific runtime directly when the automatic choice is not appropriate:

```bash
docker build --platform linux/amd64 \
  -f docker/Dockerfile.cpu \
  -t blendgen:latest .
```

```bash
docker build --platform linux/amd64 \
  -f docker/Dockerfile.gpu \
  -t blendgen:latest .
```

## Apple Silicon [#apple-silicon]

Blender 5.1.2's maintained Linux artifact is x86-64, so the project image runs with `--platform linux/amd64` under Docker Desktop emulation. Use `CyclesDevice.CPU`; Docker Desktop on macOS does not provide NVIDIA GPU passthrough.

## Confirm the image [#confirm-the-image]

```bash
docker run --rm --platform linux/amd64 blendgen:latest blender --version
```

## Mounting a project [#mounting-a-project]

BlendGen expects the repository or dataset project at `/data` in the container:

```bash
docker run --rm \
  --platform linux/amd64 \
  -v "$PWD":/data \
  -w /data \
  blendgen:latest \
  blender --background --python-exit-code 1 \
  /data/examples/blend/character_4_cams.blend \
  --python /data/examples/simple.py
```

Add `--gpus all` only with the GPU image on a host where NVIDIA Container Toolkit is configured.


# Architecture (/guides/architecture)



## Ownership [#ownership]

| Component   | Owns                                                          | Does not own                  |
| ----------- | ------------------------------------------------------------- | ----------------------------- |
| `Session`   | Frame iteration, callbacks, orchestration                     | Pass configuration            |
| `Renderer`  | Scene render settings, compositor graph, one render per frame | Dataset serialization         |
| Backend     | Engine-specific configuration and pass socket binding         | Frame iteration               |
| Render pass | Output format, compositor operations, final file path         | Calling Blender's render loop |
| `Dataset`   | Frame records, attributes, JSON/NPY serialization             | Rendering                     |

## Frame lifecycle [#frame-lifecycle]

For every frame in `[frame_start, frame_start + frame_length)` the session:

1. sets the Blender timeline frame;
2. updates the dependency graph;
3. invokes `on_before_new_frame(session)`;
4. asks the renderer to render all declared passes together;
5. adds the verified pass paths to the dataset;
6. invokes `on_after_new_frame(session)`.

After the range completes, it saves the dataset index and invokes `on_complete()`.

## Why one render matters [#why-one-render-matters]

Beauty, depth, normals, optical flow, and IDs must describe the same scene state and sample realization. Calling Blender separately for each pass can introduce animation drift, random-sampling differences, and unnecessary cost. BlendGen configures the view-layer passes and compositor before calling `bpy.ops.render.render()` once per frame.

## Defaults versus explicit configuration [#defaults-versus-explicit-configuration]

`Session(passes=[...])` remains a shorthand: it creates a default Cycles renderer and dataset. Prefer explicit `Renderer` and `Dataset` instances in production files because resolution, background, backend device, output root, and index format are then reviewable in one place.


# Callbacks and attributes (/guides/callbacks-and-attributes)



## Callback order [#callback-order]

```python
session = Session(
    renderer=renderer,
    dataset=dataset,
    on_start=on_start,
    on_before_new_frame=before_frame,
    on_after_new_frame=after_frame,
    on_complete=on_complete,
)
```

* `on_start()` runs before frame iteration.
* `on_before_new_frame(session)` runs after Blender changes frame and updates its dependency graph, but before rendering.
* `on_after_new_frame(session)` runs after pass paths have been added to the current frame record.
* `on_complete()` runs after the index is saved.

Use the before-frame callback to randomize transforms, materials, lighting, or cameras. Keep all scene-specific `bpy` mutations in the dataset file or callbacks.

## Attach an annotation [#attach-an-annotation]

`Dataset.add_attribute()` queues a key/value object for the next frame record:

```python
def before_frame(_session):
    box = compute_box_for_current_scene()
    dataset.add_attribute("vehicle_bbox_2d", box)
```

The queued per-frame attributes are cleared after `Dataset.add_frame()`. Values written to a JSON dataset must be JSON serializable; convert NumPy arrays and Blender math types to ordinary lists or dictionaries.

## Camera and geometry utilities [#camera-and-geometry-utilities]

The public helpers in `blendgen.util` and `blendgen.utils.scene` support world-space boxes, projected screen coordinates, pose matrices, and camera calibration. Compute annotations from the same evaluated scene state that is about to render.

Do not render inside a callback. `Session.run()` must remain the single owner of the render loop so declared outputs stay synchronized.


# Dataset output (/guides/dataset-output)



`Dataset` stores a name, creation timestamp, and ordered frame records. Each frame contains its timeline index as a string, a list of pass-path mappings, and a list of custom attributes.

```json
{
  "name": "My BlendGen dataset",
  "date": "07/17/2026,12:00:00",
  "data": [
    {
      "index": "1",
      "passes": [
        { "ColorPass": "/data/output/color/Image0001.png" },
        { "DepthPass": "/data/output/depth/Image0001.exr" }
      ],
      "attributes": [
        { "camera_id": "Camera" }
      ]
    }
  ]
}
```

The exact pass keys come from each pass class's `type`. Treat recorded file paths as the output contract: a successful manifest entry must point to an existing individual pass file.

## JSON or NPY [#json-or-npy]

Use `DatasetOutputType.JSON` for portable, inspectable metadata. `DatasetOutputType.NPY` serializes the dataset object with NumPy and is Python/NumPy oriented. Image pass files remain separate in both cases.

## Attributes-only runs [#attributes-only-runs]

`Renderer(render_images=False)` allows a session to iterate frames and save annotations without writing image passes. This is useful only when the intended dataset is genuinely metadata-only; it must not be used to mask missing requested images.


# Guides (/guides)



These guides move from the core execution model to output semantics and production workflows. Read [Architecture](/guides/architecture) first if you plan to extend BlendGen or write non-trivial dataset files.

* [Render backends](/guides/render-backends) compares Cycles and Eevee.
* [Render passes](/guides/render-passes) explains formats and semantic tradeoffs.
* [Callbacks and attributes](/guides/callbacks-and-attributes) covers procedural scene changes and annotations.
* [Dataset output](/guides/dataset-output) documents the index contract.


# Render backends (/guides/render-backends)



## Cycles [#cycles]

Cycles is the general-purpose choice and supports every BlendGen pass, including material indices.

```python
from blendgen.renderers import CyclesBackend, CyclesDevice

backend = CyclesBackend(samples=64, device=CyclesDevice.GPU)
```

Use `CyclesDevice.GPU` only when Blender can see a supported compute device. In Docker, that means the GPU image and `--gpus all`. Use `CyclesDevice.CPU` everywhere else.

## Eevee [#eevee]

Eevee is useful for fast iterations and supported workloads:

```python
from blendgen.renderers import EeveeBackend

backend = EeveeBackend(samples=16)
```

Color, alpha, depth, normal, and optical-flow pass classes work with Eevee. The current Blender 5 backend rejects material-index passes because Eevee does not expose that pass reliably. This is an early configuration error, not a partially rendered dataset.

## Choose by required semantics [#choose-by-required-semantics]

| Requirement                | Recommended backend |
| -------------------------- | ------------------- |
| Material IDs               | Cycles              |
| Fast color/depth iteration | Eevee               |
| GPU production on NVIDIA   | Cycles GPU          |
| Apple Silicon Docker       | Cycles CPU or Eevee |

Do not switch engines only for speed without comparing the resulting imagery and semantic passes on representative frames.


# Render passes and formats (/guides/render-passes)



## Pass matrix [#pass-matrix]

| Pass                           | Typical format | Meaning                                                  |
| ------------------------------ | -------------- | -------------------------------------------------------- |
| `ColorPass`                    | PNG or EXR     | Combined scene color; EXR preserves scene-linear values  |
| `AlphaPass`                    | PNG or EXR     | Combined coverage alpha                                  |
| `DepthPass`                    | EXR            | Camera-space metric Z with a large background sentinel   |
| `NormalPass`                   | EXR            | Signed XYZ surface normal components                     |
| `OpticalFlowPass`              | EXR            | Signed XYZW Blender vector pass                          |
| `RawMaterialIndexPass`         | EXR            | Full integer material-ID field stored in a float channel |
| `MaterialIndexPass(index=...)` | PNG or EXR     | A mask for one selected material ID                      |

`ImageOutputType` supports `PNG`, `JPEG`, `TIFF`, and `EXR`. Use display formats for display-oriented color and masks. Use EXR whenever values are signed, high-dynamic-range, or metric.

## Raw data versus visualization [#raw-data-versus-visualization]

Mapping depth into `[0, 1]`, inverting a pass, or colorizing flow can be useful for inspection, but those transforms change the data. Keep authoritative training outputs lossless and generate previews separately.

## Alpha is not depth [#alpha-is-not-depth]

`Background.ALPHA` makes film transparent and gives useful Combined alpha, but removes the visible world from Combined color. `Background.SKY` preserves the world and normally makes Combined alpha opaque. Depth indicates geometric distance; it is not a substitute for volumetric transmittance or authored transparency.

## Material-ID semantics [#material-id-semantics]

Native material indices follow authored shading coverage. Transparent, dithered, and volumetric materials may alternate between exact ID zero and positive IDs. Rounding, denoising, or inventing a background ID does not correct that semantic boundary. A hard opaque material override is a separate render with different scene semantics.

## Optical-flow boundaries [#optical-flow-boundaries]

Flow depends on adjacent animation states. Render guard frames when downstream consumers need centered temporal support at the requested range boundaries. Store all XYZW components losslessly even when a preview uses only XY.


# dataset (/api/generated/dataset)



# `blendgen.dataset` [#blendgendataset]

Public symbols exposed by `blendgen.dataset`.

## `DatasetOutputType` [#datasetoutputtype]

[Class source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/dataset.py#L10)

```python
class DatasetOutputType(Enum)
```

Defines the type of dataset output file

### Values [#values]

```python
JSON = 'JSON'
NPY = 'NPY'
```

## `Dataset` [#dataset]

[Class source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/dataset.py#L16)

```python
class Dataset
```

A wrapper class to define the dataset index file

Raises:
ValueError: When prefix is not set
ValueError: When calling add\_frame without a frame\_num arg

Returns:
Dataset -- The instance of dataset created

### `Dataset.__init__` [#dataset__init__]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/dataset.py#L28)

```python
def __init__(self, prefix=None, dataset_name='BlendGen toy dataset', output_dir='data/toy_dataset/', filename='blendgen_dataset', output_type=None)
```

Create a dataset wrapper class

Keyword Arguments:
prefix \{str} -- The folder prefix to prepand (default: \{None})
dataset\_name \{str} -- The name of the                 dataset (default: \{"BlendGen toy dataset"})
output\_dir \{str} -- The base path                 of the dataset (default: \{"data/toy\_dataset/"})
filename \{str} -- Name of dataset index file                 without extension (default: \{"blendgen\_dataset"})
output\_type \{DatasetOutputType} -- The type of output                 file to save (default: \{None})

Raises:
ValueError: when a prefix is not provided

### `Dataset.add_attribute` [#datasetadd_attribute]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/dataset.py#L66)

```python
def add_attribute(self, attribute_name=None, attribute_value=None)
```

A method to manually add an attribute to the dataset

Keyword Arguments:
attributeName \{str} -- The name of the attribute (default: \{None})
attributeValue \{any} -- Any value you want to add (default: \{None})

### `Dataset.add_frame` [#datasetadd_frame]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/dataset.py#L79)

```python
def add_frame(self, frame_num=None, attributes=None, passes=None)
```

Add a frame to the dataset index file

Keyword Arguments:
frame\_num \{int} -- The current frame index (default: \{None})
attributes \{list} -- List of attributes (default: \{None})
passes \{list} -- List of render passes (default: \{None})

Raises:
ValueError: when a frame number is not provided

### `Dataset.save` [#datasetsave]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/dataset.py#L107)

```python
def save(self)
```

Save the dataset to file

### `Dataset.name` [#datasetname]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/dataset.py#L127)

```python
def name(self)
```

Dataset name getter

Returns:
str -- Name of the dataset

### `Dataset.prefix` [#datasetprefix]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/dataset.py#L136)

```python
def prefix(self)
```

Dataset prefix getter

Returns:
str -- The path prefix

### `Dataset.output_type` [#datasetoutput_type]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/dataset.py#L145)

```python
def output_type(self)
```

Getter for dataset file output type

Returns:
DatasetOutputType -- The type of output file

### `Dataset.raw` [#datasetraw]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/dataset.py#L154)

```python
def raw(self)
```

Dataset frames getter

Returns:
list -- The raw dataset frames list


# passes.alpha (/api/generated/passes-alpha)



# `blendgen.passes.alpha` [#blendgenpassesalpha]

Public symbols exposed by `blendgen.passes.alpha`.

## `AlphaPass` [#alphapass]

[Class source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/alpha.py#L8)

```python
class AlphaPass(BaseRenderPass)
```

No description is available yet.

### Values [#values]

```python
kind = RenderPassKind.ALPHA
```

### `AlphaPass.__init__` [#alphapass__init__]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/alpha.py#L10)

```python
def __init__(self, prefix='', output_type=ImageOutputType.PNG)
```

No description is available yet.


# passes.base (/api/generated/passes-base)



# `blendgen.passes.base` [#blendgenpassesbase]

Public symbols exposed by `blendgen.passes.base`.

## `ImageOutputType` [#imageoutputtype]

[Class source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/base.py#L11)

```python
class ImageOutputType(Enum)
```

An enum to change output file type of a given pass in a session
@todo Add FFMPEG video and npy binary options to BlendGen

### Values [#values]

```python
PNG = 'PNG'
JPEG = 'JPEG'
TIFF = 'TIFF'
EXR = 'OPEN_EXR'
```

## `BaseRenderPass` [#baserenderpass]

[Class source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/base.py#L22)

```python
class BaseRenderPass
```

No description is available yet.

### Values [#values-1]

```python
kind = None
```

### `BaseRenderPass.__init__` [#baserenderpass__init__]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/base.py#L24)

```python
def __init__(self, prefix=None, output_type=None, display_transform=False)
```

No description is available yet.

### `BaseRenderPass.init` [#baserenderpassinit]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/base.py#L42)

```python
def init(self, scene, base_path, background)
```

No description is available yet.

### `BaseRenderPass.add_map_value` [#baserenderpassadd_map_value]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/base.py#L50)

```python
def add_map_value(self, minimum=0, maximum=255, size=0.08)
```

Add a clamped Map Value compositor operation.

### `BaseRenderPass.add_invert` [#baserenderpassadd_invert]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/base.py#L55)

```python
def add_invert(self)
```

Add an image invert compositor operation.

### `BaseRenderPass.add_material_index_mask` [#baserenderpassadd_material_index_mask]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/base.py#L59)

```python
def add_material_index_mask(self, index, color=None)
```

Add a material-index mask, optionally colored with RGB values.

### `BaseRenderPass.output` [#baserenderpassoutput]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/base.py#L64)

```python
def output(self)
```

Create this pass's File Output node.

### `BaseRenderPass.connect_nodes` [#baserenderpassconnect_nodes]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/base.py#L71)

```python
def connect_nodes(self, layer_input)
```

No description is available yet.

### `BaseRenderPass.create_pass` [#baserenderpasscreate_pass]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/base.py#L86)

```python
def create_pass(self, source_socket)
```

Build this pass from a backend-resolved compositor socket.

### `BaseRenderPass.render_path` [#baserenderpassrender_path]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/base.py#L96)

```python
def render_path(self)
```

No description is available yet.

### `BaseRenderPass.ops` [#baserenderpassops]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/base.py#L100)

```python
def ops(self)
```

No description is available yet.

### `BaseRenderPass.linker` [#baserenderpasslinker]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/base.py#L104)

```python
def linker(self)
```

No description is available yet.

### `BaseRenderPass.node_manager` [#baserenderpassnode_manager]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/base.py#L108)

```python
def node_manager(self)
```

No description is available yet.

### `BaseRenderPass.prefix` [#baserenderpassprefix]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/base.py#L112)

```python
def prefix(self)
```

No description is available yet.

### `BaseRenderPass.base_path` [#baserenderpassbase_path]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/base.py#L116)

```python
def base_path(self)
```

No description is available yet.

### `BaseRenderPass.output_type` [#baserenderpassoutput_type]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/base.py#L120)

```python
def output_type(self)
```

No description is available yet.

### `BaseRenderPass.file_extension` [#baserenderpassfile_extension]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/base.py#L124)

```python
def file_extension(self)
```

No description is available yet.

### `BaseRenderPass.type` [#baserenderpasstype]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/base.py#L130)

```python
def type(self)
```

No description is available yet.

### `BaseRenderPass.display_transform` [#baserenderpassdisplay_transform]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/base.py#L134)

```python
def display_transform(self)
```

Whether non-EXR output should be converted to sRGB for display.


# passes.color (/api/generated/passes-color)



# `blendgen.passes.color` [#blendgenpassescolor]

Public symbols exposed by `blendgen.passes.color`.

## `ColorPass` [#colorpass]

[Class source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/color.py#L8)

```python
class ColorPass(BaseRenderPass)
```

No description is available yet.

### Values [#values]

```python
kind = RenderPassKind.COLOR
```

### `ColorPass.__init__` [#colorpass__init__]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/color.py#L10)

```python
def __init__(self, prefix='', output_type=ImageOutputType.PNG)
```

No description is available yet.


# passes.depth (/api/generated/passes-depth)



# `blendgen.passes.depth` [#blendgenpassesdepth]

Public symbols exposed by `blendgen.passes.depth`.

## `DepthPass` [#depthpass]

[Class source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/depth.py#L8)

```python
class DepthPass(BaseRenderPass)
```

No description is available yet.

### Values [#values]

```python
kind = RenderPassKind.DEPTH
```

### `DepthPass.__init__` [#depthpass__init__]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/depth.py#L10)

```python
def __init__(self, prefix='', map_values=False, minimum=0, maximum=255, invert_values=False, size=0.08, output_type=ImageOutputType.PNG)
```

No description is available yet.

### `DepthPass.create_pass` [#depthpasscreate_pass]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/depth.py#L25)

```python
def create_pass(self, source_socket)
```

No description is available yet.


# passes.index (/api/generated/passes-index)



# `blendgen.passes.index` [#blendgenpassesindex]

Public symbols exposed by `blendgen.passes.index`.

## `MaterialIndexPass` [#materialindexpass]

[Class source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/index.py#L8)

```python
class MaterialIndexPass(BaseRenderPass)
```

No description is available yet.

### Values [#values]

```python
kind = RenderPassKind.MATERIAL_INDEX
```

### `MaterialIndexPass.__init__` [#materialindexpass__init__]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/index.py#L10)

```python
def __init__(self, prefix='', index=0, output_type=ImageOutputType.PNG, rgb=None)
```

No description is available yet.

### `MaterialIndexPass.create_pass` [#materialindexpasscreate_pass]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/index.py#L19)

```python
def create_pass(self, source_socket)
```

No description is available yet.

## `RawMaterialIndexPass` [#rawmaterialindexpass]

[Class source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/index.py#L30)

```python
class RawMaterialIndexPass(BaseRenderPass)
```

Write Blender's unmodified per-pixel material index pass.

### Values [#values-1]

```python
kind = RenderPassKind.MATERIAL_INDEX
```

### `RawMaterialIndexPass.__init__` [#rawmaterialindexpass__init__]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/index.py#L35)

```python
def __init__(self, prefix='', output_type=ImageOutputType.EXR)
```

No description is available yet.


# passes.normal (/api/generated/passes-normal)



# `blendgen.passes.normal` [#blendgenpassesnormal]

Public symbols exposed by `blendgen.passes.normal`.

## `NormalPass` [#normalpass]

[Class source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/normal.py#L8)

```python
class NormalPass(BaseRenderPass)
```

No description is available yet.

### Values [#values]

```python
kind = RenderPassKind.NORMAL
```

### `NormalPass.__init__` [#normalpass__init__]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/normal.py#L10)

```python
def __init__(self, prefix='', output_type=ImageOutputType.PNG)
```

No description is available yet.


# passes.opticalflow (/api/generated/passes-opticalflow)



# `blendgen.passes.opticalflow` [#blendgenpassesopticalflow]

Public symbols exposed by `blendgen.passes.opticalflow`.

## `OpticalFlowPass` [#opticalflowpass]

[Class source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/opticalflow.py#L8)

```python
class OpticalFlowPass(BaseRenderPass)
```

No description is available yet.

### Values [#values]

```python
kind = RenderPassKind.OPTICAL_FLOW
```

### `OpticalFlowPass.__init__` [#opticalflowpass__init__]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/passes/opticalflow.py#L10)

```python
def __init__(self, prefix='', output_type=ImageOutputType.PNG)
```

No description is available yet.


# renderer (/api/generated/renderer)



# `blendgen.renderer` [#blendgenrenderer]

Shared render orchestration for all Blender render backends.

## `Background` [#background]

[Class source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderer.py#L15)

```python
class Background(Enum)
```

Background behavior for color rendering.

### Values [#values]

```python
ALPHA = 'TRANSPARENT'
SKY = 'SKY'
```

## `Renderer` [#renderer]

[Class source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderer.py#L22)

```python
class Renderer
```

Render requested semantic passes using an explicit backend.

### `Renderer.__init__` [#renderer__init__]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderer.py#L25)

```python
def __init__(self, *, backend=None, background=Background.ALPHA, resolution_percentage=100, resolution_x=1920, resolution_y=1080, output_base_path='data/toy_dataset/', passes=None, render_images=True)
```

No description is available yet.

### `Renderer.render` [#rendererrender]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderer.py#L122)

```python
def render(self, current_frame)
```

Render a frame and return the existing dataset pass-path schema.

### `Renderer.backend` [#rendererbackend]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderer.py#L209)

```python
def backend(self)
```

The explicit backend configuration used by this renderer.

### `Renderer.cameras` [#renderercameras]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderer.py#L214)

```python
def cameras(self)
```

Return the cameras available in the current Blender project.

### `Renderer.scenes` [#rendererscenes]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderer.py#L219)

```python
def scenes(self)
```

Return the scenes available in the current Blender project.

### `Renderer.camera` [#renderercamera]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderer.py#L224)

```python
def camera(self)
```

Return the active camera.

### `Renderer.scene` [#rendererscene]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderer.py#L229)

```python
def scene(self)
```

Return the active scene.

### `Renderer.width` [#rendererwidth]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderer.py#L234)

```python
def width(self)
```

Return the configured render width in pixels.

### `Renderer.height` [#rendererheight]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderer.py#L239)

```python
def height(self)
```

Return the configured render height in pixels.


# renderers.base (/api/generated/renderers-base)



# `blendgen.renderers.base` [#blendgenrenderersbase]

Renderer backend contracts and shared render-pass semantics.

## `RenderPassKind` [#renderpasskind]

[Class source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderers/base.py#L8)

```python
class RenderPassKind(Enum)
```

Semantic passes exposed by BlendGen, independent of Blender sockets.

### Values [#values]

```python
COLOR = 'color'
ALPHA = 'alpha'
DEPTH = 'depth'
NORMAL = 'normal'
OPTICAL_FLOW = 'optical_flow'
MATERIAL_INDEX = 'material_index'
```

## `UnsupportedRenderPassError` [#unsupportedrenderpasserror]

[Class source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderers/base.py#L19)

```python
class UnsupportedRenderPassError(ValueError)
```

Raised when a backend cannot reliably produce a requested pass.

## `RenderBackend` [#renderbackend]

[Class source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderers/base.py#L23)

```python
class RenderBackend(Protocol)
```

The small interface used by :class:`blendgen.renderer.Renderer`.

### `RenderBackend.name` [#renderbackendname]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderers/base.py#L28)

```python
def name(self) -> str
```

Return the Blender engine identifier.

### `RenderBackend.validate_passes` [#renderbackendvalidate_passes]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderers/base.py#L33)

```python
def validate_passes(self, pass_kinds) -> None
```

Reject semantic passes unsupported by this backend.

### `RenderBackend.configure_scene` [#renderbackendconfigure_scene]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderers/base.py#L38)

```python
def configure_scene(self, scene, blender) -> None
```

Apply this backend's settings to one Blender scene.

### `RenderBackend.bind_pass` [#renderbackendbind_pass]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderers/base.py#L43)

```python
def bind_pass(self, pass_kind, view_layer, render_layers)
```

Enable and return the compositor source for a semantic pass.

## `resolve_socket` [#resolve_socket]

[Function source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderers/base.py#L58)

```python
def resolve_socket(render_layers, pass_kind)
```

Resolve a compositor socket with compatibility aliases.

## `validate_known_passes` [#validate_known_passes]

[Function source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderers/base.py#L69)

```python
def validate_known_passes(pass_kinds)
```

Raise when a backend receives a pass outside BlendGen's semantics.


# renderers.cycles (/api/generated/renderers-cycles)



# `blendgen.renderers.cycles` [#blendgenrendererscycles]

Cycles renderer configuration.

## `CyclesDevice` [#cyclesdevice]

[Class source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderers/cycles.py#L10)

```python
class CyclesDevice(Enum)
```

Cycles rendering device choices.

### Values [#values]

```python
CPU = 'CPU'
GPU = 'GPU'
```

## `CyclesBackend` [#cyclesbackend]

[Class source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderers/cycles.py#L18)

```python
class CyclesBackend
```

Configuration for Blender's Cycles render engine.

### Values [#values-1]

```python
samples = 2
device = CyclesDevice.CPU
```

### `CyclesBackend.name` [#cyclesbackendname]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderers/cycles.py#L31)

```python
def name(self)
```

Return Blender's Cycles engine identifier.

### `CyclesBackend.validate_passes` [#cyclesbackendvalidate_passes]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderers/cycles.py#L35)

```python
def validate_passes(self, pass_kinds)
```

Ensure all requested passes are known to BlendGen.

### `CyclesBackend.configure_scene` [#cyclesbackendconfigure_scene]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderers/cycles.py#L39)

```python
def configure_scene(self, scene, blender)
```

Configure Cycles and, when requested, its GPU preferences.

### `CyclesBackend.bind_pass` [#cyclesbackendbind_pass]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderers/cycles.py#L47)

```python
def bind_pass(self, pass_kind, view_layer, render_layers)
```

Enable and resolve one Cycles compositor pass.


# renderers.eevee (/api/generated/renderers-eevee)



# `blendgen.renderers.eevee` [#blendgenrendererseevee]

Eevee renderer configuration.

## `EeveeBackend` [#eeveebackend]

[Class source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderers/eevee.py#L10)

```python
class EeveeBackend
```

Configuration for Blender's Eevee engine.

### Values [#values]

```python
samples = 16
```

### `EeveeBackend.name` [#eeveebackendname]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderers/eevee.py#L20)

```python
def name(self)
```

Return Blender's Eevee engine identifier.

### `EeveeBackend.validate_passes` [#eeveebackendvalidate_passes]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderers/eevee.py#L24)

```python
def validate_passes(self, pass_kinds)
```

Ensure requested passes are reliable in Eevee.

### `EeveeBackend.configure_scene` [#eeveebackendconfigure_scene]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderers/eevee.py#L31)

```python
def configure_scene(self, scene, _blender)
```

Configure Eevee samples for one Blender scene.

### `EeveeBackend.bind_pass` [#eeveebackendbind_pass]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/renderers/eevee.py#L38)

```python
def bind_pass(self, pass_kind, view_layer, render_layers)
```

Enable and resolve one Eevee compositor pass.


# session (/api/generated/session)



# `blendgen.session` [#blendgensession]

Public symbols exposed by `blendgen.session`.

## `Session` [#session]

[Class source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/session.py#L15)

```python
class Session
```

A session wrapper class used to manage dataset creation

### `Session.__init__` [#session__init__]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/session.py#L18)

```python
def __init__(self, renderer=None, dataset=None, output_dir=f'{getcwd()}/data/toy_dataset/', frame_start=0, frame_length=1, passes=None, on_before_new_frame=None, on_after_new_frame=None, on_start=None, on_complete=None)
```

Creates a session wrapper class used for a rendering session

Keyword Arguments:
renderer \{Renderer} -- BlendGen Renderer instace (default: \{None})
dataset \{Dataset} -- BlendGen Dataset instace (default: \{None})
output\_dir \{str} -- Dataset base path                 (default: \{"data/toy\_dataset/"})
frame\_length \{int} -- Length of sequence to render (default: \{1})
passes \{list} -- A list of render passes (default: \{None})
on\_before\_new\_frame \{function} -- Callback called before a                 new frame is rendered (default: \{None})
on\_after\_new\_frame \{function} -- Callback called after a                 new frame is rendered (default: \{None})
on\_start \{function} -- Callback called before a                 dataset is rendered (default: \{None})
on\_complete \{function} -- Callback called after a                 dataset is rendered (default: \{None})

### `Session.run` [#sessionrun]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/session.py#L80)

```python
def run(self)
```

Run the session and capture the dataset

### `Session.update` [#sessionupdate]

[Method source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/session.py#L120)

```python
def update(self)
```

Force-update data blocks, replacing Blender 2.7's `scene.update`.

### `Session.on_complete` [#sessionon_complete]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/session.py#L125)

```python
def on_complete(self)
```

Getter for the on complete callback

Returns:
:function: -- The function assigned or None

### `Session.on_start` [#sessionon_start]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/session.py#L134)

```python
def on_start(self)
```

Getter for the on start callback

Returns:
:function: -- The function assigned or None

### `Session.on_before_new_frame` [#sessionon_before_new_frame]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/session.py#L143)

```python
def on_before_new_frame(self)
```

Getter for the on before a new frame is rendered callback

Returns:
:function: -- The function assigned or None

### `Session.on_after_new_frame` [#sessionon_after_new_frame]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/session.py#L152)

```python
def on_after_new_frame(self)
```

Getter for the on after a new frame is rendered callback

Returns:
:function: -- The function assigned or None

### `Session.on_complete.setter` [#sessionon_completesetter]

[Setter source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/session.py#L161)

```python
def on_complete(self, callback)
```

A setter for the on complete callback

Arguments:
callback \{function} -- The callback to call when completed

### `Session.on_start.setter` [#sessionon_startsetter]

[Setter source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/session.py#L170)

```python
def on_start(self, callback)
```

A setter for the on start callback

Arguments:
callback \{function} -- The callback to call when started

### `Session.on_before_new_frame.setter` [#sessionon_before_new_framesetter]

[Setter source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/session.py#L179)

```python
def on_before_new_frame(self, callback)
```

A setter for the on new frame callback

Arguments:
callback \{function} -- The callback to call before every new frame

### `Session.on_after_new_frame.setter` [#sessionon_after_new_framesetter]

[Setter source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/session.py#L188)

```python
def on_after_new_frame(self, callback)
```

A setter for the after new frame callback

Arguments:
callback \{function} -- The callback to call after every new frame

### `Session.info` [#sessioninfo]

[Property source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/session.py#L197)

```python
def info(self)
```

Get a pretty printed ASCII table with the session info

Returns:
str -- The ASCII table string


# util (/api/generated/util)



# `blendgen.util` [#blendgenutil]

Public symbols exposed by `blendgen.util`.

## `camera_view_bounds_2d` [#camera_view_bounds_2d]

[Function source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/util.py#L25)

```python
def camera_view_bounds_2d(scene, cam_ob, me_ob)
```

Returns camera space bounding box of mesh object.

Negative 'z' value means the point is behind the camera.

Takes shift-x/y, lens angle and sensor size into account
as well as perspective/ortho projections.

Thanks to the wonderful
[https://blender.stackexchange.com/questions/7198/save-the-2d-bounding-box-of-an-object-in-rendered-image-to-a-text-file](https://blender.stackexchange.com/questions/7198/save-the-2d-bounding-box-of-an-object-in-rendered-image-to-a-text-file)

:arg scene: Scene to use for frame size.
:type scene: :class:`bpy.types.Scene`
:arg obj: Camera object.
:type obj: :class:`bpy.types.Object`
:arg me: Untransformed Mesh.
:type me: :class:`bpy.types.Mesh`
:return: a Box object (call its to\_tuple() method to get x, y, width and height)
:rtype: :class:`Box`

## `get_pose_bone_world_matrix` [#get_pose_bone_world_matrix]

[Function source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/util.py#L108)

```python
def get_pose_bone_world_matrix(armature_object, bone_name)
```

Get a pose bone's world matrix

Arguments:
armature\_object \{`bpy.types.Object`} -- The armature's object in the scene
pose\_bone \{`str`} -- The pose bone name to transform

Returns:
\{`mathutils.Matrix`} -- The world matrix for the pose bone

## `get_screen_coords` [#get_screen_coords]

[Function source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/util.py#L121)

```python
def get_screen_coords(world_position, renderer)
```

Utility to get screen coordinates of a world vector

Arguments:
world\_position \{`mathutils.Vector`} -- The vector 3 to transform
renderer \{\`blendgen.renderer.Renderer} -- The blendgen renderer instance

Returns:
\[type] -- \[description]

## `get_sensor_size` [#get_sensor_size]

[Function source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/util.py#L139)

```python
def get_sensor_size(sensor_fit, sensor_x, sensor_y)
```

Get the size of the sensor based on it's X, Y sizes

Returns:
\[float] - Width of sensor in float

## `get_sensor_fit` [#get_sensor_fit]

[Function source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/util.py#L150)

```python
def get_sensor_fit(sensor_fit, size_x, size_y)
```

Get the aspect ratio of the sensor based on it's X, Y sizes

Returns:
\[str] - Type of sensor

## `get_intrinsic_matrix` [#get_intrinsic_matrix]

[Function source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/util.py#L163)

```python
def get_intrinsic_matrix(renderer)
```

uild intrinsic camera parameters from Blender camera data
Arguments:
camera \{`blendgen.renderer.Renderer`} -- The Blender camera object

Returns:
\[mathutils.Matrix] -- A 3x4 projection matrix

## `get_rt_matrix` [#get_rt_matrix]

[Function source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/util.py#L208)

```python
def get_rt_matrix(renderer)
```

Returns camera rotation and translation matrices from Blender.

Arguments:
renderer \{blendgen.renderer.Renderer} - The BlendGen renderer

Returns:
\[mathutils.Matrix] - The RT matrix

## `get_camera_matrices` [#get_camera_matrices]

[Function source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/util.py#L250)

```python
def get_camera_matrices(renderer)
```

Get projection, intrinsic and rotation and translation matrices from camera


# utils.scene (/api/generated/utils-scene)



# `blendgen.utils.scene` [#blendgenutilsscene]

Helpers for reading Blender scene objects.

## `select` [#select]

[Function source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/utils/scene.py#L6)

```python
def select(name)
```

Return the Blender object with `name`.

## `bounding_box_to_world_positions` [#bounding_box_to_world_positions]

[Function source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/utils/scene.py#L13)

```python
def bounding_box_to_world_positions(obj)
```

Return an object's local bounding-box vertices as coordinate lists.

## `clamp` [#clamp]

[Function source](https://github.com/juniorxsound/BlendGen/blob/main/blendgen/utils/scene.py#L18)

```python
def clamp(value, minimum, maximum)
```

Constrain a numeric value to an inclusive range.