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

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

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

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();