MTOR Scripting


Table of Contents

Working with MTOR Attributes

MTOR's Maya Attributes

Appearance Keys

Blind Data

MTOR's Maya Commands

Access to TCL

Project Commands

Control Commands

Slim Commands

Miscellaneous Commands

Geometry Commands

MTOR Palette Commands

Appearance Commands

Parameter Commands

MTOR Scripting Examples

Example 1

Example 2


 

MTOR has support for two forms of scripting. The first type is based on the Tcl scripting language. For more information on Tcl based scripting of MTOR see the mtor MAN page and the MTOR Scripting Reference. The second type of scripting and one that is particular to MTOR (among Pixar's products, that is) is support for Maya's scripting language, known as MEL. If you're interested in MEL scripting, well read on!

Working with MTOR Attributes

When working with Slim and MTOR you are, in effect, editing many attributes. However, because MTOR isn't a native Maya component, not all of MTOR's attributes are available for modification by MEL scripts in the standard Maya manner. For this reason we distinguish between MTOR's Maya Attributes and MTOR's Hidden Attributes. In order to manipulate the hidden attributes MTOR supports a small set of Maya Commands. If you like to skip the techo-stuff, jump straight to the commands or even to the examples.

MTOR's Maya Attributes

When you use Slim to attach an appearance to a Maya object, you are actually causing MTOR to attach to the currently selected objects a reference, or key, to your appearance. MTOR ensures that the currently selected Maya objects have types appropriate to the appearance and sets up dynamic Maya attributes on your Maya objects. Usually, MTOR attaches the appearance key at the lowest (leaf-most) level in the DAG or DG while still preserving instancing information. This is accomplished by embodying the appearance key as a string and adding dynamic stringArray attributes at Maya Light and Primitive DAG Nodes as well as at Shading Group Nodes. At a given primitive, for example, MTOR can store up to seven different attributes (one for each type of MTOR appearance). Each attribute is represented as a MEL stringArray whose length is related to the instancing of the primitive (did you know you can attach different Maya shaders to different instances of the same primitive?). Finally, at an individual element of a stringArray, MTOR supports the notion of multiple appearances attached to a single object by treating a string as a comma separated list of appearance keys. Note that multi-appearances are supported for Lightsource Shaders and Map Generators only. This way, for example, you can attach many lights to a single geometric primitive.

So now we're almost ready to write MEL scripts which attach appearance keys to Maya objects. The last pieces of the puzzle are:

Here's the list of attributes which MTOR modifies in order to associate appearances with nodes in your scene graph:

Appearance Keys:

mtorCamCtl (shortname; mcc, type: stringArray)
mtorDispl (shortname: mds, type: stringArray)
mtorLight (shortname: mls, type: stringArray)
mtorRibbox (shortname: mrb, type: stringArray)
mtorRibgen (shortname: mrg, type: stringArray)
mtorSurf (shortname: mss, type: stringArray)
mtorVol (shortname: mvs, type: stringArray)
slimRIB (shortname: rib, type: stringArray)
slimMapGen (shortname: smg, type: stringArray)
slimEns (shortname: sen, type: stringArray)
slimSurf (shortname: sss, type: stringArray)
slimDispl (shortname: sds, type: stringArray)
slimLight (shortname: sls, type: stringArray)
slimVol (shortname: svs, type: stringArray)
slimArchiver (shortname: saa type: stringArray)
slimTCL (shortname: tcl type: stringArray)
slimDSO (shortname: sdso, type: stringArray)

MTOR & Slim Data:
mtorData (shortname: md, type: mtorData) 
rmanData (shortname: rmd, type: string)
slimData (shortname: sd, type: string)

So, at last, we can attach appearance keys to Maya objects via MEL and, interestingly enough, that's precisely what happens every time Maya reads a Maya scene file. Here's an excerpt from an ascii Maya wirefile which contains MTOR information:

//Maya ASCII 4.0ff02 (Beta 1) scene
//Name: bumply.ma
//Last modified: Mon, May 14, 2001 03:09:50 PM
requires maya "4.0ff02 (Beta 1)";
requires "mtor_maya4" "3.0";
(stuff removed)...
createNode transform -n "nurbsPlane1";
   (stuff removed)...
createNode nurbsSurface -n "nurbsPlaneShape1" -p "nurbsPlane1";
    addAttr -ci true -sn "mss" -ln "mtorSurf" -bt "UNKN" -dt "stringArray";
    addAttr -ci true -sn "mls" -ln "mtorLight" -bt "UNKN" -dt "stringArray";
    addAttr -ci true -sn "mds" -ln "mtorDispl" -bt "UNKN" -dt "stringArray";
    (stuff removed)...
    setAttr ".mss" -type "stringArray" 1 "CdpZ3G3VSg100000"  ;
    setAttr ".mls" -type "stringArray" 1 "CdpZ3G3Qfl900000,CdpZ3G3Qpl200000,CdpZ3G3VJk000000"  ;
    setAttr ".mds" -type "stringArray" 1 "CdpZ3G3VOU700000"  ;
    
(stuff removed)...

    select -ne mtorPartition;
    addAttr -ci true -sn "rmd" -ln "rmanData" -bt "UNKN" -dt "string";
    addAttr -ci true -sn "sd" -ln "slimData" -bt "UNKN" -dt "string";
    setAttr ".rmd" -type "string" (
                "  RManControls {\n"
                + "     RIBFormat ascii\n"
                + "     RIBGen immediate\n"
                + "     alfNRMMax 5\n"
                + "     alfNRMMin 1\n"
                + "     alfNRMVers {}\n"
                + "     alfPause 0\n"
                + "     alfSvc {}\n"
                + "     alfTag {}\n"
                + "     animFPS 30\n"
                + "     backPlane 1\n"
                + "     binaryDice 1\n"
                + "     blurCamera 0\n"
(stuff removed)...
    setAttr ".sd" -type "string" (
               "slim 1 TOR slim {\n"
               + "palette mmE50Clpxh300000 {\n"
               + "  guiinfo 734x463+124+453 0 {\n"
               + "    graphArea {\n"
               + "      graphState \"work area 0\" {\n"
               + "        zoom 0\n"
               + "        offset -1 -1\n"
               + "        node GhZm1umpxh300000 336.0 8.0\n"
               + "        node GhZm1ulpxh300000 454.0 10.0\n"
               + "        node 483g_xKA0i300000 225.0 10.0\n"
               + "        node GhZm143qxh300000 447.0 99.0\n"
               + "        node GhZm1a4qxh300000 330.0 97.0\n"
               + "        node 483g_BcB0i300000 548.0 111.0\n"
               + "        node 483g_doB0i300000 126.0 99.0\n"
               + "        node 483g_pIJ0i300000 24 109\n"
               + "      }\n"
               + "    }\n"
               + "  }\n"
               + "  label untitled\n"
               + "  function shadingmodel \"hbfacecl\" \"pixar,Blinn#0\" {\n"
               + "    identity GhZm1ulpxh300000\n"
               + "    description {Mimics the Maya Blinn shader.}\n"
               + "    master {$torShaders/$INSTANCENAME}\n"
(stuff removed)...

If you wish to write MEL scripts which attach appearance keys be careful to ensure that:

 

no more than a single attribute of a particular type is present on a Maya object

the attribute constains properly formatted strings

the object is either a primitive, a lightsource or a Shading Group

Note that we also provide a higher level function which ensures the appropriate conditions (see below).

MTOR's Maya Commands

As mentioned above, MTOR hides many attributes from the standard Maya Dependency Graph. MTOR provides access to these hidden attributes through a collection of Maya Commands. We've divided these attributes into several categories and provided MEL commands to both query and set their values. Through this interface it's possible perform all common operations performed by users through the Graphical User Interface.

In order to guarantee unique command names, MTOR adopts the convention that all MTOR commands are preceded with the words mtor or slimcmd. This really means that MTOR only adds a couple commands to the MEL interpretter and all following commands are really subcommands of these commands.

MTOR TCL Commands

The eval command provides access to MTOR's internal TCL interpretter. This is the repository of all preference and policy information derived from MTOR's (and all RAT appliciations) boot/initialization sequence.

 

mtor eval "cmd"

Returns the string result of the TCL command argument. Standard RAT TCL commands are documented elsewhere, but

% mtor eval "GetPrefNames *"

and

% mtor eval "GetPref thePrefName"

are the commands you need to access preferences.

MTOR Project Commands

The project commands provide access to information about MTOR's notion of the current project. The term project is loosely equivalent to Maya's workspace concept. MTOR attempts to track the Maya workspace and causes resynchronization with its workspace after any file is opened or a new one is created. The mel command: workspace is quite useful for manipulating Maya's state and, if applicable, should usually be used over commands provided here.

 

mtor project get

Returns the directory name associated with MTOR's current project.

 

mtor project set "directory" ?"workspaceName"?

Sets the directory of MTOR's current project. If the directory doesn't exist, MTOR will attempt to create it as well as the standard set of subdirectories.  Set Takes an optional workspaceName parameter.  If this is set MTOR will use this file to define the workspace settings.

 

mtor project getpaths

Returns a string representing the project searchpaths.

 

mtor project setpaths

Allows you to set the project searchpaths.

Control Commands

Control commands govern rendering and render spooling attributes. Complete access over RenderMan Globals are provided. Since there are many attributes which comprise RenderMan Globals, we haven't included the particular rg names here. This information is available in the MTOR Scripting Reference.

 

mtor control getvalue -rg "rgname" or -sync

Retrieves the value of the render global given by rgname. To synchronize Slim's settings with MTOR, use the -sync option first. This option causes MTOR to transfer Slim's RenderMan Global state to MTOR. This takes a relatively long time so you should try to minimize its use. For example, if you plan to query a number of values, you should synchronize once before querying them:

mtor control getvalue -sync
mtor control getvalue -rg "camName"
mtor control getvalue -rg "formatX"

mtor control setvalue -rg "rgname" -value value

sets the value of the render global given by rgname to value.  To set a string value to empty, use the standard Tcl representation for the empty string - {}.  Note that mel's rules for escaping special characters also apply.

 

mtor control renderspool

The renderspool command has the same effect as pressing the Render button through the GUI. Namely, it uses the current RenderMan Globals to determine rendering and ribgen parameters and returns the result to Alfred for job control.

 

mtor control genrib -frame framenum or "preflight"

The genrib subcommand can be used to control the rib generation process. Note that though this mechanism, you circumvent the standard renderspool mechanisms. On success, the genrib subcommand returns the full pathname to the resulting ribfile. It's up to you to cause this ribfile to be rendered and all associated temporary assets to be cleaned up.

 

mtor control attach apptype appid

Attaches the specified Slim appearance to the current selection. MTOR will only attach appearance keys to objects it deems appropriate and will ensure that the attribute state of all selected objects is correct. Note that only Slim appearances of particular types can be attached: ensemble, surface, displacement, light, volume, ribbox, tclbox, mapgen, dso, archiver

 

mtor control detach apptype appid

Detaches the specified Slim appearance from the current selection.

 

mtor control pickobjects appid

Objects in the scene with the specified appearance attached will be selected. If appid is the empty string all objects with no appearances attached will be selected.

 

mtor control showpicked

Returns a string array containing all appearance keys associated with currently selected objects.

 

mtor control dirty
Causes mtor to mark the current file as having been changed.  Results in the creation of the famed mtorPartition.

Slim Commands

Slim commands differ slightly from other MTOR commands. This is because they actually run within Slim rather than in MTOR.  The Slim Scripting reference describes Slim's scripting commands in detail.  When invoking them from MTOR, simply precede the Slim command with the MTOR keywords slimcmd or slimmsg.  Use slimcmd when you need a return result and slimmsg when no result is returned or required.  Again, you'll need to familiarize yourself with mel's standards for escaping special characters.

This example prints the name and type of all appearances in all palettes:

string $apparray[];
string $apps = `slimcmd slim GetAppearances`;
string $app;
$numtokens = tokenize($apps,$apparray);
for ($app in $apparray) {
    if ($app != "") {
        print (`slimcmd $app GetLabel` + ":" + `slimcmd $app GetType` + "\n");
    }
}

Miscellaneous Commands

mtor getversion component

Provides version information to your mel script. If component nisn't specified the MTOR revision string is returned.


Components
:

rat - gets RAT build internal build level.

prman - gets RenderMan version level.

mayaAPI - gets Maya API version level.

mtor Store

Issue this command before accessing the Maya attributes mtorData, rmanData, and slimData inside the node mtorPartition. This command ensures that the Mtor data is now stored in Maya.

Example:

    mtor Store	
    string $slimData = `getAttr mtorPartition.slimData`;
    

Geometry Commands

Geometry commands provide access to geometric information of your scene. This subcommand supports the mtorFuzz RIB generator and the chord length paramerization features. Please use it for other purposes as well.

mtor geom getInfo surfaceName
computes location of points and/or normals on a NURB surface.

-pts

requests point locations.

 

-normals

requests normals.

 

-samples u v jitter

describes how to sample the surface. u by v samples are taken at equal intervals in parameter space. The jitter parameter (between 0 and 1) is used to randomize the sample location within each sample cell.

 

-trim

requests that samples within trimmed regions be removed.

 

-tofile filename

requests that the result be place in the specified file. If not specified, the command returns the results. Since the result can be quite large, we recommend outputting the results to file. In any event the values are returned in sampled order as an array of floats with points followed by normals.

 

-seed seedval

a seed for the random function. Used to prevent undesirable variance due to the state of the random number generator. Typically static but can also be animated.

 

-mask vertexVarName  

the name of a vertex variable to serve as a mask for the points and normals. If you want to sample a subset of the surface, use this channel to indicate the subset. If the channel evaluates to zero at a sample point, the data is removed.

 

mtor geom getPrimVars surfaceName

evaluates RenderMan vertex variables associated with NURB surfaces on a sampling grid.


-vars var1 var2 ...

the names of the vertex variables to evaluate. These can be created with Maya Artisan.

 

-samples u v jitter

(as above)

 

-trim

(as above)

 

-tofile filename

(as above)

 

-seed seedval

(as above)

 

-mask vertexVarName
(as above)

 

mtor geom reparametrize surfaceName -chordlength
creates and associated with surfaceName rmanFs and rmanFt vertex variables whose values are the result of the chord length parameterization calculation.

mtor geom freezeCVs surfaceName -vvname vertexVariableName
causes the vertex data of surfaceName at the current frame to be stored into a point-type vertex variable named vertexVariableName. Depending on the type of geometry, this will either be comprised of 3 or 4 components. This function is used to store __Pref geometry onto your surfaces.


Example 1

This example simply switches between RenderMan Globals settings governing rendering quality.
global proc mtorSetQuality( string $quality )
{
  if ($quality == "low")
  {
    mtor control setvalue -rg dspyName -value lowquality;
    mtor control setvalue -rg dspyRez -value "320 256";
    mtor control setvalue -rg shadingRate -value 100;
    mtor control setvalue -rg pixelSamples -value 1;
    mtor control setvalue -rg pixelFilter -value Box;
    mtor control setvalue -rg filterWidth -value 2;
    mtor control setvalue -rg shadInterp -value 0;
    mtor control setvalue -rg binaryDice -value 0;
    mtor control setvalue -rg jitter -value 0;
    mtor control setvalue -rg doDOF -value 0;
    mtor control setvalue -rg motionBlur -value 0;
    mtor control setvalue -rg frontPlane -value 0;
    mtor control setvalue -rg backPlane -value 0;
    mtor control setvalue -rg computedMaps -value ignore;
  }
  else if ($quality == "medium")
  {
    mtor control setvalue -rg dspyName -value mediumquality;
    mtor control setvalue -rg dspyRez -value "512 384";
    mtor control setvalue -rg shadingRate -value 5;
    mtor control setvalue -rg pixelSamples -value 3;
    mtor control setvalue -rg pixelFilter -value CatmullRom;
    mtor control setvalue -rg filterWidth -value 3;
    mtor control setvalue -rg shadInterp -value 1;
    mtor control setvalue -rg binaryDice -value 0;
    mtor control setvalue -rg jitter -value 0;
    mtor control setvalue -rg doDOF -value 0;
    mtor control setvalue -rg motionBlur -value 0;
    mtor control setvalue -rg frontPlane -value 0;
    mtor control setvalue -rg backPlane -value 0;
    mtor control setvalue -rg computedMaps -value use;
  }
  else
  {
    mtor control setvalue -rg dspyName -value highquality;
    mtor control setvalue -rg dspyRez -value "1280 1024";
    mtor control setvalue -rg shadingRate -value 1;
    mtor control setvalue -rg pixelSamples -value 4;
    mtor control setvalue -rg pixelFilter -value CatmullRom;
    mtor control setvalue -rg filterWidth -value 3;
    mtor control setvalue -rg shadInterp -value 1;
    mtor control setvalue -rg binaryDice -value 1;
    mtor control setvalue -rg jitter -value 1;
    mtor control setvalue -rg doDOF -value 1;
    mtor control setvalue -rg motionBlur -value 1;
    mtor control setvalue -rg frontPlane -value 1;
    mtor control setvalue -rg backPlane -value 1;
    mtor control setvalue -rg computedMaps -value use;
  }
}

Example 2 

This example walks through the list of appearances looking for all appearances based on a particular shader $master. Next, it sets the value of the parameter given by $parmname to the value: $newval (if the parameter is of type: rmFloat). This procedure might be invoked like: mtorSetValue plastic Kd .3
global proc mtorSetValue( string $master, string $parmname, float $newval )
{
  int $i, $nAppearances = `mtor palette length`;
  for($i=0; $i < $nAppearances; $i++)
  {
    $appkey = `mtor palette findappearance -index $i`;
    if ( $master == `mtor appearance master -key $appkey` )
    {
      // we've found an appearance based on $master, now lets
      // loop through all the parameters looking for a 
      // parameter name match.
      int $j, $nParameters=`mtor appearance paramcount -key $appkey`;
      string $pname, $ptype;
      for($j=0;$j<$nParameters;$j++)
      {
        $pname = `mtor parameter slname -key $appkey -index $j`;
        $ptype = `mtor parameter type -key $appkey -index $j`;
        if($pname == $parmname && $ptype == "rmFloat")
        {
          string $oldval = `mtor parameter getvalue -key $appkey -index $j`;
          print( "Changing app#" + $i + " param#" + $j + " from " + $oldval +  " to " + $newval + "\n" );
          mtor parameter setvalue -key $appkey -index $j -value $newval;
        }
      } // end of parameter loop
    }
  } // end of appearance loop
}

 

 

 

 

 

Pixar Animation Studios
(510) 752-3000 (voice)   (510) 752-3151 (fax)
Copyright © 1996- Pixar. All rights reserved.
RenderMan® is a registered trademark of Pixar.