EnvironmentLight

EnvironmentLights illuminate objects using an image of light from a real-world environment. This image-based lighting is generated using High Dynamic Range (HDR) images.

To use an environment light, you first need to shoot a real life environment as an HDR image. Using the SphericalTransform node, you then convert this image into a spherical mapped image. The sphere is used to surround the 3D objects, so that the mapped image color illuminates them.

Environment light only works with shiny object materials that can reflect the mapped image. It results in a very realistic lighting that makes it easier to integrate the objects into the environment.

See also DirectLight, PointLight, and SpotLight.

To learn more about the workflow, see Light Your Scene.

Note:  The USD native equivalent light node in the New 3D System is the GeoDomeLight.

Tip:  EnvironmentLight's classic 3D system equivalent is the Environment node.

Inputs and Controls

Connection Type

Connection Name

Function

Input

map An optional input to load in an image map to show up in the reflections of a mesh.

Control (UI)

Knob (Scripting)

Default Value

Function

EnvironmentLight Tab

Live Read read_from_scene_link on If enabled read values from the source prim attributes dynamically into the knobs. If disabled the knobs switch into normal/local mode. Note that in this dynamic mode the values are not baked into keyframes in the knobs hey are dynamically created as if they were an expression. This means that the node will always update to the latest prim state.

Source Prim

source_prim_path

N/A

Specify the source prim's scene graph location.

Basic

Intensity

intensity

50000

Scales the power of the light linearly.

Exposure

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.

Color

color

1

Sets the color of the emitted light.

Enable Color Temperature

enable_color_temperature

off

Enables using color temperature.

Color Temperature

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.

Guide Radius

guide_radius

100000

The radius of guide geometry to use to visualize the environment light.
Refine

Diffuse Amount

diffuse

1

A multiplier for the effect this light has on the diffuse response of materials. Note that this is a non-physical control and can break energy-conservation calculations.

May not be respected by all light shader implementations.

Specular Amount

specular

1

A multiplier for the effect this light has on the specular response of materials. Note that this is a non-physical control and can break energy-conservation calculations.

May not be respected by all light shader implementations.

ScanlineRender Options
Blur Size blur_size 1 Increase the size of the texture sampling region for each texture sample, causing it to blur. (ScanlineRender only option)
Mirror Image X mirror_image_x off Flips the image in X. (ScanlineRender only option)
Mirror Image Y mirror_image_y off Flips the image in Y. (ScanlineRender only option)
Position Tab
Live Read read_from_scene_link on If enabled read values from the source prim attributes dynamically into the knobs. If disabled the knobs switch into normal/local mode. Note that in this dynamic mode the values are not baked into keyframes in the knobs hey are dynamically created as if they were an expression. This means that the node will always update to the latest prim state.

Source Prim

source_prim_path

N/A

Specify the source prim's scene graph location.

Constrain
Apply Constrain to Local Parent TRS local_parent_constrain_enable off Enabling this will apply any constrain transform only to the Local Parent Translate/Rotate/Scale controls, leaving the Local Xform controls available for application -after- the constrain is applied. This reduces the need for parenting connections. For example a light can be Local Parent constrained to a surface point while allowing the light to be translated back from the object via Local Axis.
Type constraint Look At

The type of constraint:

Look At - Allows your constrained prim to always face and look at the target prim you are constraining to.

Parent - Modifies the prim’s transformation as if the target was the parent hierarchically. Allows your constrained prim to match the translation, rotation and scale of the target prim and allows you to set whether you want that transformation to be absolute or relative to the constrained prims existing location in world space, using the maintain offset knob.

Transformation - Matches the location, rotation and scale of the prim to the those of the target. Acts similarly to the Parent constraint but is a quick way to constrain via translation or rotation.

Translation - Matches the location transformations of the prim to that of the target.

Rotation - Matches the rotation transformations of the prim to that of the target .

Scale - Matches the scale transformations of the prim to that of the target.

Orientation Axis (Look At only) constraint_orient_axis -Z Orientation axis of the effect. Applies to following types of constraint: LookAt. Also has controls for enabling and disabling the X Y Z axes rotation.
Strength (Look At only) constraint_strength 1 Strength of the effect. Applies to following types of constraint: LookAt.
Translate (Parent and Transformation only) constraint_apply_translate on Enables or disables the translation for the constraint for Parent and Transformation Types only.
Rotate (Parent and Transformation only) constraint_apply_rotate on Enables or disables the rotation for the constraint for Parent and Transformation Types only.
Scale (Parent and Transformation only) constraint_apply_scale off Enables or disables the Scale for the constraint for Parent and Transformation Types only.
Maintain Offset Frame constraint_maintain_offset off, 0 When enabled, the prim maintains the relative offset between itself and the target at the specified offset frame.
Maintain Offset Frame (Set to Current Frame) constraint_set_maintain_offset_frame N/A Set the frame to use to the current frame for maintain offset calculation.

Local Parent Xform

Parent Translate

local_parent_translate

0, 0, 0

Applies translation prior to the local transform allowing a parenting hierarchy to be kept separate from the local transform. The transform is applied in fixed SRT transform order and XYZ rotation order.

When loading xform prim data from a scene file, the prim's parent transform can be placed here.

Parent Rotate

local_parent_rotate

0, 0, 0

Applies rotation prior to the local transform allowing a parenting hierarchy to be kept separate from the local transform. The transform is applied in fixed SRT transform order and XYZ rotation order.

When loading xform prim data from a scene file, the prim's parent transform can be placed here.

Parent Scale

local_parent_scale

1, 1, 1

Applies scaling prior to the local transform allowing a parenting hierarchy to be kept separate from the local transform. The transform is applied in fixed SRT transform order and XYZ rotation order.

When loading xform prim data from a scene file, the prim's parent transform can be placed here.

Local Axis Xform
Local Xform Sync sync_local_xform on If enabled extract the prim’s local Xform. If the ‘Combine With Parent’ control is enabled the local and parent Xforms are combined.
Combine With Parent parent_combine_enable off If enabled the parent prim Xform is combined (concatened) with the local prim Xform and placed in the local-Xform TRS knobs.
When not enabled the parent prim Xform is extracted separately and placed in the local parent Xform TRS knobs, while the local primXform is extracted and placed in the local axis Xform TRS knobs.
Snap geosnap_operation N/A

Choose what a selection in the Viewer or pivot point is snapped to in the Viewer:

Geo to Set your geometry to a vertex selection within the scene.

Geo to Set your geometry to a vertex selection within the scene in a frame range.

Geo to Snaps your geometry by using a custom script.

Pivot Point to Set your pivot point to a vertex selection within the scene in a frame range.

Pivot Point to Set your geometry to a vertex selection within the scene in a frame range.

Pivot Point to Set your geometry to the selected prim’s bounding box within the scene. Click knob to select which part of the bounding box to snap to.

Pivot Point to Snaps your pivot point by using a custom script.

(Snap) T geosnap_translate on Sets the translation to the selection within the scene.
(Snap) R geosnap_rotate off Sets the rotation to the selection within the scene.
(Snap) S geosnap_scale off Sets the scale to the selection within the scene.

Transform Data

file_menu

N/A

Select to import or export a channel file:

Import chan file - import a channel file and transform the object according to the transformation data in the channel file. Channel files contain a set of Cartesian coordinates for every frame of animation in a given shot. You can create and export them using Nuke or 3D tracking software, such as 3D-Equalizer, Maya, or Boujou.

Export chan file - export the translation parameters that you’ve applied to the object as a channel file. This is a useful method of sharing setups between artists.

Transform Order

xform_order

SRT

Sets the operation order for scale (S), rotation (R), and translation (T). The possible operation combinations are SRT, STR, RST, RTS, TSR, TRS.

Rotation Order

rot_order

ZXY

Sets the order of rotation. The possible axial combinations are ZXY, XYZ, XZY, YXZ, YZX, ZXY, ZYX.

Translate

translate

0, 0, 0

Lets you translate the object along the x, y, and z axes. You can also adjust translate values by clicking and dragging the object in the 3D Viewer.

Rotate

rotate

0, 0, 0

Lets you rotate the object around the x, y, and z axes. You can adjust rotate values by holding down Ctrl/Cmd and dragging in the 3D Viewer.

Scale

scaling

1, 1, 1

Lets you scale the object on the x, y, and z axes.

Uniform Scale

uniform_scale

1

Lets you scale the object simultaneously on the x, y, and z axes.

Skew

skew

0, 0, 0

Lets you skew the object on the x, y, and z axes.

Pivot Translate

pivot_translate

0, 0, 0

When you make changes to a 3D object’s position, scaling, skewing, and rotation, these occur from the location of the object’s origin point or pivot. The pivot translate and rotate x, y, and z controls allow you to move and rotate the pivot point as required - you can even move it outside of the object. Subsequent transformations applied then occur relative to the new pivot point location and rotation.

You can hold down Ctrl/Cmd and drag the pivot point to a new location in the 3D Viewer.

Pivot Rotate

pivot_rotate

0, 0, 0

Local Matrix

Specify Matrix

useMatrix

N/A

Enable this control to specify matrix values for the object you’re transforming as an alternative to setting transform, scale, skew and pivot values above.

Matrix

matrix

N/A

The matrix displays values from the object’s transform, rotate, scale, skew, and pivot controls.

Check Specify Matrix and copy or drag-and-drop matrix values from another object to apply those values, for example, if you wanted to align objects in a scene.

World Matrix

World matrix

world_matrix

N/A

Displays the world or absolute xyz transform of the node in world coordinates.

Note:  Unlike the Local matrix, you can’t adjust the World matrix manually.

Import/Export Tab
Live Read read_from_scene_link on If enabled read values from the source prim attributes dynamically into the knobs. If disabled the knobs switch into normal/local mode. Note that in this dynamic mode the values are not baked into keyframes in the knobs hey are dynamically created as if they were an expression. This means that the node will always update to the latest prim state.
Source Prim source_prim_path N/A Specify the source prim's scene graph location to load the prim.

Import From File

file_source_enabled

off

If enabled an external scene file is used to retrieve prim attribute data, overriding the scene input connection which is ignored.

If a valid source prim path specified that prim’s attribute data will be ‘live’ pulled into the node’s parameters - not baked into knob curves.

A valid path to the input prim must be specified otherwise the node will produce an error.

File Path file N/A Path to external scene file, if scene input is not connected
Reload reload N/A Force-update the scene source data. Typically used when file contents have changed but Nuke is not aware of the change.

Rotations Euler Filter

euler_filter_enable

on

When enabled, check for possible Euler flips in the decomposed rotation curves and remove them.

The Euler filter can help to avoid discontinuity in rotations.

Output Prim Path

prim_path

none

Sets the scene graph path for the new camera prim, such as /Scene/Objects/Axis1.

If the output path is left blank, the node name is used with a preceding / (forward slash). For example, /Axis1.

Create Missing Parents create_missing_parents on When turned on, this will create the missing ancestor prims which don’t already exist in the path. When off, missing ancestors will be pure overs (i.e. overrides), which will cause the prim to not appear in the scene graph or render unless the parent prim ‘overs’ are turned into ‘concrete’ prims.
Create Missing Parents (Type) parent_prim_type Xform The type of prim to create for any ancestor prims in the path which don’t already exist.
Display Tab

Display

display

wireframe

Adjust the display characteristics of the 3D object. These settings don’t affect the render output of the scene; these are for display purposes only in the 3D Viewer.

off - hides the 3D geometry object.

wireframe - displays only the outlines of the object’s geometry.

solid - displays all geometry with a solid color.

solid + wireframe - displays the geometry as solid color with the object’s geometry outlines.

textured - displays only the surface texture.

textured + wireframe - displays the wireframe plus the surface texture.

Note:  The Viewer node 3D > display setting overrides this control.

Selectable selectable on Turn off to prevent picking with the mouse in the viewer.
Editable editable on Turn off to prevent changing values when manipulating in Viewer.
Fixed locator size locator_fixed_size off When checked, the locator will be drawn in a fixed size regardless of current camera/zoom settings.
Locator Fill Color locator_fill_color N/A The fill color used for the locator when the light color isn’t being used.
Set locator to Light Color locator_use_light_for_fill_color on Sets the locator color to the same color as the light itself.