PyBlenderRender

A modular Python-based rendering pipeline for Blender, designed for automated camera positioning and rendering of 3D models.

Features

• Modular configuration for camera, lighting, and rendering
• Multiple camera path generation techniques (spiral, pole rotation, cube views, etc.)
• Blender Python API for high-quality 3D rendering
• Extensible architecture for custom camera paths and lighting setups

---

Installation

Prerequisites

• Python 3.7 to 3.11
• Blender Python API 4.1 or later

Install Dependencies

Clone the repository and install the required dependencies:

git clone https://github.com/spa-dev/PyBlenderRender.git  
cd PyBlenderRender  
pip install .  

---

Usage

1. Basic Example: Render with Default Settings

from renderer.model_renderer import ModelRenderer

renderer = ModelRenderer()  # Uses default configs
renderer.render("model.glb", "output_renders")  # Run pipeline

2. Custom Camera Configuration

from renderer.config.render_config import RenderConfig
from renderer.config.camera_config import CameraConfig, CameraPathType
from renderer.model_renderer import ModelRenderer

custom_render_config = RenderConfig(resolution=(300,600), samples=2048)
custom_camera_config = CameraConfig(
    distance=15.0, 
    camera_density=30, 
    path_type=CameraPathType.SPIRAL_PHI
)

renderer = ModelRenderer(
    render_config=custom_render_config,
    camera_config=custom_camera_config
)

renderer.render("model.glb", "output_renders")

---

Examples

Orbit Camera Path

The following GIF was created with make_gif.py from a sequence of PNG images generated by PyBlenderRender and a Rubik's Cube model (see Attributions below). The script is located at:
PyBlenderRender/scripts/make_gif.py

Orbit Camera Path Animation:

---

3D Path Visualization

This GIF is an animated visualization of a 3D camera path created from visualize_path.ipynb. The notebook is located at:
PyBlenderRender/notebooks/visualize_path.ipynb

Spiral Linear Camera Path:

---

Project Structure

PyBlenderRender/
├── README.md
├── setup.py
├── requirements.txt
├── src/
│   ├── renderer/
│   │   ├── model_renderer.py         # Main rendering logic
│   │   ├── config/                   # Configuration classes
│   │   ├── camera/                   # Camera path logic
│   │   ├── lighting/                 # Lighting setups
│   │   └── utils/                    # Utilities (logging, etc.)
│   └── __init__.py
├── tests/                            # Unit tests
├── notebooks/                        # Jupyter Notebooks for experiments
├── scripts/                          # Utility scripts
├── docs/                             # Documentation
└── .gitignore

---

Known Issues and Limitations

Limited Number of Keyword Arguments

Keyword arguments are generally limited to core features of Blender. The code needs further modification to accept and pass additional keyword arguments.

Camera Distance Variability (Notable in CameraPathType.CUBE)

With the CUBE camera path type, the bottom view appears closer than others. This issue is related to object tracking inconsistencies, where the camera may not focus on the intended center of the object. Possible causes:

• Tracking constraint issues: The Damped Track constraint may affect final positioning in different ways, especially at extreme elevations.

• Object center definition variation: An object’s center can be calculated in multiple ways (e.g. GEOMETRY, CENTER_OF_MASS, MEDIAN, BOUNDS). The command bpy.ops.object.origin_set(...) modifies the object’s origin, potentially shifting the tracking target.

• Bounding box vs. true center: If the tracking target is set to the bounding box center, it may not match the intended center (i.e., geometric centroid or center of mass), or vice versa.

Workaround: Try various options until suitable tracking is achieved.

Light Energy Calculation Inconsistencies

Light energy calculations vary depending on lighting type. Try varying the light_intensity in LightingConfig until you reach a suitable level.

Camera Elevation Limits Not Implemented Yet

The min_elevation and max_elevation attributes in the CameraConfig class are currently defined but not implemented. These attributes do not affect camera positioning yet.

---

Extending the Project

Want to add a custom camera path?

1. Create a new file in src/renderer/camera/paths/, e.g., custom_path.py.
2. Subclass CameraPathGenerator and implement generate_positions().
3. Register it in camera/registry.py.

---

Contributing

Contributions are welcome! Feel free to submit issues or pull requests. This project is a low priority for me, so please accept my apologies in advance for slow responses.

---

Attributions

The test model is used under the Creative Commons Attribution 4.0 License:

• Rubik's Cube (https://skfb.ly/opCGZ) by BeyondDigital Licensed under Creative Commons Attribution (CC BY 4.0) License Details

---

License

MIT License – Free to use and modify. Test model is under CC BY 4.0 (see above).