PyBlend

PyBlend is a Python library for Blender. It provides a lot of valuable functions for Blender scripting.

Figure 1. Depth maps, random material images, and normal maps rendered using PyBlend with the Stanford Bunny.

Installation

Setting up the environment for Python in Blender is a challenge. However, following the steps below, you can easily configure the environment.

1. Download Blender from here.

   Note: if your project has strict environmental requirements, you must carefully select the version of Blender. Currently, there appears to be NO official release of Blender that directly supports Python 3.8, which can be verified from blender/tags. Here I use blender-3.3.1-linux-x64.tar.xz for Linux users with Python 3.10.2. Once you unzip the file, you will find a folder structured like this:

   ./blender-3.3.1-linux-x64
   ├── blender
   ├── 3.3
   ...

   where blender is the executable file (I will use {path/to/blender} or blender_app to represent this path in the following) and 3.3 contains the Python environment for Blender.

2. Download get-pip.py and install pip for Blender Python.

   $ wget https://bootstrap.pypa.io/get-pip.py
   
   $ ./blender-3.3.1-linux-x64/3.3/python/bin/python3.10 get-pip.py

3. Install PyBlend.

   $ ./blender-3.3.1-linux-x64/3.3/python/bin/pip install git+https://github.com/anyeZHY/PyBlend.git

4. You could install other packages in the same way. E.g.,

   $ ./blender-3.3.1-linux-x64/3.3/python/bin/pip install torch

Usage

Some functions of this package are used in the following papers:

• 3D-LLM: Injecting the 3D World into Large Language Models [NeurIPS 2023].
• CHORD: Category-level in-Hand Object Reconstruction via Shape Deformation [ICCV 2023].

I suggest using the following alias to simplify the command: alias blender_app='{path/to/blender}'.

1. Render Normal and Depth Images

Like teaser.gif, you can use PyBlend to render normal and depth images. By using the following command, you can generate 60 images ranging from 0 to 60 degrees.

$ blender_app -b -P scripts/teaser.py -- --begin 0 --end 60

2. OBJ in, Multi-view Images out

Figure 2. Multi-view images rendered using PyBlend with the XYZ Dragon, teapot, and Stanford Bunny.

With PyBlend, you can effortlessly render multi-view images from a single OBJ file. Using the provided command, you’ll be able to generate an impressive set of 30 images. Additionally, you have the option to assign HEX color to the object using the --color argument. A big thank you to Silvia Sellán for generously sharing her insightful blog!

$ blender_app -b -P scripts/multiview.py -- --input docs/bunny.obj --name bunny --num 30

$ blender_app -b -P scripts/multiview.py -- --input docs/dragon.obj --name dragon --num 30 --color 127EB4

3. Objaverse Extension 🔮

Figure 3. Rendering images for Objaverse dataset. Our script provides semantic segmentation (left), bounding box (middle left), RGB (middle), normal map (middle right), and depth map (right) images.

The Objaverse is an extensive 3D object dataset. To harness the potential of this dataset, we offer a script designed to assemble scenes with informative annotations. The script seamlessly fetches the required objects and orchestrates the rendering of scenes. By executing the following command, you can produce a total of {num_scene} * {num_views} images, with {num_obj} different objects randomly selected and positioned within each scene:

$ blender_app -b -P scripts/show_objaverse.py -noaudio -- --num_scene 10 --num_views 2 --num_obj 10

Please note that the -noaudio flag is included in order to prevent any audio device usage during this process.

4. Soft Body Simulation (Coming Soon!)

Figure 4. Soft body simulation using PyBlend with the Teddy Bear and Cloth.

TODO

Still under development. More functions will be added soon.

• Add visualization scripts.

• Add animation and physics simulation functions.

• Add Objaverse extension.

• Documentation.

Acknowledgements and Other Resources

• Blender Python API
• DLR-RM/BlenderProc
• yuki-koyama/blender-cli-rendering
• njanakiev/blender-scripting
• Objaverse-XL Rendering Script