MTOR Scripting Reference

MTOR supports batch scripting mechanisms. This is delivered as a standalone application which supports the Tcl scripting language. It may also be delivered as part of the native scripting system of your modeling and animation system (as it is with MTOR). Most commonly, you'll want to script the generation of RIB files for just-in-time rendering (aka: Deferred RIB Generation). Before gen-ing the RIB, you'll need to choose Rendering options and attributes. For this reason, we've provided an interface to the complete set of RenderMan Globals. The scripting interface to these commands are presented here. They can also be listed with the command "mtor control getvalue -rg". Please refer to the individual scriptable app (eg: mtor) docs for other details.

Use this handy reference to determine the names and datatypes of scriptable parameters. Datatype notation:

%b - boolean with values 0 or 1
%f - floating point value
%d - integer value
%s - string value.

Note that while these datatypes are required to parse the return values, that all values are passed through the scripting language as a single string.

Command Line Options for Batch MTOR:

-scene scenefile (required)
-version (causes exit)
-edit (optional)
-mode (alfred or std) (optional)
-cmd %s (a valid mtor command) (optional)
-wsroot (workspace root directory (optional))
-wsfile (workspace attributes file (optional))

Script and Command Files

If you're doing anything more trivial than a single command, it's probably best to create a script with the commands it in, one per line and send it to MTOR standalone on standard input (being sure to call the appropriate MTOR executable):

mtor_maya3 -scene foo.ma  mybatchfile

MTOR is capable of executing full-blown TCL scripts. So the MTOR commands can be added to a TCL script, which allows programming logic to be built in. More than a series of commands, you can do standard looping, condition testing, etc. The TCL command file can then be called with the appropriate executable:

mtor_ maya4 -scene foo.ma -cmd source commandFile.tcl

Render/RIB Control

projDir %s: This allows you to control where to find and output associated texture maps and computed images. By default, *tor goes through a series of tests to automatically determine the correct project location. First, *tor checks your environment for the variable: RAT_PROJECT. Setting RAT_PROJECT is equivalent to using the internal projDir command; providing a full path to a valid location will establish that location as the head of a standard RAT project. If RAT_PROJECT isn't present in your environment, *tor will examine the directory name where your wirefile resides. If the directory is either wire, scene or rmantmp, *tor will assume that the project directory is the directory containing the current directory. If none of these conditions are true, *tor will use the current working directory as the project directory. The internal projDir command can be invoked directly within the *tor interpretter and will override the default mechanism above.
genRib %d: (Also: genRib %s/%d (framenum or "preflight") ?-cleanuplist %s? ?-timervar %s?); This causes the RIB file(s) for the given frame to be generated into the location associated with the current project. To retrieve a list of files requiring cleanup after rendering use the -cleanuplist option following by the name of a Tcl variable. On completion, this variable will contain a Tcl list of transitory rendering files. It's up to the programmer to perform the removal, presumably after rendering is complete. To retrieve timing information, specify the -timevar option followed by the name of a Tcl variable. When the RIB generation is complete this variable will contain the elapsed time for the operation measured in seconds. Note that the genRib command ignores the jobChunkSize setting and forces all subframes for a given frame to appear in a single RIB file. If you need more granularity, you should use genWorklist.
genWorklist %d nohost %d (%d) (startframe, number of frames (frame step)): Like the genRib command, this causes RIB files for the given frames to be generated into the location associated with the current project. In addition, it will generated an Alfred script describing the rendering, texture conversion, and cleanup tasks associated with those RIB files. Unlike the genRib command, genWorklist does not ignore the jobChunkSize setting.
render %d (%d ) startframe (numberofframes} ?-timelist %s: This causes *TOR to render the specified frames. *TOR will invoke the renderer as specified in the renderGlobals below. If you require timing information, specify the -timelist followed by the name of a Tcl variable. On completing this variable will contain a Tcl list of 3 values per frame. The values represent execution time, measured in seconds, for each of: ribgen, render and imager/cleanup.
renderSpool: The renderSpool command (-cmd renderSpool) 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.
runup %d (desiredframe): This command is useful in the case where you're distributing RIB generation around a network of machines and in which there are dynamics in your scene. Runup causes all frames up to the requested frame to be "touched" and thereby results in proper simulation state. Usually *TOR invokes this command automatically.
syncSlimWorkspace: This command is used in situations where the Slim workspace settings need to by synced to the *TOR workspace. This situation can arise when the *TOR workspace command is used to change values that are needed by Slim during rib generation. For example, changing torShaders to change the destination of compiled shaders requires this command to be run before rib generation (genRib, genWorklist, render, etc).

Render Globals

Display

dspyName %s: The base name of all image and texture files which are created.
dspyUnique %d: When rendering to "it", this determines whether to reuse an existing framebuffer window. 0 causes the existing window to always be reused. 1 results in the creation of a new window with each rendering unless you have a crop region specified. 2 results in the creation of a new framebuffer with each rendering irregardless of crop window settings.
camName %s: The name of the camera use when rendering.
contextString %s: The string which defines the abstract context used during rendering.
dspyRez %d %d (also dspyFormatX %d and dspyFormatY %d): The resolution of the file images in pixels.
pixelRatio %f: The pixel aspect ratio of your display device.
dspyServer %s: The name of the RenderMan display driver to use for rendering.
dspyServerMode %s: The display mode to use for rendering.
dspyQuantizeMode %s: Controls the display mode for the quantization parameters.
dspyQuantizeOne %f: Sets maximum range of input for quantization.
dspyQuantizeMin %f: Sets minimum range of output for quantization.
dspyQuantizeMax %f: Sets maximum range of output for quantization.
dspyQuantizeDither %f: Sets the amplitude of dithering to add during quantization.
dspyGain %f: The display gain.
dspyGamma %f: The display gamma.
dspyBucketX %d: The width of a display bucket.
dspyBucketY %d: The height of a display bucket.
dspyGrid %d: The maximum size of micropolygon grids.

Secondary Display

dspyName_x %s: The secondary display name for slot x
dspyType_x %s: The secondary display type for slot x, usually "tiff".
dspyMode_x %s: The secondary display mode for slot x. One of: "N", "Ng, "P", "u", "v", "du", "dv", "s", "t", "dPdu", "dPdv", "dPdtime", "Cs", "Os", "Ci", "Oi", or a custom value.
dspyQuantize_x %b: Enables quantization values for secondary display.
dspyZero_x %d: Sets minimum range of input for quantization for secondary display.
dspyOne _x %d: Sets maximum range of input for quantization for secondary display
dspyMin_x %d: Minimum integer values used for clamping secondary display output
dspyMax_x %d: Maximum integer values used for clamping secondary display output
dspyDither_x %f: Floating point values to be used as random() to dither secondary display output
dspyPixelFilter_x %s: The name of the secondary display pixel filter. Choose from: box, triangle, catmull-rom, sinc, gaussian, mitchell, separable-catmull-rom, blackman-harris.
dspyFilterWidthX_x %s: The width of the secondary display pixel filter.
dspyFilterWidthY_x %s: The height of the secondary display pixel filter.

Camera

doDOF %b: Turn on or off the Depth of Field calculations.
dofUseLookat %b: Use the lookat point to control the depth of field calculations.
doMotionBlur %b: Turn on or off motion blur.
blurSubframe %b: Turn on or off subframe motion blur.
blurCamera %b: Turn on or off the motion blurring due to camera movement.
shutterAngle %d: Choose the shutter angle for motion blur calculations.
shutterTiming %s: Control when the virtual camera shutter opens: "frameOpen" or "frameCenter".
shutterConfig %s: Controls the shutter times - can be "moving" or "stationary".
frontPlane %b: Turn on or off the frontPlane glows feature.
backPlane %b: Turn on or off the backPlane sampling feature.

Reyes

shadingRate %f: The shading rate.
pixelSamples %d (also pixelSamplesX %d and pixelSamplesY %d): The number of pixel samples for supersampling.
pixelFilter %s: The name of the pixel filter. Choose from: box, triangle, catmull-rom, sinc, gaussian, mitchell, separable-catmull-rom, blackman-harris.
filterWidth %d (also filterWidthX %d and filterWidthY %d): The width of the pixel filter.
shadingInterp %b: Turn on or off shading interpolation.
binaryDice %b: Turn on or off binary dicing.
shadowBias %f: Specify the shadow bias.
eyeSplits %d: Specify the eyesplits.
dspyBucketX %f
          The bucket size in X.
dspyBucketY %f
          The bucket size in Y.
dspyGrid %f
          Set the grid size/
motionFactor %f: Specify a motion factor for decreasing shading on fast moving objects.

Rays

rayTrace %b: This controls whether special ray tracing attributes for reflection visibility and trace groups are included in the RIB stream.
traceBreadthSampleFactor %f: A global multiplier for all multi-sampling ray tracing operations.
traceDepthSampleFactor %f: A global multiplier for all multi-sampling ray tracing operations that varies the requested ray sample count according to the current ray depth.
traceMaxDepth %d: The absolute maximum ray depth affects all ray tracing effects including reflections, refractions and indirect diffuse illumination.
traceSpecularThreshold %f: Specifies the threshold of the cone angle, in degrees, used to discriminate between diffuse and specular ray paths.
traceMaxSpecularDepth %d: Limits the number of specular bounces (reflections and refractions) for rays trace from the associated primitive.
traceMaxDiffuseDepth %d: Limits the number of bounces (diffuse or specular) for indirect illuminance relative to the associated primitive.
traceDisplacements %b: Controls whether displacements are considered when ray tracing primitives.
traceSampleMotion %b: This sets the default value for the per-object attribute governing whether motion blurred objects appear in ray traced results.
traceBias %f: The default bias value for ray tracing. This value is added to the ray origin when tracing rays to overcome numerical precision issues resulting in false ray-primitive intersections.
irradianceMaxError %f: An error metric to control quality/speed traceoff for indirect illumination. Larger numbers result in a courser approximation but speed up the rendering. Set this value to 0 if you wish to force a recalculation of global illumination at every point. Set this value to a million to force complete reliance on indirect seed file, if provided.
irradianceMaxPixelDist %f: A secondary error metric to control quality/speed traceoff for indirect illumination. Larger numbers result in a courser approximation but speed up the rendering. Set this value to 0 if you wish to force a recalculation of global illumination at every point. Set this value to a million to force complete reliance on indirect seed file, if provided.
irradianceHandle %s: An irradiance cache file is used to accelerate the indirect diffuse calculations.
irradianceFileMode %s: The file mode associated with the Irradiance Cache File. Choose from "" (Ignore), "r" (Read Only), "w" (Write Only), "rw" (Read/Write).
photonShadingModel %s: Specifies a simplified shading model to employ when tracing photons.
photonCausticMap %s: Specifies the name of a caustic photon map to access when a shader that requires this information is attached to a particular primitive.
photonGlobalMap %s: Specifies the name of a global photon map to access when gathering soft indirect illuminance (color bleeding, etc.).
photonEstimator %d: The number of photons to consider when calculating indirect illumination via caustic or global photon maps. Larger numbers result in more blurry approximation.

Features (deprecated)

hider %s: The hider. Choose from "standard" or "pdisc".
jitter %b: Turn jittering on or off.
convertTextures %b: Turn on or off the automatic texture conversion feature.

Acceleration

computedMaps %s: Choose the behavior for computed maps such as shadows. Choose from: use or ignore.
lazyCompute %s: Choose the behavior for computed maps such as shadows. Choose from: off, maps or all.
objectsOnly %b: Turn on or off rendering of selected objects only.
lightsOnly %b: Turn on or off rendering of selected lights only.
selectedSet %s: Specify the use of a selection set rather than the current selection.
zealousCaching %b: Enable/disable zealous caching when rendering selected objects only.
doCrop %b: Turn on or off crop windows.
cropWin %f %f %f %f (also cropWinXMin %f, cropWinXMax %f, cropWinYMin %f, cropWinYMax %f): Specify the crop window.

Spool: Frames

doAnim %b: Turn on or off the generation of RIB for multiple frames.
computeStart %d: Specify the start frame for RIB generation.
computeStop %d: Specify the stop frame for RIB generation.
computeBy %d: Specify the frame increment for RIB generation.
computeOrder %s: Specify ordering of generated frames - may be "counting" or "binary".
animFPS %f: Specify the Frames Per Second for your scene.
sequenceStart %d: Specify the sequence start value.
sequenceStop %d: Specify the sequence end value.
referenceFrame %f: Specify the reference frame for your scene. Once per job maps will be computed and reference geometry will be cached from this frame.

Spool: Alfred

alfPause %b: Toggles whether created alfred tasks are started up in paused mode.
alfSvc %s: Specify a job-wide service (when generating worklists).
alfTag %s: Specify a job-wide tag (when generating worklists).
alfNRMMin %d: Specify the minimum number of CPUs to use for netrender.
alfNRMMax %d: Specify the maximum number of CPUs to use for netrender.
alfNRMVers %s: Specify a PRMan version to run on remote server machines when rendering with netrender. Note that this feature requires alfserver.
alfEnvKey %s: Specify an alfserver environment key. This key is used by alfred and alfserver to establish a set of environment variables on servers before executing remote commands.

Spool: Job Setup

jobChunkSize %s: Choose from superframe, frame or subframe.
superframeCount %d: Set the size of the superframe chunk.
RIBGen %s: choose a RIB generation mode from: immediate, deferred, distributed and distrender.
RIBFormat %s: Choose the format of your RIB files: ascii, binary, asciigzip, binarygzip.
computeLocation %s: Choose between local and remote.
renderer %s: Choose between none, netrender, render and custom.
imager %s: Choose between none and custom.
jobCleanup %s %s ...: Choose any of tex, map, rib, jtex, jmap.

Spool: Custom

customRenderer %s: Specify a custom rendering command.
customRendererSvc %s: Specify a service to use for the custom rendering command.
customRendererTag %s: Specify tags to use for the custom rendering command.
customImager %s: Specify a custom imaging command.
customImageSvc %s: Specify a service to use for the custom imaging command.
customImageTag %s: Specify tags to use for the custom imaging command.

Setting Render Globals via MEL and TOR.ini

The preceding Render Globals can also be set via MEL using the MTOR Control command. For more info see Control Commands in the MTOR MEL scripting section. Example:

mtor control setvalue -rg dspyName -value foo

You'll find you can set many of the default Render Global settings via the TOR.ini file:

$RATTREE/etc/TOR.ini