mjlab.terrains

mjlab.terrains#

Classes

Core#

class mjlab.terrains.TerrainEntity[source]#

Bases: Entity

Terrain entity.

The terrain is a grid of sub-terrain patches (num_rows x num_cols), each with a spawn origin. When num_envs exceeds the number of patches, environment origins are sampled from the sub-terrain origins.

Note

Environment allocation for procedural terrain: Columns (terrain types) are distributed across environments by proportion (matching each sub-terrain’s proportion field) when a TerrainGeneratorCfg is available, or evenly when it is not. Rows (difficulty levels) are randomly sampled. This means multiple environments can spawn on the same (row, col) patch, leaving others unoccupied, even when num_envs > num_patches.

See FAQ: “How does env_origins determine robot layout?”

__init__(cfg: TerrainEntityCfg, device: str) → None[source]#

configure_env_origins(origins: ndarray | Tensor | None = None, proportions: ndarray | None = None) → None[source]#: Configure the origins of the environments based on the terrain.

update_env_origins(env_ids: Tensor, move_up: Tensor, move_down: Tensor) → None[source]#: Update the environment origins based on the terrain levels.

randomize_env_origins(env_ids: Tensor) → None[source]#: Randomize the environment origins to random sub-terrains.

class mjlab.terrains.TerrainEntityCfg[source]#

Configuration for terrain as an entity.

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 overridden by the scene configuration if specified there.

textures: tuple[spec_cfg.TextureCfg, ...]#: Textures for the ground plane. Defaults to a checker pattern. Set to () to disable textures (e.g. when using dr.geom_rgba).

materials: tuple[spec_cfg.MaterialCfg, ...]#: Materials for the ground plane. Defaults to the checker material. Set to () to disable materials (e.g. when using dr.geom_rgba).

lights: tuple[spec_cfg.LightCfg, ...]#: Lights for the scene. Defaults to a directional sun light.

build() → TerrainEntity[source]#

Build entity instance from this config.

Override in subclasses to return custom Entity types.

class mjlab.terrains.TerrainGenerator[source]#

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.

__init__(cfg: TerrainGeneratorCfg, device: str = 'cpu') → None[source]#

class mjlab.terrains.TerrainGeneratorCfg[source]#

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.

border_width: float = 0.0#: Width of the flat border around the entire terrain grid, in meters.

border_height: float = 1.0#: Height of the border wall around the terrain grid, in meters.

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.

color_scheme: Literal['height', 'random', 'none'] = 'height'#: Coloring strategy for terrain geometry. “height” colors by elevation, “random” assigns random colors, “none” uses uniform gray.

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 mjlab.terrains.SubTerrainCfg[source]#

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.

abstractmethod function(difficulty: float, spec: MjSpec, rng: Generator) → TerrainOutput[source]#

Generate terrain geometry.

Returns:: TerrainOutput containing spawn origin and list of geometries.

class mjlab.terrains.FlatPatchSamplingCfg[source]#

Configuration for sampling flat patches on a heightfield surface.

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.

Heightfield Terrains#

class mjlab.terrains.HfDiscreteObstaclesTerrainCfg[source]#

mjlab.terrains

Contents

mjlab.terrains#

Core#

Heightfield Terrains#

Primitive (Box) Terrains#