Parameter Expressions

The Basics
Predefined Variables
Writing Numerical Expressions
Writing String Substitutions
Factory Functions and Procedures
  Accessing Client State
  Waveform Generators, Interpolators
  Color and Point Functions
  Math and Utility Functions
  Operators
File Referencing
Examples

The Basics

Slim utilizes the simple and powerful syntax of the TCL (see also http://tcl.sourceforge.net/) expr and subst commands to support parameter expressions.  String parameters automatically undergo TCL string substitution while other parameters are evaluated as expressions only when their value providers are set to Expression. 

Evaluation Context

By default, expressions are evaluated in the context of MTOR. This allows expressions to access many predefined variables that may vary per frame, per object, etc. You might instead want your expression to be evaluated within Slim. This will allow you to access Slim's scripting environment. Expressions evaluated within Slim will be evaluated once per job, instead of once per frame. Use the Context submenu of the tcl menu to control your expression's evaluation context.

Predefined Variables

You can refer to predefined variables in your expressions or substitutions. We provide several useful variables describing the current project, object and temporal context. The simplest expression is simply a reference to a predefined variable,  for example, $CONEANGLE.

Numerical Expressions

You use numerical expressions (based on expr) to compute values for parameters of type: int, float, point, color, matrix, etc. Slim and *TOR automatically vectorize the computation for non scalar data types. If writing mathematical expressions isn't your bag, you can use very simple expressions to gain access to animation curves specified in your animation environment. For example, you can create a parameter curve in Maya and refer to that curve in place of an appearance parameter value.  Another option is to rely upon the custom user interfaces that are provided to interactively edit TCL expressions.  The rampEditor is one example of this.

String Substitutions

You use string substitutions (based on subst) to construct strings to be passed to your shaders. Through standard TCL notation

[

command

]

 you can also make calls to TCL procedures like format and expr. 
Extensibility

You can extend the set of functions and variables available to your expressions by placing custom TCL procs in a file which is loaded via a LoadExtension directive in the appropriate initialization files.

top

Predefined Variables 

 

Animation variables are setup automatically by Slim in conjunction with your animation system. The value of the variables depends on the rendering context. When rendering your scene, the variables take on values which you establish through RenderMan globals and the UI of your animation system. When rendering within Slim's Appearance Editor, values are preset as specified below. 

top

Writing Numerical Expressions - Functions vs Procedures

 Here's a portion from our familiar appearance editor window. Recall that you must set the parameter's value provider to Expression in order to enable this expression entry.

The basic form of all expressions is quite simple. An expression is made of of a series of potentially nested function and/or procedure calls whose arguments are either return values of other functions or procedures or variable references. In TCL, a variable's value is accessed by preceding the variable name with the $ symbol. Slim, in conjunction with your animation software, conspire to set up a small set of special variables which you can refer to in your expressions. In this example, $pct is such a variable. Function calls can also be combined through the use of standard mathematics operators like +, *, /, %, etc. 

It's important to distinguish between TCL procedures and TCL functions because they can only be used in certain contexts. A TCL function requires parentheses to enclose its comma separated argument list and is only meaningful within the scope of the expr command..  Above we see that lerp must be a function and thus we can infer that Slim requests TCL to evaluate the provided string as a TCL expression.  In other words, Slim composes a TCL expression by prepending expr. To invoke a TCL procedure within the context of a TCL expression we are required to bound the procedure within square brackets as follows:

lerp(0,2,$pct) * [myproc 2 3 4]

Here myproc is a TCL procedure defined and loaded, presumably, via Slim's extension mechanisms.

Once you've developed an expression you can check it by invoking the Validate command in the menu associated with the tcl button to the left of your expression.   There you'll also find controls to access special purpose interfaces which provide more convenient interfaces onto certain Slim functions or procedures.

top

Writing String Substitutions


Use string substitutions as string parameter values in your parameters. Note that this differs from numerical expressions above in that you enter the expression in-line in the standard text entry widget of the parameter (and not the expression entry). Typically, you'll use string substitutions to construct texture map references by embedding the frame number in your favorite representation. Here's a typical example:

$WSRoot/rmanpix/flapping.$F4.tif

In this example we refer to two predefined variables to construct a string that looks like:

/puddle/users/bones/maya/projects/default/pix/flapping.0033.tif

Note that this substitution is made at RIB generation time. The key point to understand is that the string that you enter will be passed to TCL's subst command. You can embed numerical expressions in substitutions through the use of the bracket ([]) operators. Here's an example that remaps the current frame into a different frame:

pix/flapping.[format %0.4d [expr fit($f,10,90,1,20)]].tif

This tricky example makes two nested function calls (first to expr, then to format) to create a string that is 4 digits, padded with zeros at the front. The fit function will remap the frame number ($f) into a different range. In this example frames between 10 and 90 will be mapped to between 1 and 20. Frames outside this range will be 1 or 20. The format cmd will then convert the results of the fit.

A simpler variation of the same command can be constructed with a single procedure call:

pix/flapping.[fit -pad 4 -in 10 90 -out 1 20].tif

Note that the fit functionality is provided in both functional and procedural forms.

top

Factory Functions,  Procedures and Operators 

You can use standard functions and procedures in your expressions.  As discussed above, functions and procedures have different syntax and can be used in difference contexts.  Here, procedure calls are denoted using the notation: 
[procname arg1 arg2 ..].

Accessing Client State

[clientcmd "cmd"]  (aliases: mel)

The clientcmd procedure causes an arbitrary expression to be evaluated in the client (e.g. MTOR) application environment. Here're some examples: 
 

     [clientcmd "getAttr $OBJPATH.mystring"]

 

This command executes the mel getAttr command and replaces the $OBJPATH variable with the name of the object that the associated appearance is attached to. Presumably a user has created the variable mystring and placed interesting information therein. 

 

     [mel "getAttr -size curve1.controlPoints"]

 

We've aliased hostcmd under the name mel for brevity and clarity for Maya users. Note that the command takes a single string argument representing the host command and it's arguments. Variable substitution is performed
by *TOR and so special symbols may require escaping via the backslash symbol.   Note, too, that this command can also be utilized in standard parameter animation expressions as long as the result can be evaluated
numerically. 

 

[clientattr "attr" t] (aliases: mattr)

 

[coordsys shapename]

Corrects the name of a coordinate system reference for file referencing name munging.

 

[mattr "attr" t] (aliases: mayaattribute)

This procedure accesses the attribute named by "attr" in your Maya scene. The format for the attribute specification is the standard Maya syntax. 

 

[st0 "objectname"], [st1 "objectname"] (aliases: STMatrix0, STMatrix1)

Use these procedures to gain access to object specific texture mapping coordinates or transformations from your modeler. In this manner you connect the texture transformations on any object in your scene to a particular appearance parameter. The Mondo.sl, file provides an example of how to use this information in your own shaders. The objectname parameter is the name of a "place2dTexture" Maya object. It does not need to be the same object to which you are attaching the RenderMan shader.

 

[shdmap cameraname (px,py,pz,nx,ny,nz)]

Returns the name of the map associated with the shadow pass driven by the lightsource named cameraname.  If you're using pointlight shadows, the optional second argument should be used to choose the axis.

 

[refmap cameraname]

Returns the name of the map associated with the reflection pass driven by the camera named cameraname.   In the case of reflections maps, cameraname is often the name of the reflecting plane geometry.

 

[envmap cameraname]

Returns the name of the map associated with the environment pass driven by the camera named cameraname. 

 

[imgmap cameraname]

Returns the name of the map associated with the reference pass driven by the camera named cameraname. 

 

[zmap cameraname]

Returns the name of the map associated with the depth pass driven by the camera named cameraname. 

 

[txmake args]

Returns the name of the map resulting for the conversion of a source texture file into Pixar texture file format.  Here are the optional arguments:

Waveform Generators, Interpolators 

lerp(a,b,t)  
Linearly interpolate between a and b using t, t in the range 0 to 1. 

flerp(a,b,f,startf,endf)  
Same as lerp but more convenient for frame ranges. A value between a and b is returned when f is between startf and endf. 

ease(a,b,t)  
Cubic interpolation between a and b using t, t in the range 0 to 1. Tangent of zero at both ends. 

fease(a,b,f,startf,endf)  
Same as ease but more convenient for frame ranges. A value between a and b is returned when f is between startf and endf. 

easein(a,b,t)  
Quadratic interpolation between a and b using t, t in the range 0 to 1. Tangent of zero at beginning. 

feasein(a,b,f,startf,endf)  
Same as easein but more convenient for frame ranges. A value between a and b is returned when f is between startf and endf. 

easeout(a,b,t)  
Quadratic interpolation between a and b using t, t in the range 0 to 1. Tangent of zero at end. 

feasout(a,b,f,startf,endf)  
Same as easeout but more convenient for frame ranges. A value between a and b is returned when f is between startf and endf. 

noise(t)  
Perlin style noise, returns values between -1 and 1. t is the wave parameter representing pseudo periods of the noise function. If you want 5 periods of noise over your animation you can use: noise(5 * $pct) 

fit(x,a1,b1,a2,b2) (also map)
Takes a value x between a1 and b1 and remaps it into the range described by a2 and b2. The remapping is a linear function and values of x which lie outside the range (a1,b1) are clamped. 

The following wave generation functions are presented in Waveform Generators for Computer Graphics by C. Schlick - Graphic Gems Vol V. The parameter t is as above, s is the shape factor in the range [-1,1], f is the frequency variance in the range [0,1] and a is the amplitude variance in the range [0,1]. 

[spline1 $pct {k1 v1} {k2 v2} {k3 v3}...]
Returns the evaluation of the 1-D spline given by the list of knots provided as arguments.  Knots are x-y pairs where the x values are monotonically increasing parameter values and y is the function's value.  The spline is deemed 1D because there's a single y value for each x.

[spline3 $pct {k1 {r1 g1 b1}} {k2 {r2 g2 b2}}...]
Returns the evaluation of the 3-D spline given by the list of knots provided as arguments.  Knots are x-y pairs where the x values are monotonically increasing parameter values and y is the function's value.  The spline is deemed 3D because there're three y values for each x.

[fit args] (-pad %d, -in a b, -out c d)
A procedure version of the function described above.

Color and Point Functions 

rgb(r,g,b), rgbi(ir,ig,ib)  
Allow the specification of color (vector) parameters. r,g,b in the range [0,1], ir,ig,ib in the range [0,255]. 

hsv(h,s,v), hsvi(ih,is,iv)  
Allow the specification of color (vector) parameters in the HSV color space. h,s,v in the range [0,1], ih,is,iv in the range [0,255]. Note that this will immediately convert the hsv values to rgb values. 

xyz(x,y,z)  
Allow the specification of point (vector) parameters. 

Math and Utility Functions

Operators

top

File Referencing

Maya supports powerful file referencing functionality which relies on name munging to prevent name collisions between objects in separate files.  When refering to object names in the client, Slim and MTOR have special features to accomodate this.

When a palette is loaded, all appearances are tagged with a namespace name that is derived from the name of the referenced file they're stored in.  This was broken in Slim 1.0 and so the namespace was always the empty string.  As of Maya 2.5 there's no fool-proof way to determine the true namespace value so MTOR must currently rely on the filename to make an educated guess at the name.  Until we get more support from Alias in the Maya API, customers should not use the -namespace option of the the mel "file" command to override the default naming during file referencing operations.  This becomes an issue primarily when referencing a single file multiple times.

In our current implementation, the names in expressions are not expected to update, rather all this magic stuff happens in the evaluation of particular procs and depends upon an appearance's namespace.

MTOR implements a few special scripting commands that allow you to refer to Maya objects.  These include:  mattr, clientcmd (mel), coordsys, stmatrix, shdmap, ....  MTOR automatically attempts to correct for file referencing name munging.  This means that users shouldn't normally need to worry about constructing special expressions with the NAMESPACE variable.

EXCEPT:  there is some special-case code in the name munging code to support the use of file references in the "reference the same file many times" case.  No name munging is performed if incoming name contains one of the special separator characters: ':' or '_' AND an object with that name is present in the scene.  This logic is sufficient for allowing a customer to perform site-specific name munging through their own custom TCL procs.  In this case a mattr call might look like:

[mattr [sitePrefixGenerator]sphere.translateX]]

assuming that "proc sitePrefixGenerator {}" has been loaded into both MTOR and Slim via an instance of TOR.ini as described in the standard RAT initialization documentation.

Examples

Pure External Reference

For non programmers, the simplest method for parameter animation leverages the power of the animation system rather than the expression syntax. If you are an Alias user, the simplest expressions will be references to your Alias animation channels. Here are some examples:

Pure Mathematical Functions

For programmers, it's often simpler to throw together a simple expression than it is to construct a channel, build the animation, then refer to that in an expression. Here are some simple expressions:

Mixed Expressions

Now that you've got the hang of it, you can get a little fancier.

top

 

 

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