BlenderProc Publication Visualization

Publication-ready visualization of 3D objects and point clouds in seconds.

Mesh Point Cloud Mesh + Depth
mesh pcd mesh_depth

Head over to the repository’s GitHub Pages site for a prettier and more interactive version of this README!

Design philosophy: Following Andrej Karpathy and KISS.

Installation

Use the BlenderProc-managed Blender (the only supported workflow):

pip install git+https://github.com/hummat/bproc-pubvis.git
blenderproc pip install loguru tyro

The first call of blenderproc will download Blender. If you already have a local installation, you can use --custom-blender-path path/to/blender (this also needs to be used for all subsequent calls of blenderproc).

Development

Basic Usage

To render a mesh (or point cloud if the input is one), simply run:

blenderproc run main.py path/to/3d.obj

The following options can be added to:

You can test you render settings using any of the Blender primitives (monkey, cube, sphere, cone, cylinder, …) as the first argument.

Use blenderproc run main.py -- --help to see all available options and their descriptions (the -- passes flags through BlenderProc to Tyro).

Mesh Point cloud Depth
mesh pcd mesh_depth
suzanne (primitive, positional) --pcd True --light very_bright --pcd 1024 --point-size 0.01 --depth ray_trace --keep-mesh

Basic Options

Additional Options

Some examples of additional options to customize the rendering are shown below.

Color

To change the color of the rendered object, use the --color option using either any of the predefined colors (e.g. pale_violet), choosing from those at random (random_color), a completely random color (random), or a three-tuple of RGB values in range 0-1, e.g 0.8 0.5 0.2. Any of the matplotlib colormaps can be used as well. The background color can be changed using the --bg-color option.

Note: Use --seed None (or any changing integer) for non-deterministic results; default is 1337.

Mesh Point cloud Background
mesh pcd mesh_depth
--color bright_blue --pcd True --color cool --bg-color pale_turquoise

Background

By default, the background is transparent. To change this, use the --bg-color option as shown above. Additionally, set --transparent False to render the backdrop object. To use HDRI images as backdrops, use --backdrop path/to/hdri. HDRIs can be obtained e.g. via blenderproc download haven path/to/save/dir.

Backdrop Colored backdrop HDRI backdrop
backdrop bd_color hdri
--transparent False --transparent False --bg-color pale_red --transparent False --backdrop path/to/hdri

Light

The default light intensity for meshes is bright (0.7) and very_bright (1.0) for point clouds. Use a value between 0 and 1 or very_dark, dark, medium, bright, or very_bright to change the light intensity.

Very Dark Dark Medium
very_dark dark medium
--light very_dark --light dark --light medium

Shadow

Shadows are rendered by default. To disable them, use the --shadow off option. To make the shadow softer, use --shadow soft or --shadow hard for a harder shadow.

Soft shadow Hard shadow No shadow
soft hard no_shadow
--shadow soft --shadow hard --shadow off

Shading

The default shading is flat for meshes. Use --shade to change mesh shading; point clouds are unaffected by this option.

Flat shading (default) Smooth shading Auto-smooth shading
flat smooth auto
  --shade smooth --shade auto

Wireframe

To render the object as a wireframe, use the --wireframe option (e.g. --wireframe True or --wireframe red). The wireframe color can be changed using --wireframe color when --keep-mesh is specified.

Wireframe Mesh + Wireframe Mesh + Wireframe (Color)
wireframe wf_mesh wf_mesh_color
--wireframe True --wireframe True --keep-mesh --wireframe red --keep-mesh

Gravity

Objects hover slightly above the ground by default. To change this, use the --gravity option to run quick physics simulation to let the object fall to the ground before rendering.

Default With gravity
no_gravity gravity
  --gravity

Animations

To create an animation, use the --animate option. Control length with --frames (default: 72) and playback speed with --fps (default: 20). To keep transparency, which is not supported by GIF, use .mp4 as file extension.

Turn (default, loops) Tumble
turn tumble
--animate turn --animate tumble

Interactive 3D Visualization

To provide an interactive 3D visualization, use --export path/to/mesh.glb to export the object as a .glb file and use

<script type="module" src="https://ajax.googleapis.com/ajax/libs/model-viewer/4.1.0/model-viewer.min.js"></script>

<style>
model-viewer {
  width: auto;
  height: 300px;
  display: block;
  margin-left: auto;
  margin-right: auto;
}
</style>

<model-viewer 
  src="path/to/mesh.glb" 
  camera-controls tone-mapping="neutral" 
  shadow-intensity="1" 
  auto-rotate>
</model-viewer>

in any HTML file to display the object:

Further Options

Some additional useful options include:

Use blenderproc run main.py to see all available options and their descriptions.

Developer Setup

This repository is pyproject.toml-based and works well with uv:

uv sync --group dev   # create .venv and install app + dev deps
uv run ruff check .
uv run pyright
uv run pytest         # runs unit tests with coverage

Integration tests exercise the BlenderProc CLI end-to-end and are opt-in:

BPROC_INTEGRATION=1 uv run pytest tests/test_integration.py

To regenerate the README gallery assets with your GPU/HDRI set-up, run the gallery suite (writes into examples/ by default). This is opt-in and separate from the basic integration flag:

BPROC_INTEGRATION=1 BPROC_EXAMPLES=1 \
BPROC_HAVEN_DIR=/path/to/haven \
BPROC_EXAMPLES_OUT=examples \
uv run pytest tests/test_integration.py -k readme_gallery

Optional env knobs:

See AGENTS.md for contributor-focused details (tooling, PR expectations, and how to run integration tests safely).

Debugging

BlenderProc supports visual debugging inside Blender using blenderproc debug instead of blenderproc run. Adding --debug will further disable rendering and only set up the scene.

Credits

blenderproc

blender