lsurf.surfaces.GerstnerWaveSurface

class lsurf.surfaces.GerstnerWaveSurface(wave_params, role, name='gerstner_wave', time=0.0, reference_z=0.0, material_front=None, material_back=None, max_distance=10000.0)

Flat ocean surface with Gerstner wave physics (CPU-only).

Implements the Gerstner (trochoidal) wave model where water particles move in circular orbits, producing realistic ocean wave shapes with sharp crests and flat troughs.

Parameters:

• wave_params (list of GerstnerWaveParams) – List of wave components to superimpose.

• role (SurfaceRole) – What happens when a ray hits (typically OPTICAL).

• name (str) – Human-readable name.

• time (float, optional) – Time for wave animation in seconds. Default is 0.0.

• reference_z (float, optional) – Mean sea level z-coordinate in meters. Default is 0.0.

• material_front (MaterialField, optional) – Material above surface (air).

• material_back (MaterialField, optional) – Material below surface (water).

• max_distance (float, optional) – Maximum ray marching distance in meters. Default is 10000.0.

Examples

>>> from lsurf.surfaces import GerstnerWaveSurface, GerstnerWaveParams, SurfaceRole
>>> from lsurf.materials import AIR_STP, WATER
>>>
>>> wave = GerstnerWaveParams(amplitude=1.0, wavelength=50.0)
>>> surface = GerstnerWaveSurface(
...     wave_params=[wave],
...     role=SurfaceRole.OPTICAL,
...     name="ocean",
...     material_front=AIR_STP,
...     material_back=WATER,
... )

__init__(wave_params, role, name='gerstner_wave', time=0.0, reference_z=0.0, material_front=None, material_back=None, max_distance=10000.0)

Methods

__init__(wave_params, role[, name, time, ...])
default_kernel()	Return the default intersection kernel for this surface type.
get_gpu_parameters()	Return parameters for GPU kernel.
get_materials()	Return materials for Fresnel calculation.
get_max_wave_height()	Get maximum possible wave height above reference_z.
intersect(origins, directions[, min_distance])	Find ray-surface intersections using ray marching.
normal_at(positions[, incoming_directions])	Compute surface normal at given positions.
set_time(time)	Update the wave animation time.
signed_distance(positions)	Compute signed distance from positions to surface.
supported_kernels()	Return list of intersection kernels supported by this surface type.

Attributes

geometry	use geometry_id instead.
geometry_id	GPU geometry type ID (0 = CPU-only).
gpu_capable	This surface does NOT support GPU acceleration.
kernel_id	Return the kernel ID configured for this surface instance.
material_back
material_front
max_distance
name
reference_z
time
wave_params
role

wave_params: list[GerstnerWaveParams]

role: SurfaceRole

name: str = 'gerstner_wave'

time: float = 0.0

reference_z: float = 0.0

material_front: Any = None

material_back: Any = None

max_distance: float = 10000.0

property gpu_capable: bool

This surface does NOT support GPU acceleration.

property geometry_id: int

GPU geometry type ID (0 = CPU-only).

get_materials()

Return materials for Fresnel calculation.

get_max_wave_height()

Get maximum possible wave height above reference_z.

intersect(origins, directions, min_distance=1e-06)

Find ray-surface intersections using ray marching.

Parameters:

• origins (ndarray, shape (N, 3)) – Ray origin positions.

• directions (ndarray, shape (N, 3)) – Ray direction unit vectors.

• min_distance (float) – Minimum valid intersection distance.

Returns:

• distances (ndarray, shape (N,)) – Distance to intersection (inf if no hit).

• hit_mask (ndarray, shape (N,), dtype=bool) – True for rays that hit the surface.

Return type:

tuple[ndarray[tuple[Any, …], dtype[float32]], ndarray[tuple[Any, …], dtype[bool]]]

normal_at(positions, incoming_directions=None)

Compute surface normal at given positions.

Parameters:

• positions (ndarray, shape (N, 3)) – Points on the surface.

• incoming_directions (ndarray, shape (N, 3), optional) – Incoming ray directions.

Returns:

normals – Unit normal vectors.

Return type:

ndarray, shape (N, 3)

set_time(time)

Update the wave animation time.

__init__(wave_params, role, name='gerstner_wave', time=0.0, reference_z=0.0, material_front=None, material_back=None, max_distance=10000.0)