Python driven Blender

This is a guide on procedural scene generation using the Blender-Python API that ships with Blender.

Step 0: Setting up.

To craft a scene using Python scripts, it is imperative to start Blender from within a terminal. This is the only way that you can see error messages generated by Blender's engine and any output generated by your print statements. In Mac OSX, generate a file called startBlender.command and enter the following into it.

#!/bin/sh
/Applications/Blender/blender.app/Contents/MacOS/blender

Next, go to Finder and double click on the startBlender.command icon. Blender should launch together with a Terminal.app.

In Blender, click on the Screen Layout button (button to the right of Help) in the Information viewport, and select the Scripting mode. This will open the following viewports: Text Editor, Python Console and 3D View.

In the Text Editor viewport, click on Text -> Create Text Block (or alternatively, press Control+N). This will create an empty document. Enter the following print command,

print('Hello from the Blender-Python API !');

then hit the Run Script button. You should see Hello from the Blender-Python API ! in the Terminal that launched with Blender. Great!

We will now proceed with the procedural generation of a scene using the Blender-Python API (bpy) module. To ease this process, we have created a Python module (called SceneUtilsV1.py) which contain methods for generating, configuring and positioning various scene components. Using this module the user can experience the power of procedurally-generated scenes without having to first learn the intricacies of the bpy module. More experienced users are welcome to modify and extend the supplied module to fit their needs.

Download the SceneUtilsV1.py module. In the following, it is assumed that the SceneUtilsV1.py module exists at /Users/Shared/PythonDrivenBlender/Toolboxes. It is also assumed that an empty directory named ColladaExports exists at /Users/Shared/PythonDrivenBlender. Let's begin.

Step 1: Importing the necessary modules.

In the Text Editor, create a new Text Block and type the following:

# Import the Blender-Python API module
import bpy
# Import necessary system modules
import sys
import imp
# Import necessary math functions from the math and mathutils modules
from math import pi, floor
from mathutils import Vector

# Set the root, toolboxes, and exports directories
rootDirectory    = '/Users/Shared/PythonDrivenBlender';  
toolboxDirectory = '{}/Toolboxes'.format(rootDirectory);
exportsDirectory = '{}/ColladaExports'.format(rootDirectory);

# Append the toolboxDirectory to the Blender scripts path
sys.path.append(toolboxDirectory);
 
# Import our custom scene toolbox module
import SceneUtilsV1;
imp.reload(SceneUtilsV1);

# Notify user that all is good so far.
print('All ok with the imports')

Hit Text->Save as and save this file as SceneTutorial.py. Then hit the Run Script button. Check the terminal. If all the paths have been set up correctly you should see All ok with the imports. If you see an Error: message, check your paths.

Step 1: Initializing the scene.

In the Text Editor, add the following:

# Generate a dictionary with various scene initialization parameters
params = { 'name'               : 'CheckerShadowScene',  # name of new scene
           'erasePreviousScene' : True,                  # erase existing scene
           'sceneWidthInPixels' : 1024,                  # 1920 pixels along the horizontal-dimension
           'sceneHeightInPixels': 768,                   # 1200 pixels along the vertical-dimension
           'sceneUnitScale'     : 1.0/100.0,             # set unit scale to 1.0 cm
           'sceneGridSpacing'   : 10.0/100.0,            # set the spacing between grid lines to 10 cm
           'sceneGridLinesNum'  : 20,                    # display 20 grid lines
         };
# Instantiate a sceneManager object with the above params
scene = SceneUtilsV1.sceneManager(params);

Save the code. Before re-running the script, note that the 3D view contains Blender's stock scene. Now hit the Run Script button. Note that the 3D viewport is now empty, only displaying a 20x20 spatial grid.

The above code block, instantiates a sceneManager object. The sceneManager class is defined in the SceneUtilsV1 module, and contains several utility methods for managing a Blender scene. This particular initialization, asks to erase all components of the previous scene, sets the size of the rendered image to 1024x768 (this can be changed in RenderToolbox3), specifies a metric coordinate system in which units are 1 cm, and sets a 20x20 display grid with a 10 cm line separation.