newton.Heightfield#

class newton.Heightfield(data, nrow, ncol, hx=1.0, hy=1.0, min_z=None, max_z=None)[source]#

Bases: object

Represents a heightfield (2D elevation grid) for terrain and large static surfaces.

Heightfields are efficient representations of terrain using a 2D grid of elevation values. They are always static (zero mass, zero inertia) and more memory-efficient than equivalent triangle meshes.

The elevation data is always normalized to [0, 1] internally. World-space heights are computed as: z = min_z + data[r, c] * (max_z - min_z).

Example

Create a heightfield from raw elevation data (auto-normalizes):

import numpy as np
import newton

nrow, ncol = 10, 10
elevation = np.random.rand(nrow, ncol).astype(np.float32) * 5.0  # 0-5 meters

hfield = newton.Heightfield(
    data=elevation,
    nrow=nrow,
    ncol=ncol,
    hx=5.0,  # half-extent X (field spans [-5, +5] meters)
    hy=5.0,  # half-extent Y
)
# min_z and max_z are auto-derived from the data (0.0 and 5.0)

Create with explicit height range:

hfield = newton.Heightfield(
    data=normalized_data,  # any values, will be normalized
    nrow=nrow,
    ncol=ncol,
    hx=5.0,
    hy=5.0,
    min_z=-1.0,
    max_z=3.0,
)
__init__(data, nrow, ncol, hx=1.0, hy=1.0, min_z=None, max_z=None)#

Construct a Heightfield object from a 2D elevation grid.

The input data is normalized to [0, 1]. If min_z and max_z are not provided, they are derived from the data’s minimum and maximum values.

Parameters:

  • data (Sequence[Sequence[float]] | ndarray[Any, dtype[Any]]) – 2D array of elevation values, shape (nrow, ncol). Any numeric values are accepted and will be normalized to [0, 1] internally.

  • nrow (int) – Number of rows in the heightfield grid.

  • ncol (int) – Number of columns in the heightfield grid.

  • hx (float) – Half-extent in X direction. The heightfield spans [-hx, +hx].

  • hy (float) – Half-extent in Y direction. The heightfield spans [-hy, +hy].

  • min_z (float | None) – World-space Z value corresponding to data minimum. Must be provided together with max_z, or both omitted to auto-derive from data.

  • max_z (float | None) – World-space Z value corresponding to data maximum. Must be provided together with min_z, or both omitted to auto-derive from data.

finalize(device=None, requires_grad=False)#

Construct a simulation-ready Warp array from the heightfield data and return its ID.

Parameters:

  • device (Device | str | None) – Device on which to allocate heightfield buffers.

  • requires_grad (bool) – If True, data is allocated with gradient tracking.

Returns:

The ID (pointer) of the simulation-ready Warp array.

Return type:

uint64

property data#

Get the normalized [0, 1] elevation data as a 2D numpy array.