feat: 增强程序化地形生成——阶梯地形与地形组合

[wlgys8]

增强程序化地形生成：阶梯地形与地形组合

背景

当前 TerrainGeneratorCfg（motrix_env_core/src/motrix_env_core/config/scene/asset.py）只有
NoiseTerrainGeneratorCfg 一个实现，只能生成均匀噪声高度场。参照 Isaac Lab sub-terrain 的能力，
希望支持阶梯形地形与多种地形的组合，本期只聚焦 build 时的地形生成，不涉及训练侧
curriculum / 运行时按难度切换。

现有契约（保持不变）

• generator 输出归一化 [0, 1] 高度场，物理高度由 generator.height_scale 在 compiler 统一换算；
• generate(size, shape) 签名不变；compiler 只校验有限性与 shape，[0, 1] 由各 generator 自行保证。

方案

新增独立模块 motrix_env_core/src/motrix_env_core/config/scene/terrain.py，
TerrainGeneratorCfg 与现有 Noise 实现不动，新符号从 motrix_env_core.config.scene 公共门面导出。

1. 图元 generator

• FlatTerrainGeneratorCfg：平地，height: float = 0.0（归一化），作组合基底 / reset 区。
• StairsTerrainGeneratorCfg：规则台阶。
  • axis: "x" | "y"（x 沿 shape[0] 行、y 沿 shape[1] 列，实现时用方向性测试钉死并写入文档）；
  • profile: "ascending" | "descending" | "pyramid" | "inverted_pyramid"，
    其中 inverted_pyramid 即中央凹陷坑（对应 Isaac Lab 反金字塔台阶）；
  • step_count: int、step_height: float（米，任务语义）；
  • 校验 (step_count - 1) * step_height <= height_scale。
• DiscreteObstaclesTerrainGeneratorCfg：平坦基面（归一化 0.5）上随机散布矩形障碍，
  height 为正是凸块、为负是凹坑（单位米），尺寸 size_min/size_max 为全场比例，
  位置由 seed 采样、同 seed 可复现；校验 |height| <= 0.5 * height_scale。
  随机散布、无规则网格模式（规则阵列如有需要另立 issue）。
• QuantizedTerrainGeneratorCfg：包装任意子 generator，把归一化输出量化为
  levels 档（梯田/等高线地形）；source 自身 height_scale 被忽略，物理缩放由本类 height_scale 决定。

2. 组合 generator

• CompositeTerrainGeneratorCfg：base 铺底 + regions 依次覆盖（重叠时后写覆盖先写）。
• TerrainRegionCfg：center/size（全场比例坐标）、generator、blend（过渡带宽度比例，0 = 硬接），
  过渡带内线性混合，避免 hfield 垂直墙。
• 物理高度守恒：子 generator 输出按 sub.height_scale / composite.height_scale 重缩放后贴入，
  保证如台阶 step_height=0.05 m 嵌套后物理高度不变；composite 需 height_scale >= 所有子地形物理峰值，
  超出时 generate() 抛出明确错误（compiler 不查 [0,1]，须自行守界）。
• seed 由用户在各子 generator 上显式设置，不做隐式派生。

3. 棋盘布局辅助

grid_terrain() 工厂函数：把 rows × cols 的 cell generator 列表展开成 composite regions
（Isaac Lab 棋盘风格是 composite 的布局特例）。难度梯度由用户在 cells 中自行排列，
运行时难度切换不在本期范围。

4. 待定：blend 在场地边界的行为（讨论中）

区域横贯全场时，blend 过渡带同样在贴场边的那条边上生效，导致区域两端的贴入权重被压低
（台阶带两端被混出斜坡）。两个候选语义：

1. 维持现状：权重只由区域几何决定，规则最简单；
2. 贴边不 blend（倾向）：区域某条边贴住/超出场地边界时该边不做渐变，渐变只出现在
   两种地形的内部接缝上，符合"贴边 = 延伸到场外"的直觉。

验收要点

• 新 generator 经 OmegaConf.structured → to_object 往返可用（含嵌套 regions 元组），
  模式对齐现有 test_procedural_hfield_supports_hydra_overrides；
• 行为测试放 motrix_envs/tests/test_scene_cfg.py，只测契约：
  台阶级数 / 单调性 / inverted 中央最低、composite 区域覆盖与 blend 后仍在 [0, 1]、
  物理高度守恒、同 seed 可复现；
• 两个 backend compiler（MuJoCo / MotrixSim）无需改动即可消费新 generator。

[wlgys8]

与 IsaacLab 图元差距盘点（图元增强实现后更新）

对照 IsaacLab ROUGH_TERRAINS_CFG（demo 图 + hf_terrains.py / mesh_terrains_cfg.py 源码）。
本表为图元增强落地后的最新状态（替换前一条盘点的表格部分），对比验证材料见仓库 terrain_compare/。

图元（Sub-terrain）对比

Isaac Lab 图元	形状	我们的状态	剩余差距
HfRandomUniformTerrainCfg	均匀噪声	✅ NoiseTerrainGeneratorCfg + downsampled_scale（本轮新增，粗采样+双线性插值）	Isaac 的 noise_range 支持高度偏移（min>0）；我们起点固定为 0（可用组合抬高基底）。noise_step 量化用 QuantizedTerrainGeneratorCfg 包装实现
HfPyramidSlopedTerrainCfg / HfInvertedPyramidSloped...	平滑金字塔斜坡（正/反）	✅ PyramidSlopeTerrainGeneratorCfg（本轮新增：slope + inverted + platform_width）	Isaac 按 difficulty 插值 slope；我们由用户直接给定数值
HfPyramidStairsTerrainCfg	同心方环台阶（中心高台）	✅ StairsTerrainGeneratorCfg(axis="radial", profile="descending"/"pyramid", step_width, platform_width)（本轮新增物理踏面与平台）	每图元级 border_width（平坦缓冲带）暂无（现有 region blend 是斜坡过渡，语义不同）
HfInvertedPyramidStairsTerrainCfg	反金字塔（中央坑）	✅ 同上（profile="inverted_pyramid"，平台=坑底）	同上
HfDiscreteObstaclesTerrainCfg	随机凸块/凹坑	✅ DiscreteObstaclesTerrainGeneratorCfg(height_mode="choice", platform_width)（本轮新增）	无
HfSteppingStonesTerrainCfg	碎石桩	❌	按任务需求另立 issue
HfWaveTerrainCfg	波浪地形	❌	同上
MeshRandomGridTerrainCfg	规则网格凸台阵列	❌	跳格子/梅花桩场景需要
trimesh 类（带孔台阶、横梁、沟壑、深坑、悬浮环等）	mesh 专属形状	❌	依赖 trimesh 资产管线，建议独立评估

机制/配套能力对比

能力	Isaac Lab	我们的状态
多地形组合	sub_terrains + proportion 按比例分配	✅ CompositeTerrainGeneratorCfg（base + regions + blend）
网格平铺	num_rows × num_cols 天然网格	✅ grid_terrain()
同族难度梯度	difficulty 0→1 插值，每格一档	⚠️ 用户手动排 cells 参数；无 difficulty 插值机制
格间 border 缓冲	border_width（平坦缓冲带）	⚠️ 现有 region blend 是斜坡过渡，语义不同
平地 patch 采样	FlatPatchSamplingCfg	❌ 训练侧能力，暂缓
Curriculum 运行时换难度	TerrainImporter + env 重定位	❌ 训练侧，本期不做
生成结果缓存	use_cache	❌ 生成很快，暂无需要

结论

• hfield 六大核心图元已全部覆盖（噪声/斜坡/台阶/反台阶/离散障碍 + 平地），几何参数（step_height、
  step_width、platform_width、obstacle height_mode、slope、noise smoothing）与 Isaac Lab 对齐；
• 剩余差距集中在：① 每图元 border_width 平坦缓冲带；② 难度插值机制；③ 少量低频需求图元
  （stepping stones / wave / 规则网格凸台）；④ trimesh 资产管线（独立评估）。