Cutter
Ri Mel Scripting

return to main index

Introduction

This tutorial explains how Cutter handles Pixar's RenderMan Studio (RMS) ".rman" documents. Rman files describe the characteristics of custom attributes that appear within the "Extra RenderMan Attributes" tab. For example, listing 1 defines the interface shown in the first illustration.

Listing 1 (grassOnPatchUI.rman)

Each of the Declare param blocks in listing 1 act, in effect, as a (user-interface) cookie cutter. The interface is created and added to the "Extra RenderMan Attributes" tab as a result of calling a proc implemented in one of the Mel scripts that accompany the ".rman" document.

The tutorial "RMS: Ri Scripting" recommends the use of a strict naming convention for ".rman" files and their "associated" Mel scripts. For example, the Mel script that adds custom attributes to the RenderMan tab should have the same name as the ".rman" script. Likewise the Mel script that querries the interface and injects additional statements into the Rib stream should have a name that matches the ".rman" file.

Hence, ".rman" script, shown in listing 1, should be accompanied by,
    grassOnPatchUI.mel, and
    grassOnPatchRi.mel.

The next section looks at the ways in which Cutter can assist in editing "xxxUI.rman" files and how it can generate their associated "xxxUI.mel" and "xxxRI.mel" scripts.

Popup Menu

The popup menu (activated by a right-mouse click or control+click) has several menu items help a user to edit a ".rman" file. Figure 2 shows a Declare param that has been added to a ".rman" document as the result of using the Strings->file menu item.

Figure 2

Figure 3 shows how the UI PreShape Script item can create the Mel script (shown in the background window) that implements a proc that will add the custom attributes to the Extra RenderMan Attributes tab as a result of referencing the param's defined by a ".rman" document.

Figure 3 - Generating a UI Mel Script

Work Flow

This section provides a step-by-step example of creating a ".rman" document and its associated Mel scripts from scratch. The trio of files implement a preShapeScript that querries the positions of particles in a particle system so that a pre-baked rib can be instanced at each particle position. The scripts that will be created are,

    addBakedToParticlesUI.rman
    addBakedToParticlesUI.mel
    addBakedToParticlesRI.mel

As each file is created it should be saved in the following directory,
    maya/projects/RMS_mel
If you do not have a RMS_mel and/or a RMS_ini directory create it/them. Refer to the suggestions in the tutorial RMS: Directories & Scripts concerning RMS directories, environment variables and initialization files.

Step 1

Use the Templates menu to generate an "empty" rman document ie.
    Templates->Rman->cutrBasic.rman
Save it as "addBakedToParticlesUI.rman".

Step 2

Use the popup menu to insert a "file" block - figure 4.

Figure 4 - A file param block inserted by Cutter

Change the name of the param from "abtp_Str1" to "abtp_bakeFile". The prefix abtp_ will be assigned to each of the param's generated by the popup. The prefix is derived from the name of the ".rman" document ie,
    addBakedToParticlesUI.rman

Edit the label and the description, as shown in figure 5.

Figure 5

Step 3

Use the popup menu to add three "float slider" blocks. Edit their text so that they conform to listing 2.

Listing 2 (addBakedToParticlesUI.rman)

rman "-version 1" {
  
Declare param {string abtp_bakeFile} {
    label "Pre-Baked Rib"
    description "The path to a rib archive file."
    subtype file
    range {*.rib}
    }
Declare param {float abtp_xScale} {
    label "X Scale"
    subtype slider
    range {0 10 .001}
    description "Scales the archive in x."
    }
Declare param {float abtp_yScale} {
    label "Y Scale"
    subtype slider
    range {0 10 .001}
    description "Scales the archive in y."
    }
Declare param {float abtp_zScale} {
    label "Z Scale"
    subtype slider
    range {0 10 .001}
    description "Scales the archive in z."
    }
}

Step 4

Use the General Options->Select Block menu item to ensure the curley braces are "balanced" - figure 6.

Figure 6

To preview the interface defined by the ".rman" script, use the keyboard shortcut alt + e or control + e (MacOSX can also use Apple + e) - figure 7. A html document, plus its associated graphics, will be saved in a folder named "addBakedToParticles" within the Cutter directory.

Figure 7 - Previewing the interface with a browser.

Step 5

Use the RMS Mel Export menu to generate a preShapeScript - figure 8.

Figure 8

Listing 3 shows the Mel script that Cutter will generate. Save the script in the RMS_mel directory.

Listing 3 (addBakedToParticlesUI.mel)

global proc addBakedToParticlesUI() 
{
string $selected[] = `ls -sl`;
int $i, $j;
  
for( $i=0; $i < size($selected); $i++ ) 
    {
    string $shp[] = `listRelatives -shapes $selected[$i]`;
    string $shapeName = $shp[0];
    string $attr = `rmanGetAttrName "preShapeScript"`;
  
    // "Connect" to the mel script that calls 
    // Pixar's custom Ri mel procedures.
    rmanAddAttr $shapeName $attr "addBakedToParticlesRI";
        
    $attr = `rmanGetAttrName "abtp_bakeFile"`;
    rmanAddAttr $shapeName $attr "RIB_Archive/";
  
    $attr = `rmanGetAttrName "abtp_xScale"`;
    rmanAddAttr $shapeName $attr "1.0";
  
    $attr = `rmanGetAttrName "abtp_yScale"`;
    rmanAddAttr $shapeName $attr "1.0";
  
    $attr = `rmanGetAttrName "abtp_zScale"`;
    rmanAddAttr $shapeName $attr "1.0";
  
    }
}

Step 6

Use the RMS Mel Export menu to generate an RI Script - figure 9.

Figure 9

Listing 4 shows the Mel code that will be generated. Save the script in the RMS_mel directory.

Listing 4 (addBakedToParticlesRI.mel)

obal proc addBakedToParticlesRI()
{
// Get the name of the shape node
string $shapeNode = `rman ctxGetObject`;
  
// Get the name of the transform node
string $parents[] = `listRelatives -parent $shapeNode`;
string $tformNode = $parents[0];
  
// The node may hava a number in its name that we can use to set the
// random number generator
int    $nodeNumber = `match "[0-9]+" $shapeNode`;    
if($nodeNumber != "") {
    seed(int($nodeNumber));
    }
  
string $attr;
$attr = `rmanGetAttrName "abtp_bakeFile"`;
string $abtp_bakeFile = `getAttr($shapeNode + "." + $attr)`;
  
$attr = `rmanGetAttrName "abtp_xScale"`;
float $abtp_xScale = `getAttr($shapeNode + "." + $attr)`;
  
$attr = `rmanGetAttrName "abtp_yScale"`;
float $abtp_yScale = `getAttr($shapeNode + "." + $attr)`;
  
$attr = `rmanGetAttrName "abtp_zScale"`;
float $abtp_zScale = `getAttr($shapeNode + "." + $attr)`;
  
// Use of Pixar's custom RenderMan Studio procedures begins here...
RiTransformBegin();
    RiSphere(1, -1, 1, 360);
RiTransformEnd();
}

The last three lines of Mel are present only for the purposes of testing the script. In step 8 they will be replaced by the code that will querry a particle system and write the appropriate Rib statements.

The remaining steps assume the reader has set up their maya environment as suggested in the RMS: Directories & Scripts tutorial.

Step 7

There should be three scripts in the maya/projects/RMS_mel directory. Launch Maya so that the RfM Pro plugin will source the "addBakedToParticlesUI.rman" script. As of version 1.1 of RenderMan Studio, ".rman" scripts cannot be re-sourced after Maya has started. If changes are made to a ".rman" script Maya must be restarted for the effects of the edits to be seen.

For the purposes of testing the Mel scripts an object such as a poly plane should be added to the Maya scene. At this stage it is not necessary to use a particle system. Make sure the poly plane is selected, then enter the following command in Maya's Script Editor.
    addBakedToParticlesUI;

It may be necessary to toggle the pPlane1 and pPlaneShape1 tabs in order to see the "Extra RenderMan Attributes" tab - figure 10.

Figure 10

Use the Render->Render Using menu item to select "RenderMan" and then choose Render->Render Current Frame (options) to choose "Internal Render to it". Render one frame. If the camera has been pulled far enough from the poly plane you should see a single sphere - figure 11.

Figure 11

Next, the code for handling particle systems will be added to the "addBakedToParticlesRI.mel" script.

Step 8

Replace the last three lines of code in the "addBakedToParticlesRI.mel" script with the text shown in listing 5.

Listing 5

// Use of Pixar's custom RenderMan Studio procedures begins here...
int     $numParticles = `particle -q -count $tformNode`;
float    $pos[];
  
for($n = 0; $n < $numParticles; $n++) {
    $pos = `getParticleAttr -at position ($shapeNode + ".pt[" + $n + "]")`;
    RiTransformBegin();
        RiTranslate($pos[0], $pos[1], $pos[2]);
        RiScale($abtp_xScale, $abtp_yScale, $abtp_zScale);
        RiReadArchive($abtp_bakeFile);
    RiTransformEnd();
    if($n == ($numParticles - 1)) {
  
        // Ensure the proxy object to which our script is "attached" 
        // is completely "inactive" with regard to rendering
        RiAttribute "visibility" "int camera" 0;
        RiAttribute "visibility" "int transmission" 0; 
        RiAttribute "visibility" "int diffuse" 0; 
        RiAttribute "visibility" "int specular" 0; 
        RiAttribute "visibility" "int photon" 0; 
        RiAttribute "visibility" "int midpoint" 0;  
        }
    }

Save the file and re-source it in Maya's Script Editor ie.
    source "addBakedToParticlesRI.mel";

Step 9

Delete the poly plane and add a particle emitter to the scene. Scrub the time line so that some particles are emitted. Select a few of the particles, but not the emiter, and run the addBakedToParticlesUI command from the Script Editor.

The text of a simple baked rib file is shown in listing 6. Save the rib file in the RIB_Archive folder in the current Maya project directory. If the folder does not exist, create it "manually".

Listing 6 (teapot.rib)

AttributeBegin
    Surface "plastic" "Kd" 0.8 "Ks" 0.8
    Rotate -90  1 0 0
    Scale 0.1 0.1 0.1
    Geometry "teapot"   # standard "Utah" Bezier patch teapot
AttributeEnd

Edit the "Pre-Baked Rib" path (figure 12) so that the "teapot.rib" file is referenced.

Figure 12

Render the scene again and a cluster of teapots should be seen.

Figure 13 - Using the default scaling values.

Figure 14 - X Scale and Z Scale set to 0.5.