Ben Heasly edited this page Oct 17, 2016 · 8 revisions

The BlenderPython example uses a parent scene generated procedurally via the Blender-Python API and a custom python module for RenderToolbox Python module.

Above, Mitsuba rendered the scene.


The parent scene itself is called "CheckerShadow", and models a checkerboard and a cylinder, which casts a shadow on the checkerboard.

See Python-driven-Blender for more about modeling with Blender and Python in general.


Use the example script rtbMakeCheckerShadowScene.m to produce the image above.


The BlenderPython scene is special in that its geometry is defined procedurally, instead of using Blender's GUI. Procedural generation of scene geometry offers several advantages:

  • Arbitrarily complex geometric patterns with specified spatial statistics can be easily generated, e.g., the table cloth in the scenes below. Such patterns would be very difficult, if at all possible, using Blender's GUI.
  • The geometric attributes of all each and every scene component can be loaded from a text file. In such a case, the mappings file, the conditions file, and this geometry file form a complete parametric description of the stimulus.
  • A family of scenes varying in one or more geometric aspect(s) can be generated automatically.
  • Use of the complicated Blender GUI can be kept at a bare minimum, or even eliminated.

The BlenderPython scene depicts a version of the checker-shadow illusion. It consists of a checkerboard, a cylinder, a table cloth, two area lights and a room enclosure. The left area light is responsible for the shadow cast by the cylinder on the checkerboard, whereas the front area light provides a more uniform illumination of the scene. There are two versions, one with a dimpled checkerboard, and one with a flat surface checkerboard. Note that in both versions, the luminance of the square at (row,col) = (3,3) from the top left corner is nearly identical to that of the square at (row,col) = (1,4). Yet, the square at (3,3) appears light and the square at (1,4) appears dark. Also note that the cloth material adds significant realism to the overall scene.

Here is what the dimpled checkerboard version looks like (Mitsuba rendering):

And here is what the non-dimpled checkerboard version looks like (Mitsuba rendering):

Geometric scene modeling (Blender-Python code)

The scene geometry is generated procedurally via a Python script,, located in (path-to-RenderToolbox3)/ExampleScenes/BlenderPython/. This script calls methods of our custom BlenderPython module,, located in (path-to-RenderToolbox3)/Utilities/BlenderPython/. The provides a high-level interface for generating a number of scene elements. Its methods interact directly with Blender's 3D modeling engine via the module which ships with Blender (version 2.68a).

To generate this scene, launch Blender from a terminal as described at Python-driven-Blender. Then open a TextEditor viewport, and type the following:

path = '(path-to-RenderToolbox3)/ExampleScenes/BlenderPython';
sceneName = '';
filename = '{}/{}'.format(path,sceneName);
exec(compile(open(filename).read(), filename, 'exec'));

Then hit the Run Script button.

Alternatively, you can interactively build the scene one component at a time, by running parts of the script as described at Python-driven-Blender.