Rendering Using Python in mantra renders

There are two places where mantra can call Python. This allows users to fine-tune mantra’s processing of data.

• As the IFD is parsed, mantra can call a filtering function to query and change properties.

• Mantra can call a function at the completion of every tile. This lets you insert more sophisticated statistical analysis of the rendering process.

In Python scripts run by mantra, you can import the mantra module. The mantra module has two functions:

Use the -P option to mantra to specify a Python script that mantra should run during parting of the IFD file. You can specify multiple scripts separated by semicolons (;).

You can optionally specify arguments which mantra passes to the Python script when it’s loaded. You can use this to modify the behavior of the filtering script.

This script may define any of the following functions. If the script defines a function, mantra will call the function at the appropriate point while parsing the IFD file. Mantra will ignore any functions you don’t define.

def filterPlane():
    print 'Defining plane:',
          mantra.property('plane:channel'),
          mantra.property('plane:variable')
    mantra.setproperty('plane:quantization', 'float')

#
# Simple Example Filter
#

import sys, mantra

Verbose = False

# Process any arguments during initialization of the module

for arg in sys.argv[1:]:
    if arg == '-v':
        Verbose = True

# A callback to change the surface shader of all objects

def filterInstance():
    if Verbose:
        print 'Filtering:', mantra.property('object:name')

    mantra.setproperty('object:surface', 'plastic diff 1 0 0')

    catstr = mantra.property('object:categories')[0]
    categories = catstr.split(', ')
    for c in categories:
        if c == 'pass1':
            mantra.setproperty('object:renderable', 0)

        elif c == 'pass2':
            mantra.setproperty('object:surface', 'matte')
            mantra.setproperty('object:overridedetail', 1)

You can use the renderer:tilecallback property to specify a python script (and optional arguments) which mantra will run after each tile is completed.

Unlike the Python filters, only one script may be specified (commands may not be semi-colon separated). The script does not define functions that mantra calls. Instead, mantra runs the entire script each time a tile is complete. The tile script can not call mantra.setproperty().

Some additional properties are available to the tile callback which might be useful for gathering/printing statistics.

• tile:ntiles – The total number of tiles in the image.

• tile:ncomplete – The number of tiles completed so far.

• tile:laptime – The number of seconds taken to render the last tile.

• tile:totaltime – The total number of seconds to render since the render began. This does not include time to load the scene, but rather is defined as the time since the first tile began rendering.

• tile:coords – The tile bounding box (in pixels).

• tile:memory – The amount of RAM in use by mantra.

import sys,mantra

tile = mantra.property('tile:ncomplete')[0]
if tile == 1:
    # This is the first tile rendered in the image

    print mantra.property('renderer:name')
    ntiles = mantra.property('tile:ntiles')[0]
    prev_pct = -1
    lap = 0
    lsum = 0

lap += mantra.property('tile:laptime')[0]
pct = tile * 100 / ntiles

if pct != prev_pct:
    mem = mantra.property('tile:memory')[0]
    total = mantra.property('tile:totaltime')[0]
    fpct = float(tile)/float(ntiles) # Percent complete
    prev_pct = pct

    print('%03d%% Complete - Laptime %g/%g - ETA %g seconds\n' %
            (pct, lap, total, total/fpct))

    lap = 0         # Reset the lap counter