Dome Light

A DomeLight emits inwards from an environment surrounding the scene. Set a high-dynamic-range texture to provide image-based lighting, or leave the texture unset to use the common color and intensity controls.

A textured dome light supplies both environment illumination and a background.

USD declaration	Description
asset inputs:texture:file	Color texture, normally a high-dynamic-range environment image.
token inputs:texture:format = "automatic"	Texture parameterization: automatic, latlong, mirroredBall, angular, or cubeMapVerticalCross.

The following examples create a dome light using a latitude-longitude environment texture:

USDA

def DomeLight "Environment"
{
    asset inputs:texture:file = @../../data/studio.exr@
    token inputs:texture:format = "latlong"
}

USD Python

light = UsdLux.DomeLight.Define(stage, "/World/Environment")
light.GetTextureFileAttr().Set(Sdf.AssetPath("../../data/studio.exr"))
light.GetTextureFormatAttr().Set(UsdLux.Tokens.latlong)

Multiple Dome Lights

The outdoor dome supplies only the camera background. A second studio dome, hidden from direct camera rays, illuminates the objects and appears in the chrome sphere’s reflection.

ovrtx supports multiple dome lights in the same scene by default. Create a separate DomeLight prim for each environment you want to combine. Each dome can have its own texture, rotation, color, intensity, and exposure. This lets you combine an environment with a separate studio-lighting texture or a constant-color fill.

The domes’ contributions add together; they are not automatically averaged or normalized. Adding a second dome can therefore make the scene brighter. Adjust each dome’s intensity and exposure to balance its contribution. For example, two identical domes at half the original intensity produce the same combined emission as one dome at the original intensity.

Choosing Which Domes Appear in the Background

A dome can illuminate the scene without appearing in the camera’s background. For example, you can show an outdoor environment in the background while using a second, hidden studio dome to light the subject. The DomeLight’s visibleInPrimaryRay attribute controls whether the light is visible to the camera or not.

When using scene partitions, the domes available to a camera depend on its partition. Multiple domes do not bypass scene-partition isolation.

Using Separate Domes for the Background and Lighting

To show one environment to the camera while lighting the scene with a different environment, create two dome lights and configure them as follows. Ensure omni:rtx:lights:visibilityOverride = "perLight" (the default) on the RenderProduct.

Attribute	Background dome	Lighting dome
inputs:texture:file	Image the camera should see	Environment used for illumination
visibleInPrimaryRay	true	false
inputs:diffuse	0	1
inputs:specular	0	1

Setting both response multipliers to zero on the background dome removes its diffuse and specular contributions while preserving its appearance to direct camera rays. Hiding the lighting dome from primary rays removes it from the background while retaining its illumination and reflections.

Keep both domes’ intensities nonzero. Adjust the background dome’s intensity or exposure to control the visible background brightness, and adjust the lighting dome’s intensity or exposure to control illumination. Setting the background dome’s intensity to zero would also make its camera-visible image black.

Finite Dome Modes

Finite dome modes project the environment onto virtual ground, sphere, or box geometry. They are useful when an infinite environment gives incorrect parallax, scale, or horizon placement. The projection geometry affects dome lighting and background rays; it does not create renderable USD geometry.

OmniFiniteDomeLightAPI is auto-applied to every DomeLight and provides six modes:

Mode	Behavior
infinite	Standard infinite environment-map lighting. This is the default.
ground	Infinite environment with the lower portion projected onto a ground plane.
sphere	Projects the environment onto a finite sphere. Rays that miss the sphere return black.
box	Projects the environment onto a finite box. Rays that miss the box return black.
sphereWithGround	Finite sphere plus a projected ground plane that replaces the lower portion.
boxWithGround	Finite box plus a projected ground plane that replaces the lower portion.

The following comparison uses the same environment, camera, and subject for all six modes:

Finite modes project the same environment onto different virtual boundaries.

Finite Dome Attributes

Author these attributes on the DomeLight prim:

USD declaration	Description
token omni:rtx:domeLight:mode = "infinite"	Selects the projection mode listed above.
float omni:rtx:domeLight:radius = 100	Base radius for sphere and sphereWithGround. The geometry transform’s X scale multiplies this value.
float3 omni:rtx:domeLight:size = (200, 200, 200)	Full width, height, and depth for box and boxWithGround. The geometry transform scales each axis independently.
float omni:rtx:domeLight:groundTextureScale = 0	Sets the projection’s vanishing-point distance along its up axis. ovrtx uses the absolute value.
rel coordSys:domeGeometry:binding	Optionally targets an Xformable prim that positions, rotates, and scales the finite boundary independently. The identity transform is used when no target is authored.

The DomeLight transform controls environment texture orientation and the ground origin. The optional coordSys:domeGeometry:binding target controls the finite sphere or box center, orientation, and scale. This separation lets you orient the image independently from its projection boundary.

Radius

The following comparison changes omni:rtx:domeLight:radius on a sphereWithGround dome:

Radius changes the extent and curvature of the spherical projection boundary.

Size

The following comparison changes omni:rtx:domeLight:size on a boxWithGround dome:

Size controls the width, height, and depth of the box projection boundary.

Ground Texture Scale

The following comparison changes omni:rtx:domeLight:groundTextureScale on a boxWithGround dome:

Ground texture scale changes the vanishing-point distance used to project the environment onto the ground.

Authoring A Finite Dome

The following examples create a sphere-with-ground dome and bind separate projection geometry. The API schema is already auto-applied to the dome light.

USDA

def DomeLight "Studio"
{
    asset inputs:texture:file = @../../data/studio.exr@
    token inputs:texture:format = "latlong"

    # OmniFiniteDomeLightAPI is auto-applied to DomeLight prims.
    token omni:rtx:domeLight:mode = "sphereWithGround"
    float omni:rtx:domeLight:radius = 5
    float3 omni:rtx:domeLight:size = (10, 6, 8)
    float omni:rtx:domeLight:groundTextureScale = 10

    # Use a separate transform to position and scale the finite geometry.
    rel coordSys:domeGeometry:binding = </World/DomeGeometry>
}

def Xform "DomeGeometry"
{
    double3 xformOp:translate = (0, 2, 0)
    double3 xformOp:scale = (1, 1, 1)
    uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:scale"]
}

USD Python

dome = UsdLux.DomeLight.Define(stage, "/World/Studio")
dome.CreateTextureFileAttr("../../data/studio.exr")
dome.CreateTextureFormatAttr("latlong")

# OmniFiniteDomeLightAPI is auto-applied to DomeLight prims.
dome.GetPrim().GetAttribute("omni:rtx:domeLight:mode").Set("sphereWithGround")
dome.GetPrim().GetAttribute("omni:rtx:domeLight:radius").Set(5.0)
dome.GetPrim().GetAttribute("omni:rtx:domeLight:size").Set(Gf.Vec3f(10, 6, 8))
dome.GetPrim().GetAttribute("omni:rtx:domeLight:groundTextureScale").Set(10.0)

# Use a separate transform to position and scale the finite geometry.
geometry = UsdGeom.Xform.Define(stage, "/World/DomeGeometry")
geometry.AddTranslateOp().Set(Gf.Vec3d(0, 2, 0))
geometry.AddScaleOp().Set(Gf.Vec3d(1, 1, 1))
dome.GetPrim().GetRelationship("coordSys:domeGeometry:binding").SetTargets(
    [geometry.GetPath()]
)