Expressions

Any mappable parameter (Map > Expression) and the Expression node take an expression, evaluated per strand, or per point along it. The direction of a Bend, Gravity or Displace takes one too (the f(x) button beside it) and gives a vector per strand.

The language is SeExpr, the one Maya XGen uses: the same operators, statements and built-in functions, with XGen's variable names accepted. Most XGen expressions paste in unchanged. The exceptions are listed under Coming from XGen.

$n = fbm($P * 3, 4);                  # a local, read below
$crown = smoothstep($ny, -0.2, 0.8);  # SeExpr's order: smoothstep(x, a, b)
mix($n, 1, $crown)                    # the last line is the value

A number expression on a mappable parameter is mapped from 0-1 onto the parameter's min and max. Expressions give the same values on every machine and every thread count.

Script nodes use this language too, with blocks that run per strand and per point, outputs they assign (the point, its width, its color, channels) and loops.

Writing an expressionCopy Anchor Link

• Names take a $ or not: $length and length are the same variable.
• Comments start with # or // and run to the end of the line.
• Locals: $name = expression; makes a local for the lines below it. The last line, without an assignment, is the value. A local may hide a built-in variable ($P = $P * 10;).
• The node's own variables (numbers and vectors, shown as sliders on the Expression node) read as $amount, $center or $center.x. Make one keyable and it animates.
• Per point: an expression that reads t, pt, px, py, pz, pointIndex or a point channel is evaluated at every point of every strand, on the parameters marked per point. Elsewhere it reads the root's values.
• Time: an expression that reads frame or time is evaluated again on every frame. One that doesn't is cached.

SyntaxCopy Anchor Link

Operators, from the loosest binding to the tightest:

Statements, before the final value:

$a = 1;                     # assignment
$a += 2;                    # also -=  *=  /=  %=  ^=
if ($x > 0) {
    $side = 1;
} else if ($x < -0.5) {
    $side = -2;
} else {
    $side = -1;
}

Inside braces go assignments and further if statements. A local set in an if keeps its value from before the if where its branch doesn't run. A local set in one branch only, and nowhere before, is an error when it is read after the if.

Vectors: + - * / % ^ and the number functions work component by component. A number beside a vector applies to every component, and a number passed where a function takes a vector becomes [x, x, x]. A vector where a number is needed is an error (write .x, length(v) or dot(a, b)), as is comparing vectors.

Strings appear only as map names: map("crown"), map('crown').

VariablesCopy Anchor Link

The shape variables (length, reach, tip...) read 0 where strands don't exist yet, as in Scatter's density.

FunctionsCopy Anchor Link

The number functions below work on vectors component by component. A noise function's point p is a vector; a number x there is the point [x, 0, 0].

Math

Ranges and blends

Random and noise

Cells

Vectors

Colors

Curves and picking

Curve keys are fixed when the expression compiles: numbers, or the node's own variables (which can be keyed). The value t and spline's values can be anything.

Maps

Coming from XGenCopy Anchor Link

Paste the expression into the parameter's Expression field. Names, operators, ->, statements, comments and the built-in functions read as they do in XGen.

Paint maps. XGen's map('${DESC}/paintmaps/length/') points at a Ptex folder. GroomLab reads the last part of such a path as a map name, so that line reads the groom's own map named length. Paint a map with that name (Groom Tools > Paint) and the expression works as it is. Without one, the expression reports the missing map by name. vmap(...) reads the map's color.

Slider comments. XGen turns $min = 0.4; #0.1,1.0 into a slider. Here the comment is only a comment and the line is an ordinary local. For a slider, give the Expression node its own variable and read it as $min.

What differs:

• Random values. rand, hash, the noises, cellnoise, voronoi and pick have SeExpr's ranges and behaviour, but come from GroomLab's own hash and noise. The pattern is a different one from XGen's, so a groom that depends on a particular random layout won't match.
• rand without a seed is random per strand and repeatable (it hashes the strand's ID). It is not a new number on each evaluation.
• $u, $v are the scalp's UV coordinates. On a polygon mesh, XGen's are the root's position within its Ptex face, so expressions that build patterns from them look different.
• $cLength is the strand's length at the point in the graph where the expression is read, before later nodes change it.
• Curve keys must be constants (numbers or the node's own variables). XGen's ramps write constants, so this only matters for hand-written curves with computed keys.
• Vectors in a number's place are an error here (SeExpr takes the first component). Write $v[0] or $v.x. Comparing two vectors is also an error.
• Not supported: printf, sprintf and getVar, and the variables $Nref, $dPdu, $dPdv (and their variants), $cWidth, $cDepth, $aCount, $descId, $patchId, $objectId, $Cs and $As. Each is an error that names it. None is read as 0.
• A number as a noise point is [x, 0, 0], a line through the noise, where other vector functions spread a number to [x, x, x].

GroomLab's own additions, kept for expressions written before it followed SeExpr:

• smoothstep(e0, e1, x) and linearstep(e0, e1, x) with the edges first (GLSL's order) still read that way when both edges are constants and x is not. In every other case the order is SeExpr's (x, a, b). A pasted XGen expression always passes x first, so the rule never changes one.
• curve(t, p0, v0, p1, v1, ...) with pairs (a smooth curve, as the ramps draw) still reads that way when the arguments can't be SeExpr's triples.
• mod, step, lerp, gain, linearcurve, rand(seed), .x .y .z components, and the variables listed above without an XGen name.

ExamplesCopy Anchor Link

Each of these is checked by GroomLab's tests. The parameter is a suggestion; any mappable parameter takes any of them.

Longer hair on the crown (Length > keep, min 0.3, max 1):

# 1 where the scalp faces up, less toward the back of the head (+Z is the face)
$crown = smoothstep($ny, -0.2, 0.8);
$nape = smoothstep(-$nz, 0.3, 0.9);
clamp($crown - 0.5 * $nape, 0, 1)

Length by UV region (Length > keep): full length inside a band of U, short outside it.

# the band runs from U 0.3 to 0.7, with edges 0.05 wide
$inside = smoothstep($u, 0.25, 0.3) * (1 - smoothstep($u, 0.7, 0.75));
mix(0.2, 1, $inside)

Random clump strength (Clump > strength):

# most strands clump tightly; one in five stays loose
$loose = $rand < 0.2;
$loose ? rand(0.2, 0.5, 11) : rand(0.85, 1, 12)

Frizz on the tips only (Noise > amplitude, per point, max 0.3):

# nothing on the first 60% of each strand, full at the tip, on a third of the strands
$tips = smoothstep($t, 0.6, 1);
$frizzy = $rand < 0.33;
$frizzy * $tips

A noise mask (any parameter, or a Group's value):

# soft-edged patches; the scale sets their size, the 0.45-0.55 band their edge
$scale = 3;
$n = fbm($P * $scale, 4);
smoothstep($n, 0.45, 0.55)

Melanin variation (HairColor > melanin):

# a base of 0.55, each clump a little darker or lighter, each strand a little more,
# and 3% grey strands
$clump = (hash($clumpId) - 0.5) * 0.15;
$strand = rand(-0.05, 0.05);
$grey = $rand < 0.03;
$grey ? 0.05 : clamp(0.55 + $clump + $strand, 0, 1)

Gravity leaning out from the head (Gravity > direction, a vector):

# down, tipped out along the scalp's normal, more on the sides than the top
$lean = 0.2 + 0.4 * (1 - abs($ny));
normalize([0, -1, 0] + $N * $lean)

A centre part (Bend > direction): if/else picks the side.

if ($x < 0) {
    $side = -1;
} else {
    $side = 1;
}
normalize([$side, -0.3, 0])

An XGen ramp over the root's height (Length > keep), with ->:

# the root's height from 1.2 to 1.8 onto 0-1, then a monotone curve through four keys
$h = $P[1] -> fit(1.2, 1.8, 0, 1) -> clamp(0, 1);
curve($h, 0, 0.3, 4, 0.5, 1, 4, 1, 0.6, 4)

A painted map from XGen (any parameter; the groom has a map named length):

$a = map('${DESC}/paintmaps/length/');  #3dpaint, 200
$a

In the viewportCopy Anchor Link

The GPU preview evaluates number expressions built from numbers, the number variables, channels, + - * / ^, comparisons, &&, ||, !, ~, ?:, if/else, and these functions: sin cos tan asin acos atan atan2 abs sqrt floor ceil fract exp log sign pow min max mod step clamp mix lerp smoothstep linearstep round trunc radians degrees gamma bias gain fit. Any other expression (vectors, %, noise, curves, maps, the other functions) is evaluated on the CPU for that node, with the same result.

The Expression editor completes names and functions as you type and lists examples to start from (Maya: the Expression node's panel).