Lights#

Lights are declared on a Nyx camera sensor via the lights field of NyxCameraOptions. At scene.build(), the plugin collects the lights from every Nyx sensor in the scene, converts each one to a LightAsset (kinds enumerated by ELightType), and writes the union into the shared Nyx scene description.

This page describes the supported light types, their parameters, the coordinate convention, and the runtime constraints that apply once the scene is built.

Declaring lights#

A light is a Python dictionary with a required type key. The dictionary is passed to the lights field of NyxCameraOptions as a list:

SPOT = {
    "type":      "spot",
    "pos":       (2.0, -2.0, 3.0),
    "dir":       (0.0, 0.707, -0.707),
    "color":     (0.8, 0.4, 0.4),
    "intensity": 50.0,
    "range":     10.0,
}

POINT = {
    "type":      "point",
    "pos":       (0.0, 1.0, 3.0),
    "color":     (0.4, 0.8, 0.4),
    "intensity": 50.0,
    "range":     10.0,
}

cam = scene.add_sensor(NyxCameraOptions(
    res=(512, 512),
    pos=(0, 0, 10),
    lookat=(0, 0, 0),
    lights=[SPOT, POINT],
))

Lights declared on different Nyx sensors in the same scene are merged. Two cameras cannot see different lighting setups; they share one scene.

Supported light types#

Type

type value

Required

Optional

Point

"point"

pos

range, color, intensity, shadow

Directional

"directional"

dir

color, intensity, shadow

Spot

"spot"

pos, dir

inner_angle, outer_angle, range, color, intensity, shadow

Note

Ambient light is not supported. Use an environment map for image-based lighting instead (see Environment maps).

Note

Area lights are not exposed by the plugin. The Nyx engine supports rectangle / sphere / tube / disc emitters internally (see EAreaShape), but they are not surfaced through NyxCameraOptions.

Common properties#

These keys are accepted by every light type.

Key

Type

Default

Description

color

(r, g, b)

(1, 1, 1)

Linear RGB in [0, 1].

intensity

float

1.0

Light intensity in the unit set by the light type (see Units).

Type-specific properties#

Point light#

A point light emits uniformly in every direction from a position.

Key

Type

Default

Description

pos

(x, y, z)

(0, 0, 5)

World position in Genesis Z-up coordinates.

range

float

100.0

Effective falloff distance.

Directional light#

A directional light emits along a direction vector. Position is irrelevant — the light is treated as infinitely far away.

Key

Type

Default

Description

dir

(x, y, z)

(0, 0, -1)

Light direction in Genesis Z-up coordinates.

Spot light#

A spot light emits from a position in a cone defined by two cutoff angles.

Key

Type

Default

Description

pos

(x, y, z)

(0, 0, 5)

World position in Genesis Z-up coordinates.

dir

(x, y, z)

(0, 0, -1)

Cone axis in Genesis Z-up coordinates.

inner_angle

float (degrees)

15.0

Full intensity is delivered inside this half-angle.

outer_angle

float (degrees)

30.0

Falloff reaches zero at this half-angle.

range

float

100.0

Effective falloff distance.

Units#

Light intensity is expressed in photometric units — quantities weighted by the human eye’s spectral response, in contrast with radiometric (energy-based) units. The plugin fixes one photometric unit per light type to match physical convention. The full Nyx unit enum (ELightUnit: Candela / Nit / EV100) is not currently surfaced through NyxCameraOptions.

Plugin defaults#

Light type

intensity unit

Quantity

Point

Lumen (lm)

Luminous power

Spot

Lumen (lm)

Luminous power

Directional

Lux (lx)

Illuminance

Photometric reference#

Quantity

Photometric term

Unit

Power

Luminous power / luminous flux (\(\Phi_v\))

Lumen (lm)

Power per solid angle

Luminous intensity (\(I_v\))

Candela (cd) — equivalent to lm/sr

Power per area

Illuminance / luminous exitance (\(E_v\), \(M_v\))

Lux (lx) — equivalent to lm/m²

Power per area per solid angle

Luminance (\(L_v\))

Nit (nt) — equivalent to cd/m² or lm/(m²·sr)

Energy

Luminous energy (\(Q_v\))

Lumen-second (lm·s)

Conventions by light kind#

Light kind

Typical unit

Rationale

Punctual (point, spot)

Luminous power (lm)

A real bulb is rated by total light emitted in all directions.

Photometric (IES profile)

Luminous intensity (cd)

A photometric profile measures intensity per direction.

Sun / directional

Illuminance (lx)

A directional source has no finite total power; lux describes the light landing on a surface perpendicular to the rays.

Sky / image-based

Luminance (cd/m²)

Captured environment maps are calibrated per solid angle.

Area / emissive surface

Luminance (cd/m²) or EV

Matches how displays and emissive textures are specified.

The last two rows are included for reference — the plugin does not currently surface area lights or photometric (IES) profiles, so luminance and per-direction candela values are not reachable through NyxCameraOptions.

Coordinate convention#

All positions and directions are specified in Genesis Z-up world coordinates. The plugin converts them to Nyx Y-up at build time. No manual axis swap is required.

Lifecycle and constraints#

Warning

Lights are baked into the scene at scene.build() and cannot be modified at runtime. Mutating the lights field of NyxCameraOptions after build has no effect on rendered output. To change lighting, rebuild the scene.

Note

Genesis VisOptions.lights (DirectionalLight, PointLight, AmbientLight) is ignored by the Nyx plugin. Configure lights through NyxCameraOptions instead.

Note

If a scene contains no lights and no environment maps, the plugin emits a warning at build time and the scene is lit solely by Nyx’s default mid-grey HDRI sky (RGB ≈ (0.5, 0.5, 0.5)). This is rarely what you want; add at least one light, an HDRI, or a solid-colour HDRI with a chosen tint (use black to suppress the default sky entirely).

See also#