# dlr-rm/blenderproc architecture

> Architecture diagram of the GitHub repository dlr-rm/blenderproc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dlr-rm/blenderproc
- Repository: https://github.com/dlr-rm/blenderproc

## Overview

##### Project Type and Purpose
- BlenderProc2 is a Python-based application meant to be run within the Blender Python environment. From the README, its primary purpose is to build and render 3D scenes in Blender procedurally. It supports loading various 3D file formats, applying physics, camera and lighting setup, and outputting different data formats (RGB images, depth maps, annotations, etc.).
- The project is structured as a library with a CLI (the “blenderproc” command) that initializes BlenderProc, reads user scripts, and executes a well-defined rendering pipeline leveraging Blender’s API.

##### File Structure Components
- Core Modules and Packages:
- The “blenderproc” directory contains the core modules. There are several submodules under “blenderproc/api” (e.g., camera, loader, lighting, renderer, writer, constructor, etc.) that encapsulate main functionalities.
- The “blenderproc/python” directory mirrors these functionalities with higher-level Python wrappers and utility functions. These packages are used to define the actual pipeline operations (scene creation, object manipulation, camera sampling, etc.).
- External Integrations:
- The “blenderproc/external” directory, for instance, includes integration with VHACD (used for convex decomposition), suggesting that some computational geometry tasks are handled externally.
- The “resources” directory and its subfolders contain data files (e.g., material files, mapping CSVs, 3D resource files), which serve as application input data.
- Supporting Files:
- CLI-related scripts (e.g., “blenderproc/__main__.py” and “cli.py”) provide an entry point for running the system.
- The “docs”, “examples”, and “tests” directories help illustrate usage patterns, document API details, and ensure the stability of each module.
- Configuration files (.pylintrc, setup.py, MANIFEST.in, etc.) are used for development, packaging, and deployment.

##### Key Architectural Components
A. Command-Line Interface (CLI) & Execution:
B. Blender Runtime Environment Integration:
- A component that denotes that execution happens inside Blender’s Python environment. This part of the architecture is responsible for interfacing with Blender’s API, enabling the creation and manipulation of 3D scenes.
C. Core Pipeline Modules:
- Camera API: Handling camera configuration and sampling (blenderproc/api/camera, blenderproc/python/camera).
- Loader API: In charge of loading different 3D file formats (blenderproc/api/loader, blenderproc/python/loader).
- Lighting API: Controls light creation and sampling within scenes.
- Object and Material APIs: Managing object properties, materials, and object manipulation.
- Renderer API: Configuring various rendering setups (RGB, depth, segmentation, etc.) including rendering control logic.
- Writer API: Handling result exporting (e.g., writing to HDF5, COCO, or BOP formats).
- Additional modules (constructor, filter, sampler, postprocessing, etc.) which complement the core functionality.
D. Utility and Helper Components:
- A block denoting “Utility Modules” (located under blenderproc/python/utility and blenderproc/api/utility) that provide shared functionality such as configuration, math utilities, physics simulation helpers, and installation support.
- External libraries integrated for tasks like convex decomposition (e.g., VHACD).
E. Data & Resource Management:
- A component for “Resources & Data Files” (resources, resources inside the blenderproc directory, examples) that are consumed at runtime by loaders and other modules.

##### Relationships and Data Flow
- Interactions among API modules: for example, the Loader module feeds 3D object data to the Object API; the Camera API and Lighting API set up rendering parameters which are then utilized by the Renderer; after scene processing, the Writer API exports the results.
- Pipeline sequence: Initialization → Scene Construction → Camera & Lighting Setup → Rendering → Data Writing/Export.
- Configuration flow (e.g., how utility modules are used for parsing configurations and setting default parameters).

##### Architectural Patterns & Design Principles
- Modularization: The clear separation of responsibilities (camera, loader, material, etc.) indicates a modular design that can be diagrammed as separate yet interconnected components.
- API Layering: There is a logical distinction between low-level API modules (found under blenderproc/api) and higher-level integration (in blenderproc/python), reflecting an abstraction layering pattern.

## Diagram (Mermaid)

```mermaid
flowchart TD
    US["User Script (via CLI)"]:::cli
    CLI["CLI Entry Point"]:::cli
    ENG["BlenderProc Engine (Blender Environment)"]:::engine
    LD["Loader API"]:::api
    CST["Constructor Module"]:::api
    subgraph "Scene Setup"
        OBJ["Object API"]:::api
        MAT["Material API"]:::api
        CAM["Camera API"]:::api
        LIT["Lighting API"]:::api
    end
    RND["Renderer API"]:::api
    WRT["Writer API"]:::api
    EXP["Exported Data"]:::engine

    UTIL["Utility Modules"]:::utility
    RES["Resources & Data Files"]:::external
    EXT["External: VHACD"]:::external

    subgraph "Supporting"
        DOC["Documentation"]:::support
        EX["Examples"]:::support
        TEST["Tests"]:::support
    end

    US --> CLI
    CLI --> ENG
    ENG --> LD
    RES --> LD
    EXT -.-> LD
    LD --> CST
    CST --> OBJ
    CST --> MAT
    CST --> CAM
    CST --> LIT
    OBJ --> RND
    MAT --> RND
    CAM --> RND
    LIT --> RND
    RND --> WRT
    WRT --> EXP

    UTIL -.-> LD
    UTIL -.-> CST
    UTIL -.-> RND

    CLI -.-> DOC
    CLI -.-> EX
    CLI -.-> TEST

    click CLI "https://github.com/dlr-rm/blenderproc/blob/main/blenderproc/__main__.py"
    click CLI "https://github.com/dlr-rm/blenderproc/blob/main/cli.py"
    click ENG "https://github.com/dlr-rm/blenderproc/tree/main/blenderproc"
    click CAM "https://github.com/dlr-rm/blenderproc/tree/main/blenderproc/api/camera"
    click CAM "https://github.com/dlr-rm/blenderproc/tree/main/blenderproc/python/camera"
    click LD "https://github.com/dlr-rm/blenderproc/tree/main/blenderproc/api/loader"
    click LD "https://github.com/dlr-rm/blenderproc/tree/main/blenderproc/python/loader"
    click LIT "https://github.com/dlr-rm/blenderproc/tree/main/blenderproc/api/lighting"
    click LIT "https://github.com/dlr-rm/blenderproc/tree/main/blenderproc/python/lighting"
    click MAT "https://github.com/dlr-rm/blenderproc/tree/main/blenderproc/api/material"
    click MAT "https://github.com/dlr-rm/blenderproc/tree/main/blenderproc/python/material"
    click RND "https://github.com/dlr-rm/blenderproc/tree/main/blenderproc/api/renderer"
    click RND "https://github.com/dlr-rm/blenderproc/tree/main/blenderproc/python/renderer"
    click WRT "https://github.com/dlr-rm/blenderproc/tree/main/blenderproc/api/writer"
    click WRT "https://github.com/dlr-rm/blenderproc/tree/main/blenderproc/python/writer"
    click OBJ "https://github.com/dlr-rm/blenderproc/tree/main/blenderproc/api/object"
    click OBJ "https://github.com/dlr-rm/blenderproc/tree/main/blenderproc/python/object"
    click CST "https://github.com/dlr-rm/blenderproc/tree/main/blenderproc/api/constructor"
    click CST "https://github.com/dlr-rm/blenderproc/tree/main/blenderproc/python/constructor"
    click UTIL "https://github.com/dlr-rm/blenderproc/tree/main/blenderproc/api/utility"
    click UTIL "https://github.com/dlr-rm/blenderproc/tree/main/blenderproc/python/utility"
    click EXT "https://github.com/dlr-rm/blenderproc/tree/main/blenderproc/external/vhacd"
    click RES "https://github.com/dlr-rm/blenderproc/tree/main/blenderproc/resources"
    click DOC "https://github.com/dlr-rm/blenderproc/tree/main/docs"
    click EX "https://github.com/dlr-rm/blenderproc/tree/main/examples"
    click TEST "https://github.com/dlr-rm/blenderproc/tree/main/tests"
    click TEST "https://github.com/dlr-rm/blenderproc/tree/main/blenderproc/python/tests"

    classDef cli fill:#CEF6F5,stroke:#1E90FF,stroke-width:2px;
    classDef engine fill:#F5D0A9,stroke:#FF8000,stroke-width:2px;
    classDef api fill:#D0F5A9,stroke:#32CD32,stroke-width:2px;
    classDef utility fill:#F6CEF5,stroke:#FF69B4,stroke-width:2px;
    classDef external fill:#F5A9A9,stroke:#FF4500,stroke-width:2px;
    classDef support fill:#A9D0F5,stroke:#1E90FF,stroke-width:2px;
```
