Environment maps#

Environment maps provide image-based lighting (IBL) using an HDR image as both the visible background and the source of indirect illumination. They drive reflections, ambient colour, and global indirect light without requiring explicit light sources.

Environment maps are declared on a Nyx camera sensor via the env_maps field of NyxCameraOptions. The plugin collects them from every Nyx sensor at scene.build() and writes the union into the shared scene description.

Declaring an environment map#

An environment map is built by constructing an EnvironmentMapAsset, setting its texture and parameters, and passing it through env_maps:

import math
import gs_nyx.nyx_py_sdk as nps

env_map            = nps.EnvironmentMapAsset()
env_map.texture    = "path/to/envmap.hdr"
env_map.layout     = nps.EEnvMapLayout.LongLat
env_map.rotation   = math.radians(30)
env_map.multiplier = 1.5

cam = scene.add_sensor(NyxCameraOptions(
    res=(1280, 720),
    pos=(2.0, -1.5, 2.0),
    lookat=(0.0, 0.0, 0.9),
    env_maps=(env_map,),
))

env_maps is a tuple. Multi-environment scenes use the tuple index to assign a different map to each Genesis env (see Per-environment selection).

Properties#

Property	Type	Description
`texture`	`str`	Path to an `.hdr` or `.exr` file. Leave unset for a solid-colour HDRI driven entirely by `tint`.
`layout`	`EEnvMapLayout`	Image layout. `LongLat` is the standard equirectangular HDRI projection.
`rotation`	`float`	Yaw rotation around the up axis, in radians.
`multiplier`	`float`	Brightness multiplier applied to the HDRI values.
`tint`	`float3` `(r, g, b)`	Colour tint multiplied into the HDRI. When `texture` is unset, this is the HDRI: a constant RGB radiance applied across the whole sphere.

Supported file formats#

Extension	Status
`.hdr`	Supported (Radiance RGBE)
`.exr`	Supported (OpenEXR)

Solid-colour HDRI (default sky and how to override it)#

A Nyx scene with no environment map declared is not rendered against a black background. The renderer falls back to a flat mid-grey HDRI sky (RGB ≈ (0.5, 0.5, 0.5)) so unlit surfaces still receive ambient illumination and untouched scenes look reasonable out of the box. That fallback is convenient, but it is itself a light source: it contributes diffuse ambient and reflections to every PBR surface in the scene.

To replace the default sky with a different constant colour, attach an EnvironmentMapAsset with no texture and set tint to the colour you want. The renderer treats a texture-less asset as a uniform-radiance sky:

import gs_nyx.nyx_py_sdk as nps

# Pitch-black sky: kills the default grey ambient entirely, leaving the
# scene lit purely by the explicit `lights` on the camera.
black_sky      = nps.EnvironmentMapAsset()
black_sky.tint = nps.float3(0.0, 0.0, 0.0)

cam = scene.add_sensor(NyxCameraOptions(
    ...,
    env_maps = (black_sky,),
))

Use this whenever you need a clean, controllable lighting setup, for example when isolating the contribution of a single light, comparing materials under identical illumination, or generating synthetic data where ambient light would confound the labels. multiplier still applies, so a warm overcast wash can be expressed as tint = nps.float3(0.6, 0.55, 0.5) with multiplier tuned to taste.

Per-environment selection#

In a batched scene (scene.build(n_envs=N)), the env-map tuple is indexed by Genesis environment. Environment i renders with env_maps[i].

env_map_a = nps.EnvironmentMapAsset()
env_map_a.texture = "studio.hdr"
env_map_a.tint = nps.float3(0.6, 0.2, 0.1)

env_map_b = nps.EnvironmentMapAsset()
env_map_b.texture = "outdoor.exr"
env_map_b.tint = nps.float3(0.3, 0.8, 0.2)
env_map_b.multiplier = 0.8

cam = scene.add_sensor(NyxCameraOptions(
    ...,
    env_maps=(env_map_a, env_map_b),
))

scene.build(n_envs=2)

The plugin calls set_env_map(env_index) on the renderer inside the per-environment loop of the render pass (see Sensor lifecycle). This is the one piece of per-frame lighting state the plugin pushes, and it makes per-env HDRI domain randomisation cheap.

Lifecycle and constraints#

Warning

Environment maps are baked into the scene at scene.build(). The texture, layout, rotation, multiplier, and tint fields cannot be modified at runtime. To change the HDRI, rebuild the scene.

Note

A scene with no environment map and no explicit lights renders against Nyx’s default mid-grey HDRI sky as its only light source. The plugin emits a warning at build time, since this is rarely what you want: every PBR surface picks up the same flat grey ambient and the frame looks washed out. Add at least one light (see Lights), an HDRI environment map, or a solid-colour HDRI with a chosen tint to take control of the illumination.

Note

Procedural sun and sky generation is not supported. Use a captured HDRI or pair an EnvironmentMapAsset with a directional light.