Merge pull request #16 from KraHsu/feat/m3-terrain-curriculum

Add terrain_levels_vel curriculum + terrains concept page

Author: KraHsu

CHANGELOG.md

@@ -23,6 +23,16 @@ trajectory so breaking changes can land in any minor release until the 1.0 stabi
 - `TerrainImporter` gains `heightfield_tensor(device, dtype)` (device-keyed cache),
   `horizontal_scale`, `vertical_scale`, and `terrain_origin` accessors used by the
   ray-cast sampler.
+- `TerrainImporter` tracks per-env curriculum state via `terrain_levels` /
+  `terrain_cols` / `spawn_pos`; `init_per_env_state(num_envs, device)` is called once
+  by `InteractiveScene.build()` post-Genesis-build. `update_env_origins(env_ids)`
+  recomputes spawn origins after a level change.
+- `genelab.mdp.curriculums.terrain_levels_vel`: curriculum term that promotes /
+  demotes each env's terrain level by how far it walked from spawn (XY distance vs
+  configurable `distance_threshold` and `demote_ratio`), then writes the new spawn
+  pose into the sim via `Articulation.write_root_state`.
+- `docs/concepts/terrains.{en,zh}.md`: bilingual concept page covering the generator,
+  importer, sensor integration, curriculum, and known failure modes.
 - `genelab.actuator` namespace with `ActuatorBase` and three concrete electromechanical
   models: `ImplicitPDActuator` (Genesis-internal PD), `IdealPDActuator` (Python-side PD
   via `control_dofs_force`), `DCMotorActuator` (`IdealPD` plus driving-direction torque

docs/concepts/terrains.en.md

@@ -0,0 +1,123 @@
+# Terrains
+
+`genelab.terrains` is a thin GeneLab-shaped wrapper over Genesis's native
+`gs.morphs.Terrain` morph. Sub-terrain configs map onto Genesis's built-in subterrain
+string types, `TerrainGenerator` assembles them into a 2D grid, and `TerrainImporter`
+spawns the terrain into the scene plus tracks per-env curriculum state.
+
+## Why a dedicated layer
+
+Genesis ships the height-field terrain primitives, but its native API uses pydantic
+options keyed by string names (`"pyramid_stairs_terrain"`, `"random_uniform_terrain"`).
+A GeneLab cfg layer keeps the surface dataclass-shaped (matching the rest of the project),
+gives every sub-terrain a typed Python class with explicit fields, and tracks per-env
+spawn / level state so curriculum terms can promote and demote without touching the
+Genesis handle directly.
+
+## Three shipped sub-terrains
+
+| Class | Genesis type | Parameters |
+|---|---|---|
+| `FlatPatchCfg` | `flat_terrain` | none |
+| `PyramidStairsCfg` | `pyramid_stairs_terrain` | `step_width`, `step_height` |
+| `RandomRoughCfg` | `random_uniform_terrain` | `min_height`, `max_height`, `step`, `downsampled_scale` |
+
+`PyramidStairsCfg(step_height=-0.1)` builds concentric descending steps; positive
+`step_height` would invert the pyramid. `RandomRoughCfg` samples bumps at
+`downsampled_scale` then upsamples, so the apparent feature size is independent of
+`horizontal_scale`. Three more Genesis types (`sloped`, `wave`, `stepping_stones`) are
+not wrapped yet — extending `SubTerrainCfg` to expose them is a 20-line task.
+
+## Composing a terrain grid
+
+```python
+from genelab.terrains import (
+    FlatPatchCfg,
+    PyramidStairsCfg,
+    RandomRoughCfg,
+    TerrainGeneratorCfg,
+)
+from genelab.configs import InteractiveSceneCfg
+
+scene = InteractiveSceneCfg(
+    env_spacing=(0.0, 0.0),
+    terrain=TerrainGeneratorCfg(
+        num_rows=4,
+        num_cols=4,
+        subterrain_size=(8.0, 8.0),
+        horizontal_scale=0.1,
+        vertical_scale=0.005,
+        sub_terrains={
+            "flat": FlatPatchCfg(proportion=1.0),
+            "stairs": PyramidStairsCfg(step_width=0.5, step_height=-0.08, proportion=2.0),
+            "rough": RandomRoughCfg(min_height=-0.05, max_height=0.05, proportion=1.0),
+        },
+        curriculum=True,
+        seed=0,
+    ),
+)
+```
+
+`sub_terrains` is a `dict[str, SubTerrainCfg]`; the key is the local cfg label, the
+value carries the Genesis parameters. `layout` defaults to `None` (random tiling by
+`proportion`); pass a `tuple[tuple[str, ...], ...]` of cfg keys to pin the grid
+deterministically.
+
+!!! warning "One parameter set per Genesis type"
+    Genesis keys `subterrain_parameters` by the *type string*, not per cell. Two
+    `PyramidStairsCfg` instances with different `step_width` collapse to a single
+    parameter set. Use distinct keys for distinct geometries, or rely on
+    `randomize=True` on the importer for in-type variation.
+
+## Ray-cast sensor integration
+
+When `InteractiveSceneCfg.terrain` is set, `InteractiveScene.build()` spawns
+`gs.morphs.Terrain` instead of the default plane and exposes the importer as
+`scene.terrain`. `RayCastSensor` checks for it and, when present, bilinearly samples
+`terrain.heightfield_tensor` at each ray's world `(x, y)` to compute hit elevation.
+`TerrainHeightSensor` is a thin wrapper around the same path, so the per-link height
+scan output reflects the true terrain instead of a constant plane.
+
+Vertical and near-vertical rays match the underlying height field to within
+`vertical_scale`. Oblique rays use the elevation at the ray-start `(x, y)` — accurate
+for height-scan grids but approximate for BVH-style queries; override
+`RayCastSensor._intersect_world_rays` for those.
+
+## Curriculum: `terrain_levels_vel`
+
+```python
+from genelab.managers import CurriculumTermCfg
+from genelab.mdp import terrain_levels_vel
+
+curriculum_cfg = {
+    "terrain_levels": CurriculumTermCfg(
+        func=terrain_levels_vel,
+        params={"distance_threshold": 2.0, "demote_ratio": 0.5},
+    ),
+}
+```
+
+Each reset, the term compares every env's walked distance (XY norm of `root_pos -
+spawn_pos`) against `distance_threshold`. Envs that walked further than the threshold
+move up one row of the difficulty grid (capped at `num_rows - 1`); envs that walked
+less than `distance_threshold * demote_ratio` move down (floored at 0). The curriculum
+then writes the new spawn pose into the sim via `Articulation.write_root_state`, so
+the next episode starts on the new sub-terrain. The manager logs the mean level under
+`Curriculum/terrain_levels`.
+
+## Failure modes worth knowing
+
+* **Empty `sub_terrains`** — `TerrainGenerator.__init__` raises immediately; the
+  generator has nothing to tile.
+* **`layout` shape mismatch** — `ValueError` lists the actual vs declared shape.
+* **`layout` references unknown key** — `ValueError` lists the missing keys.
+* **Per-env state access before build** — `terrain_levels` / `terrain_cols` /
+  `spawn_pos` raise `RuntimeError` until `init_per_env_state` runs;
+  `InteractiveScene.build` calls it automatically.
+* **`heightfield` access before spawn** — `RuntimeError`; spawn first, then read.
+
+## See also
+
+- [Configs](configs.md)
+- [Sensors](sensors.md)
+- [Actuators](actuators.md)

docs/concepts/terrains.zh.md

@@ -0,0 +1,88 @@
+# 地形
+
+`genelab.terrains` 是 Genesis 原生 `gs.morphs.Terrain` morph 之上的一层 GeneLab 风格薄包装。子地形 cfg 对应 Genesis 内建的 subterrain 字符串类型，`TerrainGenerator` 把它们拼成一个二维网格，`TerrainImporter` 负责把地形 spawn 进场景并跟踪每个 env 的课程状态。
+
+## 为什么需要专门的一层
+
+Genesis 自带 height-field 地形原语，但其原生 API 使用按字符串名键控的 pydantic options（`"pyramid_stairs_terrain"`、`"random_uniform_terrain"`）。GeneLab 的 cfg 层把接口保持成 dataclass 形态（与项目其它部分一致），让每种子地形拥有带显式字段的 typed Python 类，并跟踪每个 env 的 spawn / level 状态，让课程项可以提升和降级而不直接接触 Genesis 句柄。
+
+## 自带 3 种子地形
+
+| 类 | Genesis 类型 | 参数 |
+|---|---|---|
+| `FlatPatchCfg` | `flat_terrain` | 无 |
+| `PyramidStairsCfg` | `pyramid_stairs_terrain` | `step_width`、`step_height` |
+| `RandomRoughCfg` | `random_uniform_terrain` | `min_height`、`max_height`、`step`、`downsampled_scale` |
+
+`PyramidStairsCfg(step_height=-0.1)` 生成一圈圈向下的同心方形台阶；正的 `step_height` 会反转金字塔方向。`RandomRoughCfg` 在 `downsampled_scale` 下采样后再上采样，所以表观特征尺寸与 `horizontal_scale` 无关。Genesis 还有另外 3 种类型（`sloped`、`wave`、`stepping_stones`）尚未包装 —— 扩展 `SubTerrainCfg` 暴露它们是一个 20 行的小活。
+
+## 拼装地形网格
+
+```python
+from genelab.terrains import (
+    FlatPatchCfg,
+    PyramidStairsCfg,
+    RandomRoughCfg,
+    TerrainGeneratorCfg,
+)
+from genelab.configs import InteractiveSceneCfg
+
+scene = InteractiveSceneCfg(
+    env_spacing=(0.0, 0.0),
+    terrain=TerrainGeneratorCfg(
+        num_rows=4,
+        num_cols=4,
+        subterrain_size=(8.0, 8.0),
+        horizontal_scale=0.1,
+        vertical_scale=0.005,
+        sub_terrains={
+            "flat": FlatPatchCfg(proportion=1.0),
+            "stairs": PyramidStairsCfg(step_width=0.5, step_height=-0.08, proportion=2.0),
+            "rough": RandomRoughCfg(min_height=-0.05, max_height=0.05, proportion=1.0),
+        },
+        curriculum=True,
+        seed=0,
+    ),
+)
+```
+
+`sub_terrains` 是 `dict[str, SubTerrainCfg]`；key 是本地 cfg 标签，value 携带 Genesis 参数。`layout` 默认为 `None`（按 `proportion` 随机平铺）；传入 `tuple[tuple[str, ...], ...]` 形态的 cfg key 二维表则可以确定性地固定网格。
+
+!!! warning "每个 Genesis 类型只有一套参数"
+    Genesis 的 `subterrain_parameters` 按*类型字符串*键控，而不是按单元格。两个 `step_width` 不同的 `PyramidStairsCfg` 实例会塌成单一一套参数。要区分几何就用不同的 key，要做同类型内变化就在 importer 上启用 `randomize=True`。
+
+## ray-cast 传感器接入
+
+当 `InteractiveSceneCfg.terrain` 被设置时，`InteractiveScene.build()` 会 spawn `gs.morphs.Terrain` 而不是默认 plane，并把 importer 暴露为 `scene.terrain`。`RayCastSensor` 检测到地形后，会对每条射线在世界坐标 `(x, y)` 处对 `terrain.heightfield_tensor` 做双线性采样，得到命中点高度。`TerrainHeightSensor` 是同一路径上的薄封装，所以每个关节的 height scan 输出反映的是真实地形而不是常数平面。
+
+垂直 / 接近垂直的射线，输出与底层 height field 的误差不超过 `vertical_scale`。斜射线使用射线起点 `(x, y)` 处的高度 —— 对 height-scan 网格足够准，但对 BVH 风格查询是近似的；这类场景请覆写 `RayCastSensor._intersect_world_rays`。
+
+## 课程项: `terrain_levels_vel`
+
+```python
+from genelab.managers import CurriculumTermCfg
+from genelab.mdp import terrain_levels_vel
+
+curriculum_cfg = {
+    "terrain_levels": CurriculumTermCfg(
+        func=terrain_levels_vel,
+        params={"distance_threshold": 2.0, "demote_ratio": 0.5},
+    ),
+}
+```
+
+每次 reset，该项把每个 env 的已走距离（`root_pos - spawn_pos` 在 XY 上的范数）与 `distance_threshold` 比较。走得超过阈值的 env 在难度网格中上移一行（封顶在 `num_rows - 1`）；走得不到 `distance_threshold * demote_ratio` 的 env 下移一行（地板在 0）。课程项随后通过 `Articulation.write_root_state` 把新 spawn 位姿写入仿真，下一个 episode 就从新子地形开始。manager 自动以 `Curriculum/terrain_levels` 记录平均 level。
+
+## 需要知道的失败模式
+
+* **`sub_terrains` 为空** —— `TerrainGenerator.__init__` 立刻抛错；生成器没东西可拼。
+* **`layout` 形状不匹配** —— `ValueError` 列出实际形状与声明形状。
+* **`layout` 引用未知 key** —— `ValueError` 列出缺失的 key。
+* **build 前访问 per-env 状态** —— `terrain_levels` / `terrain_cols` / `spawn_pos` 在 `init_per_env_state` 之前抛 `RuntimeError`；`InteractiveScene.build` 会自动调一次。
+* **spawn 前访问 `heightfield`** —— `RuntimeError`；先 spawn 再读。
+
+## See also
+
+- [Configs](configs.md)
+- [Sensors](sensors.md)
+- [Actuators](actuators.md)

mkdocs.yml

@@ -98,6 +98,7 @@ plugins:
             Registry: 注册表
             Configs: 配置系统
             Sensors: 传感器
+            Terrains: 地形
             Extensions: 扩展加载
             Examples: 示例
             Inverted Pendulum: 倒立摆
@@ -162,6 +163,7 @@ nav:
       - Configs: concepts/configs.md
       - Actuators: concepts/actuators.md
       - Sensors: concepts/sensors.md
+      - Terrains: concepts/terrains.md
       - Extensions: concepts/extensions.md
   - Examples:
       - Overview: examples/overview.md

src/genelab/mdp/__init__.py

@@ -8,6 +8,7 @@
     UniformVelocityCommand,
     UniformVelocityCommandCfg,
 )
+from genelab.mdp.curriculums import terrain_levels_vel
 from genelab.mdp.events import (
     push_by_setting_velocity,
     reset_joints_to_default,
@@ -104,6 +105,7 @@
     "robot_body_pos_b",
     "root_height_below",
     "sensor_data",
+    "terrain_levels_vel",
     "time_out",
     "track_angular_velocity_z_exp",
     "track_linear_velocity_xy_exp",

src/genelab/mdp/curriculums.py

@@ -0,0 +1,59 @@
+"""Reusable curriculum term functions: adapt difficulty / spawn distribution per episode."""
+
+from typing import TYPE_CHECKING
+
+import torch
+
+if TYPE_CHECKING:
+    from genelab.envs.manager_based_rl_env import ManagerBasedRlEnv
+
+
+def terrain_levels_vel(
+    env: "ManagerBasedRlEnv",
+    env_ids: torch.Tensor | slice | None,
+    distance_threshold: float,
+    demote_ratio: float = 0.5,
+) -> torch.Tensor:
+    """Promote / demote each env's terrain level by how far it walked from spawn.
+
+    Computes the horizontal (XY) distance between the env's current root position and
+    its last recorded spawn position. Envs that walked more than ``distance_threshold``
+    move up one level (capped at ``cfg.num_rows - 1``); envs that walked less than
+    ``distance_threshold * demote_ratio`` move down (floored at 0). Levels then drive a
+    fresh spawn origin lookup on the importer, and the curriculum writes the new root
+    pose into the sim so the next episode starts on the new sub-terrain.
+
+    No-op when ``env.scene.terrain`` is ``None``.
+
+    Returns the mean terrain level across all envs, so the curriculum manager logs it
+    under ``"Curriculum/<term-name>"`` automatically.
+    """
+    terrain = env.scene.terrain
+    if terrain is None:
+        return torch.zeros((), device=env.device)
+    # Curriculum manager passes ``None`` on the first frame and a 1D tensor on resets;
+    # ``slice`` is accepted for parity with the manager's type signature.
+    if env_ids is None or isinstance(env_ids, slice):
+        return terrain.terrain_levels.float().mean()
+    if env_ids.numel() == 0:
+        return terrain.terrain_levels.float().mean()
+
+    current_pos = env.articulation.data.root_pos[env_ids]
+    spawn_pos = terrain.spawn_pos[env_ids]
+    walked = torch.linalg.vector_norm(current_pos[:, :2] - spawn_pos[:, :2], dim=-1)
+
+    move_up = walked > distance_threshold
+    move_down = walked < distance_threshold * demote_ratio
+    delta = move_up.long() - move_down.long()
+    levels = terrain.terrain_levels
+    new_levels = (levels[env_ids] + delta).clamp(0, terrain.cfg.num_rows - 1)
+    levels[env_ids] = new_levels
+
+    new_origins = terrain.update_env_origins(env_ids)
+    n = int(env_ids.numel())
+    zero_quat = torch.zeros(n, 4, device=env.device)
+    zero_quat[:, 0] = 1.0
+    zero_vel = torch.zeros(n, 3, device=env.device)
+    env.articulation.write_root_state(new_origins, zero_quat, zero_vel, zero_vel, env_ids)
+
+    return levels.float().mean()

src/genelab/scene/interactive_scene.py

@@ -134,6 +134,8 @@ def build(self) -> None:
         for entity in self._entities.values():
             if isinstance(entity, Articulation):
                 entity.bind(self._num_envs, self._device)
+        if self._terrain is not None:
+            self._terrain.init_per_env_state(self._num_envs, self._device)
         self._built = True
 
     def _compute_env_origins(self) -> torch.Tensor: