Environment Package

Tools for attaching a baked scene environment to a Luxar store. The environment lights meshes authored with material="physical" and is stored as a root-level sidecar rather than as scene geometry.

Baked scene environments (luxar env bake / luxar env attach).

The scene environment lights material="physical" meshes (docs/guides/specs/MESH_PHYSICAL_MATERIALS_SPEC.md §3.3). A live viewer can capture it from the scene itself; this package moves that cost off the viewer for a published scene by storing the six captured cube faces in the store as a root-level environment/ sidecar group. luxar.environment.container defines the blob the viewer hands back, luxar.environment.attach writes it into a store, and the luxar env bake CLI drives the headless capture end to end.

class luxar.environment.AttachReport(store: Path, status: str, array_name: str, digest: str, scene_content_hash: str, resolution: int, removed: List[str] = <factory>)

Bases: object

What attach_environment() did.

store: Path

status: str

attached (first map), replaced (a different map was there), unchanged (the same map was already attached; nothing written).

array_name: str

digest: str

scene_content_hash: str

resolution: int

removed: List[str]

__init__(store: Path, status: str, array_name: str, digest: str, scene_content_hash: str, resolution: int, removed: List[str] = <factory>) → None

luxar.environment.attach_environment(store: str | Path, faces: str | Path | bytes, *, force: bool = False) → AttachReport

Attach the container at faces (a path or its bytes) to store.

Refuses a non-scene store, a malformed container (see luxar.environment.container), and — unless force — a map whose scene_content_hash is not the store’s current root content_hash: the viewer would ignore such a map as stale anyway, so writing it would only look like success.

luxar.environment.pack(header: Dict[str, Any], faces: ndarray) → bytes

Serialize header + faces into one container blob.

faces must be uint16 of shape (6, H, W, 4) with H == W == header["resolution"]; the header must carry REQUIRED_HEADER_KEYS. Validated up front so a malformed blob is never produced.

luxar.environment.unpack(data: bytes) → Tuple[Dict[str, Any], ndarray]

Parse a container blob into (header, faces).

Raises ValueError naming the first thing wrong: magic, header length, header JSON, a missing required key, or a sample payload whose length does not match 6 * resolution² * 4 halves.

See Also

• Luxar CLI Reference — the luxar env bake and luxar env attach commands

• Mesh Package — the geometry type that consumes scene environments