unilab.terrains.terrain_generator

Classes

FlatPatchSamplingCfg

Configuration for sampling flat patches on a heightfield surface.

GeneratedTerrain

Merged terrain heightfield ready to be exported as a single PNG asset.

HeightfieldSurfaceSampler

Compact world-space sampler for a generated hfield surface.

SubTerrainCfg

SubTerrainCfg(proportion: 'float' = 1.0, size: 'tuple[float, float]' = (10.0, 10.0), flat_patch_sampling: 'dict[str, FlatPatchSamplingCfg] | None' = None)

TerrainGenerator

Generates procedural terrain grids with configurable difficulty.

TerrainGeneratorCfg

TerrainGeneratorCfg(*, seed: 'int | None' = None, curriculum: 'bool' = False, size: 'tuple[float, float]', horizontal_scale: 'float' = 0.05, vertical_scale: 'float' = 0.005, border_width: 'float' = 0.0, num_rows: 'int' = 1, num_cols: 'int' = 1, sub_terrains: 'dict[str, SubTerrainCfg]' = <factory>, difficulty_range: 'tuple[float, float]' = (0.0, 1.0), add_lights: 'bool' = False)

TerrainHeightField

Backend-agnostic heightfield data for one sub-terrain patch.

TerrainOutput

TerrainOutput(origin: 'np.ndarray', heightfield: 'TerrainHeightField', flat_patches: 'dict[str, np.ndarray] | None' = None)
class unilab.terrains.terrain_generator.FlatPatchSamplingCfg[source]

Bases: object

Configuration for sampling flat patches on a heightfield surface.

Parameters:
num_patches: int = 10

Number of flat patches to sample per sub-terrain.

patch_radius: float = 0.5

Radius of the circular footprint used to test flatness, in meters.

max_height_diff: float = 0.05

Maximum allowed height variation within the patch footprint, in meters.

x_range: tuple[float, float] = (-1000000.0, 1000000.0)

Allowed range of x coordinates for sampled patches, in meters.

y_range: tuple[float, float] = (-1000000.0, 1000000.0)

Allowed range of y coordinates for sampled patches, in meters.

z_range: tuple[float, float] = (-1000000.0, 1000000.0)

Allowed range of z coordinates (world height) for sampled patches, in meters.

grid_resolution: float | None = None

Resolution of the grid used for flat-patch detection, in meters. When None (default), the terrain’s own horizontal_scale is used. Set to a smaller value (e.g. 0.025) for finer boundary precision at the cost of a larger intermediate grid.

__init__(num_patches=10, patch_radius=0.5, max_height_diff=0.05, x_range=(-1000000.0, 1000000.0), y_range=(-1000000.0, 1000000.0), z_range=(-1000000.0, 1000000.0), grid_resolution=None)
Parameters:
class unilab.terrains.terrain_generator.TerrainHeightField[source]

Bases: object

Backend-agnostic heightfield data for one sub-terrain patch.

Parameters:
noise: ndarray

Quantized height units before normalization.

size: tuple[float, float]

Patch size as (x, y) in meters.

horizontal_scale: float
vertical_scale: float
elevation_min: int
elevation_max: int
max_physical_height: float
base_thickness: float
z_offset: float
physical_heights_xy()[source]

Return world-space surface heights as an (x, y) matrix.

Return type:

ndarray

normalized_elevation()[source]

Return normalized hfield values in [0, 1].

Return type:

ndarray

__init__(noise, size, horizontal_scale, vertical_scale, elevation_min, elevation_max, max_physical_height, base_thickness, z_offset)
Parameters:
class unilab.terrains.terrain_generator.TerrainOutput[source]

Bases: object

TerrainOutput(origin: ‘np.ndarray’, heightfield: ‘TerrainHeightField’, flat_patches: ‘dict[str, np.ndarray] | None’ = None)

Parameters:
origin: ndarray

Spawn origin position (x, y, z) in the sub-terrain’s local frame.

heightfield: TerrainHeightField

Backend-agnostic heightfield data.

flat_patches: dict[str, ndarray] | None = None

Named sets of flat patch positions, each an (N, 3) array. None if not configured.

__init__(origin, heightfield, flat_patches=None)
Parameters:
class unilab.terrains.terrain_generator.GeneratedTerrain[source]

Bases: object

Merged terrain heightfield ready to be exported as a single PNG asset.

Parameters:
heights_yx: ndarray

rows=y, cols=x.

Type:

World-space surface heights in image convention

horizontal_scale: float
z_min: float
z_max: float
base_thickness: float
terrain_origins: ndarray
property size: tuple[float, float]
property height_extent: float
property hfield_size: tuple[float, float, float, float]
property geom_pos: tuple[float, float, float]
to_uint16()[source]
Return type:

ndarray

surface_sampler()[source]
Return type:

HeightfieldSurfaceSampler

write_png(path)[source]

Write the merged hfield as a 16-bit grayscale PNG.

Parameters:

path (Path)

Return type:

None

hfield_size_xml()[source]
Return type:

str

geom_pos_xml()[source]
Return type:

str

__init__(heights_yx, horizontal_scale, z_min, z_max, base_thickness, terrain_origins)
Parameters:
class unilab.terrains.terrain_generator.HeightfieldSurfaceSampler[source]

Bases: object

Compact world-space sampler for a generated hfield surface.

Parameters:
heights_uint16: ndarray
horizontal_scale: float
z_min: float
height_extent: float
property size: tuple[float, float]
sample_height(xy)[source]
Parameters:

xy (ndarray)

Return type:

ndarray

__init__(heights_uint16, horizontal_scale, z_min, height_extent)
Parameters:
class unilab.terrains.terrain_generator.SubTerrainCfg[source]

Bases: ABC

SubTerrainCfg(proportion: ‘float’ = 1.0, size: ‘tuple[float, float]’ = (10.0, 10.0), flat_patch_sampling: ‘dict[str, FlatPatchSamplingCfg] | None’ = None)

Parameters:
proportion: float = 1.0

Robot spawning weight for this terrain type.

In curriculum mode, controls how many robots are spawned on this terrain’s column relative to other terrain types. Each terrain type always gets exactly one column; proportion only affects spawning distribution.

In random mode, controls the sampling probability for each patch.

size: tuple[float, float] = (10.0, 10.0)

Width and length of the terrain patch, in meters.

flat_patch_sampling: dict[str, FlatPatchSamplingCfg] | None = None

Named flat-patch sampling configurations, or None to disable.

abstract 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)
Parameters:
class unilab.terrains.terrain_generator.TerrainGeneratorCfg[source]

Bases: object

TerrainGeneratorCfg(*, seed: ‘int | None’ = None, curriculum: ‘bool’ = False, size: ‘tuple[float, float]’, horizontal_scale: ‘float’ = 0.05, vertical_scale: ‘float’ = 0.005, border_width: ‘float’ = 0.0, num_rows: ‘int’ = 1, num_cols: ‘int’ = 1, sub_terrains: ‘dict[str, SubTerrainCfg]’ = <factory>, difficulty_range: ‘tuple[float, float]’ = (0.0, 1.0), add_lights: ‘bool’ = False)

Parameters:
seed: int | None = None

Random seed for terrain generation. None uses a random seed.

curriculum: bool = False

Controls terrain allocation mode:

  • curriculum=True: Each terrain type gets exactly ONE column. The generator uses

    len(sub_terrains) columns regardless of num_cols. Difficulty increases along rows. The proportion field controls how many robots are spawned per column, not column count.

  • curriculum=False: Every patch is randomly sampled from all terrain types.

    Proportions control sampling probability. Use this for random variety.

size: tuple[float, float]

Width and length of each sub-terrain patch, in meters. Both components must be integer multiples of horizontal_scale.

horizontal_scale: float = 0.05

Heightfield grid resolution along x and y, in meters per cell. Shared by every sub-terrain (overwritten in TerrainGenerator __init__). All length-like sub-terrain parameters (step_width, platform_width, border_width, etc.) must be integer multiples of this value.

__init__(*, seed=None, curriculum=False, size, horizontal_scale=0.05, vertical_scale=0.005, border_width=0.0, num_rows=1, num_cols=1, sub_terrains=<factory>, difficulty_range=(0.0, 1.0), add_lights=False)
Parameters:
vertical_scale: float = 0.005

Heightfield height resolution, in meters per integer unit of the noise array. Shared by every sub-terrain (overwritten in TerrainGenerator __init__).

border_width: float = 0.0

Width of the flat border around the entire terrain grid, in meters. Must be an integer multiple of horizontal_scale if non-zero. The border is a flat hfield slab whose top surface is flush with the inner-terrain floor at z=0; it is NOT a wall.

num_rows: int = 1

Number of sub-terrain rows in the grid. Represents difficulty levels in curriculum mode. Note: Environments are randomly assigned to rows, so multiple envs can share the same patch.

num_cols: int = 1

Number of sub-terrain columns in the grid.

In curriculum mode the generator ignores this value and uses one column per terrain type (len(sub_terrains)). In random mode it is used as-is.

sub_terrains: dict[str, SubTerrainCfg]

Named sub-terrain configurations to populate the grid.

difficulty_range: tuple[float, float] = (0.0, 1.0)

Min and max difficulty values used when generating sub-terrains.

add_lights: bool = False

If True, adds a directional light above the terrain grid.

class unilab.terrains.terrain_generator.TerrainGenerator[source]

Bases: object

Generates procedural terrain grids with configurable difficulty.

Creates a grid of terrain patches where each patch can be a different terrain type. Supports two modes:

  • Random mode (curriculum=False): Every patch independently samples a

    terrain type weighted by proportions. Results in random variety across all patches.

  • Curriculum mode (curriculum=True): Each terrain type gets exactly one column

    (the generator uses len(sub_terrains) columns regardless of num_cols). Difficulty increases along rows. The proportion field controls robot spawning distribution, not column count.

Terrain types are weighted by proportion and their geometry is generated based on a difficulty value in the configured range. The grid is centered at the world origin. A border can be added around the entire grid along with optional overhead lighting.

Parameters:
__init__(cfg, device='cpu')[source]
Parameters:
generate()[source]

Generate the full terrain as one backend-agnostic merged hfield.

Return type:

GeneratedTerrain

write_png(path)[source]
Parameters:

path (Path)

Return type:

GeneratedTerrain