Python driven Blender

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

Getting setup

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.pymodule exists at/Users/Shared/PythonDrivenBlender/Toolboxes. It is also assumed that an empty directory named ColladaExportsexists 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 2: Initializing the scene.

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

# Initialize a sceneManager
    params = { 'name'               : sceneParams['sceneName'],  # name of new scene
               'erasePreviousScene' : True,                      # erase old 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
              };

    scene = SceneUtilsV1.sceneManager(params);