Cutter
Testing Python Rifs

return to main index

Introduction

Filtering alters the statements in a Rib file, or Rib files, before they are rendered. Filters can be written in C++ using Pixar's RifPlugin 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. It is assumed the reader has downloaded and installed the scripts presented in the tutorial RfM 23: Customizing.

Up to version 22 of RenderManForMaya (RfM) it was possible to apply one of more compiled RifPlugins using a GUI that was built into Maya's Render Setting window. Unfortunately, RfM has never provided a convenient way of using python rifs. However, as explained in the tutorial "RfM 22 - Batch Rendering and Filtering" the scripts provided by the tutorial "RfM 23: Customizing" make it relatively easy to use python rifs when rendering an animation using Maya.

The goal of the tutorial is to encourage readers to experiment with python Rifs using the Cutter text editor.

What Are the Benefits of Rif'ing?

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 many shape and shading experimentations to be done efficiently because ribgen need not repeatedly occur prior to rendering. Depending on the type of filtering to be performed a rib (or a sequence of ribs) can be filtered/rendered and re-filtered/re-rendered several times before it is necessary to generate a new rib (or sequence of ribs). Using Cutter to develop a python Rif is efficient because it minimizes the use of Maya, or Houdini or any other bridge product.

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):
        driver = 'it'
        channels = 'rgba'
        params = {}
        #self.m_ri.ArchiveRecord(prman.Ri.COMMENT, " rif_it has been applied.");
        self.m_ri.Display(name, driver, channels, params)

Using a Rif with 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.

Figure 1

The script makes direct use of Pixar's prman module. Save the script as rif_tester.py in your maya/rfm_scripts/python directory.

Listing 1 (rif_tester.py)

# handy script for testing prman rif filters
import prman, rif_examples
  
ribin = 'PATH_TO_INPUT_RIB_FILE'
ribout = 'PATH_TO_OUTPUT_RIB_FILE'
    
ri = prman.Ri() # Access prman's RiXXX procs and definitions
  
 # Format the output for easier reading
ri.Option("rib", {"string asciistyle": "indented"}) 
 
rif = rif_examples.Rif(ri)    # Get an instance of our Rif
prman.RifInit([rif])          # Tell prman about our Rif
  
ri.Begin('-')                 # Echo the rib stream as it is rendered
#ri.Begin(ribout)             # Divert the rib stream to a file
prman.ParseFile(ribin)        # Process the input rib
ri.End()                      # Tell prman we're done!

As an example of using a specific rif, change rif_examples to rif_it on lines 2 and 13. The rif, listing 2, will change the Dispaly statement to that instead of an image being saved as an openexr file it will be rendered directly to "it" (Pixar's Image Tool). For example,

Display "FULL_PATH_TO/rib__perspShape_beauty.0001.exr" "openexr" "Ci,a" "string camera" ["|persp|perspShape"]

Display "FULL_PATH_TO/rib__perspShape_beauty.0001.exr" "it" "rgba" 

If the reader has downloaded the scripts provided in the tutorial "RfM 23: Customizing" there will be no need to save listing 2 as rif_it.py in their maya/rfm_scripts/python folder.

Listing 2 (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):
        driver = 'it'
        channels = 'rgba'
        params = {}
        #self.m_ri.ArchiveRecord(prman.Ri.COMMENT, " rif_it has been applied.");
        self.m_ri.Display(name, driver, channels, params)

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. 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/maya/rfm_scripts/image_tool
    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\maya\rfm_scripts\image_tool
    java -Xms256m -Xmx256M -classpath .:cutter.jar Cutter