Cutter
Rman & RiMel Scripting

return to main index

Download code.zip
View:
    runProgram.rman
    runProgramUI.mel
    runProgramRI.mel
    gen_points.py

Introduction

This tutorial explains how Cutter handles Pixar's RenderMan for Maya (RfM) ".rman" documents. A .rman file describes the UI that appears within the "Extra RenderMan Attributes" tab of a transform node or shape node - figure 1.

Figure 1
A custom interface added to the shape node.

A .rman script does not create the interface in Maya. That task is accomplished by a Mel script that uses two Pixar Mel procedures, rmanGetAttrName() and rmanAddAttr(). Based on the information contained in a .rman script the Mel script creates the UI widgets to a panel labelled "Extra RenderMan Attributes".

Naming Conventions

Cutter's authoring environment uses the following scripting and naming conventions. It is assumed a custom UI should be implemented by a .rman script and (at least) two Mel scripts. For example, the interface shown in figure 1 uses the following scripts.
    runProgram.rman (describes the interface)
    runProgramUI.mel (creates the interface)
    runProgramRI.mel (querries the interface and outputs extra rib statements)
Note the name of Mel script that creates the custom interface has the same name as the .rman script but with a UI suffix. The Mel script that querries the interface and calls RiMel commands has a RI suffix. The next section demonstrates how Cutter can pre-visualize an interface as well as generate code for the Mel scripts.

Example - An Interface for a Procedural Primitive

This section provides a step-by-step example of creating a ".rman" script and its associated Mel scripts from scratch. The work flow consists of three steps.
    Step 1 - A .rman script is created and previsualized in a browser.
    Step 2 - Cutter automatically generates the UI and RI .mel scripts.
    Step 3 - The .mel scripts are manually edited.

For the purposes of this tutorial the trio of files generated in steps 1 to 3 produce an interface that enables a procedural primitive, implemented by a gen_points.py script to render a large number of RenderMan points (particles) distributed in the vicinity of a proxy object. Therefore, this example consists of four scripts.

Figure 3 shows a nurbs sphere acting as a proxy object. The interface shown in figure 1 was "assigned" to the sphere by selecting the sphere and then running this mel command.

    runProgramUI();

At render time the sphere does not appear in the image, instead, it is replaced by a cluster of points as shown in figure 4.

Figure 3

Figure 4

The reader should review the tutorial, RfM: Customizing before continuing.

Step 1 - Creating the .rman UI description script

Use the Templates menu to generate an "empty" rman document - figure 5.
Save it as "runProgram.rman".

Figure 5

Adding a File Text Field

Right mouse click in the document, immediately after the first open curly brace, and use the popup menu to insert a "string" (file) param block - figure 6. Cutter will insert text that describes the widget - shown below on the right.

Figure 6

    Declare param {string rp_python_path} {
        label "Helper App Path"
        description "The path to the procedural helper app."
        subtype file
        range {*.py}
        }

Change the name of the param to rp_python_path and the label to Helper App Path and set the "range" to *.py. The prefix rp_ is derived from the name of the ".rman" document ie, runProgramUI

Adding a Int Slider

Use the popup menu to insert an "int" (slider) param block - figure 7. Then edit the code as shown below.

Figure 7

    Declare param {int rp_points_num} {
        label "Number of Particles"
        subtype slider
        range {1 10000 10}
        description "The number of particles to generate."
        }

Adding a Float Slider

Use the popup menu to insert a "float" (slider) param block - figure 8. Then edit the code as shown below.

Figure 8

    Declare param {float rp_points_width} {
        label "Particle Size"
        subtype slider
        range {0.001 1}
        description "The diameter of the particles."
        }

The .rman script should now look like this,

# runProgram.rman file
rman "-version 1" {
Declare param {string rp_python_path} {
    label "Helper App Path"
    description "The path to the procedural helper app."
    subtype file
    range {*.py}
    }
  
Declare param {int rp_points_num} {
    label "Number of Particles"
    subtype slider
    range {1 10000 10}
    description "The number of particles to generate."
    }
  
Declare param {float rp_points_width} {
    label "Particle Size"
    subtype slider
    range {0.001 1}
    description "The diameter of the particles."
    }
}

Although the coding of the .rman script has not been completed it can be pre-visualized in a browser.

Previewing the UI

To preview the interface defined by the ".rman" script use the keyboard shortcut alt + e, control + e or Apple + e. A representation of the user interface defined by the .rman script will open in a browser - figure 9.

Figure 9
UI previewed in a web browser

Two more float slider widgets must be added to the .rman script. When complete the script should like this.

Step 2.1 - Creating the UI Mel script

Right mouse click anywhere in the .rman document and from the popup menu select "UI PreShape script" - figure 10.

Figure 10

The Mel script generated by Cutter should be saved as runProgramUI.mel in the users RfM_mel directory. Refer to the tutorial "RfM: Customizing" for information about this directory.

In addition to writing the script Cutter will also append two additional blocks of information to the runProgram.rman script. The Collection and NodeOptions blocks added by Cutter enable the interface implemented by runProgramUI.mel to be assigned to the Geometric Settings panel of the RenderMan Controls window. This information is maintained by Cutter so the reader should not edit that part of the .rman script.

Step 2.2 - Creating the RI Mel script

Use the RfM Mel Export menu to generate the RI Script - figure 11.

Figure 11

The Mel script generated by Cutter should be saved as runProgramRI.mel in the users RfM_mel directory.

Step 3 - Editing the Mel scripts

The runProgramRI.mel script will require editing. The finished script is shown here.

Using the Scripts

The finished scripts (runProgram.zip) should be saved in the following locations.

    maya/
        |_ scripts/gen_points.py
        |
        |_projects/
                  |_ RfM_mel/
                            |_ runProgram.rman
                            |_ runProgramUI.mel
                            |_ runProgramRI.mel

To add the interface to the shape node of surface follow these two steps.
Step 1 - shape node
    Create an object, say a nurbs sphere one unit in radius.
Step 2 - shape node
    In the script window run this command,
        runProgramUI;
The interface shown in figure 1 will appear under the Shape tab of the Attributes editor. Use the browse button of the runProgram interface to reference the gen_points.py script.