Gaussian splat#

A captured Gaussian splat composited into a live Genesis scene, lit by a single directional sun. The cactus is a .ply radiance field; the plane it sits on is a stock gs.morphs.Plane. Both are rendered in the same Nyx frame.

Rendered output of

What it shows#

Loading a 3D Gaussian Splatting .ply file as a LightFieldAsset and attaching it to the camera through light_fields.
Mixing the splat with simulated geometry (a Genesis Plane) lit by a single directional light. The plane is shaded by the sun; the cactus’s appearance is whatever the splat baked in at capture time.

How the splat is declared#

A splat is a LightFieldAsset with ELightFieldType set to GaussianField. Set its uri to a .ply (Inria-style 3DGS) or .spz (compressed) file, then hand it to the camera:

import gs_nyx.nyx_py_sdk as nps

cactus      = nps.LightFieldAsset()
cactus.type = nps.ELightFieldType.GaussianField
cactus.uri  = "examples/assets/cactus.ply"

cam = scene.add_sensor(NyxCameraOptions(
    ...,
    light_fields = [cactus],
))

A few things worth noting:

Splats are not Genesis entities. They never enter the rigid / FEM / MPM solvers, never collide, and have no morph. They live entirely on the renderer side; the only Genesis-facing surface is the light_fields field of the camera options.
Light fields are scene-wide. The plugin collects light_fields from every Nyx sensor at scene.build() and merges them into one shared scene description. Declaring the same splat on two cameras isn’t required — and would duplicate it.
Format is auto-detected. .ply for plain 3DGS output, .spz for the compressed variant. The extension decides which loader runs; there’s no flag to set.
The splat has a transform. position, rotation (quaternion), and per-axis scale are all on LightFieldAsset. The defaults — origin, identity, unit scale — keep this example simple, but you can move or resize the cactus by setting them before scene.build(). See Gaussian splats for the full field list.

Source#

"""Gaussian splat example for the Nyx renderer plugin.

Renders a captured Gaussian splat (``plant.ply``) sitting on a Genesis
``Plane``, lit by the ``green_sanctuary`` HDRI environment map. Demonstrates
declaring a ``LightFieldAsset`` on ``NyxCameraOptions.light_fields`` so the
radiance field renders alongside simulated geometry every frame.

Usage:
    uv run python examples/05_gaussian_splat.py
"""

from __future__ import annotations

import os

from PIL import Image

import genesis as gs
import gs_nyx.nyx_py_renderer as npr
import gs_nyx.nyx_py_sdk as nps
from gs_nyx_plugin.nyx_camera_options import NyxCameraOptions


HERE        = os.path.dirname(__file__)
PLANT_PLY   = os.path.join(HERE, "assets", "plant.ply")
ENV_MAP     = os.path.join(HERE, "assets", "green_sanctuary_4k.hdr")
OUTPUT_PATH = os.path.join(HERE, "out", "05_gaussian_splat.png")


def main() -> None:
    gs.init()
    os.makedirs(os.path.dirname(OUTPUT_PATH), exist_ok=True)

    scene = gs.Scene(
        sim_options=gs.options.SimOptions(dt=0.01),
        show_viewer=False,
    )

    scene.add_entity(morph=gs.morphs.Plane(plane_size=(2.0, 2.0)))

    # The splat is declared on the camera as a LightFieldAsset rather than as
    # a Genesis entity. light_fields from every Nyx sensor are collected at
    # scene.build() and rendered alongside simulated geometry.
    plant          = nps.LightFieldAsset()
    plant.type     = nps.ELightFieldType.GaussianField
    plant.uri      = PLANT_PLY
    # 90° rotation about Z stands the capture upright in Genesis' Z-up world.
    plant.rotation = nps.quaternion(0.0, 0.0, -0.70710678, 0.70710678)

    # HDRI environment lighting the plane. The splat already has
    # view-dependent colour baked in, so only the simulated geometry needs
    # the env map as a light source.
    env_map            = nps.EnvironmentMapAsset()
    env_map.texture    = ENV_MAP
    env_map.layout     = nps.EEnvMapLayout.LongLat
    env_map.multiplier = 2.0

    cam = scene.add_sensor(NyxCameraOptions(
        res          = (1920, 1080),
        pos          = (1.0, 1.5, 0.8),
        lookat       = (0.0, 0.0, 0.1),
        fov          = 30.0,
        spp          = 64,
        render_mode  = npr.ERenderMode.FastPathTracer,
        env_maps     = [env_map],
        light_fields = [plant],
    ))

    scene.build(n_envs=1)
    scene.step()

    rgb = cam.read().rgb[0].cpu().numpy()
    Image.fromarray(rgb).save(OUTPUT_PATH)
    print(f"Saved {OUTPUT_PATH}")


if __name__ == "__main__":
    main()

Run it:

uv run python examples/05_gaussian_splat.py

The PNG is written to examples/out/05_gaussian_splat.png. The Sphinx build copies it to _static/generated/examples/05_gaussian_splat.png and embeds it at the top of this page, so the docs site always shows whatever the latest run produced.

Gaussian splat#

What it shows#

How the splat is declared#

Source#

See also#