v1.1.1-rc2; add README

2026-01-27 20:52:01 +08:00
parent 777f688cfe
commit f98b75bdf9
3 changed files with 409 additions and 78 deletions
--- a/CMD.md
+++ b/CMD.md
@@ -1,4 +1,15 @@
+# CMD for RoboGauge
+
+- [Single Pipeline](#single-pipeline): Evaluate metrics in a single run
+- [Multi Pipeline](#multi-pipeline): Evaluate metrics in multiple runs with different seeds and environment parameters
+- [Level Pipeline](#level-pipeline): Evaluate metrics across different terrain levels to find the maximum level the policy can handle
+- [Stress Pipeline](#stress-pipeline): Evaluate metrics across different terrain types and environment parameters to test policy robustness
+- [Radar/Bar Plot](#radarbar-plot): Plot Multi Run results in Radar and Bar charts
+- [Terrain Levels Plot](#terrain-levels-plot): Plot terrain levels analysis
+
 # Single Pipeline
+Evaluate metrics in a single run
+
 ```bash
 # Default goals: max_velocity, diagonal_velocity
 python robogauge/scripts/run.py \
@@ -18,6 +29,8 @@ python robogauge/scripts/run.py \
 ```

 # Multi Pipeline
+Evaluate metrics in multiple runs with different seeds and environment parameters
+
 ```bash
 python robogauge/scripts/run.py \
    --task go2_moe.flat \
@@ -45,6 +58,8 @@ python robogauge/scripts/run.py \
 ```

 # Level Pipeline
+Evaluate metrics across different terrain levels to find the maximum level the policy can handle
+
 ```bash
 # Must specify single frictions for LevelPipeline!
 python robogauge/scripts/run.py \
@@ -59,6 +74,8 @@ python robogauge/scripts/run.py \
 ```

 # Stress Pipeline
+Evaluate metrics across different terrain types and environment parameters to test policy robustness
+
 ```bash
 python robogauge/scripts/run.py \
    --task go2_moe \
@@ -74,15 +91,15 @@ python robogauge/scripts/run.py \
 ```

 # Radar/Bar Plot
-将Multi Run结果绘制在雷达图中
+Plot Multi Run results in Radar and Bar charts
 ```bash
-# 可选--out保存到图片
+# Optional: --out to save to image
 python robogauge/utils/visualize/plot_radar_and_bar.py \
    aggregated_results_1.yaml \
    aggregated_results_2.yaml \
    --out logs/1.jpg

-# 绘制下全部 *.yaml, 可选range控制radar, bar y轴显示范围
+# plot all results in a directory, range for radar and bar y-axis
 python robogauge/utils/visualize/plot_radar_and_bar.py \
    /home/xfy/Coding/robot_gauge/mytest/results \
    --range 0.35 1.0 \
@@ -91,7 +108,7 @@ python robogauge/utils/visualize/plot_radar_and_bar.py \

 # Terrain Levels Plot
 ```bash
-# 绘制5种可变等级的地形与摩擦系数的关系图
+# plot 5 types of terrains with varying levels and friction coefficients
 python robogauge/utils/visualize/plot_terrain_levels.py \
    aggregated_results_1.yaml \
    aggregated_results_2.yaml \
--- a/README.md
+++ b/README.md
@@ -1,19 +1,49 @@
-# Robot Gauge

-本仓库提供一系列**强化学习训练的运动控制模型指标**, 目标是衡量模型的以下信息, 以衡量Sim2Real间隙:
- 鲁棒性: 随机变化地形, 地面类型(环境摩擦、弹性系数), 模型是否能继续稳定控制
- 稳定性: 电机出力是否合理, 长时间运行是否导致电机过热, 是否出现极端关节位置
- 控制稳定性及准确性: 对于速度追踪指令, 能否准确追踪; 对于目标点指令, 到达误差大小
+<div align="center">
+	<h1 align="center">RoboGauge</h1>
+	<p align="center">
+		<span>🌎 English</span> | <a href="README_zh.md">🇨🇳 中文</a>
+	</p>
+</div>

-能间接地衡量模型部署在真机上的效果, 该流程使用Mujoco进行自动化指标评测, 全部代码基于Python实现.
+This repository provides a suite of **motion-control evaluation for reinforcement-learning locomotion policies**. The goal is to measure the following aspects of a policy, so we can partially predict Sim2Real performance and reduce the risk of damaging real hardware:

-## 支持机器人
-| 机器人型号 | 机器人类型 | 速度追踪指令 |
+- **Robustness**: Under randomized terrains and ground types (e.g., friction / restitution), can the policy keep controlling stably?
+- **Stability**: Are motor outputs reasonable? Does long-horizon execution risk motor overheating? Does it reach extreme joint positions?
+- **Control stability & accuracy**: For velocity-tracking commands, can it track accurately? For target-point commands, how large is the final tracking error?
+
+The evaluation is automated with MuJoCo and implemented fully in Python.
+
+Demo of the evaluation process (4 terrains, 2 difficulty levels):
+
+<table style="width: 100%; text-align: center;">
+	<tr>
+		<td><b>Wave</b></td>
+		<td><b>Slope</b></td>
+	</tr>
+	<tr>
+		<td><img src="https://raw.githubusercontent.com/robogauge/picture-bed/refs/heads/main/robogague/robogauge_wave.gif" width="100%"></td>
+		<td><img src="https://raw.githubusercontent.com/robogauge/picture-bed/refs/heads/main/robogague/robogauge_slope.gif" width="100%"></td>
+	</tr>
+	<tr>
+		<td><b>Stairs</b></td>
+		<td><b>Obstacles</b></td>
+	</tr>
+	<tr>
+		<td><img src="https://raw.githubusercontent.com/robogauge/picture-bed/refs/heads/main/robogague/robogauge_stairs.gif" width="100%"></td>
+		<td><img src="https://raw.githubusercontent.com/robogauge/picture-bed/refs/heads/main/robogague/robogauge_obstaces.gif" width="100%"></td>
+	</tr>
+</table>
+
+## Supported Robots
+
+| Robot | Type | Velocity Tracking |
 | - | - | - |
-| Unitree go2 | 四足 | ✅ |
+| Unitree go2 | Quadruped | ✅ |

-## 安装
-推荐安装`python=3.8`, 参考[PyTorch官网](https://pytorch.org/get-started/locally/)安装2.0以上任意版本, 安装本仓库
+## Installation
+
+Recommended environment: `python=3.8`. Install any PyTorch version >= 2.0 following the [official PyTorch guide](https://pytorch.org/get-started/locally/), then install this repo:

 ```bash
 git clone https://github.com/wty-yy/RoboGauge.git
@@ -21,92 +51,177 @@ cd RoboGauge
 pip install -e .
 ```

-## 目录结构
- `robogauge/scripts`: 启动指标测试程序
- `robogauge/tasks`: 定义测试任务
- `robogauge/utils`: 常用工具
+## Usage

-## 指标/目标/地形
-指标的计算方法是通过在环境中发送固定指令及持续时长, 通过Mujoco获取所需参数并计算.
+### Run evaluations directly

-### 环境参数
-#### 域随机化
-所有的评测指标都会先配置相应的域随机化参数, 在随机参数下进行评测, 以下为常用的域随机化参数
+We provide four evaluation modes: **Single Pipeline**, **Multi Pipeline**, **Level Pipeline**, and **Stress Pipeline**. Compute cost increases gradually, and parallel execution is supported to speed up evaluation. See examples in [CMD.md](./CMD.md).

-| 参数名称 | 变量名 | 范围 |
+### Asynchronous evaluation during training
+
+Start the evaluation server:
+
+```bash
+python robogauge/scripts/server.py
+```
+
+Key arguments:
+
+- `--port`: server port (default: `9973`)
+- `--num-processes`: total number of evaluation processes (default: `30`)
+
+The client `robogauge/scripts/client.py` submits evaluation requests to the server and returns results. Example:
+
+```python
+from robogauge.scripts.client import RoboGaugeClient
+
+# Create client and submit a test task
+client = RoboGaugeClient(f"http://127.0.0.1:9973")
+task_id = client.submit_task(
+		model_path=test_payload["model_path"],
+		step=test_payload["step"],
+		task_name=test_payload["task_name"],
+		experiment_name=test_payload["experiment_name"],
+		wait_for_server=True
+)
+
+# Monitor task status and get results
+while True:
+		client.monitor_tasks()
+		for task_id, resp in client.response_data.items():
+				scores = resp['results']['scores']
+				print("[RoboGaugeClient]📊 Scores:")
+				print(json.dumps(scores, indent=2, ensure_ascii=False))
+		client.response_data.clear()
+		time.sleep(5)
+```
+
+Example integration: `update_robogauge` in [`go2_rl_gym - on_policy_runner.py`](https://github.com/wty-yy/go2_rl_gym/blob/f9024e807758d497445857a21dce3b266876f375/rsl_rl/rsl_rl/runners/on_policy_runner.py#L252)
+
+> You can launch training with evaluation enabled via `python legged_gym/scripts/train.py --task=xxx --robogauge`. The trainer waits for the evaluation client to be available. Results are saved under `logs/{experiment_name}` and visualized in TensorBoard.
+
+## Metrics / Goals / Terrains
+
+Metrics are computed by sending fixed commands to the environment for a fixed duration, reading required signals from MuJoCo, and aggregating them.
+
+### Environment Parameters
+
+#### Domain Randomization
+
+All evaluations are run with configured domain randomization (DR). Below are commonly used DR parameters:
+
+| Parameter | Variable | Range |
 | - | - | - |
-| 电机动作执行随机延迟 | `action delay` | `<= RL控制间隔` |
-| base负重 | `base mass` | `-1, 0, 1, 2, 3 kg` |
-| 地面摩擦力 | `friction` | `0.4, 0.7, 1.0, 1.3, 1.6` |
+| Random action execution delay | `action delay` | `<= RL control interval` |
+| Base payload mass | `base mass` | `-1, 0, 1, 2, 3 kg` |
+| Ground friction | `friction` | `0.4, 0.7, 1.0, 1.3, 1.6` |

-#### 地形
-1. 支持legged_gym中的部分地形, 包括: `wave, slope, stairs up, stairs down, obstacles, flat`, 除`flat`地形外其他地形可进行难度系数提升
-2. 地面类型 (影响接触摩擦系数, 弹性摩擦系数), 包括: 橡胶地, 木地板, 瓷砖地
+#### Terrains

-### 指标
-目前在每个`env.step`后可度量的指标, 所有指标均要求**越大越好**, 目前支持:
+1. Supports a subset of terrains from `legged_gym`, including: `wave, slope, stairs up, stairs down, obstacles, flat`. All terrains except `flat` can be evaluated with increasing difficulty levels.
+2. Ground material types (affecting contact friction / restitution) include: rubber, wooden floor, tile.

-| # | 指标名称 Metrics | 描述 | 包含的超参数 | 归一化系数 | 变化 |
+### Metrics
+
+Supported per-step metrics (measured after each `env.step`). **All metrics are normalized so that higher is better**:
+
+| # | Metric | Description | Hyper-parameters | Normalization | Transform |
 | - | - | - | - | - | - |
-| 1 | `dof_limits` | 关节超出软关节范围的大小 | 软关节范围阈值 | 总关节变化范围 | `1-x` |
-| 2 | `lin_vel_err` | 线速度L2误差 | NA | 总线速度指令范围 | `1-x` |
-| 3 | `ang_vel_err` | 角速度L2误差 | NA | 总角速度指令范围 | `1-x` |
-| 4 | `dof_power` | 电机耗能 | 缩放系数 | 100 | `1-x` |
-| 5 | `orientation_stability` | 机身姿态稳定性 (Roll) | NA | NA | `1-x` |
-| 6 | `torque_smoothness` | 力矩平滑度 | 缩放系数 | 30 | `1-x` |
+| 1 | `dof_limits` | Magnitude of joint excursions beyond soft limits | Soft-limit threshold | Total joint range | `1-x` |
+| 2 | `lin_vel_err` | L2 error of linear velocity tracking | NA | Total commanded linear-velocity range | `1-x` |
+| 3 | `ang_vel_err` | L2 error of angular velocity tracking | NA | Total commanded angular-velocity range | `1-x` |
+| 4 | `dof_power` | Motor energy consumption | Scaling factor | 100 | `1-x` |
+| 5 | `orientation_stability` | Body orientation stability (Roll) | NA | NA | `1-x` |
+| 6 | `torque_smoothness` | Torque smoothness | Scaling factor | 30 | `1-x` |

-### 速度追踪目标
-针对在虚实迁移中发现的问题, 整理指标 (metrics) 内容如下:
+### Velocity-Tracking Targets

-| # | 描述 | 标准化范围 | 对应真机问题 | 地形 |
+Based on common issues observed in Sim2Real transfer, we organize metrics and their corresponding real-robot risks as follows:
+
+| # | Description | Normalization | Real-robot issue | Terrain |
 | - | - | - | - | - |
-| 1 | 关节出现极端值的比例 | 关节范围 | 移动时发生危险的高抬腿行为 | Any |
-| 2 | 线速度与指令速度的L2误差 | 最大线速度指令 | 移动时可能无法达到指定速度 | Any |
-| 3 | 角速度与指令速度的L2误差 | 最大角速度指令 | 移动时可能无法达到指定速度 | Any |
-| 4 | 高速移动/速度对角突变base高度变化 | 固定高度 | 高速移动时机身存在趴低问题, 速度发生对角突变时无法平衡 | 平地 |
-| 5 | 高速移动急停稳定性 | 固定用时 | 楼梯上静止时, 关节不稳定 | Any |
+| 1 | Ratio of extreme joint values | Joint range | Dangerous high-stepping behavior during motion | Any |
+| 2 | L2 error between linear velocity and command | Max linear command | Might fail to reach the requested speed | Any |
+| 3 | L2 error between angular velocity and command | Max angular command | Might fail to reach the requested yaw rate | Any |
+| 4 | Base-height variation at high speed / diagonal command jumps | Fixed height | Body crouches at high speed; loses balance when diagonal command flips | Flat |
+| 5 | Stability after emergency stop at high speed | Fixed duration | Joints become unstable when standing still (e.g., on stairs) | Any |

-总结速度最总目标 (goals) 如下:
+Summary of velocity-related goals:

-| # | 目标名称 Goals | 描述 | reset条件 | 最大reset次数 |
+| # | Goal | Description | Reset condition | Max resets |
 | - | - | - | - | - |
-| 1 | `max_velocity` | 单一维度的最大线/角速度 | 每次执行一个方向的指令, 再急停 | 6 |
-| 2 | `diagonal_velocity` | 对角线速度变化 | 每次执行一对对角指令 | 8 |
-| 3 | `target_pos_velocity` | 比例差分控制到达目标位置 | 到达目标位置或超时 | 1 |
+| 1 | `max_velocity` | Maximum linear / angular speed along a single axis | Run one-direction command then hard stop | 6 |
+| 2 | `diagonal_velocity` | Diagonal velocity changes | Execute a pair of diagonal commands | 8 |
+| 3 | `target_pos_velocity` | Reach a target position via PD control | Target reached or timeout | 1 |

-## 创建新任务
-评测任务注册在[`tasks/__init__.py`](./robogauge/tasks/__init__.py)中完成, 包含四个部分:
- BasePipline: 标准Pipline一般无需修改
- MujocoConfig: 仿真器配置文件, 一般无需修改
- BaseGaugeConfig: 指标配置文件, 参考下文创建新指标
- RobotConfig: 机器人配置文件, 参考下文创建新机器人
-### 新指标
-在`robogauge/tasks/gauge`下创建新的场景、评估指标
-### 新机器人
-在`robogauge/tasks/robots`下创建新机器人、配置控制模型, 参考`go2`配置
- [go2.py](./robogauge/tasks/robots/go2/go2.py)控制模型, 包含观测构建和动作输出两个函数, 继承`BaseRobot`
- [go2_config.py](./robogauge/tasks/robots/go2/go2_config.py)配置文件, 包含机器人模型xml路径, 控制模型路径, 观测构建参数, 关节映射顺序, 各类缩放系数, 控制频率等
+## Create a New Task

-## 注意事项
-### 导入新机器人/控制模型
-1. 在Robot中创建新的机器人xml文件时, 需包含力矩控制`actuator`, 传感器`sensor - jointpos, jointvel, imu (framequat, gyro, accelerometer)`, 参考[`go2.xml`](resources/robots/go2/go2.xml), **注意: actuator的顺序需要和joint顺序一致, 该顺序称为mujoco关节顺序**
-2. 控制模型相关位置位于[`RobotConfig.control`](robogauge/tasks/robots/base_robot_config.py)中, 不同仿真中关节顺序可能不同, 需保证`mj2model_dof_indices`从mujoco映射到模型训练的关节次序配置正确 (IsaacGym次序和Mujoco相同), 其他模型配置需保持一致
+Tasks are registered in [robogauge/tasks/__init__.py](./robogauge/tasks/__init__.py). A evaluation task consists of four parts:

-## 代码架构
-### Pipeline逻辑
+- **BasePipeline**: the standard pipeline (usually no changes needed)
+- **MujocoConfig**: simulator configuration (usually no changes needed)
+- **BaseGaugeConfig**: metric configuration (see below to add new metrics)
+- **RobotConfig**: robot configuration (see below to add a new robot)

-[BasePipeline](./robogauge/tasks/pipeline/base_pipeline.py)用于管理仿真`sim`, 度量器(控制指令, 指标计算)`gauge`, 机器人运控模型`robot`三者的调度, 并包含异常处理, 域随机化, 观测噪声的添加.
+### Add a New Metric
+
+Create a new scenario / metric implementation under `robogauge/tasks/gauge`.
+
+### Add a New Robot
+
+Create a new robot implementation and control-model configuration under `robogauge/tasks/robots`. See the `go2` example:
+
+- [go2.py](./robogauge/tasks/robots/go2/go2.py): control wrapper (inherits `BaseRobot`), implements observation construction and action output
+- [go2_config.py](./robogauge/tasks/robots/go2/go2_config.py): config including robot XML path, control-model path, observation params, joint mapping order, scaling factors, control rate, etc.
+
+## Notes
+
+### Importing a New Robot / Control Model
+
+1. When creating a new robot XML, it must include torque-control `actuator` and sensors: `sensor - jointpos, jointvel, imu (framequat, gyro, accelerometer)`. See [resources/robots/go2/go2.xml](resources/robots/go2/go2.xml). **Important**: actuator order must match joint order (this is referred to as the MuJoCo joint order).
+2. Control-model related configuration is in [robogauge/tasks/robots/base_robot_config.py](robogauge/tasks/robots/base_robot_config.py) under `RobotConfig.control`. Joint orders may differ across simulators; ensure `mj2model_dof_indices` correctly maps MuJoCo joint order to the joint order used during training (IsaacGym uses the same order as MuJoCo). Keep other model configs consistent.
+
+## Code Architecture
+
+## Directory Structure
+
+- `robogauge/`: core Python package
+	- `robogauge/scripts/`: runnable entry scripts (run evaluation / start server)
+	- `robogauge/tasks/`: task system (sim config + metrics/scenes + robot + scheduling)
+		- `robogauge/tasks/pipeline/`: scheduling & execution layer (lifecycle, DR, parallel seeds, aggregation)
+		- `robogauge/tasks/gauge/`: gauge layer (command generation, metric computation, result aggregation)
+		- `robogauge/tasks/robots/`: robot adapters (obs/action, joint mapping, model loading, control rate)
+		- `robogauge/tasks/simulator/`: simulator wrappers / environment interfaces (MuJoCo integration, stepping, state access)
+		- `robogauge/tasks/custom/`: project-specific extensions and custom tasks
+	- `robogauge/utils/`: utilities (logging, config/file helpers, stats, math)
+- `resources/`: simulation static assets
+	- `resources/robots/`: robot assets (XML / meshes / textures), organized by robot type
+	- `resources/terrains/`: terrain assets (e.g., `flat.xml`, slope/stairs/wave/obstacle variants)
+	- `resources/models/`: policy/model resources
+- `assets/`: documentation assets
+- `scripts/`: helper shell scripts for running experiments
+
+### Pipeline Logic
+
+[BasePipeline](./robogauge/tasks/pipeline/base_pipeline.py) manages scheduling among the simulator `sim`, the gauge (command generation + metric computation) `gauge`, and the locomotion policy wrapper `robot`. It also includes exception handling, domain randomization, and observation noise.

 ![robogauge_basepipeline](./assets/robogauge_basepipeline.png)

-[MultiPipeline](./robogauge/tasks/pipeline/multi_pipeline.py)用于多进程启动不同seed, 域随机化参数下的`BasePipeline`, 并合并结果文件.
+[MultiPipeline](./robogauge/tasks/pipeline/multi_pipeline.py) launches `BasePipeline` in multiple processes across different seeds and DR parameter sets, then merges result files.

-[LevelPipeline](./robogauge/tasks/pipeline/level_pipeline.py)对于当前的环境配置, 找到环境地形下模型能稳定通过(三个seed均通过)的最高地形难度.
+[LevelPipeline](./robogauge/tasks/pipeline/level_pipeline.py) searches, for the current environment configuration, the highest terrain difficulty that the policy can stably pass (all three seeds pass).

 ![robogauge_levelpipeline](./assets/robogauge_levelpipeline.png)

-## 可能的报错
-### Mujoco OpenGL Context Error
+## Common Errors
+
+### MuJoCo OpenGL Context Error
+
 ```mujoco.FatalError: an OpenGL platform library has not been loaded into this process, this most likely means that a valid OpenGL context has not been created before mjr_makeContext was called```
-问题原因: Mujoco在无头模式下无法创建OpenGL上下文
-解决方案: 在`robogauge/scripts/run.py`和`robogauge/scripts/server.py`中, 将`os.environ['MUJOCO_GL']`设置为`egl`(GPU)或`osmesa`(CPU, 慢)
+
+Cause: MuJoCo cannot create an OpenGL context in headless mode.
+
+Fix: In `robogauge/scripts/run.py` and `robogauge/scripts/server.py`, set `os.environ['MUJOCO_GL']` to `egl` (GPU) or `osmesa` (CPU, slower).
+
+## Thanks
+Thanks to [@windigal](https://github.com/windigal) for editing the videos.
--- a/README_zh.md
+++ b/README_zh.md
@@ -0,0 +1,199 @@
+<div align="center">
+	<h1 align="center">RoboGauge</h1>
+	<p align="center">
+		<a href="README.md">🌎 English</a> | <span>🇨🇳 中文</span>
+	</p>
+</div>
+
+本仓库提供一系列**强化学习训练的运动控制模型指标**, 目标是衡量模型的以下信息, 从而能一定程度预测模型Sim2Real的结果, 避免损坏真机:
+- 鲁棒性: 随机变化地形, 地面类型(环境摩擦、弹性系数), 模型是否能继续稳定控制
+- 稳定性: 电机出力是否合理, 长时间运行是否导致电机过热, 是否出现极端关节位置
+- 控制稳定性及准确性: 对于速度追踪指令, 能否准确追踪; 对于目标点指令, 到达误差大小
+
+能间接地衡量模型部署在真机上的效果, 该流程使用Mujoco进行自动化指标评测, 全部代码基于Python实现.
+
+评估过程展示，四种地形及两种难度展示:
+<table style="width: 100%; text-align: center;">
+  <tr>
+    <td><b>Wave</b></td>
+    <td><b>Slope</b></td>
+  </tr>
+  <tr>
+    <td><img src="https://raw.githubusercontent.com/robogauge/picture-bed/refs/heads/main/robogague/robogauge_wave.gif" width="100%"></td>
+    <td><img src="https://raw.githubusercontent.com/robogauge/picture-bed/refs/heads/main/robogague/robogauge_slope.gif" width="100%"></td>
+  </tr>
+  <tr>
+    <td><b>Stairs</b></td>
+    <td><b>Obstacles</b></td>
+  </tr>
+  <tr>
+    <td><img src="https://raw.githubusercontent.com/robogauge/picture-bed/refs/heads/main/robogague/robogauge_stairs.gif" width="100%"></td>
+    <td><img src="https://raw.githubusercontent.com/robogauge/picture-bed/refs/heads/main/robogague/robogauge_obstaces.gif" width="100%"></td>
+  </tr>
+</table>
+
+## 支持机器人
+| 机器人型号 | 机器人类型 | 速度追踪指令 |
+| - | - | - |
+| Unitree go2 | 四足 | ✅ |
+
+## 安装
+推荐安装`python=3.8`, 参考[PyTorch官网](https://pytorch.org/get-started/locally/)安装2.0以上任意版本, 安装本仓库
+
+```bash
+git clone https://github.com/wty-yy/RoboGauge.git
+cd RoboGauge
+pip install -e .
+```
+
+## 使用方法
+### 直接评测指标
+包含Single Pipeline, Multi Pipeline, Level Pipeline, Stress Pipeline四种评测方式, 计算量逐个提升, 可并行加快评估速度, 参考[CMD.md](./CMD.md)中的使用示例
+
+### 训练异步评估
+启动评估客户端，
+```bash
+python robogague/scripts/server.py
+```
+
+包含如下参数：
+- `--port`: 服务端口号, 默认`9973`
+- `--num-processes`: 评估总进程数, 默认`30`
+
+客户端`robogauge/scripts/client.py`会向服务端发送评测请求, 并返回评测结果, 参考下方使用示例
+```python
+from robogauge.scripts.client import RoboGaugeClient
+
+# Create client and submit a test task
+client = RoboGaugeClient(f"http://127.0.0.1:9973")
+task_id = client.submit_task(
+    model_path=test_payload["model_path"],
+    step=test_payload["step"],
+    task_name=test_payload["task_name"],
+    experiment_name=test_payload["experiment_name"],
+    wait_for_server=True
+)
+
+# Monitor task status and get results
+while True:
+    client.monitor_tasks()
+    for task_id, resp in client.response_data.items():
+        scores = resp['results']['scores']
+        print("[RoboGaugeClient]📊 Scores:")
+        print(json.dumps(scores, indent=2, ensure_ascii=False))
+    client.response_data.clear()
+    time.sleep(5)
+```
+
+使用例子：在[`go2_rl_gym - on_policy_runner.py`](https://github.com/wty-yy/go2_rl_gym/blob/f9024e807758d497445857a21dce3b266876f375/rsl_rl/rsl_rl/runners/on_policy_runner.py#L252)中的`update_robogauge`函数
+
+> 可通过`python legged_gym/scripts/train.py --task=xxx --robogauge`启动带有评估的训练，会等待客户端启动，结果会在`logs/{experiment_name}`目录下保存，并绘制tensorboard
+
+## 指标/目标/地形
+指标的计算方法是通过在环境中发送固定指令及持续时长, 通过Mujoco获取所需参数并计算.
+
+### 环境参数
+#### 域随机化
+所有的评测指标都会先配置相应的域随机化参数, 在随机参数下进行评测, 以下为常用的域随机化参数
+
+| 参数名称 | 变量名 | 范围 |
+| - | - | - |
+| 电机动作执行随机延迟 | `action delay` | `<= RL控制间隔` |
+| base负重 | `base mass` | `-1, 0, 1, 2, 3 kg` |
+| 地面摩擦力 | `friction` | `0.4, 0.7, 1.0, 1.3, 1.6` |
+
+#### 地形
+1. 支持legged_gym中的部分地形, 包括: `wave, slope, stairs up, stairs down, obstacles, flat`, 除`flat`地形外其他地形可进行难度系数提升
+2. 地面类型 (影响接触摩擦系数, 弹性摩擦系数), 包括: 橡胶地, 木地板, 瓷砖地
+
+### 指标
+目前在每个`env.step`后可度量的指标, 所有指标均要求**越大越好**, 目前支持:
+
+| # | 指标名称 Metrics | 描述 | 包含的超参数 | 归一化系数 | 变化 |
+| - | - | - | - | - | - |
+| 1 | `dof_limits` | 关节超出软关节范围的大小 | 软关节范围阈值 | 总关节变化范围 | `1-x` |
+| 2 | `lin_vel_err` | 线速度L2误差 | NA | 总线速度指令范围 | `1-x` |
+| 3 | `ang_vel_err` | 角速度L2误差 | NA | 总角速度指令范围 | `1-x` |
+| 4 | `dof_power` | 电机耗能 | 缩放系数 | 100 | `1-x` |
+| 5 | `orientation_stability` | 机身姿态稳定性 (Roll) | NA | NA | `1-x` |
+| 6 | `torque_smoothness` | 力矩平滑度 | 缩放系数 | 30 | `1-x` |
+
+### 速度追踪目标
+针对在虚实迁移中发现的问题, 整理指标 (metrics) 内容如下:
+
+| # | 描述 | 标准化范围 | 对应真机问题 | 地形 |
+| - | - | - | - | - |
+| 1 | 关节出现极端值的比例 | 关节范围 | 移动时发生危险的高抬腿行为 | Any |
+| 2 | 线速度与指令速度的L2误差 | 最大线速度指令 | 移动时可能无法达到指定速度 | Any |
+| 3 | 角速度与指令速度的L2误差 | 最大角速度指令 | 移动时可能无法达到指定速度 | Any |
+| 4 | 高速移动/速度对角突变base高度变化 | 固定高度 | 高速移动时机身存在趴低问题, 速度发生对角突变时无法平衡 | 平地 |
+| 5 | 高速移动急停稳定性 | 固定用时 | 楼梯上静止时, 关节不稳定 | Any |
+
+总结速度最总目标 (goals) 如下:
+
+| # | 目标名称 Goals | 描述 | reset条件 | 最大reset次数 |
+| - | - | - | - | - |
+| 1 | `max_velocity` | 单一维度的最大线/角速度 | 每次执行一个方向的指令, 再急停 | 6 |
+| 2 | `diagonal_velocity` | 对角线速度变化 | 每次执行一对对角指令 | 8 |
+| 3 | `target_pos_velocity` | 比例差分控制到达目标位置 | 到达目标位置或超时 | 1 |
+
+## 创建新任务
+评测任务注册在[`tasks/__init__.py`](./robogauge/tasks/__init__.py)中完成, 包含四个部分:
+- BasePipline: 标准Pipline一般无需修改
+- MujocoConfig: 仿真器配置文件, 一般无需修改
+- BaseGaugeConfig: 指标配置文件, 参考下文创建新指标
+- RobotConfig: 机器人配置文件, 参考下文创建新机器人
+### 新指标
+在`robogauge/tasks/gauge`下创建新的场景、评估指标
+### 新机器人
+在`robogauge/tasks/robots`下创建新机器人、配置控制模型, 参考`go2`配置
+- [go2.py](./robogauge/tasks/robots/go2/go2.py)控制模型, 包含观测构建和动作输出两个函数, 继承`BaseRobot`
+- [go2_config.py](./robogauge/tasks/robots/go2/go2_config.py)配置文件, 包含机器人模型xml路径, 控制模型路径, 观测构建参数, 关节映射顺序, 各类缩放系数, 控制频率等
+
+## 注意事项
+### 导入新机器人/控制模型
+1. 在Robot中创建新的机器人xml文件时, 需包含力矩控制`actuator`, 传感器`sensor - jointpos, jointvel, imu (framequat, gyro, accelerometer)`, 参考[`go2.xml`](resources/robots/go2/go2.xml), **注意: actuator的顺序需要和joint顺序一致, 该顺序称为mujoco关节顺序**
+2. 控制模型相关位置位于[`RobotConfig.control`](robogauge/tasks/robots/base_robot_config.py)中, 不同仿真中关节顺序可能不同, 需保证`mj2model_dof_indices`从mujoco映射到模型训练的关节次序配置正确 (IsaacGym次序和Mujoco相同), 其他模型配置需保持一致
+
+## 代码架构
+
+## 目录结构
+
+- `robogauge/`：核心 Python 包
+	- `robogauge/scripts/`：可执行入口脚本（运行评测 / 启动服务端）
+	- `robogauge/tasks/`：任务系统（仿真配置 + 指标/场景 + 机器人 + 调度执行）
+		- `robogauge/tasks/pipeline/`：调度与执行层（生命周期、域随机化、多 seed 并行、结果聚合）
+		- `robogauge/tasks/gauge/`：指标层（指令生成、指标计算、结果汇总）
+		- `robogauge/tasks/robots/`：机器人适配层（观测/动作、关节映射、模型加载、控制频率）
+		- `robogauge/tasks/simulator/`：仿真器封装 / 环境接口（MuJoCo 集成、step、状态读取等）
+		- `robogauge/tasks/custom/`：项目自定义扩展与自定义任务
+	- `robogauge/utils/`：工具库（日志、配置/文件处理、统计、数学工具）
+
+- `resources/`：仿真静态资源
+	- `resources/robots/`：机器人资源（XML / mesh / 纹理等），按机器人型号组织
+	- `resources/terrains/`：地形资源（如 `flat.xml`、slope/stairs/wave/obstacle 等）
+	- `resources/models/`：策略/模型资源
+
+- `assets/`：文档资源
+- `scripts/`：实验运行的辅助 shell 脚本
+
+### Pipeline逻辑
+
+[BasePipeline](./robogauge/tasks/pipeline/base_pipeline.py)用于管理仿真`sim`, 度量器(控制指令, 指标计算)`gauge`, 机器人运控模型`robot`三者的调度, 并包含异常处理, 域随机化, 观测噪声的添加.
+
+![robogauge_basepipeline](./assets/robogauge_basepipeline.png)
+
+[MultiPipeline](./robogauge/tasks/pipeline/multi_pipeline.py)用于多进程启动不同seed, 域随机化参数下的`BasePipeline`, 并合并结果文件.
+
+[LevelPipeline](./robogauge/tasks/pipeline/level_pipeline.py)对于当前的环境配置, 找到环境地形下模型能稳定通过(三个seed均通过)的最高地形难度.
+
+![robogauge_levelpipeline](./assets/robogauge_levelpipeline.png)
+
+## 可能的报错
+### Mujoco OpenGL Context Error
+```mujoco.FatalError: an OpenGL platform library has not been loaded into this process, this most likely means that a valid OpenGL context has not been created before mjr_makeContext was called```
+问题原因: Mujoco在无头模式下无法创建OpenGL上下文
+解决方案: 在`robogauge/scripts/run.py`和`robogauge/scripts/server.py`中, 将`os.environ['MUJOCO_GL']`设置为`egl`(GPU)或`osmesa`(CPU, 慢)
+
+## 致谢
+感谢[@windigal](https://github.com/windigal)剪辑视频