Blender Render Toolkit

A Python-based toolkit for rendering high-quality images and videos of 3D objects using Blender, specifically designed for research projects.

Features

• Simple command-line interface for headless rendering
• GPU-accelerated rendering with CUDA support
• Easy integration with research pipelines

Requirements

Hardware

• CUDA-compatible GPU
• Sufficient GPU memory for rendering

Software

• Python >= 3.10
• Blender >= 4.0 (via bpy)

Installation

pip install bpy

Usage

1. Render an object with albedo and normal uv maps

Check examples/avocado for an example input data including a base mesh, an albedo uv map, and a normal uv map.

Full Color Rendering

# Render a 360° rotating video (x-rotation: 75°)
CUDA_VISIBLE_DEVICES=0 python blender_obj_uv_normal.py --data_path ./examples/avocado --start_rot_x 75 --rotate_video

# Use ffmpeg to convert images to a video
ffmpeg -y -i output/avocado_full_color_rotate/%4d.png -c:v libx264 -r 30 -pix_fmt yuv420p output/avocado_full_color_rotate.mp4

Note: Remove the --rotate_video flag to render a single frame instead of a video sequence.

Normal Map Rendering

# Render a 360° rotating video (x-rotation: 75°)
CUDA_VISIBLE_DEVICES=0 python blender_obj_uv_normal.py --data_path ./examples/avocado --start_rot_x 75 --rotate_video --texture_type normal

# Use ffmpeg to convert images to a video
ffmpeg -y -i output/avocado_normal_rotate/%4d.png -c:v libx264 -r 30 -pix_fmt yuv420p output/avocado_normal_rotate.mp4

Note: Remove the --rotate_video flag to render a single frame instead of a video sequence.

Note: Add --normal_map "None" flag to render the base geometry normal without tactile textures

Note: Add --disable_shadow flag to render without the casted shadow

Albedo Map Rendering

# Render a 360° rotating video (x-rotation: 75°)
CUDA_VISIBLE_DEVICES=0 python blender_obj_uv_normal.py --data_path ./examples/avocado --start_rot_x 75 --rotate_video --texture_type albedo

# Use ffmpeg to convert images to a video
ffmpeg -y -i  output/avocado_albedo_rotate/%4d.png -c:v libx264 -r 30 -pix_fmt yuv420p output/avocado_albedo_rotate.mp4

Note: Remove the --rotate_video flag to render a single frame instead of a video sequence.

2. After rendering rotating views, create a video to visualize two modalities side by side with swiping effect

Example usage:

CUDA_VISIBLE_DEVICES=0 python swipe_window_freeze.py --obj_name avocado
ffmpeg -y -i  output/avocado_combined_swipe/%4d.png -c:v libx264 -r 30 -pix_fmt yuv420p output/avocado_combined_swipe.mp4

3. Batch process multiple object meshes

Example usage:

bash scripts/batch_blender.sh

Note:

• remove --start_rot_x 75 or set to other appropriate rotation angles for different meshes
• update data_path when necessary

Featured Projects

Projects that have successfully used this toolkit:

• FlashTex
• TactileDreamFusion

References and related works

• BlenderToolBox
• Blender-cli-rendering
• kiuikit

Contributing

We welcome contributions! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License.