Mtor
Scripting a Slim Palette


return to main index


Introduction

Pixar's RenderMan Artist Toolkit (RAT) enables most of the functionality "normally" accessed via their GUI's ie. mouse and keyboard input, to be controlled directly via MEL scripts. The documentation on mtor/MEL scripting can be found at,

    Pixar/docs-X.X/programmingRAT/mtor_slim/index.html

The documentation on slim/MEL scripting can be found at,

    Pixar/docs-X.X/programmingRAT/mtor_slim/index_slim.html

This tutorial developes a MEL script that

  1. creates a slim palette
  2. adds a standard appearance, aka, a shader
  3. sets some parameter values of the appearance
  4. attaches the appearance to a surface
  5. defines some renderman globals and renders an animation

A new script Making & Writing a Ribbox with Mel was added to this tutorial May 2007.


Accessing Slim Commands

Invoking a slim command from MEL takes the general form of,

slimcmd slim COMMAND -flag1  -flag2...
// for example
string $palette = `slimcmd slim CreatePalette -edit -new`;
 
    or
 
slimcmd reference COMMAND -flag  data;
// for example
string $path = "$RMANTREE/lib/shaders/plastic.slo";
string $plastic = `slimcmd $palette CreateInstance -file $path`;
slimcmd $plastic GetProperties -name "Cs";
 
    or
 
slimcmd reference COMMAND info;
// for example
slimcmd $palette SetLabel "my palette";

By reference I mean a string that indentifies a slim object - Pixar's documentation calls them "handles".


Accessing Mtor Commands

Invoking an mtor command from MEL takes the general form of,

mtor control COMMAND parameter_name   parameter_value;
// for example
mtor control attach surface `slimcmd $plastic GetID`;

or

mtor control COMMAND -rg parameter_name  -value  parameter_value;
// for example
mtor control setvalue -rg dspyRez -value "320 240";

The -rg flag means "renderman globals".


Creating a Palette

Because the MEL script we are writing will most probably be run several times we need to check for the existance of a previously created palette.


code snippet 1


global proc string makePalette(string  $paletteName)
{
// Activate the next command to remove ALL palettes
// slimcmd slim Clear;
  
string $palette = `slimcmd slim FindPalette $paletteName`;
if($palette == "")
    {
    // The named palette does not exist
    $palette = `slimcmd slim CreatePalette -edit -new`;
    slimcmd $palette SetLabel $paletteName;
    }
else
    {
    // Clear existing appearances from the named palette
    string $all = `slimcmd $palette GetAppearances`;
    slimcmd $palette DeleteEntries $all -remove;
    }
return $palette;
}

Adding a Shader

The macro $RMANTREE will expand to the full path of the Pixar directory.


code snippet 2


global proc string addShader(string $pal, string $shadername)
{
string $path = "$RMANTREE/lib/shaders/" + $shadername + ".slo";
string $shdr = `slimcmd $pal CreateInstance -file $path`;
slimcmd $palette UpdateEditor;
return $shdr;
}

Setting Shader Values

Notice the use of quoted curly braces to enclose multiple values. Internally
slim uses the TCL scripting language - lists are enclosed in parenthesises.


code snippet 3


lobal proc setColor(string $pal, string $shader, 
                     string $paramname, vector $v)
{
string $item = `slimcmd $shader GetProperties -name $paramname`;
string $vStr = "{" + $v.x + " " + $v.y + " " + $v.z + "}"; 
slimcmd $item SetValue $vStr;
slimcmd $shader PreviewRender;
slimcmd $pal UpdateEditor;
}
  
global proc setFloat(string $pal, string $shader, 
                     string $paramname, float $v)
{
string $item = `slimcmd $shader GetProperties -name $paramname`;
slimcmd $item SetValue ("" + $v);
slimcmd $shader PreviewRender;
slimcmd $pal UpdateEditor;
}

Attaching a Shader

Notice an instance of the shader is referenced by its ID number.


code snippet 4


gglobal proc attach(string $shader)
{
mtor control attach surface `slimcmd $shader GetID`;
}

Setup Mtor & Render


code snippet 5


global proc setRmanOutput(int $w, int $h, int $doSeq, 
                          int $seqBegin, int $seqEnd)
{
mtor control setvalue -rg dspyRez -value ($w + " " + $h);
mtor control setvalue -rg doAnim -value $doSeq;
if($doSeq == 0)
    {
    mtor control setvalue -rg renderer -value "PRMan";
    mtor control setvalue -rg dspyServer -value "it";
    }
else
    {
    mtor control setvalue -rg renderer   -value "None";
    mtor control setvalue -rg dspyServer -value "tiff";
    }
mtor control setvalue -rg computeStart  -value $seqBegin;
mtor control setvalue -rg computeStop   -value $seqEnd;
mtor control setvalue -rg sequenceStart -value $seqBegin;
mtor control setvalue -rg sequenceStop  -value $seqEnd;
  
// You should manually select the cleanup options.
// mtor control setvalue -rg jobCleanup
// seems to have a bug!!
mtor RenderSpool;
}


Making & Writing a Ribbox with Mel

//-----------------------------------------
proc string SlmUtils_createPalette(string $name)
{
// Does the palette already exist?
string $handle = `slimcmd slim FindPalette $name`;
if($handle != "")
    return $handle;
// Cannot be found, therefore, go ahead and create it
$handle = `slimcmd slim CreatePalette -edit -new`;
slimcmd $handle SetLabel $name;
return $handle;
}
//-----------------------------------------
proc PalUtils_clear(string $palette)
{
string $all = `slimcmd $palette GetAppearances`;
slimcmd $palette DeleteEntries $all -remove;
}
//-----------------------------------------
global proc string PalUtils_addTemplate(string $pltHandle, string $templatename)
{
return `slimcmd $pltHandle CreateInstance -template $templatename`;
}
//-----------------------------------------
proc string[] AppUtils_getParams(string $appHandle)
{
string $all = `slimcmd $appHandle GetProperties`;
string $out[];
tokenize($all, $out);
return $out;
}
//-----------------------------------------
proc string[] AppUtils_getParamNames(string $appHandle)
{
string $handles[] = AppUtils_getParams($appHandle);
string $names[];
  
for($n = 0; $n < size($handles); $n++)
    $names[$n] = `slimcmd $handles[$n] GetLabel`;
return $names;
}
//-----------------------------------------
  
proc string AppUtils_getParamNamed(string $appHandle, string $name)
{
string $handles[] = AppUtils_getParams($appHandle);
string $names[];
  
for($n = 0; $n < size($handles); $n++)
    {
    $names[$n] = `slimcmd $handles[$n] GetLabel`;
    if($names[$n] == $name)
        return $handles[$n];
    }
return "";
}
//-----------------------------------------
  
proc makeRIBBox()
{
string $palette = SlmUtils_createPalette("lod_palette");
PalUtils_clear($palette);
string $ribbox = PalUtils_addTemplate($palette, "pixar,RIBBox");
string $param = AppUtils_getParamNamed($ribbox, "Box of RIB");
  
string $rib = "{AttributeBegin\n";
$rib += "   Detail \\[-1 1 -1 1 -1 1\\]\n";
$rib += "   Color 1 0 0\n";
$rib += "   Surface \"plastic\" \"Kd\" 0.8\n";
$rib += "   DetailRange \\[ 1 1  1000 2000 \\]\n";
$rib += "       ReadArchive \"../lod/gumball_lowres.rib\"\n\n";
  
$rib += "   Color 0 1 0\n";
$rib += "   DetailRange \\[ 1000 2000 8000 12550 \\]\n";
$rib += "       ReadArchive \"../lod/gumball_medres.rib\"\n\n";
  
$rib += "   Color 0 0 1\n";
$rib += "   DetailRange \\[ 8000 12550 400000 400000 \\]\n";
$rib += "       ReadArchive \"../lod/gumball_hires.rib\"\n";
$rib += "AttributeEnd\n";
$rib += "Opacity 0 0 0}";
slimcmd $param SetValue $rib;
mtor control attach ribbox `slimcmd $ribbox GetID`;
}
  
makeRIBBox();




© 2002- Malcolm Kesson. All rights reserved.