Work: 为 UniLab 增加 batch raycaster sensor 并迁移 mjlab rough terrain 任务

[TATP-233]

Work type

feature

Area

mujoco

Scope correction

本 issue 不应改动现有 G1WalkFlat、G1WalkRough、Go1/Go2 rough terrain 或已有 hfield height scan 任务的行为。实现应通过新增任务接入 mjlab raycaster rough terrain 迁移，避免扩大影响面。

mjlab 中实际使用 RayCastSensorCfg / terrain_scan 的 rough velocity 注册任务是：

• Mjlab-Velocity-Rough-Unitree-G1
• Mjlab-Velocity-Rough-Unitree-Go1

本 issue 先迁移 Mjlab-Velocity-Rough-Unitree-G1，在 UniLab 中新增 MuJoCo-only PPO 任务 G1WalkRoughRaycast，Hydra 入口为 task=g1_walk_rough_raycast/mujoco。Go1 raycaster rough 任务只作为已识别的 mjlab 使用者记录，不在本 issue 的迁移范围内。

Problem

当前 UniLab 已有 rough terrain 和 hfield height scan 路径，但还缺少与 mjlab G1 raycaster rough terrain 任务对齐的批量 raycaster sensor 能力。mjlab 的 Mjlab-Velocity-Rough-Unitree-G1 使用绑定到 G1 pelvis 的 yaw-aligned terrain ray scan，在 rough terrain velocity locomotion 中作为 actor/critic 观测的一部分；如果 UniLab 只依赖 hfield 采样或单 env Python loop，会限制任务迁移、训练吞吐和与 mjlab 配置的行为一致性。

需要在 UniLab 的 backend sensor contract 中补齐 batch raycaster sensor，让 MuJoCo 后端可以基于 mujoco-uni 的 batched multi_ray 能力一次性对所有 env 执行射线投射，并通过新增任务迁移 mjlab 的 G1 raycaster rough terrain 配置、观测和测试。

Deliverable

• 在 UniLab 增加 batch raycaster sensor 抽象，支持按 env 批量返回 ray distance / hit geom id，并按需要返回 normal。
• 在 MuJoCo backend 接入批量 raycaster 实现，优先使用 BatchEnvPool.multi_ray，避免每个 env 单独 Python loop。
• 定义 ray pattern / per-ray origin offset / origin frame / bodyexclude / geomgroup / cutoff 等配置入口，使新增 rough terrain 任务可以复用。
• 新增 G1WalkRoughRaycast 任务迁移 Mjlab-Velocity-Rough-Unitree-G1，尽量保持算法、任务、地形、机器人模型、课程学习和 PPO 配置一致。
• 不修改现有 G1WalkFlat、G1WalkRough 等任务的观测维度、注册后端或运行行为。
• 补充文档或示例，说明如何运行迁移后的 raycaster rough terrain 任务，并记录与 mjlab 的主要差异。

Definition of done

• SimBackend 层有明确的 raycaster sensor contract，env 层不直接调用 MuJoCo 私有实现。
• MuJoCo batch raycaster 在多 env 下返回形状稳定的数组，例如 (num_envs, num_rays)，并覆盖 mjlab grid raycast 所需的 per-ray local origin offsets 与 yaw-aligned shared direction。
• 新增 G1WalkRoughRaycast 可通过现有 Hydra/脚本入口启动，并能完成 reset、step 和 observation 构造。
• 新增或更新单元测试覆盖：raycaster 配置解析、backend 输出 shape、bodyexclude/geomgroup/cutoff 的基本行为、rough terrain 任务配置可实例化。
• 与现有 G1 walk / Go1-Go2 rough terrain / hfield height scan 路径不互相破坏，相关测试保持通过。
• 文档或任务说明包含运行命令、迁移自 Mjlab-Velocity-Rough-Unitree-G1、Go1 raycaster rough 未迁移，以及与 mjlab 任务的主要差异。

Dependencies and blockers

• BatchEnvPool.multi_ray 依赖 TestPyPI 上的 mujoco-uni==3.8.0.post1 或后续包含该接口的版本。该接口不能假设来自默认 pyproject.toml 依赖解析；本地验证 native MuJoCo raycaster 前需要显式安装 TestPyPI 构建，例如：

uv pip install --index-url https://test.pypi.org/simple \
  --extra-index-url https://pypi.org/simple \
  --index-strategy unsafe-best-match \
  mujoco-uni==3.8.0.post1

• mjlab 中 G1 raycaster rough terrain 的主要对齐点：PPO、G1 robot、pelvis raycast frame、GridPatternCfg(size=(1.6, 1.0), resolution=0.1) 的 187 条 yaw-aligned 垂直 terrain ray、rough terrain preset、terrain generator curriculum、velocity-command locomotion、actor/critic MLP [512, 256, 128]、24 steps/env、PPO epoch/minibatch、KL/GAE 和 30000 iterations。
• UniLab 新任务应通过新文件/继承实现，不把新增 raycaster 任务逻辑写入 src/unilab/envs/locomotion/g1/joystick.py。
• mjlab command 的 resampling_time_range=(3.0, 8.0) 在 UniLab 当前 Commands contract 中只能表达为固定 resampling_time；迁移任务使用中点 5.5 并保留 heading/standing/forward 比例配置。
• mjlab manager-based reward/event/contact terms 比 UniLab 现有 G1 joystick 契约更丰富；本 issue 在 UniLab 现有 G1 walk env contract 上迁移 raycaster rough PPO 任务，不在本 issue 中完整重写为 mjlab manager-based velocity env。
• mjlab 中只包含 PPO 算法，所以本 issue 只迁移 PPO 算法，不涉及 UniLab 中其他 RL 算法。
• 如需支持 Motrix 后端，需要先确认 Motrix 是否有等价批量 raycast API；否则本 issue 先限定 MuJoCo backend，并在 contract 中声明其他 backend 的未实现行为。

Proposed owner

TBD

Validation plan

• 后端级别：构造简单 plane/box 场景，比较 batch raycaster 与 MuJoCo 单 env mj_multiRay 参考输出，或用 fake BatchEnvPool.multi_ray 覆盖参数透传和 shape 校验。
• 任务级别：运行新增 G1WalkRoughRaycast reset/step smoke test，检查 observation shape、无 NaN、ray distance 范围合理。
• 回归级别：运行 locomotion config tests、terrain generator tests、MuJoCo backend smoke tests，特别确认原有 G1 walk / Go1-Go2 rough 任务不受影响。
• 性能级别：对比 batch raycaster 与 Python env loop，在典型 num_envs x num_rays 配置下记录吞吐。

[TATP-233]

Implementation note from branch fix/issue-627-batch-raycaster: the issue states that mujoco-uni 3.8.0.post1 provides BatchEnvPool.multi_ray, but the current repo environment under uv run exposes BatchEnvPool.sample_hfield_height and does not expose BatchEnvPool.multi_ray. I am treating the UniLab-side raycaster contract as valid, but the MuJoCo native adapter must be feature-detected and should fail with a clear dependency error until the mujoco-uni package/version exposing multi_ray is confirmed or pinned.

[TATP-233]

Correction to my previous implementation note: the BatchEnvPool.multi_ray API is expected from the TestPyPI package mujoco-uni==3.8.0.post1, not from the default dependency resolution in this repo's pyproject.toml. Local validation for this issue should explicitly install/use that TestPyPI build before exercising the native MuJoCo raycaster path.