Light path expressions¶

Light path expressions (LPEs) allow custom AOVs to be created by specifying what light paths should be included in the AOV output. A light path is described as a sequence of events. For example, the light path expression “CVL” describes light that reaches the camera (“C”) from a volume scattering event (“V”) which started from a light source (“L”) - i.e. volume direct lighting.

Warning

When entering a LPE into Nuke, any “[” characters must be escaped, i.e. replaced with “\[”. This is because Nuke interprets “[” as the start of a TCL script expression. The backslash tells Nuke to leave it alone and pass it through unchanged to Eddy.

If you get an error like “Failed to tokenize light path expression ‘RV: Unknown command’” then it is due to a missing “\\”. Without this Nuke replaces the light path expression with “Unknown command” which then causes an error in Eddy.

Event types¶

These events can appear in a LPE on their own, or can be the first part of a fully described event (see below).

C	Camera event, this is always the first event listed in a LPE.
R	Surface reflection event. This includes specular, glossy, and diffuse reflections.
T	Surface transmission event. This includes both refraction and sub-surface scattering.
V	Volume scattering event.
L	Light source emission event.
O	Emission event. This is emission from any source that is not called a ‘light’, e.g. volume emission or emission from a surface shader.
B	Background event. This occurs when a ray misses all objects and lights in the scene and instead returns the background color.
A	Albedo event. This a special event type that returns the albedo instead of the lighting.

Scattering types¶

These scattering types can appear in a LPE on their own, or can be the second part of a fully described event (see below). When they appear on their own they match both reflection and transmission events. For example, “S” matches both specular reflection events and specular transmission (refraction) events.

D	Diffuse scattering.
G	Glossy scattering.
S	Specular scattering.
s	‘Straight’ scattering, i.e. a ray that passes through the surface without changing direction.

Matching any event¶

The “.” character can be used in an expression to match any event. For example, “CV.L” will match the light paths “CVVL”, “CVDL”, “CVSL” etc. Note it will not match “CVL”.

Matching multiple events¶

Any event can be followed by one of these characters, which control how many events can be matched.

+	Matches one or more events. For example, “CV+L” will match the light paths “CVL”, “CVVL”, “CVVVVVL”, i.e. volume direct light plus indirect light scattered from volumes.
*	Matches zero or more events. For example, “CV*L” will match the light paths “CL”, “CVL”, “CVVVVL”, i.e. emission from lights plus volume direct and indirect light.
?	Matches zero or one events. For example, “CV?L” will match only the light paths “CL” or “CVL”, i.e. emission from lights plus volume direct light.

Event classes¶

To match a particular set of events, square brackets can be used to define an event class. So for example “[DG]” will match a diffuse or glossy scattering event, “[RTV]” will match a reflection, transmission, or volume event.

Negated classes can also be defined by starting the list of events with “^”. For example, “[^VS]” will match any event except for volume or specular scattering.

Tip

Take care when using negated events. “[^S]” does not just mean a non-specular scattering event, it will also match lights, emission, etc. Use “<[RTV] [^S]>” to get a non-specular scattering event (see the fully described event syntax below).

Grouping¶

Events can be grouped together using parentheses. This allows the match characters “+”, “*”, and “?” to apply to an entire sequence of events.

For example, “C(VD)+L” would match the light paths “CVDL”, “CVDVDL”, “CVDVDVDVDL”, etc. The expression “C(VD)?L” would match only the light paths “CL” or “CVDL”.

Alternation¶

The symbol “|” can be used to match either one of two possible event sequences.

For example, “C(VD|DS)L” will match the light paths “CVDL” or “CDSL”.

Tip

Be careful to use the grouping parentheses correctly with the “|” alternation symbol. For example, to match the light paths “CDL” or “CSL” the correct expression is “C(D|S)L”.

The expression “CD|SL” is incorrect, it will match only the light paths “CD” or “SL”. Similarly “C(D)|(S)L” is also wrong, it also matches only the paths “CD” or “SL”.

Fully described event syntax¶

The events specified using a single letter are actually a convenient shortcut for the full event description syntax. The full syntax for an event is “< event_type scattering_type object_tags material_tags >”. The event_type and scattering_type are required, the object_tags and material_tags are optional.

Any of the four parts can be replaced by a “.” to indicate that they are not specified and should match anything. This allows for matching of just a tag, for example “<… ‘material1’>” or “<.. ‘object1’>”.

The event and scattering type parts also support the square bracket event classes to allow matching multiple types. For example, “<[RT] [SG]>” will match any reflection or transmission event that is also specular or glossy. Negation is supported too, for example “<R [^G]>” will match any reflection type that is not glossy scattering.

The tags also support a version of the event classes. For example, “<.. [ ‘object1’ ‘object2’ ]>” will match any event with an object tag of either ‘object1’ or ‘object2’. Negation can also be used, e.g. “<.. [^ ‘object2’]>” will match any event except for those with an object tag of ‘object2’.

Some examples of the fully described event syntax:

“<RD>” - matches diffuse reflections only.
“<R.>” - matches any reflection event (this is equivalent to just “R”).
“<.D>” - matches any diffuse scattering event (this is equivalent to just “D”).
“<[RTV].>” - matches any reflection, transmission, or volume event.
“<[^V].>” - matches anything except volume events.
“<.[^D]>” - matches anything except diffuse scattering events. Note this also includes volume events, light events, etc.
“<R. ‘object1’>” - matches reflection events from objects tagged with ‘object1’.
“<L. [^ ‘light1’]>” - matches a light event from any light that is not tagged ‘light1’.

Examples¶

See the Standard AOVs for many additional examples, equivalent light path expressions for all the built-in AOVs are listed. They can be a good starting point to build your own light path expressions.

Direct light from objects tagged ‘object1’:
“C<[RTV]. ‘object1’>L”
Direct light from lights tagged ‘light1’ (note that the light tag filter setting on all AOVs is an easier way to achieve this):
“C[RTV]<L. ‘light1’>”
Direct light from all lights except those tagged ‘light1’:
“C[RTV]<L. [^ ‘light1’]>”
Indirect light with exactly two bounces:
“C..L”
Surface reflections from objects tagged with ‘object1’, and volume scattering from objects tagged ‘object2’:
“C(<R.’object1’>|<V.’object2’>).*”
Direct light from diffuse and glossy reflections only:
“C[DG]L”
Surfaces lit by indirect volume scattering:
“C[RT]V.*”