SpotLight

aspect_ratio

Float
default: 1.0

The aspect ratio of the lens - its local y dimension divided by its local x dimension. Values other than 1.0 will give the lens a non-circular elliptical shape.

focal_plane_distance

Float
default: 10000000000.0

The distance from the SpotLight's position, measured in the direction the light is pointing, at which the projected image will be in focus.

inner_cone_angle

Float
default: 30.0

The apex angle of the bright inner cone of the light emitted by the SpotLight. Full illumination takes place inside this region. This is a full angle, measured from one side to the other. There is a falloff function applied between the outer and inner cones - see the angle_falloff_type attribute.

lens_radius

Float
default: 1.0

The radius of the SpotLight's lens (when the aspect ratio is 1.0, so that the lens is circular).

outer_cone_angle

Float
default: 60.0

The apex angle of the bounding cone of the light emitted by the SpotLight. No illumination takes placeoutside this angle. This is a full angle, measured from one side to the other. There is a falloff function applied between the outer and inner cones - see the angle_falloff_type attribute.

angle_falloff_type

Int enum
  0 = “off”
  1 = “linear”
  2 = “ease in”
  3 = “ease out”
  4 = “ease in/out” (default)

The falloff function applied between the outer and inner cones. To calculate this, the angle from the cone's axis to the the point being illuminated is measured as seen from the SpotLight's position. This angle is converted into a fractional value representing the fraction from the outer cone angle to the inner cone angle, clamped to the range [0,1]. The resulting value is then fed into one of the following user-selectable functions to determine the final 0-1 scaling value to be applied to thelight's radiance:
0 (off) - no fallof, a step function at the outer cone boundary is applied
1 (linear) - a linear ramp, i.e. the fractional parameter is applied as-is
2 (ease in) - a quadratic ramp with zero gradient at the start point (outer cone)
3 (ease out) - a quadratic ramp with zero gradient at the end point (inner cone)
4 (ease in/out) - a cubic ramp with zero gradient at both ends (outer and inner cone)

black_level

Float
default: 0.001

The radiance used for rendering the SpotLight lens as seen through the camera via a primary ray, when the true computed radiance would otherwise be black. This is simply a convenience feature to make the SpotLight lens visible in the camera view.

contrast

Rgb
default: [ 1, 1, 1 ]

Per-channel contrast used in color-correcting the light's texture, if one is present. The operation mimics Nuke's ColorCorrect node's contrast function:
For input > 0, output = 0.18 * pow(inputCompnent/0.18, contrast).
For input <= 0, output = 0.18 * input * pow(1/0.18, contrast).

gain

Rgb
default: [ 1, 1, 1 ]

Per-channel gain used in tandem with a per-channel offset for color-correcting the light's texture, if one is present. This is achieved by applying the following formula for each channel:
output = input * gain + offset

gamma

Rgb
default: [ 1, 1, 1 ]

Per-channel gamma used in color-correcting the light's texture, if one is present. This is achieved by applying the following formula for each channel:
For input > 0, output = pow(input, gamma)
For input <= 0, output = input

offset

Rgb
default: [ 0, 0, 0 ]

Per-channel offset used in tandem with a per-channel gain for color-correcting the light's texture, if one is present. This is achieved by applying the following formula for each channel:
output = input * gain + offset

saturation

Rgb
default: [ 1, 1, 1 ]

Per-channel saturation used in color-correcting the light's texture, if one is present. This is achieved by applying the following formula for each channel:
output = lerp(luminance(inputRGB), input, saturation).

temperature

Vec3f
default: [ 0, 0, 0 ]

Color temperature using Nuke-style T/M/I settings (T = temperature, M = magenta/green, I = intensity). This is achieved as follows:
The 3-channel temperature is interpreted as the vector (T,M,I). The followiong scale values are then applied to the RGB components:
outputR = inputR * (pow(2,I) + M/3 - T/2)
outputG = inputG * (pow(2,I) - 2*M/3
outputB = inputB * (pow(2,I) + M/3 + T/2)

texture

String filename
default:

File name of the texture applied to the light. If set to the empty string, no texture is applied. Any file format supported by OpenImageIO can be used. The texture is used in 2 ways - for looking up the texture value at the intersection point when a ray hits the light, and for building a lookup-table-based auxilliary data structure used for distributing light samples over the texture.

texture_border_color

Rgb
default: [ 1, 1, 1 ]

RGB value used when a texture lookup occurs outside the texture.

texture_coverage

Vec2f
default: [ 1, 1 ]

Texture scales in the u and v-directions.

texture_mirror_u

Bool
default: False

Whether to mirror the texture in the u-direction. If set to false, the texture is repeated in the u-direction.

texture_mirror_v

Bool
default: False

Whether to mirror the texture in the v-direction. If set to false, the texture is repeated in the v-direction.

texture_reps_u

Float
default: 1.0

Number of times texture repeats in u over the scaled texture space.

texture_reps_v

Float
default: 1.0

Number of times texture repeats in v over the scaled texture space.

texture_rotation

Float
default: 0.0

Clockwise rotation angle in degrees.

texture_translation

Vec2f
default: [ 0, 0 ]

Translation of the texture in (u,v)-space, in units of the texture size. For example, a translation of (0.25, 0.5) will translate the texture one-quarter of its width in the u-direction and one-half of its height in the v-direction.

apply_scene_scale

Bool
default: True

Whether to apply scene scale variable when normalized.

clear_radius

Float
default: 0.0

Shadows less than this distance from the light are ignored. Setting this value to 0.0 or less effectively disables this feature.

clear_radius_falloff_distance

Float
default: 0.0

Distance over which the shadows fall off. Shadows are fully visible at a distance clear_radius + clear_radius_falloff_distance from the light, and fully invisble at a distance clear_radius from the light.

clear_radius_interpolation_type

Int enum
  0 = “linear” (default)
  1 = “exponential_up”
  2 = “exponential_down”
  3 = “smoothstep”

Interpolation type to use for the clear radius shadow falloff.

color

Rgb
default: [ 1, 1, 1 ]

The light's RGB values.
These are combined multiplicatively with the intensity and other attributes in determining the light's 3-channel radiance.

exposure

Float
default: 0.0

The light's exposure value.
This value provides an alternative to the intensity value as a mechanism for controlling the light's overall brightness, and is inspired by the corresponding photographic term but is generalised to apply independently to each light. To calculate its effect, pow(2, exposure) is combined multiplicatively with the color and other attributes in determining the light's 3-channel radiance.

intensity

Float
default: 1.0

The light's intensity.
This is combined multiplicatively with the color and other attributes in determining the light's 3-channel radiance.

label

String
default:

Label used in light aov expressions.

max_shadow_distance

Float
default: 0.0

The distance from the light beyond which a light-receiving surface will no longer receive shadows cast from that light.
Note that the distance is thresholded for each occlusion ray cast for this light, it is possible for a receiving point to lie at an intermediate distance such that some parts of the light are closer than the threshold distance and other parts beyond it, in which case the point will appearto be in partial shadow.

mb

Bool
default: False

Whether motion-blur is active for this light. When set to true, the scene's illumination will correctly account for any blur() applied to the light's transformation matrix.

min_shadow_distance

Float
default: 0.0

The distance from the light before which a light-receiving surface will no longer receive shadows cast from that light.
Note that the distance is thresholded for each occlusion ray cast for this light, it is possible for a receiving point to lie at an intermediate distance such that some parts of the light are closer than the threshold distance and other parts beyond it, in which case the point will appearto be in partial shadow.

normalized

Bool
default: True

When set to true, the size of the light can be changed without altering the amount of total energy cast into the scene. This is achieved via scaling the light's radiance by the reciprocal of its surface area. When set to false, the radiance is used as-is, regardless of surface area.

on

Bool
default: True

Whether the light is switched on.

presence_shadows

Int enum
  0 = “force off”
  1 = “force on”
  2 = “use default” (default)

Switch this attribute on for shadows cast from this light to correctly respect presence values. When off, surfaces with a material with presence less than 1.0 will cast opaque shadows from this light. This is an optimization - when the attribute is off, occlusion rays (fast) are used for testing for shadows. When it is on, regular rays (slower) are used, and the material's presence is evaluated to determine how much shadowing should occur. When set to "use default" it reads from the value of SceneVariable enable_presence_shadows.

ray_termination

Bool
default: False

Whether the light is used for ray termination color. Ray termination color is used for filling in falsely dark areas where ray paths have been terminated too early by the depth controls. Such a ray path immediately exits to any ray termination light(s) present in the light set being applied to the lobe, ignoring occlusion by scene geometry. Any light can either be a regular light or a ray termination light (but not both). Thus they can be freely assigned to light sets, which provides a mechanism for applying specific ray termination lights to specific materials, parts or objects. Ray termination color is only applied to non-hair transmission lobes.

texture_filter

Int enum
  0 = “nearest neighbor” (default)
  1 = “bilinear”
  2 = “nearest neighbor with nearest mip”
  3 = “bilinear with nearest mip”

The filtering mode to apply to the texture. Nearest neighbor is the cheapest filtering mode but produces a blocky result. Switch linear filtering on for a smoother result. Additionally, mip-mapping can be switched on with either nearest neighbor or linear filtering.

visible_in_camera

Int enum
  0 = “force off”
  1 = “force on”
  2 = “use default” (default)

Whether the light is directly visible in the scene's active camera. When set to "use default" it reads from the value of SceneVariable lights_visible_in_camera.

visible_diffuse_reflection

Bool
default: True

Whether the light is visible in diffuse reflection.

visible_diffuse_transmission

Bool
default: True

Whether the light is visible in diffuse transmission.

visible_glossy_reflection

Bool
default: True

Whether the light is visible in glossy reflection.

visible_glossy_transmission

Bool
default: True

Whether the light is visible in glossy transmission (refraction).

visible_mirror_reflection

Bool
default: True

Whether the light is visible in miror reflection.

visible_mirror_transmission

Bool
default: True

Whether the light is visible in miror transmission (refraction).

light_filters

SceneObject Vector
default: {}

Vector of LightFilters associated with the light.

node_xform

Mat4d blurrable
default: [ [ 1, 0, 0, 0 ], [ 0, 1, 0, 0 ], [ 0, 0, 1, 0 ], [ 0, 0, 0, 1 ] ]

The 4x4 matrix describing the transformation from local space to world space.