Struct HeightField 

pub struct HeightField {
    pub heights: Vec<Real>,
    pub rows: usize,
    pub cols: usize,
    pub scale_x: Real,
    pub scale_z: Real,
}

A grid-based height field for terrain representation.

Heights are stored in row-major order. The field spans from (0,0) to (scale_x * (cols-1), scale_z * (rows-1)) in the XZ plane.

Fields

heights: Vec<Real>

Height values in row-major order.

rows: usize

Number of rows (Z direction).

cols: usize

Number of columns (X direction).

scale_x: Real

Spacing in the X direction.

scale_z: Real

Spacing in the Z direction.

Implementations

impl HeightField

pub fn new( heights: Vec<Real>, rows: usize, cols: usize, scale_x: Real, scale_z: Real, ) -> Self

Create a new height field.

pub fn height_at(&self, row: usize, col: usize) -> Real

Get the height at grid position (row, col).

pub fn from_fn( cols: usize, rows: usize, cell_size: Real, f: impl Fn(usize, usize) -> Real, ) -> Self

Create a height field from a function.

The function f(col, row) returns the height at each grid point.

pub fn height_at_uv(&self, u: Real, v: Real) -> Real

Bilinear interpolation of height at normalized coordinates (u, v).

u and v are in [0, 1], mapping to the full extent of the grid.

pub fn normal_at_grid(&self, col: usize, row: usize) -> [Real; 3]

Compute the surface normal at grid point (col, row) via finite differences.

pub fn to_triangle_mesh(&self) -> (Vec<[Real; 3]>, Vec<[usize; 3]>)

Tessellate the height field into a triangle mesh.

Returns (vertices, triangles) where each vertex is [x, y, z] and each triangle is 3 vertex indices.

pub fn min_height(&self) -> Real

Return the minimum height in the field.

pub fn max_height(&self) -> Real

Return the maximum height in the field.

pub fn surface_area(&self) -> Real

Compute the total surface area by summing triangle areas from tessellation.

pub fn smooth(&mut self, iterations: usize)

Apply Laplacian smoothing to the height field.

Each interior height is replaced by the average of its 4-connected neighbors. Boundary heights are unchanged.

pub fn ray_cast_grid( &self, origin: [Real; 3], dir: [Real; 3], max_toi: Real, ) -> Option<(Real, [Real; 3])>

Ray cast using grid DDA traversal and per-cell triangle intersection.

Returns Some((toi, [nx, ny, nz])) for the closest hit within max_toi, or None if no intersection.

impl HeightField

pub fn lod_downsample(&self, factor: usize) -> HeightField

Generate a downsampled (LOD) version of the height field.

factor must be ≥ 1. A factor of 2 halves the resolution by averaging 2×2 blocks of cells. If the grid is too small the original is returned.

pub fn lod_pyramid(&self, levels: usize) -> Vec<HeightField>

Generate multiple LOD levels.

Returns a Vec where index 0 is the original, index 1 is 2× downsampled, index 2 is 4× downsampled, etc., until the grid is too small.

pub fn normal_at_world(&self, x: Real, z: Real) -> [Real; 3]

Compute the normal at an arbitrary world-space XZ position via bilinear interpolation of the four surrounding grid normals.

pub fn serialize(&self) -> Vec<Real>

Serialize the height field to a flat Vecf64` prefixed by metadata.

Format: \[rows, cols, scale_x, scale_z, h0, h1, ...\]

pub fn deserialize(data: &[Real]) -> Option<HeightField>

Deserialize a height field from a flat Vecf64(inverse ofserialize`).

pub fn compute_all_normals(&self) -> Vec<[Real; 3]>

Compute per-vertex normals for all grid vertices.

Returns a flat Vec<[Real; 3]> in row-major order.

pub fn height_at_world(&self, x: Real, z: Real) -> Real

Height at arbitrary world-space XZ position (bilinear interpolation).

Clamps to grid extents.

pub fn ray_cast_bounded( &self, origin: [Real; 3], dir: [Real; 3], max_toi: Real, max_steps: usize, ) -> Option<(Real, [Real; 3])>

Ray cast with DDA and a maximum number of steps (bounded version).

Avoids unbounded loops on very large grids.

impl HeightField

pub fn aabb(&self) -> ([f64; 3], [f64; 3])

Axis-aligned bounding box of this height field in world space.

Returns (min, max) where each is [x, y, z].

pub fn height_at_xz(&self, x: f64, z: f64) -> f64

Bilinear height interpolation at world-space position (x, z).

Unlike height_at(row, col) (grid indices) and height_at_world, this method accepts (x, z) world coordinates and returns the interpolated height, clamping to the grid extents.

pub fn normals(&self) -> Vec<[f64; 3]>

Per-vertex normals for the entire grid in row-major order.

Each normal is computed via finite differences over the 4-connected neighborhood and returned as a unit vector [nx, ny, nz].

pub fn tessellate(&self) -> (Vec<[f64; 3]>, Vec<[usize; 3]>)

Tessellate the height field into a triangle mesh.

Returns (vertices, indices) where:

• vertices is a list of world-space [x, y, z] positions, one per grid point, in row-major order.
• indices is a list of [i0, i1, i2] triangles (two per quad cell).

pub fn ray_intersect( &self, origin: [f64; 3], dir: [f64; 3], ) -> Option<(f64, [f64; 3])>

DDA ray intersection returning (t, normal) for the first hit.

Uses grid-cell DDA traversal in the XZ plane, testing the two triangles of each cell with Möller–Trumbore intersection. Returns None if the ray misses the terrain or is going away from it.

The search is limited to a reasonable distance (diagonal of the AABB).

impl HeightField

pub fn slope_at(&self, col: usize, row: usize) -> f64

Compute the slope magnitude at grid point (col, row).

Slope is defined as sqrt((dh/dx)² + (dh/dz)²) using the same finite-difference stencil as normal_at_grid.

pub fn curvature_at(&self, col: usize, row: usize) -> f64

Compute the mean curvature at grid point (col, row).

Uses a second-order central difference approximation: κ ≈ (d²h/dx² + d²h/dz²) / 2.

pub fn slope_map(&self) -> Vec<f64>

Return a flat Vecf64` of slope magnitudes in row-major order.

pub fn curvature_map(&self) -> Vec<f64>

Return a flat Vecf64` of mean curvatures in row-major order.

pub fn closest_vertex(&self, q: [f64; 3]) -> ([f64; 3], usize, usize)

Find the closest surface point to query point q by brute-force search over all grid vertices.

Returns (closest_world_point, row, col).

pub fn resample(&self, new_cols: usize, new_rows: usize) -> HeightField

Resample the height field to new grid dimensions by bilinear interpolation.

new_cols and new_rows must be ≥ 2. Returns a new HeightField with the same world extents but a different resolution.

pub fn hydraulic_erode(&mut self, sediment_rate: f64, iterations: usize)

Simple hydraulic erosion step: for each cell, water flows to the steepest-descent neighbor and carries a fraction sediment_rate of height difference.

iterations controls how many passes are performed. For correctness the caller should keep sediment_rate ≤ 0.5.

pub fn flow_accumulation(&self) -> Vec<f64>

Compute a simple flow-accumulation map (watershed proxy).

Each cell accumulates 1 unit plus the total of all upstream cells that drain into it following steepest descent. Returns a flat Vecf64` in row-major order; larger values indicate valleys/channels.

pub fn clamp_heights(&mut self, min_h: f64, max_h: f64)

Clamp all height values to the range \[min_h, max_h\].

pub fn scale_heights(&mut self, factor: f64)

Scale all heights by a uniform factor.

pub fn offset_heights(&mut self, offset: f64)

Offset all heights by a constant value.

pub fn normalize_heights(&mut self)

Normalize heights to the range \[0, 1\]. If all heights are equal, all become 0.

pub fn invert_heights(&mut self)

Invert heights: each height h becomes max_height - (h - min_height).

pub fn mean_height(&self) -> f64

Compute the average height over the entire grid.

pub fn height_variance(&self) -> f64

Compute the variance of heights.

pub fn count_peaks(&self) -> usize

Count the number of local maxima (peaks) in the grid.

A cell is a peak if it is strictly higher than all 4-connected neighbors.

pub fn volume(&self) -> f64

Approximate volume under the height field (above y=0) using the trapezoidal rule.

Each grid cell contributes (average_height) * cell_area.

pub fn ray_cast( &self, ray_origin: &Vec3, ray_direction: &Vec3, max_toi: f64, ) -> Option<HeightfieldRayHit>

Cast a ray against the height field. Returns hit information if intersection found.

Uses the tessellated triangle mesh for accurate intersection.

Trait Implementations

impl Clone for HeightField

fn clone(&self) -> HeightField

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for HeightField

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Shape for HeightField

fn bounding_box(&self) -> Aabb

Compute the axis-aligned bounding box of this shape (in local space).

fn support_point(&self, direction: &Vec3) -> Vec3

Compute the support point in the given direction (for GJK).

fn volume(&self) -> Real

Compute the volume of this shape.

fn center_of_mass(&self) -> Vec3

Compute the center of mass in local space.

fn inertia_tensor(&self, _mass: Real) -> Mat3

Compute the inertia tensor for the given mass.

fn ray_cast( &self, ray_origin: &Vec3, ray_direction: &Vec3, max_toi: Real, ) -> Option<RayHit>

Cast a ray against this shape (in local space). Returns the first intersection within max_toi.

fn mass_properties(&self, density: Real) -> MassProperties

Compute full mass properties for a given density.