RMS - Ri Scripting Naming Conventions

RMS
Directories & Scripts

Introduction

Naming conventions are either a subject of personal preference or are imposed on an artist by the established practices of their studio. Depending on your circumstances you may prefer to ignore this section.

This tutorial looks at the issue of setting up a directory structure that might help an artist manage the many scripts (assets) they will write, or generate, for their RenderMan Studio (RMS) projects. The majority of the assets will be mel scripts, but some will be RMS specific rman scripts. Another set of scripts, known as slim templates, will also require management. The tutorial, "RMS: Cutter & Slim Templates", explains what slim files are and how the Cutter text editor can automatically generate them.

Directory Structure

maya/
    |_ scripts  # regular mel scripts ie. not related to RMS
    |
    |_ projects/
               |_ RMS_ini/
               |         |_ RenderMan_for_Maya.ini  # loads the users .rman files
               |         |_ slim.ini                # loads the users .slim files
               |
               |_ RMS_mel/
               |         |_ addSphereRI.mel         # sample file - explained later
               |         |_ addSphereUI.mel         # ditto
               |         |_ addSphereUI.rman        # ditto
               |
               |_ RMS_slim/ # the users slim template files would be stored here

The directory structure shown above confines an artists RMS scripts to three sub-directories. Setting up Maya and RMS so that both applications reference those scripts consists of three steps.

set two environment variables,
save two initialization files in the RMS_ini directory,
save three sample scripts in the RMS_mel directory,
save a sample slim file in the RMS_slim directory,
launch Maya and see if it can use the scripts.

Setting the Environment Variables

Windows & Linux

Add these two lines of text to your maya/8.5/Maya.env or maya/2008/Maya.env file.

    RMS_SCRIPT_PATHS=$MAYA_APP_DIR/projects/RMS_ini
    MAYA_SCRIPT_PATH=$MAYA_APP_DIR/projects/RMS_mel

OSX

In your Library/Preferences/AutoDesk/maya/8.5/Maya.env file add these two lines of text.

    RMS_SCRIPT_PATHS=/Users/$USER/Documents/maya/projects/RMS_ini
    MAYA_SCRIPT_PATH=/Users/$USER/Documents/maya/projects/RMS_mel

Initialization Scripts

The initialization scripts shown next should be saved in the RMS_ini directory as RenderMan_for_Maya.ini and slim.ini respectively.

RenderMan_for_Maya.ini (Windows & Linux)

# Assume we're on the "M" drive of Windows
set userdir M:/maya/projects/RMS_mel
  
set os [array get tcl_platform platform]
if {[llength $os] == 2} {
    set os [lindex $os 1]
    }
# Wrong guess, we're on linux...
if {$os == "unix"} {
    set userdir /home/$USER/maya/projects/RMS_mel
    }  
if { [file exists $userdir] } {
    set scripts [glob -nocomplain -directory $userdir *rman]
    foreach item $scripts {       
        set scriptName [file tail $item]
        LoadExtension rman [file join $userdir $scriptName]
        }
    }

RenderMan_for_Maya.ini (OSX)

set userdir /Users/$USER/Documents/maya/projects/RMS_mel
   
if { [file exists $userdir] } {
    set scripts [glob -nocomplain -directory $userdir *rman]
    foreach item $scripts {       
        set scriptName [file tail $item]
        LoadExtension rman [file join $userdir $scriptName]
        }
    }

slim.ini (Windows & Linux)

# Slim template files generated by Cutter will have a first line
# of (commented) text that tells the ::Slim::RegisterLazyTemplates
# procedure in which menu the template should be placed. A typical
# first line might be,
#          # menuInfo fundza,MyColor#0 color MyColor utility
# This line of text has the effect of telling Slim that a template
# named "MyColor" implements a color node. As a menu item it 
# should be labelled "MyColor" and should appear in the "Utility"
# sub-menu of the "Colors" menu that is displayed by Slim.
# Author: Malcolm Kesson October 21 2007
 
# Assume we're on the "M" drive of Windows
set userdir M:/maya/projects/RMS_slim
  
set os [array get tcl_platform platform]
  
if {[llength $os] == 2} {
    set os [lindex $os 1]
    }
# Wrong guess, we're on linux...
if {$os == "unix"} {
    set userdir /home/$USER/SFDM-HOME/$USER/maya/projects/RMS_slim
    }  
  
if { [file exists $userdir] } {
    set slimfiles [glob -nocomplain -directory $userdir *slim]
    # Might be useful to log our templates as they are registered
    set out [open "/home/$USER/slim_log.txt" w]
    puts $out "registering..."
  
    foreach item $slimfiles {       
        set slimName [file tail $item]
        puts $out "$slimName"
        set fileID [open $userdir/$slimName r]
  
        # Read the first line of text. It may contain Cutter's 
        # "menuInfo" tag. The tag provides a hint about how the 
        # slim template should be registered.
        gets $fileID info
        close $fileID
        
        # Remove the comment character and any leading white
        # space 
        set info [string trimleft $info "\# "]
    
        # Does the line begin with the "menuInfo" tag? The tag is
        # automatically added by Cutter when it is used to generate
        # a slim template file from a users shader source code file.
        # However, if a user has authored their own template files
        # they will probably NOT have added the "menuInfo" tag.
        if { [string equal -nocase -length 8 $info "menuInfo"] == 1} {
            set info [string trimleft $info]
            # Remove the tag
            set info [string range $info 8 end]
            set info [string trimleft $info]
            
            set rltStr     "::Slim::RegisterLazyTemplates \{\n"
            append rltStr  "    $userdir/$slimName \{\n"
            append rltStr  "        \{ $info \}\n"
            append rltStr  "    \}\n"
            append rltStr  "\}"
            eval $rltStr
        } else {
            # Cannot use lazy registration - load the template immediately.
            LoadExtension slim $item slim
            }
        }
    close $out
    }

slim.ini (OSX)

set userdir /Users/$USER/Documents/maya/projects/RMS_slim
    
if { [file exists $userdir] } {
    set slimfiles [glob -nocomplain -directory $userdir *slim]
 
    # Might be useful to log our templates as they are registered
    set out [open "/home/$USER/Documents/slim_log.txt" w]
    puts $out "registering..."
    foreach item $slimfiles {       
        set slimName [file tail $item]
        puts $out "$slimName"
        set fileID [open $userdir/$slimName r]
  
        # Read the first line of text. It may contain Cutter's 
        # "menuInfo" tag. The tag provides a hint about how the 
        # slim template should be registered.
        gets $fileID info
        close $fileID
        
        # Remove the comment character and any leading white
        # space 
        set info [string trimleft $info "\# "]
    
        # Does the line begin with the "menuInfo" tag? The tag is
        # automatically added by Cutter when it is used to generate
        # a slim template file from a users shader source code file.
        # However, if a user has authored their own template files
        # they will probably NOT have added the "menuInfo" tag.
        if { [string equal -nocase -length 8 $info "menuInfo"] == 1} {
            set info [string trimleft $info]
            # Remove the tag
            set info [string range $info 8 end]
            set info [string trimleft $info]
            
            set rltStr     "::Slim::RegisterLazyTemplates \{\n"
            append rltStr  "    $userdir/$slimName \{\n"
            append rltStr  "        \{ $info \}\n"
            append rltStr  "    \}\n"
            append rltStr  "\}"
            eval $rltStr
        } else {
            # Cannot use lazy registration - load the template immediately.
            LoadExtension slim $item slim
            }
        }
    close $out
    }

Mel & Rman Scripts

Artists using RenderMan Studio can dramatically alter the way a Maya scene is rendered by assigning mel scripts to the entire scene or to individual elements within the scene. Such mel scripts do not effect what Maya displays, they only alter the rib file (or rib stream) that Pixar's prman renderer receives. Refer to the tutorial "RMS: Ri Scripting" for an overview of this topic. This tutorial groups mel scripts, according to their functionality, into one of two types.

UI Procedures

Procedures of this type setup what an artist will see in the "Extra RenderMan Attributes" panel of the Attribute Editor. They are generally activated by a button previously added to the Maya custom shelf. Alternatively, they are evoked directly from the script window. Either way, such procedures automate the task of assigning, say, a preTransformScript to an object. They may also setup some UI (user interface) widgets that provide an artist with additional controls such as text fields, check-boxes and drop-down menus.

RI Procedures

Procedures of this type setup what the renderer will "see" in the rib file or rib stream that it receives from the Rfm Pro plugin. These procedures implement the logic that underpins the visual effect an artist wishes to create. They make use of so-called Ri procedures that do the actual work of adding rib statements to the output rib file or rib stream. Mel scripts of this type may, or may not have a corresponding front-end or UI script.

It is appropriate the names chosen for an artists RMS mel scripts should indicate their purpose. For example, if a listing of the maya/scripts directory shows these files,

    addSquashySphere.mel
    addSquashySphereAttrs.mel

it is difficult to know what procedures or functionality they implement. On the other hand, if a naming convention is followed that uses the suffixes UI and RI to classify mel scripts according to their functionality, then the following listing at least identifies the "role" that each script plays.

    addSquashySphereUI.mel     // front-end interface script
    addSquashySphereRI.mel     // back-end script

In addition, if a naming convention also stipulates that the main procedure within a mel script has identically the same name as the file itself, then the mel script that implements, say, this procedure,

    global proc addSquashySphereRI()

should be easy to find within the users Maya directory structure.

Rman Interface Scripts

As noted above, a mel script of the RI type may have a front-end UI script. A UI script will, at the very least, add a string attribute to an object with a default value that equals the name of a procedure implemented by a RI script (refer to comments 1 and 2 in the first mel script shown below). Additionally, a UI script may also setup some UI widgets within the "Extra RenderMan Attributes" panel of the Attribute Editor - figure 1. As a convenience, the characteristics of a widget or widgets can be concisely described by a .rman script. Such scripts are written in the TCL (Tool Command Language) language. They look very similiar to Pixar's slim files.

Figure 1

By way of example, the following three scripts implement a custom RenderMan attribute that "assigns" a quadric sphere to a selected object or objects. If the primary visibility of the object to which the addSphereUI() proc was added is switched "off" only the sphere will be visible in the rendered image. As mentioned in the introduction to this tutorial the main purpose of these scripts is to enable the reader to check if their environment variables and directories have been set up correctly.

The mel and rman script should be saved in your RMS_mel directory as addSphereUI.mel, addSphereRI.mel and addSphereRI.rman respectively.

addSphereUI.mel

global proc addSphereUI() 
{
string $sel[] = `ls -sl`;
string $attr;
for($i=0;$i < size($sel);$i++)
    {
    // 1. Get the full name of a RMS attribute called "postTransformScript"
    $attr = `rmanGetAttrName "postTransformScript"`; 

    // 2. Add it to the selection and set its value
    rmanAddAttr $sel[$i] $attr "addSphereRI"; 

    // 3. Get the full name of an attribute defined in a .rman file
    $attr = `rmanGetAttrName "asRad"`;

    // 4. Add it to the selection and set its value
    rmanAddAttr $sel[$i] $attr "1.5";
    }
}

addSphereRI.rman

rman "-version 1" {
Declare param {float asRad} {
    label "Sphere Radius"
    description ""
    range {0.01 1.0}
    }
}

addSphereRI.mel

global proc addSphereRI()
{
// 1. Get the name of the object to which the 
string    $object = `rman ctxGetObject`;
  
// 1. Get the full name of an attribute defined in a .rman file
string     $attr = `rmanGetAttrName "asRad"`;

// 1. Get the full name of an attribute defined in a .rman file
float      $rad = `getAttr ($object + "." + $attr)`;
RiSphere($rad, -$rad, $rad, 360);
}

Testing

Follow these steps to check if the initialization files and the sample scripts are working properly.

Launch Maya.
In the script window enter this command,
getenv "MAYA_SCRIPT_PATH";
Look carefully along the line of paths.
If you cannot see a path to the RMS_mel directory you have made
a mistake in the Maya.env file.
In the script window enter this command,
source "addSphereUI.mel";
If an error is reported check the Maya.env file. Also, check if
addSphereUI.mel is named correctly.
Create a poly cube and turn off its primary visibility.
Select the cube and enter this command,
addSphereUI;
Open the Attributes Editor and select the transform node.
If you do not see the Extra RenderMan Attributes (figure 1) you have made a mistake in the addSphereUI.mel script.
Render the scene with RenderMan. If you do not see a sphere you have made a mistake in the addSphereRI.mel script.

RMS Directories & Scripts