# lsdtools.lighting reference
URL: https://lsd.tools/docs/sdk-lsdtools-lighting
Updated: 2026-09-09

SDK distribution **1.0.0**; API contract **1.0**; generator **1.0.0**.

Product source digest: `4ea39055732e8883c03ccfecf12af6ccebd2041a12ce1b843e4a769e200f5ef9`.

Generated from declared public exports and source syntax. Signatures and annotations are declaration spellings; decorators, factories and annotations are never executed. Class members below are declared members; base classes remain explicit. Source docstrings describe their owning implementation; they do not grant app permissions.

```text
Lazy public headless lighting contracts; importing this facade creates no UI.
```


## `lsdtools.lighting.BuildLighting`

Kind: class. Source: `services/runtime/src/lsd_runtime/lighting_steps.py:17`.

Source docstring:

```text
Build one optional lighting component from an authored per-object table.

Light rows remain in the loader's normal editable artifact. Environment is
an ordinary Configurable parameter; no second persisted light list exists.
```


Implementation alias: `lsd_runtime.lighting_steps.BuildLighting`.

Declared bases: `ShapeStep`.

### `lsdtools.lighting.BuildLighting.input_ports`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting_steps.py:23`.

```python
input_ports = ['lights']
```


### `lsdtools.lighting.BuildLighting.output_ports`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting_steps.py:24`.

```python
output_ports = ['lighting']
```


### `lsdtools.lighting.BuildLighting.cache_pin`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting_steps.py:25`.

```python
cache_pin = 'lsd-runtime-lighting-v1'
```


### `lsdtools.lighting.BuildLighting.param_group_order`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting_steps.py:26`.

```python
param_group_order = ['Lighting']
```


### `lsdtools.lighting.BuildLighting.environment`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting_steps.py:27`.

```python
environment = param(dict, default=None, label='Daylight environment', widget='lighting.environment', group='Lighting', validators=[_validate_environment], description='Supported daylight fields, or null to disable. No terrain assets or cycles.')
```


### `lsdtools.lighting.BuildLighting.run`

Kind: method. Source: `services/runtime/src/lsd_runtime/lighting_steps.py:31`.

```python
run(self, inputs) -> StepOutputs
```


```python
inputs: (unannotated)
self: (unannotated)
```


## `lsdtools.lighting.LightingDocument`

Kind: class. Source: `services/runtime/src/lsd_runtime/lighting.py:166`.

```python
LightingDocument(self)
```


Implementation alias: `lsd_runtime.lighting.LightingDocument`.

### `lsdtools.lighting.LightingDocument.lights`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:167`.

```python
lights: tuple[LightingPoint, ...]
```


### `lsdtools.lighting.LightingDocument.environment`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:168`.

```python
environment: Mapping | None
```


### `lsdtools.lighting.LightingDocument.digest`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:169`.

```python
digest: str
```


### `lsdtools.lighting.LightingDocument.__init__`

Kind: method. Source: `services/runtime/src/lsd_runtime/lighting.py:171`.

```python
__init__(self)
```


```python
self: (unannotated)
```


### `lsdtools.lighting.LightingDocument.from_dict`

Kind: method. Source: `services/runtime/src/lsd_runtime/lighting.py:175`.

```python
from_dict(cls, value)
```


```python
cls: (unannotated)
value: (unannotated)
```


### `lsdtools.lighting.LightingDocument.to_dict`

Kind: method. Source: `services/runtime/src/lsd_runtime/lighting.py:192`.

```python
to_dict(self)
```


```python
self: (unannotated)
```


### `lsdtools.lighting.LightingDocument.canonical_bytes`

Kind: method. Source: `services/runtime/src/lsd_runtime/lighting.py:197`.

```python
canonical_bytes(self)
```


```python
self: (unannotated)
```


### `lsdtools.lighting.LightingDocument.to_authoring_tables`

Kind: method. Source: `services/runtime/src/lsd_runtime/lighting.py:200`.

```python
to_authoring_tables(self)
```


```python
self: (unannotated)
```


Source docstring:

```text
Explicit detached table projection for semantic property source reads.
```


## `lsdtools.lighting.LightingError`

Kind: class. Source: `services/runtime/src/lsd_runtime/lighting.py:39`.

Source docstring:

```text
An authored lighting document or binding is invalid or unsupported.
```


Implementation alias: `lsd_runtime.lighting.LightingError`.

Declared bases: `ValueError`.

## `lsdtools.lighting.LightingPoint`

Kind: class. Source: `services/runtime/src/lsd_runtime/lighting.py:129`.

Implementation alias: `lsd_runtime.lighting.LightingPoint`.

### `lsdtools.lighting.LightingPoint.oid`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:130`.

```python
oid: str
```


### `lsdtools.lighting.LightingPoint.enabled`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:131`.

```python
enabled: bool
```


```python
enabled = True
```


### `lsdtools.lighting.LightingPoint.color`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:132`.

```python
color: tuple[float, float, float]
```


```python
color = (1.0, 1.0, 1.0)
```


### `lsdtools.lighting.LightingPoint.intensity`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:133`.

```python
intensity: float
```


```python
intensity = 1.0
```


### `lsdtools.lighting.LightingPoint.range`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:134`.

```python
range: float
```


```python
range = 10.0
```


### `lsdtools.lighting.LightingPoint.source_radius`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:135`.

```python
source_radius: float
```


```python
source_radius = 0.05
```


### `lsdtools.lighting.LightingPoint.casts_shadow`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:136`.

```python
casts_shadow: bool
```


```python
casts_shadow = True
```


### `lsdtools.lighting.LightingPoint.offset`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:137`.

```python
offset: tuple[float, float, float]
```


```python
offset = (0.0, 0.0, 0.0)
```


### `lsdtools.lighting.LightingPoint.from_dict`

Kind: method. Source: `services/runtime/src/lsd_runtime/lighting.py:154`.

```python
from_dict(cls, value)
```


```python
cls: (unannotated)
value: (unannotated)
```


### `lsdtools.lighting.LightingPoint.to_dict`

Kind: method. Source: `services/runtime/src/lsd_runtime/lighting.py:159`.

```python
to_dict(self)
```


```python
self: (unannotated)
```


## `lsdtools.lighting.LightingPropertyProvider`

Kind: class. Source: `services/runtime/src/lsd_runtime/timeline/lighting.py:11`.

```python
LightingPropertyProvider(self, context)
```


Implementation alias: `lsd_runtime.timeline.lighting.LightingPropertyProvider`.

### `lsdtools.lighting.LightingPropertyProvider.checkpoint_state_version`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/timeline/lighting.py:12`.

```python
checkpoint_state_version = 1
```


### `lsdtools.lighting.LightingPropertyProvider.__init__`

Kind: method. Source: `services/runtime/src/lsd_runtime/timeline/lighting.py:14`.

```python
__init__(self, context)
```


```python
context: (unannotated)
self: (unannotated)
```


### `lsdtools.lighting.LightingPropertyProvider.bind_property`

Kind: method. Source: `services/runtime/src/lsd_runtime/timeline/lighting.py:23`.

```python
bind_property(self, spec, target)
```


```python
self: (unannotated)
spec: (unannotated)
target: (unannotated)
```


### `lsdtools.lighting.LightingPropertyProvider.checkpoint_state`

Kind: method. Source: `services/runtime/src/lsd_runtime/timeline/lighting.py:53`.

```python
checkpoint_state(self)
```


```python
self: (unannotated)
```


### `lsdtools.lighting.LightingPropertyProvider.close`

Kind: method. Source: `services/runtime/src/lsd_runtime/timeline/lighting.py:58`.

```python
close(self)
```


```python
self: (unannotated)
```


### `lsdtools.lighting.LightingPropertyProvider.scene`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/timeline/lighting.py:18`.

```python
scene: (unannotated)
```


```python
scene = context
```


### `lsdtools.lighting.LightingPropertyProvider.owner`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/timeline/lighting.py:19`.

```python
owner: (unannotated)
```


```python
owner = getattr(context, 'lighting', None)
```


## `lsdtools.lighting.LightingSnapshot`

Kind: class. Source: `services/runtime/src/lsd_runtime/lighting.py:310`.

Source docstring:

```text
Borrowed slot data, valid until the owning reader next acquires or closes.
```


Implementation alias: `lsd_runtime.lighting.LightingSnapshot`.

### `lsdtools.lighting.LightingSnapshot.scene_id`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:312`.

```python
scene_id: str
```


### `lsdtools.lighting.LightingSnapshot.world_epoch`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:313`.

```python
world_epoch: int
```


### `lsdtools.lighting.LightingSnapshot.mapping_generation`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:314`.

```python
mapping_generation: int
```


### `lsdtools.lighting.LightingSnapshot.catalog_revision`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:315`.

```python
catalog_revision: str
```


### `lsdtools.lighting.LightingSnapshot.pose_revision`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:316`.

```python
pose_revision: int
```


### `lsdtools.lighting.LightingSnapshot.environment_revision`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:317`.

```python
environment_revision: str
```


### `lsdtools.lighting.LightingSnapshot.lights`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:318`.

```python
lights: tuple[LightingPoint, ...]
```


### `lsdtools.lighting.LightingSnapshot.positions`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:319`.

```python
positions: np.ndarray
```


### `lsdtools.lighting.LightingSnapshot.enabled`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:320`.

```python
enabled: np.ndarray
```


### `lsdtools.lighting.LightingSnapshot.environment`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:321`.

```python
environment: Mapping | None
```


### `lsdtools.lighting.LightingSnapshot.intensities`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:322`.

```python
intensities: np.ndarray
```


### `lsdtools.lighting.LightingSnapshot.value_revision`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:323`.

```python
value_revision: int
```


### `lsdtools.lighting.LightingSnapshot.object_rows`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:324`.

```python
object_rows: np.ndarray
```


## `lsdtools.lighting.PreparedLighting`

Kind: class. Source: `services/runtime/src/lsd_runtime/lighting.py:268`.

Implementation alias: `lsd_runtime.lighting.PreparedLighting`.

### `lsdtools.lighting.PreparedLighting.scene_id`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:269`.

```python
scene_id: str
```


### `lsdtools.lighting.PreparedLighting.document`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:270`.

```python
document: LightingDocument
```


### `lsdtools.lighting.PreparedLighting.object_rows`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:271`.

```python
object_rows: np.ndarray
```


### `lsdtools.lighting.PreparedLighting.object_eids`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:272`.

```python
object_eids: tuple[int, ...]
```


### `lsdtools.lighting.PreparedLighting.object_count`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:273`.

```python
object_count: int
```


### `lsdtools.lighting.PreparedLighting.catalog_revision`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:274`.

```python
catalog_revision: str
```


### `lsdtools.lighting.PreparedLighting.environment_revision`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/lighting.py:275`.

```python
environment_revision: str
```


### `lsdtools.lighting.PreparedLighting.lights`

Kind: method. Source: `services/runtime/src/lsd_runtime/lighting.py:278`.

```python
lights(self)
```


```python
self: (unannotated)
```


### `lsdtools.lighting.PreparedLighting.environment`

Kind: method. Source: `services/runtime/src/lsd_runtime/lighting.py:282`.

```python
environment(self)
```


```python
self: (unannotated)
```


## `lsdtools.lighting.build_lighting_scene`

Kind: function. Source: `services/runtime/src/lsd_runtime/lighting_steps.py:36`.

```python
build_lighting_scene(name, *, objects, lights, cameras='', actors='', environment=None, scene_id='', up_axis='z', step_prefix='', entity_id='')
```


```python
actors: (unannotated)
cameras: (unannotated)
entity_id: (unannotated)
environment: (unannotated)
lights: (unannotated)
name: (unannotated)
objects: (unannotated)
scene_id: (unannotated)
step_prefix: (unannotated)
up_axis: (unannotated)
```


Source docstring:

```text
Compose publication and editing over the same authored light artifact.

The package contributes a template through this public product composition
seam. It never imports private builders or duplicates the light table.
```


Implementation alias: `lsd_runtime.lighting_steps.build_lighting_scene`.

## `lsdtools.lighting.declares_lighting_scene`

Kind: function. Source: `sdk/src/lsdtools/lighting.py:9`.

```python
declares_lighting_scene(entity)
```


```python
entity: (unannotated)
```


Source docstring:

```text
Whether one entity declares the supported runtime scene authoring seam.
```


## `lsdtools.lighting.lighting_document_from_lights`

Kind: function. Source: `services/runtime/src/lsd_runtime/lighting.py:205`.

```python
lighting_document_from_lights(table: pa.Table, *, environment=None) -> LightingDocument
```


```python
environment: (unannotated)
table: pa.Table
```


Source docstring:

```text
Validate the authored per-oid scalar table once, without loading files.
```


Implementation alias: `lsd_runtime.lighting.lighting_document_from_lights`.

## `lsdtools.lighting.lighting_document_from_table`

Kind: function. Source: `services/runtime/src/lsd_runtime/lighting.py:252`.

```python
lighting_document_from_table(table: pa.Table) -> LightingDocument
```


```python
table: pa.Table
```


Implementation alias: `lsd_runtime.lighting.lighting_document_from_table`.

## `lsdtools.lighting.lighting_document_table`

Kind: function. Source: `services/runtime/src/lsd_runtime/lighting.py:236`.

```python
lighting_document_table(document: LightingDocument) -> pa.Table
```


```python
document: LightingDocument
```


Implementation alias: `lsd_runtime.lighting.lighting_document_table`.

## `lsdtools.lighting.lighting_lights_table`

Kind: function. Source: `services/runtime/src/lsd_runtime/lighting.py:222`.

```python
lighting_lights_table(document: LightingDocument) -> pa.Table
```


```python
document: LightingDocument
```


Source docstring:

```text
Return scalar authoring columns; the caller owns persistence and edits.
```


Implementation alias: `lsd_runtime.lighting.lighting_lights_table`.

## `lsdtools.lighting.lighting_snapshot`

Kind: function. Source: `services/runtime/src/lsd_runtime/lighting.py:440`.

```python
lighting_snapshot(prepared: PreparedLighting, *, positions=None, orientations=None, enabled=None, bundle=None, world_epoch=0, mapping_generation=0) -> LightingSnapshot
```


```python
bundle: (unannotated)
enabled: (unannotated)
mapping_generation: (unannotated)
orientations: (unannotated)
positions: (unannotated)
prepared: PreparedLighting
world_epoch: (unannotated)
```


Source docstring:

```text
Prepare one owned static/inspection snapshot outside the recurring frame path.

Supply either a matching scene bundle or all three numeric pose columns. The
returned immutable references own their storage independently of a driver.
```


Implementation alias: `lsd_runtime.lighting.lighting_snapshot`.

## `lsdtools.lighting.open_scene_lighting_editor`

Kind: function. Source: `sdk/src/lsdtools/lighting.py:25`.

```python
open_scene_lighting_editor(host, *, entity, source_view_id=None, context=None)
```


```python
context: (unannotated)
entity: (unannotated)
host: (unannotated)
source_view_id: (unannotated)
```


Source docstring:

```text
Navigate through the host's admitted actions and preserve the invoking preview.
```


## `lsdtools.lighting.prepare_lighting`

Kind: function. Source: `services/runtime/src/lsd_runtime/lighting.py:286`.

```python
prepare_lighting(document, bundle) -> PreparedLighting
```


```python
bundle: (unannotated)
document: (unannotated)
```


Source docstring:

```text
Resolve stable scene/object identities once; no system or view is created.
```


Implementation alias: `lsd_runtime.lighting.prepare_lighting`.

## `lsdtools.lighting.scene_lighting_session`

Kind: function. Source: `sdk/src/lsdtools/lighting.py:17`.

```python
scene_lighting_session(host, *, entity, view_id)
```


```python
entity: (unannotated)
host: (unannotated)
view_id: (unannotated)
```


Source docstring:

```text
Create one host-scoped editor handle; no renderer or Desktop crosses the SDK.
```