mjlab.terrains

Terrain generation and importing.

Classes:

HfPyramidSlopedTerrainCfg	HfPyramidSlopedTerrainCfg(proportion: 'float' = 1.0, size: 'tuple[float, float]' = (10.0, 10.0), *, 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)
HfRandomUniformTerrainCfg	HfRandomUniformTerrainCfg(proportion: 'float' = 1.0, size: 'tuple[float, float]' = (10.0, 10.0), *, 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), *, amplitude_range: tuple[float, float], num_waves: float = 1.0, horizontal_scale: float = 0.1, vertical_scale: float = 0.005, base_thickness_ratio: float = 0.25, border_width: float = 0.0)
BoxFlatTerrainCfg	BoxFlatTerrainCfg(proportion: 'float' = 1.0, size: 'tuple[float, float]' = (10.0, 10.0))
BoxInvertedPyramidStairsTerrainCfg	BoxInvertedPyramidStairsTerrainCfg(proportion: 'float' = 1.0, size: 'tuple[float, float]' = (10.0, 10.0), *, border_width: 'float' = 0.0, step_height_range: 'tuple[float, float]', step_width: 'float', platform_width: 'float' = 1.0, holes: 'bool' = False)
BoxPyramidStairsTerrainCfg	Configuration for a pyramid stairs terrain.
BoxRandomGridTerrainCfg	BoxRandomGridTerrainCfg(proportion: 'float' = 1.0, size: 'tuple[float, float]' = (10.0, 10.0), *, grid_width: 'float', grid_height_range: 'tuple[float, float]', platform_width: 'float' = 1.0, holes: 'bool' = False, merge_similar_heights: 'bool' = False, height_merge_threshold: 'float' = 0.05, max_merge_distance: 'int' = 3)
SubTerrainCfg	SubTerrainCfg(proportion: 'float' = 1.0, size: 'tuple[float, float]' = (10.0, 10.0))
TerrainGenerator	Generates procedural terrain grids with configurable difficulty.
TerrainGeneratorCfg	TerrainGeneratorCfg(*, seed: 'int | None' = None, curriculum: 'bool' = False, size: 'tuple[float, float]', border_width: 'float' = 0.0, border_height: 'float' = 1.0, num_rows: 'int' = 1, num_cols: 'int' = 1, color_scheme: "Literal['height', 'random', 'none']" = 'height', sub_terrains: 'dict[str, SubTerrainCfg]' = <factory>, difficulty_range: 'tuple[float, float]' = (0.0, 1.0), add_lights: 'bool' = False)
TerrainImporter	A class to handle terrain geometry and import it into the simulator.
TerrainImporterCfg	Configuration for terrain import and environment placement.

class mjlab.terrains.HfPyramidSlopedTerrainCfg

Bases: SubTerrainCfg

HfPyramidSlopedTerrainCfg(proportion: ‘float’ = 1.0, size: ‘tuple[float, float]’ = (10.0, 10.0), *, 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)

Attributes:

slope_range
platform_width
inverted
border_width
horizontal_scale
vertical_scale
base_thickness_ratio

Methods:

function(difficulty, spec, rng)	Generate terrain geometry.
__init__([proportion, size, platform_width, ...])

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

function(difficulty: float, spec: MjSpec, rng: Generator) → TerrainOutput

Generate terrain geometry.

Returns:

TerrainOutput containing spawn origin and list of geometries.

__init__(proportion: float = 1.0, size: tuple[float, float] = (10.0, 10.0), *, 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) → None

class mjlab.terrains.HfRandomUniformTerrainCfg

Bases: SubTerrainCfg

HfRandomUniformTerrainCfg(proportion: ‘float’ = 1.0, size: ‘tuple[float, float]’ = (10.0, 10.0), *, 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)

Attributes:

noise_range
noise_step
downsampled_scale
horizontal_scale
vertical_scale
base_thickness_ratio
border_width

Methods:

function(difficulty, spec, rng)	Generate terrain geometry.
__init__([proportion, size, noise_step, ...])

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

function(difficulty: float, spec: MjSpec, rng: Generator) → TerrainOutput

Generate terrain geometry.

Returns:

TerrainOutput containing spawn origin and list of geometries.

__init__(proportion: float = 1.0, size: tuple[float, float] = (10.0, 10.0), *, 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) → None

class mjlab.terrains.HfWaveTerrainCfg

Bases: SubTerrainCfg

HfWaveTerrainCfg(proportion: ‘float’ = 1.0, size: ‘tuple[float, float]’ = (10.0, 10.0), *, amplitude_range: tuple[float, float], num_waves: float = 1.0, horizontal_scale: float = 0.1, vertical_scale: float = 0.005, base_thickness_ratio: float = 0.25, border_width: float = 0.0)

Attributes:

amplitude_range
num_waves
horizontal_scale
vertical_scale
base_thickness_ratio
border_width

Methods:

function(difficulty, spec, rng)	Generate terrain geometry.
__init__([proportion, size, num_waves, ...])

amplitude_range: tuple[float, float]

num_waves: float = 1.0

horizontal_scale: float = 0.1

vertical_scale: float = 0.005

base_thickness_ratio: float = 0.25

border_width: float = 0.0

function(difficulty: float, spec: MjSpec, rng: Generator) → TerrainOutput

Generate terrain geometry.

Returns:

TerrainOutput containing spawn origin and list of geometries.

__init__(proportion: float = 1.0, size: tuple[float, float] = (10.0, 10.0), *, amplitude_range: tuple[float, float], num_waves: float = 1.0, horizontal_scale: float = 0.1, vertical_scale: float = 0.005, base_thickness_ratio: float = 0.25, border_width: float = 0.0) → None

class mjlab.terrains.BoxFlatTerrainCfg

Bases: SubTerrainCfg

BoxFlatTerrainCfg(proportion: ‘float’ = 1.0, size: ‘tuple[float, float]’ = (10.0, 10.0))

Methods:

function(difficulty, spec, rng)	Generate terrain geometry.
__init__([proportion, size])

function(difficulty: float, spec: MjSpec, rng: Generator) → TerrainOutput

Generate terrain geometry.

Returns:

TerrainOutput containing spawn origin and list of geometries.

__init__(proportion: float = 1.0, size: tuple[float, float] = (10.0, 10.0)) → None

class mjlab.terrains.BoxInvertedPyramidStairsTerrainCfg

Bases: BoxPyramidStairsTerrainCfg

BoxInvertedPyramidStairsTerrainCfg(proportion: ‘float’ = 1.0, size: ‘tuple[float, float]’ = (10.0, 10.0), *, border_width: ‘float’ = 0.0, step_height_range: ‘tuple[float, float]’, step_width: ‘float’, platform_width: ‘float’ = 1.0, holes: ‘bool’ = False)

Methods:

function(difficulty, spec, rng)	Generate terrain geometry.
__init__([proportion, size, border_width, ...])

function(difficulty: float, spec: MjSpec, rng: Generator) → TerrainOutput

Generate terrain geometry.

Returns:

TerrainOutput containing spawn origin and list of geometries.

__init__(proportion: float = 1.0, size: tuple[float, float] = (10.0, 10.0), *, border_width: float = 0.0, step_height_range: tuple[float, float], step_width: float, platform_width: float = 1.0, holes: bool = False) → None

class mjlab.terrains.BoxPyramidStairsTerrainCfg

Bases: SubTerrainCfg

Configuration for a pyramid stairs terrain.

Attributes:

border_width
step_height_range
step_width
platform_width
holes

Methods:

function(difficulty, spec, rng)	Generate terrain geometry.
__init__([proportion, size, border_width, ...])

border_width: float = 0.0

step_height_range: tuple[float, float]

step_width: float

platform_width: float = 1.0

holes: bool = False

function(difficulty: float, spec: MjSpec, rng: Generator) → TerrainOutput

Generate terrain geometry.

Returns:

TerrainOutput containing spawn origin and list of geometries.

__init__(proportion: float = 1.0, size: tuple[float, float] = (10.0, 10.0), *, border_width: float = 0.0, step_height_range: tuple[float, float], step_width: float, platform_width: float = 1.0, holes: bool = False) → None

class mjlab.terrains.BoxRandomGridTerrainCfg

Bases: SubTerrainCfg

BoxRandomGridTerrainCfg(proportion: ‘float’ = 1.0, size: ‘tuple[float, float]’ = (10.0, 10.0), *, grid_width: ‘float’, grid_height_range: ‘tuple[float, float]’, platform_width: ‘float’ = 1.0, holes: ‘bool’ = False, merge_similar_heights: ‘bool’ = False, height_merge_threshold: ‘float’ = 0.05, max_merge_distance: ‘int’ = 3)

Attributes:

grid_width
grid_height_range
platform_width
holes
merge_similar_heights
height_merge_threshold
max_merge_distance

Methods:

function(difficulty, spec, rng)	Generate terrain geometry.
__init__([proportion, size, platform_width, ...])

grid_width: float

grid_height_range: tuple[float, float]

platform_width: float = 1.0

holes: bool = False

merge_similar_heights: bool = False

height_merge_threshold: float = 0.05

max_merge_distance: int = 3

function(difficulty: float, spec: MjSpec, rng: Generator) → TerrainOutput

Generate terrain geometry.

Returns:

TerrainOutput containing spawn origin and list of geometries.

__init__(proportion: float = 1.0, size: tuple[float, float] = (10.0, 10.0), *, grid_width: float, grid_height_range: tuple[float, float], platform_width: float = 1.0, holes: bool = False, merge_similar_heights: bool = False, height_merge_threshold: float = 0.05, max_merge_distance: int = 3) → None

class mjlab.terrains.SubTerrainCfg

Bases: ABC

SubTerrainCfg(proportion: ‘float’ = 1.0, size: ‘tuple[float, float]’ = (10.0, 10.0))

Attributes:

proportion
size

Methods:

function(difficulty, spec, rng)	Generate terrain geometry.
__init__([proportion, size])

proportion: float = 1.0

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

abstractmethod function(difficulty: float, spec: MjSpec, rng: Generator) → TerrainOutput

Generate terrain geometry.

Returns:

TerrainOutput containing spawn origin and list of geometries.

__init__(proportion: float = 1.0, size: tuple[float, float] = (10.0, 10.0)) → None

class mjlab.terrains.TerrainGenerator

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 (patches get random difficulty) or curriculum (difficulty increases along rows for progressive training).

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.

Methods:

__init__(cfg[, device])
compile(spec)

__init__(cfg: TerrainGeneratorCfg, device: str = 'cpu') → None

compile(spec: MjSpec) → None

class mjlab.terrains.TerrainGeneratorCfg

Bases: object

TerrainGeneratorCfg(*, seed: ‘int | None’ = None, curriculum: ‘bool’ = False, size: ‘tuple[float, float]’, border_width: ‘float’ = 0.0, border_height: ‘float’ = 1.0, num_rows: ‘int’ = 1, num_cols: ‘int’ = 1, color_scheme: “Literal[‘height’, ‘random’, ‘none’]” = ‘height’, sub_terrains: ‘dict[str, SubTerrainCfg]’ = <factory>, difficulty_range: ‘tuple[float, float]’ = (0.0, 1.0), add_lights: ‘bool’ = False)

Attributes:

seed
curriculum
size
border_width
border_height
num_rows
num_cols
color_scheme
sub_terrains
difficulty_range
add_lights

Methods:

__init__(*[, seed, curriculum, ...])

seed: int | None = None

curriculum: bool = False

size: tuple[float, float]

border_width: float = 0.0

border_height: float = 1.0

num_rows: int = 1

num_cols: int = 1

color_scheme: Literal['height', 'random', 'none'] = 'height'

sub_terrains: dict[str, SubTerrainCfg]

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

add_lights: bool = False

__init__(*, seed: int | None = None, curriculum: bool = False, size: tuple[float, float], border_width: float = 0.0, border_height: float = 1.0, num_rows: int = 1, num_cols: int = 1, color_scheme: ~typing.Literal['height', 'random', 'none'] = 'height', sub_terrains: dict[str, ~mjlab.terrains.terrain_generator.SubTerrainCfg] = <factory>, difficulty_range: tuple[float, float] = (0.0, 1.0), add_lights: bool = False) → None

class mjlab.terrains.TerrainImporter

Bases: object

A class to handle terrain geometry and import it into the simulator.

We assume that a terrain geometry comprises of sub-terrains that are arranged in a grid with num_rows rows and num_cols columns. The terrain origins are the positions of the sub-terrains where the robot should be spawned.

Based on the configuration, the terrain importer handles computing the environment origins from the sub-terrain origins. In a typical setup, the number of sub-terrains num_rows x num_cols is smaller than the number of environments num_envs. In this case, the environment origins are computed by sampling the sub-terrain origins.

Methods:

__init__(cfg, device)
import_ground_plane(name)
configure_env_origins([origins])	Configure the origins of the environments based on the added terrain.
update_env_origins(env_ids, move_up, move_down)	Update the environment origins based on the terrain levels.
randomize_env_origins(env_ids)	Randomize the environment origins to random sub-terrains.

Attributes:

spec

__init__(cfg: TerrainImporterCfg, device: str) → None

property spec: MjSpec

import_ground_plane(name: str) → None

configure_env_origins(origins: ndarray | Tensor | None = None)

Configure the origins of the environments based on the added terrain.

update_env_origins(env_ids: Tensor, move_up: Tensor, move_down: Tensor)

Update the environment origins based on the terrain levels.

randomize_env_origins(env_ids: Tensor) → None

Randomize the environment origins to random sub-terrains.

This randomizes both the terrain level (row) and terrain type (column), useful for play/evaluation mode where you want to test on varied terrains.

class mjlab.terrains.TerrainImporterCfg

Bases: object

Configuration for terrain import and environment placement.

Attributes:

terrain_type	Type of terrain to generate.
terrain_generator	Configuration for procedural terrain generation.
env_spacing	Distance between environment origins when using grid layout.
max_init_terrain_level	Maximum initial difficulty level (row index) for environment placement in curriculum mode.
num_envs	Number of parallel environments to create.

Methods:

__init__([terrain_type, terrain_generator, ...])

terrain_type: Literal['generator', 'plane'] = 'plane'

Type of terrain to generate. “generator” uses procedural terrain with sub-terrain grid, “plane” creates a flat ground plane.

terrain_generator: TerrainGeneratorCfg | None = None

Configuration for procedural terrain generation. Required when terrain_type is “generator”.

env_spacing: float | None = 2.0

Distance between environment origins when using grid layout. Required for “plane” terrain or when no sub-terrain origins exist.

max_init_terrain_level: int | None = None

Maximum initial difficulty level (row index) for environment placement in curriculum mode. None uses all available rows.

num_envs: int = 1

Number of parallel environments to create. This will get overriden by the scene configuration if specified there.

__init__(terrain_type: Literal['generator', 'plane'] = 'plane', terrain_generator: TerrainGeneratorCfg | None = None, env_spacing: float | None = 2.0, max_init_terrain_level: int | None = None, num_envs: int = 1) → None