GafferThree

The GafferThree node type allows you to create lights under an arbitrary hierarchy of rigs. Materials, transformations, and constraints can be applied to lights from within the GafferThree's Parameters interface. This node also supports:

Creating and applying master materials to lights.

Muting and soloing lights, or all lights under a rig.

Linking lights to specific objects.

Editing lights from the incoming scene, and editing multiple lights at once.

Adding aim constraints to lights.

Note:  The GafferThree node is an improvement upon the legacy Gaffer node from Katana 1.x. Notable improvements from the Gaffer node are the following:

Improved performance when dealing with large numbers of lights in Katana projects.

Full advantage of Geolib3, the scene graph processing library.

Allows editing of existing lights from the incoming scene.

The legacy Gaffer node type from Katana 1.x is still present, and current scenes should continue to work, but it is advised to move to using the newer GafferThree node type where possible.

Connection Type

Connection Name

Function

Input

in

The place in the node graph where you want to create a GafferThree for creating several lights together.

 

Control (UI)

Function

> Select In Scenegraph

Sets the scene graph path to the location to be created.

For more information, see Common Parameter Widgets.

> Show Incoming Scene

Displays all incoming lights, rigs, and master materials from upstream Gaffer-type nodes.

sync selection

When enabled, selecting a Gaffer light within the Parameters tab selects its location within the Scene Graph tab:

off - no syncing is performed (the default).

out - selection of a light in the GafferThree node is mirrored in the Scene Graph tab, but not the other way around.

in/out - selecting in either the Scene Graph tab or GafferThree node results in the corresponding entry in the other also being selected.

[Gaffer object table]

Displays a list of all objects controlled by this GafferThree node. The object table contains the following information:

Name - the name of the object. Double-click in this column to change the name of the item.

M - click to mute the object so that it is omitted from renders.

S - click to solo the object so that everything not solo-ed is omitted from interactive renders.

Shader - displays the shader associated with the object. You can also right-click in this column to select a shader. Once you've added a shader, double-click in this column to assign or change it at any time.

Color - specifies the color of a light. Double-click the swatch to activate the color picker. If there isn't a swatch, you need to add a color in the Material tab before you can change it in this column.

Int - sets the light intensity.

Exp - sets the light exposure.

Linking - indicates whether or not the item is linked. A star in the entry indicates there are exceptions.

Right-click the [Gaffer object table item]

Add > Master Material

Adds a master material to the gaffer table. The master material is assigned to lights, providing the same material for multiple lights. Each light is also capable of overriding the defaults set by this master material.

Add > Light

Adds a light to the object table.

Add > Rig

Adds a rig for multiple lights to the object table.

Add > Light Filter Reference

Adds a light filter that references another light filter package.

Add > Light Filter

Adds a light filter that modifies the behavior of a light, depending on the renderer you're using.

Add > Sky Dome

Adds a sky dome light, used to provide environment lighting to your scene.

Add > Import Rig...

Adds a previously exported rig to the object table.

Delete

Deletes the selected entity in the object table.

Duplicate

Creates a copy of the currently selected entity.

Adopt for Editing

Allow you to make edits on a light, rig, or master material that has been shown from an incoming scene, which can be any upstream Gaffer-type node.

Delete Edit Package

If you adopted a light, rig, or master material for editing, you can revert back to a read-only state and reverse the changes that you applied.

Toggle Lock State of Selected Items

Toggles the lock state of the selected entity in the object table.

Group Selected Siblings Under Rig

Groups the selected siblings under a newly created rig.

Export Rig

Exports the currently selected item as a .rig file.

Create Shared Light Filter

Creates a light filter on a light that references a light filter that already exists in another location in the scenegraph.

Expand All

Expands the selected branch in the object table to reveal all children. If the selected branch does not have any children, nothing happens when attempting to expand.

Note:  In the menu, Expand All becomes Expand Branch whenever there is more than one item in the Gaffer object table.

Expand All To

Expand the branch to a specific type, either assembly, component, or level-of-detail group. This method of expansion applies specifically to the scene graph, and has limited use for the GafferThree.

Note:  In the menu, Expand All To becomes Expand Branch To whenever there is more than one item in the Gaffer object table.

Collapse All To

Collapse the branch to a specific type, either assembly, component, or level-of-detail group. This method of collapse applies specifically to the scene graph, and has limited use for the GafferThree.

Note:  In the menu, Collapse All To becomes Collapse Branch To whenever there is more than one item in the Gaffer object table.

Collapse All

Collapses the selected branch in the object table to hide all children. If the selected branch does not have any children, nothing happens when attempting to collapse.

Note:  In the menu, Collapse All becomes Collapse Branch whenever there is more than one item in the Gaffer object table.

Expand Location

Expands the selected location to only the children and leaves directly below it in the hierarchy.

Collapse Location

Collapses the selected location and any children and leaves directly below it, but not any entities higher than the location in the hierarchy.

The display parameters for the Object, Material, and Linking tabs are dependent on what's selected in the Gaffer object table. Where a particular tab isn't listed for an object type, there are no parameters in that tab.

Control (UI)

Default Value

Function

Object list: master material

Material tab

useLookFileMaterial

Disabled

When enabled, the material from an associated Look File is used.

Add Shader

N/A

Click to add a renderer-specific shader from the dropdown list. The Material tab is populated with controls appropriate to the shader selected, and are dependent on the renderers installed.

 

Control (UI)

Default Value

Function

Object list: light

Object tab > geometry

projection

perspective

Sets the light projection mode:

perspective - a warped projection where distant objects/features appear smaller than those nearer the camera.

orthographic - a two-dimensional representation of a three-dimensional object.

radius

1

Sets the light's radius.

fov

70

Controls the field of view angle in degrees.

orthographicWidth

30

Sets the orthographic projection width.

centerOfInterest

20

Sets the center of interest.

near

0.1

Sets the near clipping plane distance.

far

100000

Sets the far clipping plane distance.

screenWindow

-1.0, 1.0, -1.0, 1.0

Controls the screen window placement on the imaging plane. They are the left, right, bottom, and top bounds of the screen window.

Object tab > transform

transform

N/A

Transforms the light according to the SRT or matrix controls.

For more information, refer to the Transform Controls Widget Type in the Common Parameter Widgets.

transform > Tools

N/A

Adjusts the light to match selected scene graph selection options in the dropdown menu.

For more information, refer to the Transform Tools Widget Type in the Common Parameter Widgets.

enable aim constraint: enabled; aim constraint options

targetPath

N/A

Specifies the object(s) to constrain to. If you want to aim a light to point at a target, this is the target. If you set multiple targets, then the constraint aims at the average center of the objects. The targetPath parameter options are available in either a scene graph widget or dropdown menu to the right of the parameter.

For more information, refer to the Scene Graph Location Widget Type in the Common Parameter Widgets.

addToConstraintList

Yes

Specifies whether or not to add the base path for the light to the globals.constraintList at /root/world in the Attributes tab.

targetOrigin

Object

Sets how the center of the target object is calculated:

Object - uses the local origin of the object as the target.

Bounding Box - uses the center of the object’s bounding box as the target.

Face Center Average - uses the face center average of the object as the target.

Face Bounding Box - uses the face center average of the object’s bounding box as the target.

baseAimAxis

0.0, 0.0, -1.0

The axis of the base object that is pointed at the target. Adjusting these values changes the side of the object that is aimed at the target.

baseUpAxis

0.0, 1.0, 0.0

The axis of the base object that is pointed upwards relative to the target. Adjusting these values changes the rotation of the base object, while keeping the aim constant.

targetUpAxis

0.0, 1.0, 0.0

The axis of the target object that is pointed upwards relative to the base object. Adjusting these values changes the rotation of the target object, while maintaining the aim constant.

setRelativeTargets

No

Stores target paths in the scene graph constraint definition as paths relative to the base path.

Targets should still be specified as absolute paths in this node's parameters.

Object tab > annotation

text

N/A

Places a label in the Viewer containing the string entered in the text field.

previewColor

1.0, 1.0, 1.0

Specifies the color of the light annotation in the Viewer. This value does not affect the color value of the light.

For more information, refer to the Color Widget Type in the Common Parameter Widgets.

Material tab > material

useLookFileMaterial

Disabled

When enabled, the material from an associated Look File is used.

Add Shader

N/A

Click to add a renderer-specific shader from the dropdown list. The Material tab is populated with controls appropriate to the shader selected, and are dependent on the renderers installed.

useLookFileMaterial: enabled

reference > asset

N/A

Set the path to the asset you want in your scene.

For more information, refer to the Asset and File Path Widget Types in the Common Parameter Widgets.

reference > materialPath

N/A

Choose the material path from the dropdown list, based on the asset you have listed in the asset field above.

If you do not have an asset listed in the asset field, nothing appears in the dropdown list for materialPath.

Linking tab > light linking

Support for light linking is dependent on your renderer.

action

append linking information

Determines whether the linking options set in this node override the incoming scene options or if the new settings are appended to the incoming options. If this light doesn't exist in the incoming scene, this option has no effect.

initialState

on

(or use existing value for adopted lights)

Determines whether the newly-added light location is initially on, off, or use existing value.

Note:  The use existing value option is only available for adopted lights.

clearUnmatched

disabled

When linking is resolved, the clearUnmatched parameter determines whether or not existing light linking attributes for this light are removed from locations that do not match the on or off expressions.

The effect of this parameter is only visible in the Attributes tab when linking has been resolved, which means after a LightLinkResolve node or when Implicit Resolvers are active.

Examines the lightList attribute on your linked objects to ensure that the attributes have been set correctly. If the parameter has been disabled, the value of the enable child attribute in the lightList attribute for your light is 0; otherwise, the default enabled setting is 1.

on

N/A

A CEL Statement through which scene graph locations can be linked to the selected light, thereby turning the light on for those locations.

The scene graph locations are specified using the Collection Expression Language (CEL). For more information, refer to the CEL Reference document found on the documentation HTML page (accessed through Help > Documentation).

CEL Statements are edited using CEL Statement Widgets. For more information on the CEL Statement Widget type, refer to CEL Statement Widget Type in Common Parameter Widgets.

off

N/A

A CEL Statement through which scene graph locations can be linked to the selected light, thereby turning the light off for those locations.

The scene graph locations are specified using the Collection Expression Language (CEL). For more information, refer to the CEL Reference document found on the documentation HTML page (accessed through Help > Documentation).

CEL Statements are edited using the CEL Statement Widgets. For more information on the CEL Statement Widget type, refer to CEL Statement Widget Type in Common Parameter Widgets.

Linking tab > shadow linking

Support for shadow linking is dependent on your renderer.

action

append linking information

Determines whether the linking options set in this node override the incoming scene options or if the new settings are appended to the incoming options. If this light doesn't exist in the incoming scene, this option has no effect.

initialState

don't set value

(or use existing value for adopted lights)

Determines the initial value for shadow visibility in the lightList entry for the newly-added light: on, off, don't set value, or use existing value.

Note:  The use existing value option is only available for adopted lights.

clearUnmatched

disabled

When linking is resolved, the clearUnmatched parameter determines whether or not existing light linking attributes for this light are removed from locations that do not match the on or off expressions.

The effect of this parameter is only visible in the Attributes tab when linking has been resolved, which means after a LightLinkResolve node or when Implicit Resolvers are active.

Examines the lightList attribute on your linked objects to ensure that the attributes have been set correctly. If the parameter has been disabled, the value of the enable child attribute in the lightList attribute for your light is 0; otherwise, the default enabled setting is 1.

on

N/A

A CEL Statement through which scene graph locations can be linked to the selected light, thereby turning shadow casting from this light on for those locations.

The scene graph locations are specified using the Collection Expression Language (CEL). For more information, refer to the CEL Reference document found on the documentation HTML page (accessed through Help > Documentation).

CEL Statements are edited using CEL Statement Widgets. For more information on the CEL Statement Widget type, refer to the CEL Statement Widget Type in Common Parameter Widgets.

off

N/A

A CEL Statement through which scene graph locations can be linked to the selected light, thereby turning shadow casting from this light off for those locations.

The scene graph locations are specified using the Collection Expression Language (CEL). For more information, refer to the CEL Reference document found on the documentation HTML page (accessed through Help > Documentation).

CEL Statements are edited using CEL Statement Widgets. For more information on the CEL Statement Widget type, refer to the CEL Statement Widget Type in Common Parameter Widgets.

 

Control (UI)

Default Value

Function

Object list: rig

Object tab > transform

transform

N/A

Transforms the rig according to the SRT or matrix controls.

For more information, refer to the Transform Controls Widget Type in the Common Parameter Widgets.

transform > Tools

N/A

Adjusts the rig to match selected scene graph selection options in the dropdown menu.

For more information, refer to the Transform Tools Widget Type in the Common Parameter Widgets.

Object tab parameters continued

enable point constraint

disabled

When enabled, specifies the point constraint options.

enable orient constraint

disabled

When enabled, specifies the orient constraint options.

when enable point constraint: enabled; point constraint options

targetPath

N/A

Specifies the object(s) to constrain to. If you want to aim a rig to point at a target, this is the target. If you set multiple targets, then the constraint aims at the average center of the objects. The targetPath parameter options are available in either a scene graph widget or dropdown menu to the right of the parameter.

For more information, refer to the Scene Graph Location Widget Type in the Common Parameter Widgets.

addToConstraintList

Yes

Specifies whether or not to add the base path for the rig to the globals.constraintList at /root/world in the Attributes tab.

allowMissingTargets

No

When set to Yes, silently ignore the constraint if its target is not in the scene graph. When set to No, produce an error on constraint resolution if the target is missing.

baseOrigin

Object

Sets how the center of the base object is calculated:

Object - uses the local origin of the object as the origin.

BoundingBox - uses the center of the object’s bounding box as the base origin.

targetOrigin

Object

Sets how the center of the target object is calculated:

Object - uses the local origin of the object as the target origin.

BoundingBox - uses the center of the object’s bounding box as the target origin.

FaceCenterAverage - uses the face center average of the object as the target origin.

FaceBoundingBox - uses the face center average of the object’s bounding box as the target origin.

setRelativeTargets

No

Stores target paths in the scene graph constraint definition as paths relative to the base path.

Targets should still be specified as absolute paths in this node's parameters.

when enable orient constraint: enabled; orient constraint options

targetPath

N/A

Specifies the object(s) to constrain to. If you want to aim a rig to point at a target, this is the target. If you set multiple targets, then the constraint aims at the average center of the objects. The targetPath parameter options are available in either a scene graph widget or dropdown menu to the right of the parameter.

For more information, refer to the Scene Graph Location Widget Type in the Common Parameter Widgets.

addToConstraintList

yes

Specifies whether or not to add the base path for the rig to the globals.constraintList at /root/world in the Attributes tab.

targetOrientation

Object

Sets how the orientation of the target object is calculated:

Object - uses the local origin of the object as the target.

Face - uses the local origin on the face as the target.

allowMissingTargets

No

When set to Yes, silently ignore the constraint if its target is not in the scene graph. When set to No, produce an error on constraint resolution if the target is missing.

xAxis

Enabled

When enabled, orientation is constrained on the x axis.

yAxis

Enabled

When enabled, orientation is constrained on the y axis.

zAxis

Enabled

When enabled, orientation is constrained on the z axis.

setRelativeTargets

No

Stores target paths in the scene graph constraint definition as paths relative to the base path.

Targets should still be specified as absolute paths in this node's parameters.

 

Control (UI)

Default Value

Function

Object list: light filter reference

Object tab

referencePath

N/A

The path to the light filter package that you want to reference as part of this light filter.

 

Control (UI)

Default Value

Function

Object list: light filter

Object tab

inherits

N/A

The path to another light filter package that you want to inherit from.

Object tab > viewer

fill

solid

The manner in which the light filter is displayed in the viewer: as points, a wireframe, or a solid fill.

Object tab > transform

translate

0.0, 0.0, 0.0

Transforms the light filter by moving it on the x, y, or z axes. Modifying the light filter in the viewer using the Translate manipulators also updates these parameter values.

rotate

0.0, 0.0, 0.0

Transforms the light filter by rotating it around the x, y, or z axes. Modifying the light filter in the viewer using the Rotate manipulators also updates these parameter values.

scale

1.0, 1.0, 1.0

Transforms the light filter by scaling it along the x, y, or z axes. Modifying the light filter in the viewer using the Scale manipulators also updates these parameter values.

Material tab

useLookFileMaterial

disabled

When enabled, the material from an associated Look File is used.

Add Shader

N/A

Click to add a renderer-specific shader from the dropdown list. The Material tab is populated with controls appropriate to the shader selected, and are dependent on the renderers installed.

useLookFileMaterial: enabled

reference > asset

N/A

Set the path to the asset you want in your scene.

For more information, refer to the Asset and File Path Widget Types in the Common Parameter Widgets.

reference > materialPath

N/A

Choose the material path from the dropdown list, based on the asset you have listed in the asset field above.

If you do not have an asset listed in the asset field, nothing appears in the dropdown list for materialPath.

Linking tab > light linking

action

append linking information

Determines whether the linking options set in this node override the incoming scene options or if the new settings are appended to the incoming options. If this light doesn't exist in the incoming scene, this option has no effect.

initialState don't set value

Determines whether the newly-added light location is initially on, off, or doesn't have a value set.

clearUnmatched disabled

When linking is resolved, the clearUnmatched parameter determines whether or not existing light linking attributes for this light are removed from locations that do not match the on or off expressions.

The effect of this parameter is only visible in the Attributes tab when linking has been resolved, which means after a LightLinkResolve node or when Implicit Resolvers are active.

Examines the lightList attribute on your linked objects to ensure that the attributes have been set correctly. If the parameter has been disabled, the value of the enable child attribute in the lightList attribute for your light is 0; otherwise, the default enabled setting is 1.

on

N/A

A CEL Statement through which scene graph locations can be linked to the selected light, thereby turning the light on for those locations.

The scene graph locations are specified using the Collection Expression Language (CEL). For more information, refer to the CEL Reference document found on the documentation HTML page (accessed through Help > Documentation).

CEL Statements are edited using CEL Statement Widgets. For more information on the CEL Statement Widget type, refer to CEL Statement Widget Type in Common Parameter Widgets.

off

N/A

A CEL Statement through which scene graph locations can be linked to the selected light, thereby turning the light off for those locations.

The scene graph locations are specified using the Collection Expression Language (CEL). For more information, refer to the CEL Reference document found on the documentation HTML page (accessed through Help > Documentation).

CEL Statements are edited using the CEL Statement Widgets. For more information on the CEL Statement Widget type, refer to CEL Statement Widget Type in Common Parameter Widgets.

 

Control (UI)

Default Value

Function

Object list: sky dome

Object tab > transform

translate

0.0, 0.0, 0.0

Transforms the sky dome light by moving it on the x, y, or z axes. Modifying the sky dome in the viewer using the Translate manipulators also updates these parameter values.

rotate

0.0, 0.0, 0.0

Transforms the sky dome light by rotating it around the x, y, or z axes. Modifying the sky dome in the viewer using the Rotate manipulators also updates these parameter values.

scale

1000.0, 1000.0, 1000.0

Transforms the sky dome light by scaling it along the x, y, or z axes. Modifying the sky dome in the viewer using the Scale manipulators also updates these parameter values.

Material tab > material

useLookFileMaterial

enabled

When enabled, the material from an associated Look File is used and the additional parameters are contained in the reference dropdown.

Add Shader

N/A

Click to add a renderer-specific shader from the dropdown list. The Material tab is populated with controls appropriate to the shader selected, and are dependent on the renderers installed.

useLookFileMaterial: enabled

reference > asset

/tmp/hdriSkyDomeLight.klf

Set the path to the look file you've written to disk.

For more information, refer to the Asset and File Path Widget Types in the Common Parameter Widgets.

reference > materialPath

/root/materials/hdriSkyDomeLight

Choose the material path from the dropdown list, based on the asset you have listed in the asset field above.

If you do not have an asset listed in the asset field, nothing appears in the dropdown list for materialPath.

Linking tab > light linking

action

append linking information

Determines whether the linking options set in this node override the incoming scene options or if the new settings are appended to the incoming options. If this light doesn't exist in the incoming scene, this option has no effect.

initialState don't set value

Determines whether the newly-added light location is initially on, off, or doesn't have a value set.

clearUnmatched disabled

When linking is resolved, the clearUnmatched parameter determines whether or not existing light linking attributes for this light are removed from locations that do not match the on or off expressions.

The effect of this parameter is only visible in the Attributes tab when linking has been resolved, which means after a LightLinkResolve node or when Implicit Resolvers are active.

Examines the lightList attribute on your linked objects to ensure that the attributes have been set correctly. If the parameter has been disabled, the value of the enable child attribute in the lightList attribute for your light is 0; otherwise, the default enabled setting is 1.

on

N/A

A CEL Statement through which scene graph locations can be linked to the selected light, thereby turning the light on for those locations.

The scene graph locations are specified using the Collection Expression Language (CEL). For more information, refer to the CEL Reference document found on the documentation HTML page (accessed through Help > Documentation).

CEL Statements are edited using CEL Statement Widgets. For more information on the CEL Statement Widget type, refer to CEL Statement Widget Type in Common Parameter Widgets.

off

N/A

A CEL Statement through which scene graph locations can be linked to the selected light, thereby turning the light off for those locations.

The scene graph locations are specified using the Collection Expression Language (CEL). For more information, refer to the CEL Reference document found on the documentation HTML page (accessed through Help > Documentation).

CEL Statements are edited using the CEL Statement Widgets. For more information on the CEL Statement Widget type, refer to CEL Statement Widget Type in Common Parameter Widgets.

Linking tab > shadow linking

Support for shadow linking is dependent on your renderer.

action

append linking information

Determines whether the linking options set in this node override the incoming scene options or if the new settings are appended to the incoming options. If this light doesn't exist in the incoming scene, this option has no effect.

initialState

don't set value

(or use existing value for adopted lights)

Determines the initial value for shadow visibility in the lightList entry for the newly-added light: on, off, don't set value, or use existing value.

Note:  The use existing value option is only available for adopted lights.

clearUnmatched

disabled

When linking is resolved, the clearUnmatched parameter determines whether or not existing light linking attributes for this light are removed from locations that do not match the on or off expressions.

The effect of this parameter is only visible in the Attributes tab when linking has been resolved, which means after a LightLinkResolve node or when Implicit Resolvers are active.

Examines the lightList attribute on your linked objects to ensure that the attributes have been set correctly. If the parameter has been disabled, the value of the enable child attribute in the lightList attribute for your light is 0; otherwise, the default enabled setting is 1.

on

N/A

A CEL Statement through which scene graph locations can be linked to the selected light, thereby turning shadow casting from this light on for those locations.

The scene graph locations are specified using the Collection Expression Language (CEL). For more information, refer to the CEL Reference document found on the documentation HTML page (accessed through Help > Documentation).

CEL Statements are edited using CEL Statement Widgets. For more information on the CEL Statement Widget type, refer to the CEL Statement Widget Type in Common Parameter Widgets.

off

N/A

A CEL Statement through which scene graph locations can be linked to the selected light, thereby turning shadow casting from this light off for those locations.

The scene graph locations are specified using the Collection Expression Language (CEL). For more information, refer to the CEL Reference document found on the documentation HTML page (accessed through Help > Documentation).

CEL Statements are edited using CEL Statement Widgets. For more information on the CEL Statement Widget type, refer to the CEL Statement Widget Type in Common Parameter Widgets.