Expression Language
Every number parameter in the Inspector accepts an expression as well as a fixed value. Expressions give you a higher level of control over your graphs. Yeti's expression language is based on Disney's SeExpr.
Text (string) and on/off (boolean) parameters don't accept expressions, but text parameters can use environment variables written as ${NAME}.
To type an expression, click the small button to the right of a parameter's slider in the Inspector, to switch it to a text field. See Editing Parameters.
Common Examples
An expression is evaluated separately for each fibre, point or vertex the node processes, so it can give each one a different value. Here are some useful starting points:
| Expression | What it does |
|---|---|
fit(hash($id), 0, 1, 0.8, 1.2) | A random value between 0.8 and 1.2 for each fibre or point. For example, use it as a Grow node's Length Multiplier to vary the length of each hair. hash($id) gives a random number from 0 to 1 that stays the same for each fibre on every frame. |
noise($Pundef * 2) | Smooth patches that vary across the surface, from 0 to 1. Using the rest position, $Pundef, keeps the pattern stuck to the surface as the mesh moves. Multiply by more than 2 for smaller patches. |
smoothstep($strandu, 0.5, 1) | 0 for the first half of each fibre, rising smoothly to 1 at the tip. Use it to apply an effect only towards the tips. |
$F * 0.1 | A value that grows by 0.1 every frame, to animate a parameter. |
$myValue | The value of a user variable called myValue on the Yeti node, so you can control the graph from Maya. |
For values that you'd rather paint or draw than type, use a sampler instead.
Variables
Every attribute on the geometry flowing through a node is available in that node's expressions as a variable: put a $ in front of the attribute's name. For example, the strandu attribute is available as $strandu.
Common Variables
| Variable | Description |
|---|---|
$P | The position (vector). On fibres, this is the position of each vertex. |
$N | The normal (vector). |
$Pundef, $Nundef | The rest position and rest normal of each element, such as each scattered point or fibre (vectors). |
$strandu | The position along the fibre, from 0 at the root to 1 at the tip. |
$s, $t | The texture coordinates (floats). |
$id | The ID of each element, such as each point or fibre. Every element has its own ID, so the values can be large. |
$length | The length of each fibre. |
$elementCount | The number of elements (such as points or fibres) in the object. |
$frame, $F | The current frame number, rounded to a whole frame (1, 4, 10 and so on). |
$time | The current sample time, including subframes (0.8, 1.0, 1.2 and so on). |
You can also use the Yeti node's user variables, and some nodes add their own local variables, such as the Instance node.
Local Variables
You can define local variables at the start of an expression:
$a = noise($P);
$b = noise($a * 1);
pow($a, 0.5) + $b
You can also override external variables with a local assignment. For example, this is useful for scaling the frequency of noise:
$P = $P * 10; # increase noise frequency
fbm(vnoise($P) + $P/4)
Functions
Colour, Masking and Remapping
Function | Description |
|---|---|
float clamp ( float x, float lo, float hi ) | Constrains x to the range [lo, hi]. |
float compress ( float x, float lo, float hi ) | Compresses the dynamic range from [0..1] to [lo..hi]. |
float expand ( float x, float lo, float hi ) | Expands the dynamic range from [lo..hi] to [0..1]. |
float contrast ( float x, float c ) | Adjusts the contrast. For c from 0 to 0.5, the contrast is decreased. For c > 0.5, the contrast is increased. |
float invert ( float x ) | Inverts the value. Defined as 1-x. |
float remap ( float x, float source, float range, float falloff, int interp ) | A general remapping function. When x is within +/- range of source, the result is one. Beyond that range, the result falls to zero over the falloff distance. interp controls the shape of the falloff, as a number or a named constant: linear (0), smooth (1) or gaussian (2). |
color hsi ( color x, float h, float s, float i, float map=1 ) | Shifts the hue by h (in degrees), and scales the saturation and intensity by s and i respectively. |
color midhsi ( color x, float h, float s, float i, float map, float falloff=1 , int interp=0 ) | Like hsi, except that the control map is centred around its midpoint (a value of 0.5) and can scale the shift in both directions. |
color saturate ( color val, float amt ) | Scales the saturation of a colour by amt, around its Rec. 709 luminance. |
color rgbtohsl ( color rgb ) | Converts from RGB to HSL colour space. |
color hsltorgb ( color hsl ) | Converts from HSL (hue, saturation and lightness, all in the range [0..1]) to RGB colour space. |
float bias ( float x, float b) | A variation of gamma, where the control parameter goes from 0 to 1: values above 0.5 pull the curve up, and values below 0.5 pull it down. |
float gamma ( float x, float g) | pow(x, 1/g). |
float fit ( float x, float a1, float b1, float a2, float b2 ) | Linearly remaps x from [a1..b1] to [a2..b2]. |
float mix ( float a, float b, float alpha ) | Blends a and b by alpha. Defined as a*(1-alpha) + b*alpha. |
float boxstep ( float x, float a )float gaussstep ( float x, float a, float b )float linearstep ( float x, float a, float b )float smoothstep ( float x, float a, float b ) | The step functions are zero for x < a and one for x > b (or x > a for boxstep). Between a and b, the value changes continuously from zero to one. gaussstep uses the standard Gaussian "bell" curve, which is based on an exponential curve, and smoothstep uses a cubic curve. |
Noise
Function | Description |
|---|---|
float hash ( float seed1, [float seed2, …] ) | A random function of its seeds, with no internal seed. You can give it any number of seeds. |
float cellnoise ( vector v ) | Generates a field of constant-coloured cubes based on the integer location. This is the same as the RenderMan cellnoise function. |
color ccellnoise ( vector v ) | Colour cell noise. |
float noise ( vector v ) | A random function that blends smoothly between samples at integer locations. |
float noise ( float x, float y ) | |
float noise ( float x, float y, float z ) | |
float noise ( float x, float y, float z, float w ) | |
color cnoise ( vector v) | Colour noise. |
float snoise ( vector v) | Signed noise, in the range -1 to 1. |
vector vnoise (vector v ) | Signed vector noise. |
color cnoise4 ( vector v, float t) | Colour noise, in four dimensions. |
float snoise4 ( vector v, float t) | Signed noise in four dimensions, in the range -1 to 1. |
vector vnoise4 (vector v, float t ) | Signed vector noise, in four dimensions. |
float pnoise ( vector v, vector period ) | Periodic noise. |
float fbm ( vector v, int octaves = 6, float lacunarity = 2, float gain = 0.5 ) | fbm (fractional Brownian motion) is a multi-frequency noise function. Its base frequency is the same as the noise function's. octaves sets the number of frequencies, and lacunarity the spacing between them: a value of 2 means each octave has twice the frequency of the previous one. gain controls how much each frequency is scaled relative to the previous one. |
color cfbm ( vector v, int octaves = 6, float lacunarity = 2, float gain = 0.5 ) | |
vector vfbm ( vector v, int octaves = 6, float lacunarity = 2, float gain = 0.5 ) | |
float fbm4 ( vector v, float time, int octaves = 6, float lacunarity = 2, float gain = 0.5 ) | |
color cfbm4 ( vector v, float time, int octaves = 6, float lacunarity = 2, float gain = 0.5 ) | |
vector vfbm4 ( vector v, float time, int octaves = 6, float lacunarity = 2, float gain = 0.5 ) | |
float turbulence ( vector v, int octaves = 6, float lacunarity = 2, float gain = 0.5 ) | A variant of fbm that takes the absolute value of each noise term, for a more billowy look. |
color cturbulence ( vector v, int octaves = 6, float lacunarity = 2, float gain = 0.5 ) | |
vector vturbulence ( vector v, int octaves = 6, float lacunarity = 2, float gain = 0.5 ) | |
float voronoi ( vector v, int type = 1, float jitter = 0.5, float fbmScale = 0, int fbmOctaves = 4, float fbmLacunarity = 2, float fbmGain = 0.5) | A cellular noise pattern: a jittered variant of cellnoise. cvoronoi returns a random colour for each cell, and pvoronoi returns the position of the centre of each cell. type chooses between variants of the noise function. jitter controls how irregular the pattern is (a jitter of 0 is like ordinary cellnoise). The fbm parameters distort the noise field: when fbmScale is zero (the default), there's no distortion, and the rest are the same as for the fbm function. |
color cvoronoi ( vector v, int type = 1, float jitter = 0.5, float fbmScale = 0, int fbmOctaves = 4, float fbmLacunarity = 2, float fbmGain = 0.5) | |
color pvoronoi ( vector v, int type = 1, float jitter = 0.5, float fbmScale = 0, int fbmOctaves = 4, float fbmLacunarity = 2 ) |
Selection
int cycle ( int index, int loRange, int hiRange )
Cycles through the values from loRange to hiRange based on index. This is an offset "mod" function: the result is loRange + index % (hiRange - loRange + 1).
int pick ( float index, int loRange, int hiRange, [float weights, ...] )
Picks values randomly from loRange to hiRange based on index (which is hashed automatically). The values are distributed according to the weights; any weights you don't supply are 1.0.
float choose ( float index, float choice1, float choice2, [...] )
Chooses one of the choices based on index, which should be in the range [0..1].
color swatch ( float index, color choice0, color choice1, [...] )
Like choose, but for colours.
float wchoose ( float index, float choice1, float weight1, float choice2, float weight2, [...] )
Chooses one of the choices based on index, which should be in the range [0..1]. The values are distributed according to the weights.
General Math and Constants
Value | Description |
|---|---|
float PI = 3.14159… | |
float E = 2.71828… | |
float abs ( float x ) | The absolute value of x. |
float max ( float a, float b ) | The greater of a and b. |
float min ( float a, float b ) | The lesser of a and b. |
float fmod ( float x, float y ) | The remainder of x / y (also available as the % operator). |
float cbrt ( float x ) | The cube root. Not available on Windows. |
float sqrt ( float x ) | The square root. |
float ceil ( float x ) | The next higher integer. |
float floor ( float x ) | The next lower integer. |
float round ( float x ) | The nearest integer. |
float trunc ( float x ) | The nearest integer towards zero. Not available on Windows. |
float exp ( float x ) | E raised to the power x. |
float log ( float x ) | The natural logarithm. |
float log10 ( float x ) | The base 10 logarithm. |
float pow ( float x, float y ) | x to the power y (also available as the ^ operator). |
Trigonometry
Function | Description |
|---|---|
float acos ( float x ) | Arc cosine. |
float asin ( float x ) | Arc sine. |
float atan ( float x ) | Arc tangent. |
float atan2 ( float y, float x ) | Arc tangent of y/x, between -PI and PI. |
float cos ( float x ) | Cosine. |
float sin ( float x ) | Sine. |
float tan ( float x ) | Tangent. |
float acosd ( float x ) | Arc cosine, in degrees. |
float asind ( float x ) | Arc sine, in degrees. |
float atand ( float x ) | Arc tangent, in degrees. |
float atan2d ( float y, float x ) | Arc tangent of y/x in degrees, between -180 and 180. |
float cosd ( float x ) | Cosine, in degrees. |
float sind ( float x ) | Sine, in degrees. |
float tand ( float x ) | Tangent, in degrees. |
float acosh ( float x ) | Hyperbolic arc cosine. Not available on Windows. |
float asinh ( float x ) | Hyperbolic arc sine. Not available on Windows. |
float atanh ( float x ) | Hyperbolic arc tangent. Not available on Windows. |
float cosh ( float x ) | Hyperbolic cosine. |
float sinh ( float x ) | Hyperbolic sine. |
float tanh ( float x ) | Hyperbolic tangent. |
float deg ( float x ) | Converts radians to degrees. |
float rad ( float x ) | Converts degrees to radians. |
float hypot ( float x, float y ) | The length of the 2D vector (x, y). |
Vector Functions
Function | Description |
|---|---|
float angle( vector a, vector b ) | The angle between two vectors, in radians. |
vector cross ( vector a, vector b ) | The cross product of two vectors. |
float dist ( vector a, vector b ) | The distance between two points. |
float dot ( vector a, vector b ) | The dot product of two vectors. |
float length ( vector v ) | The length of a vector. |
vector norm ( vector v ) | The vector scaled to unit length. |
vector ortho ( vector a, vector b ) | A vector orthogonal to both vectors. |
vector up ( vector v, vector up ) | Rotates v so that the Y axis points in the given up direction. |
vector rotate ( vector v, vector axis, float angle ) | Rotates v around axis by angle, in radians. |
Vector Support
You can mix vectors (points, colours or 3D vectors) with scalars (single float values). When you use a scalar where a vector is expected, it's copied into all three components (for example, 0.5 becomes [0.5, 0.5, 0.5]). When you use a vector where a scalar is expected, only its first component is used.
One benefit of this is that all of the functions that work with scalars automatically work with vectors too. For example, pick, choose, cycle and spline all work with vectors.
Arithmetic operators, such as + and *, and scalar functions are applied to each component of a vector. For example, applying the gamma function to a colour adjusts the gamma of all three colour channels.
Curves
These functions interpolate a value from a set of control points. The positions, values and interpolation codes must be constants.
float curve(float param,float pos0,float val0,int interp0,float pos1,float val1,int interp1,[...])
Interpolates a 1D ramp, defined by control points, at param. Each control point is a triple of parameters, pos_i, val_i and interp_i. The interpolation codes are 0 (none), 1 (linear), 2 (smooth), 3 (spline) and 4 (monotone, non-oscillating, spline).
color ccurve(float param,float pos0,color val0,int interp0,float pos1,color val1,int interp1,[...])
Like curve, but interpolates a colour ramp.
float spline(float param,float y1,float y2,float y3,float y4,[...])
Interpolates a set of values at param, where y1, ..., yn are spaced evenly from 0 to 1.
Miscellaneous
vector getVar(string varName, vector defaultValue)
Returns the value of the variable varName if it exists, or defaultValue if it doesn't. For example, getVar("myValue", 1) uses a user variable called myValue when the Yeti node has one, and 1 otherwise.
void printf(string format,[param0,param1,...])
Prints a formatted string to the standard error stream, which is useful for debugging. Use %f for a float (the first component of a vector argument) and %v for a vector. For example, printf("test %f %v",[1,2,3],[4,5,6]); prints test 1 [4,5,6].
Operators
In decreasing order of precedence:
| Operator | Description |
|---|---|
[ a, b, c ] | Creates a vector. |
[ n ] | Accesses a vector component: n must be 0, 1 or 2 (for example, $P[0]). |
^ | Exponentiation (the same as the pow function). |
! | Logical NOT. |
~ | Inversion: ~$A gives the same result as 1-$A. |
* / % | Multiply, divide and modulus (the same as the fmod function). |
+ - | Add and subtract. |
< > <= >= | Comparison (uses only the first component of vectors). |
== != | Equality and inequality. |
&& | Logical AND. |
|| | Logical OR. |
? : | Conditional, like if-then-else (for example, $strandu < 0.5 ? 0 : 1). |
-> | Apply: the function on the right of the arrow is applied to the expression on the left. For example, noise($P) -> contrast(0.7) -> clamp(0.2, 0.8). |
Expressions can also use if (condition) { ... } else { ... } statements.
Assignment Operators
As well as the basic assignment statement, $foo=$bar;, you can use operator assignments such as $foo+=$bar;, which is the same as $foo=$foo+$bar;. The operator assignments are +=, -=, *=, /=, %= and ^=.
Comments
Everything after a # on a line is ignored, so you can use it for comments or to "comment out" part of an expression. In a multi-line expression, each line can have its own comment.
SeExpr
Yeti's expression language is based on SeExpr, an open-source project. You'll find more information on the SeExpr homepage.