LightUnits

from acron.shading import LightUnits

class LightUnits

Bases:

The photometric convention of the PBR shader, and helpers to follow it.

A light’s intensity (Light::set_intensity) is in the unit of its kind, and its colour is a linear Rec. 709 tint; the shader receives their product:

DirectionalLight illuminance at normal incidence, lux (lm/m^2) PointLight luminous intensity, candela (lm/sr) Spotlight luminous intensity on the axis, candela AmbientLight uniform sky luminance, nits (cd/m^2); lights through the diffuse lobe only

The photometric value of a light is the luminance (0.2126 R + 0.7152 G + 0.0722 B) of its colour times its intensity, so a tint of luminance 1 (as these helpers set) makes it the intensity itself. Luminous power converts to intensity as Frostbite and Filament do: I = phi / 4 pi for a point light, I = phi / pi for a spotlight (so that narrowing the cone does not brighten it).

Point lights and spotlights fall off as the inverse square of the distance, windowed to reach zero at their range (Karis 2013): E = I / max(d^2, 1e-4) * saturate(1 - (d / range)^4)^2 The range is the light’s max_distance, or, if that is infinite, get_auto_range(): the distance where the light drops to shading-light-cutoff lux.

Inheritance diagram

digraph inheritance4434017960 { bgcolor=transparent; rankdir=BT; size="8.0, 12.0"; "DTOOL_SUPER_BASE" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style=""]; "LightUnits" [URL="acron.shading.LightUnits.html#acron.shading.LightUnits",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="",target="_top",tooltip="/**"]; "DTOOL_SUPER_BASE" -> "LightUnits" [arrowsize=0.75,style=""]; }

__init__()

static get_auto_range()

The range a light of candela gets when it has no max_distance: the distance at which it gives cutoff_lux (by default shading-light-cutoff), sqrt(I / cutoff). The shader computes the same.

static get_illuminance()

A directional light’s illuminance in lux (its colour’s luminance times its intensity).

static get_luminance()

An ambient light’s luminance in nits.

static get_luminous_intensity()

A point light’s luminous intensity in candela.

A spotlight’s luminous intensity on the axis, in candela.

static luminance()

The Rec. 709 luminance of a linear colour.

static point_lumens_to_candela()

lumens / 4 pi.

static scale_to_luminance()

The colour with the chromaticity of color and the given luminance. A black colour counts as white.

static set_illuminance()

Makes a directional light give lux lux at normal incidence: its intensity becomes lux and its colour the tint color, scaled to a luminance of 1.

static set_luminance()

Makes an ambient light a uniform sky of nits luminance.

static set_luminous_intensity()

Makes a point light’s luminous intensity candela: its intensity becomes candela and its colour the tint color, scaled to a luminance of 1.

Makes a spotlight’s luminous intensity on the axis candela, as for a point light.

static set_luminous_power()

Sets a point light from its luminous power: I = lumens / 4 pi.

Sets a spotlight from its luminous power: I = lumens / pi, whatever the cone (Frostbite’s convention: the cone shapes the light, it does not focus it).

static spot_cone()

The cone the shader applies to a spotlight angle degrees off its axis, for an inner cone of inner_angle degrees (Spotlight’s inner_cone_angle) and an outer one of outer_angle (half its lens’s field of view): saturate(cos * scale + offset)^2, with scale = 1 / max(cos inner - cos outer, 1e-4) and offset = -cos outer * scale (Filament’s form of KHR_lights_punctual’s smooth edge).

static spot_lumens_to_candela()

lumens / pi.

static windowed_falloff()

The falloff the shader applies to a point light or spotlight at distance metres, for a range of range metres: saturate(1 - (d/r)^4)^2 / max(d^2, 1e-4). Multiply by the intensity in candela for the illuminance in lux.