Search Tips

Search is based on keyword.

`Ex: "Procedures"`

Do not search with natural language

`Ex: "How do I write a new procedure?"`

Give Feedback Support Portal

# UsdGaffer

You can use the UsdGaffer node to create groups of lights and store changes under one USD layer. You can view all your lights in the treeview, edit parameters, and make overrides all in one place.

See Using UsdGaffer to learn more about the workflow.

# Inputs

Connection Type | Connection Name | Function
input | in | The place in the node graph where you want to create a UsdGaffer for creating several lights together.

# Controls

Control (UI) | Default Value | Function
--- | --- | ---
+ menu | N/A | Allows you to choose prims to add: Add Light, Add Rig (Xform), or Add Scope. Allows you to turn on or off prims to interactively transform in the Viewer via Enable Interactive Transforms and Disable Interactive Transforms. Allows you to Rename, Delete, Copy and Paste prims. Note: Note that lights can be renamed only if they’ve been created locally to that node. USD doesn’t have a concept of deleting between layers, so if an upstream light gets picked up, the Rename or Delete option will not be available. You can either go upstream to delete the light where it was created or disable/set the visibility to off in order to remove its contributions.
> Select In Scenegraph | N/A | Sets the scene graph path to the location to be created. For more information, see Common Parameter Widgets.
primPath | /lights | Sets the prefix prim path for any local changes within this node. Changing the prim path will move the local children from the old prim path to the new updated prim path.
primPathSpecifier | Define | Switch between primPath specifiers for the primPath: Define, Override, or Class.
> Show Incoming Scene | disabled | Displays all incoming lights from upstream nodes.
> syncSelection | in/out | Controls how selection is synchronized between the Tree View, the Scene Explorer and the Viewer. off:0 Selections are independent. out:1 Selections in the node are synced to the Scene Explorer, but selection in the Scene Explorer is not synced to the node in/out:2 Selections are synchronized both ways in the node and the Scene Explorer.
[UsdGaffer object table] | N/A | Displays a list of all objects controlled by this UsdGaffer 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. • - distinguish between the state of the prim. • - current visibility of the prim. • Type - the type of light. Note: Right click in the object table to bring up the same options as the + menu, explained above.

The parameters for the Shader, Transform, Linking, Metadata, and All Properties tabs are dependent on what's selected in the UsdGaffer object table.

This page shows the controls of a default CylinderLight:

Control (UI) | Default Value | Function
--- | --- | ---
Object: CylinderLight
Shader Tab
shadow
Shadow Color | 0.000, 0.000, 0.000 | The color of the light's shadow.
Shadow Max Distance | -1 | The maximum distance that the shadow can extend.
Enable Shadows | enabled | When enabled, objects hit by this light will cast shadows.
Shadow Falloff | -1 | Sets how the shadow decreases as the distance from the light source increases.
Shadow Falloff Gamma | 1 | Sets the gamma within the shadow falloff zone.
shaping > cone
Cone Angle | 90 | Angular diameter of the light.
Cone Softness | 0 | The softness of the cone angle; typically a value of 1 is used for a soft gradation, while 0 would give the cone angle a hard cut-off. Values greater than 1 can be used to further soften the gradation.
shaping > ies
Profile Scale | 0 | Scale of the IES profile.
IES Profile | N/A | Allows you to load in an IES profile file.
Profile Normalization | disabled | Enable or disable the normalization of the IES profile.
Emission Focus | 0 | Controls the amount of emission focus.
Emission Focus Tint | 0.0000, 0.0000, 0.0000 | Controls the tint color of the emission focus.
Basic
Color | 1.0000, 1.0000, 1.0000 | Sets the color of the emitted light.
Color Temperature | 6500 | Color temperature, in degrees Kelvin, representing the white point of the light. When enabled the rgb converted result multiplies against the ‘Color’ control. The default is a common white point 6500k, or D65. Lower values are warmer and higher values are cooler with a valid range from 1000k to 10000k.
Enable Color Temperature | disabled | Enables using color temperature.
Exposure | 0 | Scales the power of the light exponentially as a power of 2, similar to an Fstop control. The result is multiplied against the intensity.
Intensity | 1 | Scales the power of the light linearly.
Refine
Diffuse Multiplier | 1 | The amount of diffuse applied.
Specular Multiplier | 1 | The amount of specular applied.
Geometry
Length | 1 | The length of the light.
Radius | 0.5 | The radius of the light.
(There may be other Geometry parameters dependent on the light type. E.g. Lights such as PortalLight and RectLight will also have Height and Width parameters:)
Height | 1 | The height of the light's geometry.
Width | 1 | The width of the light's geometry.
Advanced
Normalize Power | disabled | When enabled this option keeps the power of the light constant when the size of the light is altered. (This is the size of the light prim itself, not the locator in the Viewer.) This makes it easier to independently adjust the intensity/exposure and size of the light because the total illumination provided will not vary with the area or angular size of the light.
Transform Tab
xformOpName | N/A | The name to be given to the XformOp when stored in USD.
order | Scale Rot Trans | Select the order by which the three transformations are applied.
rotateOrder | Rx Ry Rz | Select the axes order by which the rotation takes place. By default the rotation is first around the x axis, then y, and finally z.
translate | 0.0, 0.0, 0.0 | Transforms the prim 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 prim 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 prim 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.
pivotTranslate | 0.0, 0.0, 0.0 | The amounts by which the pivot point for transformations is translated along the x, y, and z axes.
makeInteractive | Yes | When set to "Yes", the selected path can be interactively manipulated in the Viewer.
Linking Tab
lightLink
expansionRule | expandPrims | Specifies how the paths that are included in the collection must be expanded to determine its members. explicitOnly - only paths in the includes section and not in the excludes section belong to the collection. expandPrims - all the prims at or below the relationship includes (and not under the relationship excludes) belong to the collection. Any property paths included in the collection would also be honored. This is the default behavior as it satisfies most use cases. expandPrimsAndProperties - like expandPrims, but also includes all properties on all matched prims. We're still not quite sure what the use cases are for this, but you can use it to capture a large number of UsdObjects very concisely.
includeRoot | enabled | Boolean attribute indicating whether the pseudo-root path should be counted as one of the included target paths. This separate attribute is required because relationships cannot directly target the root.
includes | N/A | A list of paths or collections which should be included in the collection.
excludes | N/A | A list of paths which should be excluded from the collection.
membershipExpression | N/A | The Pattern-Based Collection Expression to use as the `membershipExpression` attribute for the CollectionAPI.
shadowLink
expansionRule | expandPrims | Specifies how the paths that are included in the collection must be expanded to determine its members. explicitOnly - only paths in the includes section and not in the excludes section belong to the collection. expandPrims - all the prims at or below the relationship includes (and not under the relationship excludes) belong to the collection. Any property paths included in the collection would also be honored. This is the default behavior as it satisfies most use cases. expandPrimsAndProperties - like expandPrims, but also includes all properties on all matched prims. We're still not quite sure what the use cases are for this, but you can use it to capture a large number of UsdObjects very concisely.
includeRoot | enabled | Boolean attribute indicating whether the pseudo-root path should be counted as one of the included target paths. This separate attribute is required because relationships cannot directly target the root.
includes | N/A | A list of paths or collections which should be included in the collection.
excludes | N/A | A list of paths which should be excluded from the collection.
membershipExpression | N/A | The Pattern-Based Collection Expression to use as the `membershipExpression` attribute for the CollectionAPI.
filters
filters | N/A | Paths of light filters to apply.
Metadata Tab
View additional metadata on the light prim.
All Properties Tab
extent | 0 x 3 | The extent of the light.
katana > attributeEditor > exclusiveTo > xform | UsdGaffer | Name of the xform.
light > Geometry > Material Sync Mode | noMaterialRespose | For a LightAPI applied to geometry that has a bound Material, which is entirely or partly emissive, this specifies the relationship of the Material response to the lighting response. Choose from noMaterialResponse, materialGlowTintsLight, and independent.
light > Internal > shaderId | CylinderLight | Default ID for the light's shader. This defines the shader ID for this light when a render context specific shader ID is not available.
purpose | default | Purpose is a classification of geometry into categories that can each be independently included or excluded from traversals of prims on a stage, such as rendering or bounding-box computation traversals. • default - the object has no particular purpose and is rendered by default. • render - the object is the full resolution version for use when rendering the scene. • proxy - the object is a proxy version used for test purposes, which can be a lower resolution to decrease render times. • guide - the object is not rendered, but is visible in the Viewer for reference.
visibility | inherited | Controls whether the object and its descendants are visible in the scene: • inherited - the object's visibility is controlled by its parent. • invisible - the object and its descendants are invisible in the scene. Visibility is meant to be the simplest form of "pruning" visibility that is supported by most DCC apps. Visibility is animatable, allowing a sub-tree of geometry to be present for some segment of a shot, and absent from others; unlike the action of deactivating geometry prims, invisible geometry is still available for inspection, for positioning, for defining volumes, etc.
xformOpOrder | 0 x 1 | xformOpOrder describes a series of transformations to apply.
proxyPrim | N/A | A list of paths to use as a proxy prim.
Advanced
Treat As Line | disabled | A hint that this light can be treated as a 'line' light (effectively, a zero-radius cylinder) by renderers that benefit from non-area lighting. Renderers that only support area lights can disregard this.