Cutter
Rman & RiMel Scripting


return to main index



Introduction

A .rman script 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.


Using the Pixar procedures, rmanGetAttrName() and rmanAddAttr(), a Mel script can conveniently create the widgets described by a .rman script and automatically add them to an "Extra RenderMan Attributes" panel. At render-time a second Mel script, again using some Pixar procedures, and easily querry the widgets and use their values with one or more RiMel procedures.

Using Cutter an interface defined by a .rman script can be quickly developed and visualized in a browser. In addition, Cutter can generate code for the two Mel scripts that accompany a .rman file thus relieving a technical artist of the burden of writing a lot of tedious Mel code.


Naming Conventions

Cutter's authoring environment uses the following scripting and naming conventions. It is assumed a custom UI is implemented by one .rman script and 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 (at render-time generates extra rib statements)

Note the name of Mel script that create and querry the interface have the same name as the .rman script but with UI and RI suffixes.



Example - Hello World

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,
    1 - a .rman script is created and previsualized in a browser,
    2 - the UI and RI .mel scripts are generated,
    3 - the UI and RI .mel scripts are manually edited.

For the purposes of this tutorial the trio of files generated and edited in steps 1 to 3 produce an interface that enables a sphere to replace an object in the maya scene - a small step along the road of .rman and RiMel scripting.


Step 1 - Creating the .rman UI description script

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



Figure 1

# An empty .rman file
rman "-version 1" {
  
  
}

Add a Float Slider

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



Figure 2

# helloWorld.rman 
rman "-version 1" {
Declare param {float hw_rad} {
    label "Radius"
    subtype slider
    range {0.001 10}
    description "The size of the replacement sphere."
    }
}

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 3.



Figure 3


Step 2.1 - Creating the UI Mel script

Right mouse click anywhere in the .rman document and from the popup menu and select UI PreShape Script - figure 4.



Figure 4


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


Listing 1 (helloWorldUI.mel)


global proc helloWorldUI() 
{
string $selected[] = `ls -sl`;
int $i;
  
for($i = 0; $i < size($selected); $i++ ) {
    string $shp[] = `listRelatives -shapes $selected[$i]`;
  
    // To add the UI implemented by this proc to the "Geometric
    // Settings" panel use the following mel commands,
    //        select rmanSettings;
    //        helloWorldUI;
    // where "rmanSettings" might be rmanSettings1, rmanSettings2 etc.
    if(`nodeType $selected[$i]` == "RenderMan")
        $shp[0] = $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 "helloWorldRI";
        
    $attr = `rmanGetAttrName "hw_rad"`;
    rmanAddAttr $shapeName $attr "1.0"; // <<<< Add default
    }
}


Step 2.2 - Creating the RI Mel script

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



Figure 5


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


Step 3 - Editing the Mel scripts

The helloWorldRI.mel script will require minor editing. Change line 33 from,

    RiSphere(1, -1, 1, 360);
to
    RiSphere($hw_rad, -$hw_rad, $hw_rad, 360);

This will ensure the slider in the interface controls the size of the sphere that is generated at render-time.


Using the Scripts

The scripts should be saved in the following location.

    maya/projects/RfM_mel/
                         |_ helloWorld.rman
                         |_ helloWorldUI.mel
                         |_ helloWorldRI.mel

Step 1
    Create an object, say a polyPlane. Deselect it and reselect it.
Step 2
    In the script editor window run this command,
        helloWorldUI;
The interface that was pre-visualized in figure 3 will appear under the Shape tab of the Attribute editor. Render the scene and the polyPlane will be replaced by a sphere.






© 2002- Malcolm Kesson. All rights reserved.