RMS - Setup for Mel, Rman, Slim & the Image Tool

RMS
Setup for Mel, Rman, Slim & the Image Tool

Introduction

This tutorial looks at the issue of setting up a directory structure that will help an artist manage the .mel, .py, .rman, .slim and .tcl scripts they may use with Pixar's RenderMan Studio. Naming conventions are either a subject of personal preference or are imposed on an artist by the established practices of their studio. This tutorial pays particular attention to the way that directories, scripts and procedures are named. Of course, the reader is free to impose their own naming conventions on the material presented in this tutorial.

Setting the Environment Variables

Windows & Linux

Add these two lines of text to the maya/2009/Maya.env file.

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

OSX

Add these two lines of text to the users Library/Preferences/AutoDesk/maya/2009/Maya.env file.

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

Initialization Scripts

The initialization (.ini) scripts shown next should be saved in the RMS_ini directory. Two versions of each script are given. Ensure you copy the ones intended for the operating system of your computer. The .ini files are intended to automate the loading of the users scripts.

it.ini (Windows & Linux)

# This script is suitable for dual-boot Windows/Linux computers
# The following path WILL require editing
set userdir H:/maya/projects/RMS_it
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"} {
    # The following path WILL require editing
    set userdir /PATH_TO/maya/projects/RMS_it
    } 
if { [file exists $userdir] } {
     set tclfiles [glob -nocomplain -directory $userdir *tcl]
    
    # Useful to log our "it" tcl scripts as they are registered
    set logfile [open "$userdir/it_log.txt" w]
    set day  [clock format [clock seconds] -format %D]
    set time [clock format [clock seconds] -format %R]
    puts $logfile "Registered on $day at $time"
    
    foreach item $tclfiles {
        set tclName [file tail $item]
        # Write the name of the script to our log file
        puts $logfile "$tclName"
        LoadExtension tcl $item
        }
    close $logfile
    }

it.ini (Mac OSX)

set userdir /Users/$USER/Documents/maya/projects/RMS_it
if { [file exists $userdir] } {
     set tclfiles [glob -nocomplain -directory $userdir *tcl]
    
    # Useful to log our "it" tcl scripts as they are registered
    set logfile [open "$userdir/it_log.txt" w]
    set day  [clock format [clock seconds] -format %D]
    set time [clock format [clock seconds] -format %R]
    puts $logfile "Registered on $day at $time"
    
    foreach item $tclfiles {
        set tclName [file tail $item]
        # Write the name of the script to our log file
        puts $logfile "$tclName"
        LoadExtension tcl $item
        }
    close $logfile
    }

RenderMan_for_Maya.ini (Windows & Linux)

# This script is suitable for dual-boot Windows/Linux computers
# The following path WILL require editing
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"} {
    # The following path may require editing
    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 (Mac 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 Jan 6 2010
# 
# This script is suitable for dual-boot Windows/Linux computers
# The following path WILL require editing
set userdir H:/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"} {
    # The following path WILL require editing
    set userdir /PATH_TO/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 logfile [open "$userdir/slim_log.txt" w]
    set day  [clock format [clock seconds] -format %D]
    set time [clock format [clock seconds] -format %R]
    puts $logfile "Registered on $day at $time"
  
    foreach item $slimfiles {       
        set slimName [file tail $item]
        puts $logfile "$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 $logfile
    }

slim.ini (Mac 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 "$userdir/slim_log.txt" w]
    set day  [clock format [clock seconds] -format %D]
    set time [clock format [clock seconds] -format %R]
    puts $out "Registered on $day at $time"
  
    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
    }

Image Tool Scripts

The Image Tool ("it") is an application commonly used to display images rendered using RenderMan for Maya or rendered directly from a rib file that has been prepared with Cutter. Images rendered to "it" are displayed in a window that is superficially similar to Maya's fcheck application. However, unlike fcheck the Image Tool has a powerful set of image processing functions built into its scripting environment.

To check if the it.ini initialization file and the readers RMS_it directory have been set up correctly it will be necessary to run a custom "it" script. Several sample "it" scripts can be found at RMS:Image Tool Scripts I. The reader should make a copy of the script named saveJPG.tcl and save it in their RMS_it directory. The next section explains how this script should be used.

Testing the saveJPG.tcl Script

Follow these steps to check if the it.ini initialization script and the sample Image Tool saveJPG.tcl script are working correctly.

Launch Maya and load the RfM plugin.
Ensure "it" is used as the display driver instead of Maya's "Render View" - figure 1.

Figure 1

Render a scene.
Right mouse click in the catalog window and open the "it", "console" and "message" windows - figure 2.

Figure 2

In the console window (figure 3) enter the following command
saveJPG "test.jpg"

Figure 3

The image will be saved in the present working directly, most often the Maya project directory. To change to another directory use the following command, for example,
% cd "D:/myimages"
To check your present working directory use this command,
% pwd
If no errors are reported in the message window the script was successfuly sourced. The reader can now be confident that additional .tcl scripts saved in the RMS_it directory will be similarly available for execution from the console - assuming they are written correctly!

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 user interface script
    addSquashySphereRI.mel     // back-end "RenderMan Interface" 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 TCL (Tool Command Language). Their structure is 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 is 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 following mel and rman scripts should be saved in the readers RMS_mel directory as addSphereUI.mel, addSphereRI.rman and addSphereRI.mel 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 the .mel and .rman Scripts

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

Launch Maya and load the Rfm plugin.
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 make 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.