RfM
Batch Filtering


return to main index



Introduction

Filtering alters the statements in a Rib file, or files, before they are rendered. Filters can be written in C++ using Pixar's Rif API or they can be written in python using Pixar's "PRMan for Python". This tutorial deals with the use of Ri Filters (Rifs) written in python. The goal of the tutorial is to encourage readers to experiment with python Rifs.

The filtering technique shown here unfortunately cannot be performed on Windows.

It is assumed the reader has downloaded and installed the scripts presented in the tutorial RfM: Customizing.


Applying a Rif using Maya & RfM

Rifs enable outputs and effects to be achieved that might either be very tedious or impossible to do directly via the Maya/RfM interface. Rifs also enable shape and shading experimentations to be done efficiently because ribgen need not repeatably occur prior to rendering. Depending on the type of filtering to be performed a sequence of ribs can be filtered/rendered and re-filtered/re-rendered several times before it is necessary to generate a fresh set of ribs.



Figure 1
Maya+Python+PRman workflow


Batch Rif'ing

The tutorial RfM: Batch Rendering demonstrates how a sequence of frames to be rendered with the the stand-alone version of PRMan.
The Rif given in the listing 1 can be used to check the users Maya/RfM/python environment has been set up correctly. The Rif implemented in the module "rif_it" edits the Display statement of a beauty pass rib so that it produces a rendered image that can be seen immediately with Pixar's Image Tool ("it"). Copy the code and save it as rif_it.py in the RfM_python directory.


Listing 1 (rif_it.py)


import prman, os
  
class Rif(prman.Rif):
    def __init__(self, ri):
        prman.Rif.__init__(self, ri)
    def Display(self, name, driver, channels, params):
        if driver != 'shadow' and driver != 'deepshad' and driver != 'null':
            driver = 'it'
        self.m_ri.Display(name, driver, channels, params)


Applying a Rif with Maya

Open the script editor in Maya and enter the following command. A rendered image should appear in an "it" window.

    batchRenderRI("rif_it", 1,1);
    or,
    batchRenderRI("rif_it.Rif()", 1,1);

The batchRenderRI procedure does the following.
1.    Queries the values of "defaultRenderGlobals".
2.    If the second arg equals "1" it generates a fresh set of ribs.
3.    Calls a python module named batchrender.
4.    batchrender applies one or more python rifs.
4.    If third arg equals "1" batchrender renders the rib(s).

In a later section we will see how multiple Rifs can be specified by batchRenderRI().


What to do if the Rif fails to work

Check the following if the scripts fail to work. Most importantly have the scripts presented in the tutorial RfM: Customizing been downloaded and installed ??.

1.     Has the project directory been set in Maya?
2.     Has the scene been saved?
3.     Is batchRenderRI.mel in your maya/projects/RfM_mel directory?
4.     Are the python scripts in your maya/projects/RfM_python directory?


Applying a Rif using Cutter

When developing a Rif it is best to apply it directly to a rib file using a small python script - such as the one shown in listing 2. This can be conveniently done with Cutter. The script makes direct use of Pixar's prman module. Save the script as rif_tester.py in your maya/projects/RfM_python directory.


Listing 2 (rif_tester.py)


import prman, rif_it
  
ribin = 'PATH_TO_A_BEAUTY_PASS_RIB'
# ribout = 'PATH_TO_A_TEMPORARY_RIB'

# Access prman's RiXXX procs and definitions
ri = prman.Ri()
# Format the output for easier reading
ri.Option("rib", {"string asciistyle": "indented"}) 
  
rif = rif_it.Rif(ri)    # Get an instance of our Rif
prman.RifInit([rif])    # Tell prman about our Rif
  
ri.Begin('-')           # Echo the rib as it is processed
prman.ParseFile(ribin)  # Process the input rib
ri.End()                # Tell prman we're done!

Open rif_tester.py in Cutter and execute it using control+e, alt+e or Apple+e. You will get error messages if rif_tester.py is not in the same directory as rif_it.py. If the script runs successfully Cutter's Process Monitor will echo the contents of the input (beauty pass) rib but with its Display statement edited. For example,

    Display "renderman/test/images/test.iff" "it" "rgba"

If the reader wishes to apply the Rif and render an image they should change,

    ri.Begin('-')         # See the contents of the processed rib
    to
    ri.Begin(ri.RENDER)   # See the rendered image

Alternatively, if the reader wishes to save the filtered rib statements in another file they should change,

    ri.Begin('-')         # See the contents of the processed rib
    to
    ri.Begin(ribout)      # Create an output rib file

If the Rif fails to work it is most probably because the PYTHONPATH environment variable has not been set Cutter's run script (run.bat on Windows). For example, for Linux and MacOSX.

    export RMANTREE=PATH_TO_YOUR_RPS_INSTALLATION
    export PYTHONPATH=$PYTHONPATH:$RMANTREE/bin
    export RMS_SCRIPT_PATHS=./:FULL_PATH_TO/RfM_ini
    java -Xms256m -Xmx256M -classpath .:cutter.jar Cutter

For Windows the run.bat file should contain the following.

    set RMANTREE=PATH_TO_YOUR_RPS_INSTALLATION
    set PYTHONPATH=$PYTHONPATH:$RMANTREE\bin
    set RMS_SCRIPT_PATHS=.\:FULL_PATH_TO\RfM_ini
    java -Xms256m -Xmx256M -classpath .:cutter.jar Cutter

Applying a Rif(s) to a sequence of ribs with Cutter

The next script demonstrates how a sequence of ribs can be filtered.


Listing 3 (batch_tester.py)


import os.path, prman, rif_it
  
ribs = os.listdir(PATH_TO_RIB_DIRECTORY)
ri = prman.Ri()
ri.Option("rib", {"string asciistyle": "indented"})
rif = rif_it.Rif(ri)
prman.RifInit([rif])
  
for rib in ribs:
    if os.path.dirname(rib):
        continue
    if rib.endswith('.rib') == False:
        continue
    parent = os.path.dirname(rib)
    name = os.path.basename(rib)        
    tmpRib = os.path.join(parent, 'tmp_' + name)
    ri.Begin(tmpRib)
    prman.ParseFile(rib)
    ri.End()
    os.remove(rib)
    os.rename(tmpRib,rib)

Note this script over-writes the original input rib files. You may wish to edit the code so that the edited ribs do not replace the original rib files





© 2002- Malcolm Kesson. All rights reserved.