FastRenderer: Optimized 3D Model Rendering Pipeline¶

FastRenderer is a high-throughput Python-based batch rendering system using Blender in headless mode.
Designed for both local and high-performance (HPC) GPU environments, it can process large collections of 3D models into multi-angle image outputs with adaptive camera positioning, format detection, and automatic scaling.

Quick Start¶

Scenario	Example Command	Description
Local desktop render	`python3 fastrenderer.py`	Scans `./input` for models and saves four renders per model to `./output`. Uses default “medium” quality.
Multi-GPU workstation	`python3 fastrenderer.py --parallel-mode --preset high`	Renders across all available GPUs concurrently for maximum throughput.
HPC job array execution	`python3 fastrenderer.py --hpc-mode --preset ultra`	Automatically splits datasets across nodes in SLURM or PBS job arrays.
Model validation only	`python3 fastrenderer.py --dry-run --check-textures`	Scans input dataset for valid models and textures without rendering.

Features¶

Efficient mass rendering via Blender 3.x–4.x in background mode.
Automatic scaling, centering, and clean scene management between models.
Adaptive camera distance and angle control.
Support for multiple 3D formats (.obj, .glb, .fbx, .stl, .usd, etc.).
Predefined and customizable render quality presets.
Optional multi-GPU and HPC distributed execution.
Texture presence validation with continuation control.
Fully scriptable CLI with environment-aware mode detection for SLURM or PBS clusters.

Installation¶

Requirements¶

Python 3.8+
Blender 3.0+ with background rendering support
OS with access to a CPU or GPU (Metal, CUDA, or OpenCL)

Blender must be installed system-wide and accessible via blender in your PATH.
The script automatically verifies its presence during initialization.

Usage¶

The standard, simplest usage requires only that your 3D models are placed in an input directory (./input by default):

python3 fastrenderer.py

This command will:

Scan ./input for supported model formats.
Render every model to ./output using the “medium” quality preset.
Produce four images per model (angles 0°, 90°, 180°, 270°).
Ensure transparent PNG backgrounds and write logs to the terminal.

Command-Line Arguments¶

Basic I/O and File Handling¶

Argument	Default	Description
`--input-dir`	`./input`	Path to the folder containing input 3D models.
`--output-dir`	`./output`	Destination path for rendered image outputs.
`--formats`	`.obj .glb .gltf .usdz .ply .fbx .dae .stl .usd .usda .usdc .abc`	File extensions that the renderer scans and processes. Multiple extensions supported.

Quality and Presets¶

Argument	Default	Description
`--preset`	`medium`	Predefined render quality. Choices: `draft`, `medium`, `high`, `ultra`.
`--resolution`	(from preset)	Override render resolution (pixels per dimension).
`--samples`	(from preset)	Override sample count for anti-aliasing or lighting.
`--camera-dist`	(from preset)	Override camera distance factor for model framing.

Preset summary:

Preset	Resolution	Samples	Camera Distance
`draft`	256	8	1.0
`medium`	512	32	1.8
`high`	1024	128	2.5
`ultra`	2048	256	3.0

Camera and Lighting¶

Argument	Default	Description
`--light-energy`	`4.0`	Light strength used for SunLight object in Blender scene.
`--light-angle`	`45.0`	SunLight rotation angle in degrees above the horizon.
`--transparent-background`	Enabled	Renders objects with alpha background when supported.
`--angles`	`0,90,180,270`	Fixed list of camera rotation angles (in degrees). Mutually exclusive with `--angle-iteration`.
`--angle-iteration`	None	Number of evenly spaced camera rotations around the model. Ignored if `--angles` is defined.

Texture Validation¶

Argument	Description
`--check-textures`	Enables verification that associated texture files exist.
`--skip-missing-textures`	When used with `--check-textures`, rendering continues even if textures are absent.

Examples:

python3 fastrenderer.py --check-textures --skip-missing-textures

By default (without --check-textures), no texture scanning is performed for maximum speed.

Performance and Execution¶

Argument	Default	Description
`--batch-size`	`50`	Number of models rendered per Blender batch process.
`--timeout-multiplier`	`1.0`	Scaling factor for adaptive timeout logic. Increase to prevent premature termination on heavy scenes.
`--engine`	`BLENDER_EEVEE`	Rendering engine. Options: `CYCLES`, `BLENDER_EEVEE`, `BLENDER_EEVEE_NEXT`, `BLENDER_WORKBENCH`.
`--verbose`	Off	Enables detailed debug logging output.
`--no-ansi`	Off	Removes color codes in log output (useful in CI or log systems).
`--dry-run`	Off	Runs full validation and model scanning but skips actual Blender invocation.

Parallel and HPC Modes¶

1. Parallel (Single-Node MultigPU or Multicore)¶

Argument	Description
`--parallel-mode`	Enables simultaneous rendering on multiple GPUs or CPU processes within a single node. GPU binding is automatic.

Example:

python3 fastrenderer.py --parallel-mode --preset high

This mode uses each available GPU (or CPU process) to process models concurrently, while maintaining separate logs and results aggregation.

2. HPC (Cluster Distributed Mode)¶

Argument	Description
`--hpc-mode`	Activates HPC-optimized distributed rendering. Implies `--parallel-mode`. Automatically detects SLURM or PBS job array environment.
`--chunk-index`	Manual override for job array index. Optional if HPC auto-detection is enabled.
`--total-chunks`	Manual override for total job count. Optional; used for non-cluster scripting.

When used under SLURM, the script automatically detects and correctly calculates job slices using: - SLURM_ARRAY_TASK_ID (current task ID) - SLURM_ARRAY_TASK_COUNT (total number of tasks) - SLURM_ARRAY_TASK_MIN (the starting index of the array)

If no environment variables are found, it defaults to a single-chunk (local) run.

Example HPC SLURM script:

#!/bin/bash
#SBATCH --job-name=blender_render
#SBATCH --output=logs/render_%A_%a.out
#SBATCH --array=0-7
#SBATCH --gres=gpu:2
#SBATCH --time=03:00:00

python3 fastrenderer.py \
  --hpc-mode \
  --preset high \
  --input-dir /shared/input \
  --output-dir /shared/output

Each job array index (0–7) automatically receives its partition of the files list and executes in parallel across 2 GPUs per node.

Diagnostic and Utility¶

Argument	Description
`--engine-list`	Prints all supported Blender rendering engines and exits.
`--dry-run`	Prints or logs which models would be processed, without invoking Blender.

Execution Modes Summary¶

Mode	Flags	Description
Default	`None`	Sequential rendering, one model after another.
Parallel	`--parallel-mode`	Renders across multiple GPUs or processes on a single machine.
HPC	`--hpc-mode`	Distributed job array rendering across multiple nodes; supports per-GPU parallelism on each node.

Example Workflows¶

Local quick test¶

python3 fastrenderer.py --preset draft

Batch render, GPU parallel¶

python3 fastrenderer.py --parallel-mode --preset high --angles "0,120,240"

Full HPC job¶

python3 fastrenderer.py --hpc-mode --preset ultra

Custom camera and lighting settings¶

python3 fastrenderer.py --light-energy 6.0 --light-angle 60 --angle-iteration 12

Output Structure¶

Each rendered model creates its own subdirectory inside the chosen output folder, matching the model’s relative path.
Each image file is named using the model’s base name and camera rotation:

output/
├── model_name/
│   ├── model_name_r000.png
│   ├── model_name_r090.png
│   ├── model_name_r180.png
│   └── model_name_r270.png

Logs and optional blender_error_<timestamp>.log files are written inside the output directory for debugging.

Performance Tips¶

For reliable GPU scaling, prefer Eevee or Cycles GPU engines.
Adjust --timeout-multiplier upward for large-scene batches.
Disable transparency (--no-ansi) to avoid GL composition overhead on CPU-only renders.
Always pre-stage large datasets to local SSD or node scratch space to avoid network I/O delays.
The BLENDER_EEVEE engine is significantly faster for large batches. Use CYCLES only if ray-tracing is required.
Adjust --timeout-multiplier upward (e.g., 1.5 or 2.0) if complex models or CYCLES cause batches to time out.
Adjust --batch-size to balance memory usage and per-model overhead. Smaller batches use less memory but have more startup cost.
Always pre-stage large datasets to local SSD or node scratch space to avoid network I/O delays.

Supported Formats¶

The loader supports automatic detection and import for: GLTF, GLB, FBX, OBJ, USD, USDZ, Alembic (ABC), Collada (DAE), STL, PLY, XYZ

Unsupported formats will raise a clear RuntimeError with recommendations.

Logging¶

Logging verbosity can be adjusted with --verbose.
Example output:

21:05:36 [INFO] Starting Optimized Renderer Processor CLI.
21:05:36 [INFO] Using Blender: Blender 4.1.0
21:05:46 [INFO] Found 8 model(s)
21:05:46 [INFO] Chunk 1: 8/8 successful
21:05:46 [INFO] Rendering complete.

License¶

This project is provided for research and production use under the MIT License.

Credits¶

Developed as a hybrid pipeline for high-throughput 3D dataset generation, integrating Blender’s Python API with optimized batch scheduling for both local and HPC rendering contexts.