mjlab/docs/source/terrain.rst

.. _terrain:

Terrain
=======

The terrain is the shared ground surface for all environments in a scene.
mjlab supports two modes: a flat ground plane for tasks that do not need
varying terrain, and a procedural terrain generator that assembles a grid
of sub-terrain patches with configurable difficulty. Procedural terrain
is particularly useful for training locomotion policies, where a
curriculum of increasing ground difficulty drives robust walking and
climbing behaviors.

Terrain is configured through ``TerrainEntityCfg`` and passed to the
scene via the ``terrain`` field of ``SceneCfg``. See :ref:`scene` for
how the terrain integrates with the rest of the scene.


Flat terrain
------------

The default mode. A single ground plane modeled as a MuJoCo plane geom
with no procedural geometry. Environments are arranged in a regular grid
with spacing controlled by ``env_spacing`` on ``SceneCfg``.

.. code-block:: python

    from mjlab.terrains import TerrainEntityCfg

    terrain = TerrainEntityCfg(terrain_type="plane")


Procedural terrain
------------------

For tasks that benefit from terrain variety (locomotion, navigation),
``TerrainGeneratorCfg`` assembles a rectangular grid of sub-terrain
patches. Each patch is generated from a ``SubTerrainCfg`` that defines
the geometry and how it scales with difficulty.

.. code-block:: python

    from mjlab.terrains import TerrainEntityCfg
    from mjlab.terrains.terrain_generator import TerrainGeneratorCfg
    import mjlab.terrains as terrain_gen

    terrain = TerrainEntityCfg(
        terrain_type="generator",
        terrain_generator=TerrainGeneratorCfg(
            size=(8.0, 8.0),
            num_rows=10,
            border_width=20.0,
            curriculum=True,
            sub_terrains={
                "flat": terrain_gen.BoxFlatTerrainCfg(proportion=0.2),
                "stairs": terrain_gen.BoxPyramidStairsTerrainCfg(
                    proportion=0.4,
                    step_height_range=(0.0, 0.15),
                    step_width=0.3,
                    platform_width=2.0,
                ),
                "rough": terrain_gen.HfRandomUniformTerrainCfg(
                    proportion=0.4,
                    noise_range=(0.02, 0.10),
                    noise_step=0.02,
                ),
            },
        ),
        max_init_terrain_level=5,
    )

The generator creates a grid of patches sized ``num_rows`` by either
``num_cols`` (random mode) or ``len(sub_terrains)`` (curriculum mode,
where ``num_cols`` is ignored). The ``sub_terrains`` dictionary maps
names to ``SubTerrainCfg`` instances; each sub-terrain's ``proportion``
controls robot spawning distribution across columns in curriculum mode,
or per-patch sampling probability in random mode.


Grid layout
^^^^^^^^^^^

Two generation modes control how terrain types are distributed across
the grid:

**Curriculum mode** (``curriculum=True``). Each terrain type gets exactly
one column; the generator uses ``len(sub_terrains)`` columns regardless of
``num_cols``. All patches in a column share the same terrain type, and
difficulty increases from row 0 (easiest) to row ``num_rows - 1``
(hardest). The ``proportion`` field controls how robots are distributed
across columns at spawn time, not column count. This structured layout
is what enables the curriculum system to advance environments to harder
rows as performance improves.

**Random mode** (``curriculum=False``). Every patch independently samples
a terrain type weighted by ``proportion`` and a difficulty from
``difficulty_range``. ``num_cols`` is honored. This provides maximum
variety but no structured difficulty progression.


The difficulty parameter
^^^^^^^^^^^^^^^^^^^^^^^^

Each sub-terrain's generation function receives a ``difficulty`` value
that linearly interpolates the terrain's configurable ranges. For
example, a ``BoxPyramidStairsTerrainCfg`` with
``step_height_range=(0.0, 0.2)`` produces flat ground at difficulty 0
and 20 cm steps at difficulty 1.

In curriculum mode, difficulty is determined by the row:
``difficulty = lower + (upper - lower) * row / max(num_rows - 1, 1)``,
where ``(lower, upper) = difficulty_range``. Row 0 is exactly
``lower``, row ``num_rows - 1`` is exactly ``upper``, and intermediate
rows are evenly spaced between them. All columns in a given row share
the same difficulty scalar; the visible variation across columns comes
from each sub-terrain type generating different geometry at the same
difficulty.

.. note::

   With ``num_rows=1`` and ``curriculum=True``, every patch is generated
   at ``difficulty = lower`` (the easiest configured difficulty). Use
   ``curriculum=False`` if you want a single grid of randomly sampled
   difficulties instead.

In random mode, difficulty is sampled uniformly from
``difficulty_range`` independently for every patch.


Sub-terrain types
-----------------

mjlab provides two families of sub-terrain types: **primitive terrains**
built from box geoms, and **heightfield terrains** built from continuous
elevation grids. All types inherit from ``SubTerrainCfg`` and accept a
``proportion`` weight and optional ``flat_patch_sampling`` configuration.


Primitive terrains
^^^^^^^^^^^^^^^^^^

Procedural patches built entirely from box geoms. The discrete geometry
makes them well suited for staircases, stepping stones, and other
structured obstacles. Most primitive types share common parameters:
``platform_width`` (central flat area), ``border_width`` (flat margin),
and one or more difficulty-scaled ranges.

.. grid:: 3

   .. grid-item-card:: Flat

      .. image:: _static/terrains/box_flat.png

      Flat box patch. Useful as an easy baseline in a curriculum grid.

   .. grid-item-card:: Pyramid Stairs

      .. image:: _static/terrains/box_pyramid_stairs.png

      Pyramid staircase with steps descending inward toward a central
      platform.

   .. grid-item-card:: Inverted Pyramid Stairs

      .. image:: _static/terrains/box_inverted_pyramid_stairs.png

      Inverted pyramid with steps ascending from the outside inward.

   .. grid-item-card:: Random Stairs

      .. image:: _static/terrains/box_random_stairs.png

      Pyramid staircase with random per-step heights.

   .. grid-item-card:: Open Stairs

      .. image:: _static/terrains/box_open_stairs.png

      Concentric step rings. Can be a bowl or pyramid depending on the
      ``inverted`` flag.

   .. grid-item-card:: Random Grid

      .. image:: _static/terrains/box_random_grid.png

      Grid of boxes at randomly sampled heights.

   .. grid-item-card:: Random Spread

      .. image:: _static/terrains/box_random_spread.png

      Randomly positioned and rotated boxes of varying sizes scattered
      across the patch.

   .. grid-item-card:: Stepping Stones

      .. image:: _static/terrains/box_stepping_stones.png

      Stepping-stone columns rising from a deep pit.

   .. grid-item-card:: Narrow Beams

      .. image:: _static/terrains/box_narrow_beams.png

      Radial beams extending outward from a central platform above a
      pit.

   .. grid-item-card:: Tilted Grid

      .. image:: _static/terrains/box_tilted_grid.png

      Grid of independently tilted mesh tiles.

   .. grid-item-card:: Nested Rings

      .. image:: _static/terrains/box_nested_rings.png

      Concentric ring structures at random heights.


Heightfield terrains
^^^^^^^^^^^^^^^^^^^^

Continuous terrain profiles built from MuJoCo heightfield geoms. The
surface is a dense grid of elevation samples, producing smooth slopes
and undulating ground that box geoms cannot represent.

.. grid:: 3

   .. grid-item-card:: Pyramid Slope

      .. image:: _static/terrains/hf_pyramid_slope.png

      Smooth pyramid slope with a flat platform at the peak.
      ``inverted=True`` places the platform at the bottom.

   .. grid-item-card:: Random Uniform

      .. image:: _static/terrains/hf_random_uniform.png

      Random uniform noise, optionally downsampled and interpolated to
      control feature size.

   .. grid-item-card:: Wave

      .. image:: _static/terrains/hf_wave.png

      Sinusoidal wave profile.

   .. grid-item-card:: Discrete Obstacles

      .. image:: _static/terrains/hf_discrete_obstacles.png

      Rectangular bumps and pits scattered across a flat base.

   .. grid-item-card:: Perlin Noise

      .. image:: _static/terrains/hf_perlin_noise.png

      Fractal Perlin noise producing natural terrain undulation.


Preset configurations
---------------------

mjlab ships three ready-made ``TerrainGeneratorCfg`` presets in
``mjlab.terrains.config``:

``ROUGH_TERRAINS_CFG``
    A 10x20 random-mode grid with seven terrain types (flat, stairs,
    inverted stairs, slopes, inverted slopes, random rough, waves).
    Designed for locomotion training with a moderate difficulty range.
    Set ``curriculum=True`` via ``dataclasses.replace`` to use it as a
    curriculum grid (one column per terrain type).

``STAIRS_TERRAINS_CFG``
    A 10-row curriculum grid focused on stair traversal: flat plus
    three pyramid-stair variants of increasing difficulty.

``ALL_TERRAINS_CFG``
    A 10-row random-mode grid covering all available terrain types at
    equal proportion. Useful for training on maximum terrain variety.

Both can be used directly or customized with ``dataclasses.replace()``:

.. code-block:: python

    from dataclasses import replace
    from mjlab.terrains.config import ROUGH_TERRAINS_CFG

    my_terrains = replace(ROUGH_TERRAINS_CFG, num_rows=5)


Terrain curriculum
------------------

In curriculum mode the terrain grid provides a natural axis for
progressive training: rows represent difficulty levels, and the
curriculum system moves environments up or down the grid based on
performance. See :ref:`curriculum` for full details on configuring
curriculum terms.

The key concepts:

- Each environment tracks a ``terrain_level`` (row index) and
  ``terrain_type`` (column index).
- ``TerrainEntityCfg.max_init_terrain_level`` controls how high
  environments can start at their first reset. Setting it to 5 means
  environments begin on rows 0 through 5.
- The built-in ``terrain_levels_vel`` curriculum term promotes
  environments that track commanded velocity well and demotes
  environments that fall or fail to make progress.
- When an environment is promoted past the hardest row, it is randomly
  reassigned to any row in ``[0, num_rows)`` to prevent the policy from
  collapsing to a single difficulty level.


Flat patch detection
--------------------

Heightfield terrains can pre-compute flat regions on their surface during
generation. These flat patches are useful as safe spawn points for tasks
that require the robot to start on level ground, even on otherwise rough
terrain.

Flat patch detection is configured per sub-terrain via the
``flat_patch_sampling`` field on ``SubTerrainCfg``:

.. code-block:: python

    from mjlab.terrains.terrain_generator import FlatPatchSamplingCfg

    rough = terrain_gen.HfRandomUniformTerrainCfg(
        proportion=0.5,
        noise_range=(0.02, 0.10),
        flat_patch_sampling={
            "spawn": FlatPatchSamplingCfg(
                num_patches=10,
                patch_radius=0.5,
                max_height_diff=0.05,
            ),
        },
    )

The detection algorithm uses morphological filtering to find circular
regions where height variation stays within ``max_height_diff``. Detected
patches are accessible at runtime through
``scene.terrain.flat_patches["spawn"]``.

To spawn robots on detected patches instead of at the sub-terrain center,
use ``reset_root_state_from_flat_patches`` as the reset event term. See
:ref:`events` for details.

.. note::

   Only heightfield (``Hf*``) terrains support flat patch detection.
   Primitive (``Box*``) terrains do not have heightfield data to analyze.
   If any sub-terrain in the grid configures ``flat_patch_sampling``,
   the flat patches array is allocated for all cells; sub-terrains
   without patches have their slots filled with the sub-terrain's spawn
   origin so that the reset event always receives valid positions.


Debug visualization
-------------------

The terrain entity adds debug sites to three geom groups that can be
toggled in the MuJoCo native viewer or Viser viewer:

- **Group 3**: flat patch sites (yellow boxes marking safe spawn regions)
- **Group 4**: environment origin sites (green spheres at each
  environment's position)
- **Group 5**: terrain origin sites (blue spheres at each sub-terrain
  patch center)

.. figure:: _static/terrains/flat_patch_group.png
   :width: 100%
   :align: center
   :alt: Flat patch visualization

   Flat patches (group 3) overlaid on a procedural terrain grid in the
   Viser viewer.