simvx.core.procedural_sky

Preetham analytic sky: closed-form daytime sky radiance for a dynamic, procedural environment cubemap (design D12).

Pure NumPy, no coefficient tables and no GPU: the Perez distribution coefficients and the zenith luminance/chromaticity are the small linear / cubic closed forms from Preetham et al. 1999, evaluated per texel. Both renderer backends synthesize the same six float32 RGBA cube faces from this one module (desktop feeds them to Engine.load_cubemap(faces=...) and thus the existing skybox + IBL path; the web twin uploads them to its cubemap), so a sky_mode="procedural" sky and its IBL ambient match across backends.

The faces are returned in Vulkan cube order [+X, -X, +Y, -Y, +Z, -Z] to match :func:simvx.graphics...cubemap_loader.gradient_cubemap_faces.

Module Contents

Functions

sky_cache_key

Quantised identity for a synthesized sky.

preetham_cubemap_faces

Synthesize six Preetham sky cube faces.

Data

__all__

API

simvx.core.procedural_sky.__all__

[‘preetham_cubemap_faces’, ‘sky_cache_key’]

simvx.core.procedural_sky.sky_cache_key(sun_direction: tuple[float, float, float], turbidity: float, ground_albedo: tuple[float, float, float], size: int) → tuple[source]

Quantised identity for a synthesized sky.

Quantises the sun direction to ~1.5 degrees and the scalar params to a coarse grid so a slowly-sweeping sun (the day-night example) re-bakes the cubemap + IBL only in discrete steps rather than every frame. A static sky hashes to one key and is synthesized exactly once (zero re-cost).

simvx.core.procedural_sky.preetham_cubemap_faces(sun_direction: tuple[float, float, float], turbidity: float = 2.5, ground_albedo: tuple[float, float, float] = (0.15, 0.15, 0.16), size: int = 64, exposure: float = 0.18) → list[numpy.ndarray][source]

Synthesize six Preetham sky cube faces.

Args: sun_direction: unit(-ish) vector pointing TOWARD the sun in world space (i.e. the negation of a DirectionalLight3D travel direction). turbidity: atmospheric haze, ~2 (clear) .. ~10 (hazy). Clamped to [1.7, 10] where the analytic model stays well-behaved. ground_albedo: RGB reflectance shading genuinely-downward rays as a flat ground bounce (Preetham models only the sky dome). size: per-face resolution (64-128). exposure: master linear scale applied to the analytic radiance before it is written into the HDR cube faces.

Returns: Six (size, size, 4) float32 RGBA arrays in Vulkan face order, non-negative linear radiance (HDR: values may exceed 1 near the sun).