PortalLight
Attribute Reference
Map attributes
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.
Properties attributes
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.
height
Float
default: 1.0
The height of the rectangle, i.e. the size measured in the light's local y-direction.
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.
light
Light
default: None
The light on which to use the portal.
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: False
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.
spread
Float
default: 1.0
The directionality of light emission. 1 is completely diffuse hemisphere. 0 is parallel to normal of light.
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.
width
Float
default: 1.0
The width of the rectangle, i.e. the size measured in the light's local x-direction.
Visibility Flags attributes
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).
General attributes
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.
sidedness
Int enum
0 = “regular” (default)
1 = “reverse”
2 = “2-sided”
When set to 0 (regular), light is emitted from the front-facing surface of the disk. When set to 1 (reverse), light is emitted from the back-facing surface of the disk. When set to 2 (2-sided), light is emitted from both surfaces of the disk.