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 evenly distributed across environments, but 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) → 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): Columns are deterministically assigned to terrain types based on proportions. All patches in a column share the same terrain type, with difficulty increasing along rows. Use this to ensure each terrain type occupies specific column(s).

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 column gets ONE terrain type (deterministic allocation). Difficulty increases along rows. Use this to ensure each terrain type occupies its own column(s).
curriculum=False: Every patch is randomly sampled from all terrain types. Proportions control sampling probability. Use this for random variety.

Example: With 2 terrain types and num_cols=2, curriculum=True gives one terrain per column. curriculum=False gives a random mix of both types in all patches.

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. Represents terrain type variants. Note: Environments are evenly distributed across columns (not random).

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#

Terrain type allocation weight (behavior depends on curriculum mode):

curriculum=True: Controls column allocation. Normalized proportions determine how many columns each terrain type occupies via cumulative distribution. Example: proportions [0.5, 0.5] with num_cols=2 gives one terrain per column.
curriculum=False: Sampling probability for each patch. Each patch independently samples a terrain type weighted by normalized proportions.

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#