unilab.terrains.heightfield_terrains

Terrains composed of heightfields.

This module provides terrain generation functionality using heightfields, adapted from the IsaacLab terrain generation system.

References

IsaacLab mesh terrain implementation: https://github.com/isaac-sim/IsaacLab/blob/main/source/isaaclab/isaaclab/terrains/height_field/hf_terrains.py

Classes

HfFlatTerrainCfg

A flat heightfield terrain (all-zero noise array).

HfInvertedPyramidStairsTerrainCfg

A pit-style pyramid stairs terrain encoded as a heightfield.

HfPyramidSlopedTerrainCfg

HfPyramidSlopedTerrainCfg(proportion: 'float' = 1.0, size: 'tuple[float, float]' = (10.0, 10.0), flat_patch_sampling: 'dict[str, FlatPatchSamplingCfg] | None' = None, *, slope_range: 'tuple[float, float]', platform_width: 'float' = 1.0, inverted: 'bool' = False, border_width: 'float' = 0.0, horizontal_scale: 'float' = 0.1, vertical_scale: 'float' = 0.005, base_thickness_ratio: 'float' = 1.0)

HfPyramidStairsTerrainCfg

A pyramid stairs terrain encoded as a heightfield.

HfRandomUniformTerrainCfg

HfRandomUniformTerrainCfg(proportion: 'float' = 1.0, size: 'tuple[float, float]' = (10.0, 10.0), flat_patch_sampling: 'dict[str, FlatPatchSamplingCfg] | None' = None, *, noise_range: 'tuple[float, float]', noise_step: 'float' = 0.005, downsampled_scale: 'float | None' = None, horizontal_scale: 'float' = 0.1, vertical_scale: 'float' = 0.005, base_thickness_ratio: 'float' = 1.0, border_width: 'float' = 0.0)

HfWaveTerrainCfg

HfWaveTerrainCfg(proportion: 'float' = 1.0, size: 'tuple[float, float]' = (10.0, 10.0), flat_patch_sampling: 'dict[str, FlatPatchSamplingCfg] | None' = None, *, amplitude_range: 'tuple[float, float]', num_waves: 'int' = 1, horizontal_scale: 'float' = 0.1, vertical_scale: 'float' = 0.005, base_thickness_ratio: 'float' = 0.25, border_width: 'float' = 0.0)
class unilab.terrains.heightfield_terrains.HfPyramidSlopedTerrainCfg[source]

Bases: SubTerrainCfg

HfPyramidSlopedTerrainCfg(proportion: ‘float’ = 1.0, size: ‘tuple[float, float]’ = (10.0, 10.0), flat_patch_sampling: ‘dict[str, FlatPatchSamplingCfg] | None’ = None, *, slope_range: ‘tuple[float, float]’, platform_width: ‘float’ = 1.0, inverted: ‘bool’ = False, border_width: ‘float’ = 0.0, horizontal_scale: ‘float’ = 0.1, vertical_scale: ‘float’ = 0.005, base_thickness_ratio: ‘float’ = 1.0)

Parameters:

  • proportion (float)

  • size (tuple[float, float])

  • flat_patch_sampling (dict[str, FlatPatchSamplingCfg] | None)

  • slope_range (tuple[float, float])

  • platform_width (float)

  • inverted (bool)

  • border_width (float)

  • horizontal_scale (float)

  • vertical_scale (float)

  • base_thickness_ratio (float)

slope_range: tuple[float, float]

Range of slope gradients (rise / run), interpolated by difficulty.

platform_width: float = 1.0

Side length of the flat square platform at the terrain center, in meters.

inverted: bool = False

If True, the pyramid is inverted so the platform is at the bottom.

border_width: float = 0.0

Width of the flat border around the terrain edges, in meters. Must be >= horizontal_scale if non-zero.

horizontal_scale: float = 0.1

Heightfield grid resolution along x and y, in meters per cell.

vertical_scale: float = 0.005

Heightfield height resolution, in meters per integer unit of the noise array.

base_thickness_ratio: float = 1.0

Ratio of the heightfield base thickness to its maximum surface height.

function(difficulty, rng)[source]

Generate backend-agnostic terrain data.

Return type:

TerrainOutput

Returns:

TerrainOutput containing spawn origin and heightfield data.

Parameters:
__init__(proportion=1.0, size=(10.0, 10.0), flat_patch_sampling=None, *, slope_range, platform_width=1.0, inverted=False, border_width=0.0, horizontal_scale=0.1, vertical_scale=0.005, base_thickness_ratio=1.0)
Parameters:

  • proportion (float)

  • size (tuple[float, float])

  • flat_patch_sampling (dict[str, FlatPatchSamplingCfg] | None)

  • slope_range (tuple[float, float])

  • platform_width (float)

  • inverted (bool)

  • border_width (float)

  • horizontal_scale (float)

  • vertical_scale (float)

  • base_thickness_ratio (float)

class unilab.terrains.heightfield_terrains.HfRandomUniformTerrainCfg[source]

Bases: SubTerrainCfg

HfRandomUniformTerrainCfg(proportion: ‘float’ = 1.0, size: ‘tuple[float, float]’ = (10.0, 10.0), flat_patch_sampling: ‘dict[str, FlatPatchSamplingCfg] | None’ = None, *, noise_range: ‘tuple[float, float]’, noise_step: ‘float’ = 0.005, downsampled_scale: ‘float | None’ = None, horizontal_scale: ‘float’ = 0.1, vertical_scale: ‘float’ = 0.005, base_thickness_ratio: ‘float’ = 1.0, border_width: ‘float’ = 0.0)

Parameters:

  • proportion (float)

  • size (tuple[float, float])

  • flat_patch_sampling (dict[str, FlatPatchSamplingCfg] | None)

  • noise_range (tuple[float, float])

  • noise_step (float)

  • downsampled_scale (float | None)

  • horizontal_scale (float)

  • vertical_scale (float)

  • base_thickness_ratio (float)

  • border_width (float)

noise_range: tuple[float, float]

Min and max height noise, in meters.

noise_step: float = 0.005

Height quantization step, in meters. Sampled heights are multiples of this value within noise_range.

downsampled_scale: float | None = None

Spacing between randomly sampled height points before interpolation, in meters. If None, uses horizontal_scale. Must be >= horizontal_scale.

horizontal_scale: float = 0.1

Heightfield grid resolution along x and y, in meters per cell.

vertical_scale: float = 0.005

Heightfield height resolution, in meters per integer unit of the noise array.

base_thickness_ratio: float = 1.0

Ratio of the heightfield base thickness to its maximum surface height.

border_width: float = 0.0

Width of the flat border around the terrain edges, in meters. Must be >= horizontal_scale if non-zero.

function(difficulty, rng)[source]

Generate backend-agnostic terrain data.

Return type:

TerrainOutput

Returns:

TerrainOutput containing spawn origin and heightfield data.

Parameters:
__init__(proportion=1.0, size=(10.0, 10.0), flat_patch_sampling=None, *, noise_range, noise_step=0.005, downsampled_scale=None, horizontal_scale=0.1, vertical_scale=0.005, base_thickness_ratio=1.0, border_width=0.0)
Parameters:

  • proportion (float)

  • size (tuple[float, float])

  • flat_patch_sampling (dict[str, FlatPatchSamplingCfg] | None)

  • noise_range (tuple[float, float])

  • noise_step (float)

  • downsampled_scale (float | None)

  • horizontal_scale (float)

  • vertical_scale (float)

  • base_thickness_ratio (float)

  • border_width (float)

class unilab.terrains.heightfield_terrains.HfWaveTerrainCfg[source]

Bases: SubTerrainCfg

HfWaveTerrainCfg(proportion: ‘float’ = 1.0, size: ‘tuple[float, float]’ = (10.0, 10.0), flat_patch_sampling: ‘dict[str, FlatPatchSamplingCfg] | None’ = None, *, amplitude_range: ‘tuple[float, float]’, num_waves: ‘int’ = 1, horizontal_scale: ‘float’ = 0.1, vertical_scale: ‘float’ = 0.005, base_thickness_ratio: ‘float’ = 0.25, border_width: ‘float’ = 0.0)

Parameters:

  • proportion (float)

  • size (tuple[float, float])

  • flat_patch_sampling (dict[str, FlatPatchSamplingCfg] | None)

  • amplitude_range (tuple[float, float])

  • num_waves (int)

  • horizontal_scale (float)

  • vertical_scale (float)

  • base_thickness_ratio (float)

  • border_width (float)

amplitude_range: tuple[float, float]

Min and max wave amplitude, in meters. Interpolated by difficulty.

num_waves: int = 1

Number of complete wave cycles along the terrain length.

horizontal_scale: float = 0.1

Heightfield grid resolution along x and y, in meters per cell.

vertical_scale: float = 0.005

Heightfield height resolution, in meters per integer unit of the noise array.

base_thickness_ratio: float = 0.25

Ratio of the heightfield base thickness to its maximum surface height.

__init__(proportion=1.0, size=(10.0, 10.0), flat_patch_sampling=None, *, amplitude_range, num_waves=1, horizontal_scale=0.1, vertical_scale=0.005, base_thickness_ratio=0.25, border_width=0.0)
Parameters:

  • proportion (float)

  • size (tuple[float, float])

  • flat_patch_sampling (dict[str, FlatPatchSamplingCfg] | None)

  • amplitude_range (tuple[float, float])

  • num_waves (int)

  • horizontal_scale (float)

  • vertical_scale (float)

  • base_thickness_ratio (float)

  • border_width (float)

border_width: float = 0.0

Width of the flat border around the terrain edges, in meters. Must be >= horizontal_scale if non-zero.

function(difficulty, rng)[source]

Generate backend-agnostic terrain data.

Return type:

TerrainOutput

Returns:

TerrainOutput containing spawn origin and heightfield data.

Parameters:
class unilab.terrains.heightfield_terrains.HfPyramidStairsTerrainCfg[source]

Bases: SubTerrainCfg

A pyramid stairs terrain encoded as a heightfield.

Concentric square rings from the outside in form a staircase climbing toward a central platform. With holes=True the four diagonal corners of each ring are carved out to a deep pit; agents falling into the pit reach a terminating depth instead of an infinite void.

Parameters:

  • proportion (float)

  • size (tuple[float, float])

  • flat_patch_sampling (dict[str, FlatPatchSamplingCfg] | None)

  • step_height_range (tuple[float, float])

  • step_width (float)

  • platform_width (float)

  • border_width (float)

  • holes (bool)

  • pit_depth (float)

  • horizontal_scale (float)

  • vertical_scale (float)

  • base_thickness_ratio (float)

__init__(proportion=1.0, size=(10.0, 10.0), flat_patch_sampling=None, *, step_height_range, step_width, platform_width=1.0, border_width=0.0, holes=False, pit_depth=5.0, horizontal_scale=0.05, vertical_scale=0.005, base_thickness_ratio=1.0)
Parameters:

  • proportion (float)

  • size (tuple[float, float])

  • flat_patch_sampling (dict[str, FlatPatchSamplingCfg] | None)

  • step_height_range (tuple[float, float])

  • step_width (float)

  • platform_width (float)

  • border_width (float)

  • holes (bool)

  • pit_depth (float)

  • horizontal_scale (float)

  • vertical_scale (float)

  • base_thickness_ratio (float)

step_height_range: tuple[float, float]

Min and max step height, in meters. Interpolated by difficulty.

step_width: float

Depth (run) of each step, in meters. Must be a multiple of horizontal_scale.

platform_width: float = 1.0

Side length of the flat square platform at the top of the staircase, in meters.

border_width: float = 0.0

Width of the flat outer border around the staircase, in meters.

holes: bool = False

If True, carve deep pits at the diagonal corners of each step ring.

pit_depth: float = 5.0

Depth of holes-mode pits below the lowest stair, in meters.

horizontal_scale: float = 0.05

Heightfield grid resolution. Overwritten by TerrainGenerator.

vertical_scale: float = 0.005

Heightfield height resolution. Overwritten by TerrainGenerator.

base_thickness_ratio: float = 1.0

Ratio of the heightfield base thickness to its surface height.

function(difficulty, rng)[source]

Generate backend-agnostic terrain data.

Return type:

TerrainOutput

Returns:

TerrainOutput containing spawn origin and heightfield data.

Parameters:
class unilab.terrains.heightfield_terrains.HfInvertedPyramidStairsTerrainCfg[source]

Bases: HfPyramidStairsTerrainCfg

A pit-style pyramid stairs terrain encoded as a heightfield.

Inverts HfPyramidStairsTerrainCfg: outer ring sits at world z=0, rings descend toward a central platform at the bottom. With holes=True the diagonal corners are even deeper than the platform.

Parameters:

  • proportion (float)

  • size (tuple[float, float])

  • flat_patch_sampling (dict[str, FlatPatchSamplingCfg] | None)

  • step_height_range (tuple[float, float])

  • step_width (float)

  • platform_width (float)

  • border_width (float)

  • holes (bool)

  • pit_depth (float)

  • horizontal_scale (float)

  • vertical_scale (float)

  • base_thickness_ratio (float)

__init__(proportion=1.0, size=(10.0, 10.0), flat_patch_sampling=None, *, step_height_range, step_width, platform_width=1.0, border_width=0.0, holes=False, pit_depth=5.0, horizontal_scale=0.05, vertical_scale=0.005, base_thickness_ratio=1.0)
Parameters:

  • proportion (float)

  • size (tuple[float, float])

  • flat_patch_sampling (dict[str, FlatPatchSamplingCfg] | None)

  • step_height_range (tuple[float, float])

  • step_width (float)

  • platform_width (float)

  • border_width (float)

  • holes (bool)

  • pit_depth (float)

  • horizontal_scale (float)

  • vertical_scale (float)

  • base_thickness_ratio (float)

function(difficulty, rng)[source]

Generate backend-agnostic terrain data.

Return type:

TerrainOutput

Returns:

TerrainOutput containing spawn origin and heightfield data.

Parameters:
class unilab.terrains.heightfield_terrains.HfFlatTerrainCfg[source]

Bases: SubTerrainCfg

A flat heightfield terrain (all-zero noise array).

Parameters:

  • proportion (float)

  • size (tuple[float, float])

  • flat_patch_sampling (dict[str, FlatPatchSamplingCfg] | None)

  • horizontal_scale (float)

  • vertical_scale (float)

  • base_thickness_ratio (float)

__init__(proportion=1.0, size=(10.0, 10.0), flat_patch_sampling=None, *, horizontal_scale=0.05, vertical_scale=0.005, base_thickness_ratio=0.0)
Parameters:

  • proportion (float)

  • size (tuple[float, float])

  • flat_patch_sampling (dict[str, FlatPatchSamplingCfg] | None)

  • horizontal_scale (float)

  • vertical_scale (float)

  • base_thickness_ratio (float)

horizontal_scale: float = 0.05

Heightfield grid resolution. Overwritten by TerrainGenerator.

vertical_scale: float = 0.005

Heightfield height resolution. Overwritten by TerrainGenerator.

base_thickness_ratio: float = 0.0

Ratio of the heightfield base thickness to its surface height. The helper enforces a minimum thickness so a literal zero is fine here.

function(difficulty, rng)[source]

Generate backend-agnostic terrain data.

Return type:

TerrainOutput

Returns:

TerrainOutput containing spawn origin and heightfield data.

Parameters: