Light Linking

Overview

Light linking controls which geometry receives illumination from a particular light. Shadow linking independently controls which geometry casts shadows from that light. Use these controls for selective lighting, removing an unwanted shadow, or isolating a light to part of a scene.

Each light provides two named UsdCollectionAPI collections through UsdLuxLightAPI:

Collection	Membership effect
lightLink	Members receive the light’s contribution. Non-members do not.
shadowLink	Members cast shadows from the light. Non-members do not.

By default, both collections include the pseudo-root. Every geometry prim is therefore a member: the light illuminates the whole scene and all geometry can cast shadows from it.

Light-Link Receivers

Use the lightLink collection to choose which geometry receives light. The following RTPT comparison uses the default collection, excludes the balls, and then includes only the balls:

Light-link membership controls which geometry receives the light’s contribution.

Shadow-Link Casters

Use the shadowLink collection to choose which geometry can block the light. It does not control whether that geometry is illuminated. The following RTPT comparison changes which objects cast shadows while leaving their light-link membership unchanged:

Shadow-link membership controls which geometry casts shadows from the light.

Collection Attributes

Author these collection properties on the light prim:

USD declaration	Description
uniform bool collection:lightLink:includeRoot = true	Includes the pseudo-root, so all geometry receives light unless excluded. Set to false to build an explicit receiver list.
uniform token collection:lightLink:expansionRule = "expandPrims"	Controls whether included paths also include descendants.
rel collection:lightLink:includes	Adds receiver paths to the collection.
rel collection:lightLink:excludes	Removes receiver paths from the collection. Exclusions override inclusions.
uniform bool collection:shadowLink:includeRoot = true	Includes the pseudo-root, so all geometry casts shadows unless excluded. Set to false to build an explicit caster list.
uniform token collection:shadowLink:expansionRule = "expandPrims"	Controls whether included paths also include descendants.
rel collection:shadowLink:includes	Adds shadow-caster paths to the collection.
rel collection:shadowLink:excludes	Removes shadow-caster paths from the collection. Exclusions override inclusions.

The expansion rule accepts these OpenUSD tokens:

Token	Behavior
explicitOnly	Includes only the explicitly targeted prims.
expandPrims	Includes each targeted prim and its descendant prims. This is the default.
expandPrimsAndProperties	Also includes properties. Property membership does not add renderable geometry to an ovrtx link.

Authoring Links

The following examples illuminate only Subjects and Ground, while excluding NoShadow from shadow casting. Built-in light types already provide both named collections through UsdLuxLightAPI.

USDA

def SphereLight "KeyLight"
{
    float inputs:intensity = 1000

    # Illuminate only Subjects and Ground, including their descendants.
    uniform bool collection:lightLink:includeRoot = false
    uniform token collection:lightLink:expansionRule = "expandPrims"
    rel collection:lightLink:includes = [
        </World/Subjects>,
        </World/Ground>,
    ]

    # All geometry casts shadows except NoShadow.
    uniform bool collection:shadowLink:includeRoot = true
    rel collection:shadowLink:excludes = </World/Subjects/NoShadow>
}

USD Python

light = UsdLux.SphereLight.Define(stage, "/World/KeyLight")

# Illuminate only Subjects and Ground, including their descendants.
light_link = light.LightAPI().GetLightLinkCollectionAPI()
light_link.CreateIncludeRootAttr(False)
light_link.CreateExpansionRuleAttr(Usd.Tokens.expandPrims)
light_link.CreateIncludesRel().SetTargets(
    [Sdf.Path("/World/Subjects"), Sdf.Path("/World/Ground")]
)

# All geometry casts shadows except NoShadow.
shadow_link = light.LightAPI().GetShadowLinkCollectionAPI()
shadow_link.CreateIncludeRootAttr(True)
shadow_link.CreateExcludesRel().SetTargets(
    [Sdf.Path("/World/Subjects/NoShadow")]
)

Further Reading

Refer to the UsdLux light-linking documentation and the UsdCollectionAPI reference for the complete OpenUSD collection model.