质量评测算子
功能概述
数据集质量评测算子用于对机器人轨迹数据集进行全面质量评估与分析，覆盖安全、效率、平稳性三个核心维度，并生成数据质量PDF报告供用户在前端界面上查看。支持LeRobot V3和V2.1两种格式，若为V2.1格式则自动转换为V3格式后再进行评测。
核心能力：
- 安全维度：检测关节限位余量、末端最大线速度/角速度、关节最大角速度、最大加速度等安全指标，识别潜在越界或过快风险。
- 效率维度：统计任务执行时长、冻结时长、路径效率指数、抓取尝试次数，发现长尾与停滞问题。
- 平稳性维度：分析位置残差抖动、Jerk、对数无量纲Jerk（LDLJ）、动作抖动，评估轨迹平滑度。
输入： LeRobot格式数据集目录（支持V3和 V2.1，自动识别并转换）、机器人描述文件（URDF）和yml配置文件
输出： PDF格式的数据集质量评测报告
当前支持机型： Galaxea R1（星海图）
输入说明：数据集与配置文件
从界面上选择的机器人描述文件夹需包含
├── r1_robot.urdf ├── r1_robot.yml
数据集目录结构说明
质量评测算子可以用 LeRobot V2.1 或 V3 格式的数据集目录。输入路径可以是包含 meta 文件夹的父目录，也可以是 meta 文件夹所在的层级目录。
LeRobot V3 格式：
<dataset_dir>/ # 数据集根目录（输入路径）
├── data/
│ └── chunk-000/
│ ├── episode_000000.parquet # 轨迹数据
│ ├── episode_000001.parquet
│ └── ...
├── meta/
│ ├── info.json # 数据集基本信息（版本、帧率等）
│ ├── stats.json # 数据统计信息
│ ├── tasks.parquet # 任务定义（parquet格式）
│ └── episodes/ # Episode 元信息目录
└── videos/ # 视频数据
├── observation.images.front/
├── observation.images.wrist_left/
└── observation.images.wrist_right/ LeRobot V2.1 格式：
<dataset_dir>/ # 数据集根目录（输入路径） ├── data/ │ └── chunk-000/ │ ├── episode_000000.parquet # 轨迹数据 │ ├── episode_000001.parquet │ └── ... ├── meta/ │ ├── info.json # 数据集基本信息（版本、帧率等） │ ├── tasks.jsonl # 任务定义（jsonl格式） │ ├── episodes.jsonl # Episode 元信息 │ └── episodes_stats.jsonl # Episode 统计信息 ├── images/ # 图像数据（图片序列） │ ├── observation.images.front/ │ ├── observation.images.wrist_left/ │ └── observation.images.wrist_right/ └── videos/ # 视频数据（可选）
目前仅支持单数据集输入。
机器人描述文件（URDF）
URDF文件（如星海图的）描述机器人的运动学结构，包括所有link与joint的定义。评测工具从URDF中解析左右臂的运动链结构。
URDF 文件需包含关键Link如表1。
机器人配置文件（robot_config.yml）
YAML 配置文件定义了评测时使用的机器人运动链参数，完整示例如下：
robots:
robot_name: "Galaxea R1" # 机器人名称，目前仅支持 Galaxea R1
robot_type: "R1" # 机器人类型，目前仅支持 R1
base_frame: "base_link" # 机器人基座坐标系，默认 base_link，无需修改
left_arm_base_link: "left_arm_base_link" # 左臂运动链起点
right_arm_base_link: "right_arm_base_link" # 右臂运动链起点
left_tip_link: "left_tool_link" # 左臂末端工具坐标 link
right_tip_link: "right_tool_link" # 右臂末端工具坐标 link | 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| robot_name | string | 是 | 机器人名称，用于报告展示。 |
| robot_type | string | 是 | 机器人类型，目前仅支持R1。 |
| base_frame | string | 否 | 基座坐标系，默认base_link，作为模型元数据保存，实际FK链路不直接使用此字段。 |
| left_arm_base_link | string | 是 | 左臂运动链起点，代码从left_tool_link 往父节点回溯至此link，解析出左臂所有关节。 |
| right_arm_base_link | string | 是 | 右臂运动链起点，同理用于解析右臂链路。 |
| left_tip_link | string | 是 | 左臂末端工具坐标link，位于左夹爪后面，代表任务空间中的左手/末端执行器位置。 |
| right_tip_link | string | 是 | 右臂末端工具坐标link。 |
left_arm_base_link、right_arm_base_link、left_tip_link、right_tip_link的值必须与 URDF 文件中定义的 link 名称完全一致。
输出指标说明
输出指标分属安全、效率、平稳性三大维度。
安全维度（Safety）
| 指标代码 | 指标名称 | 方向 | 单位 | 说明 |
|---|---|---|---|---|
| m_min | 最小关节限位余量 | 越高越好 | ratio | 离关节限位越远越安全 |
| s_max | 末端最大线速度 | 越低越好 | m/s | 全程末端线速度峰值 |
| a_max | 末端最大线加速度 | 越低越好 | m/s² | 全程末端线加速度峰值 |
| u_max | 末端最大角速度 | 越低越好 | rad/s | 全程末端角速度峰值 |
| joint_omega_max | 关节最大角速度 | 越低越好 | rad/s | 全程关节角速度峰值 |
| alpha_max | 末端最大角加速度 | 越低越好 | rad/s² | 全程末端角加速度峰值 |
| 规则名称 | 等级 | 判定阈值 |
|---|---|---|
| 关节限位风险 | 严重 / 中等 / 良好 |
|
| 峰值速度关注 | 严重 / 中等 / 良好 |
|
| 关节最大速度 | 严重 / 中等 / 良好 |
|
效率维度（Efficiency）
| 指标代码 | 指标名称 | 方向 | 单位 | 说明 |
|---|---|---|---|---|
| T_ep | 任务执行时长 | 越低越好 | s | 每个 episode 总执行时长 |
| T_seg | 段执行时长 | 越低越好 | s | 当前无 subtask 标注时与 T_ep 等价（1 episode = 1 segment） |
| T_freeze | 最大冻结时长 | 越低越好 | s | 主运动手末端速度持续低于 0.005m/s时的最长连续时长 |
| PEI | 路径效率指数 | 越低越好 | ratio | 实际路径长度 / 直线位移，旋转类任务该指标会偏大 |
| N_grasp_provisional | 抓取尝试数（阈值法） | 任务相关 | count | 基于夹爪阈值识别的开合尝试次数，尚未结合物体状态 |
| 规则名称 | 等级 | 判定阈值 |
|---|---|---|
| 时长长尾 | 严重 / 中等 / 良好 | 通过p95/median判断长尾分布 |
| 冻结时长 | 严重 / 中等 / 良好 | 以主运动手线速度低于 0.005 m/s 作为冻结判定条件，统计其持续时间 p95 作为评估指标。
|
平稳性维度（Stability）
| 指标代码 | 指标名称 | 方向 | 单位 | 说明 |
|---|---|---|---|---|
| J_act | 动作抖动 | 越低越好 | action_unit/s | 动作输出一阶差分范数均值 |
| s_mean | 末端平均线速度 | 描述性 | m/s | 末端线速度均值 |
| s_std | 末端线速度波动 | 越低越好 | m/s | 末端线速度标准差 |
| a_mean | 末端平均线加速度 | 描述性 | m/s² | 末端线加速度均值 |
| a_std | 末端线加速度波动 | 越低越好 | m/s² | 末端线加速度标准差 |
| u_mean | 末端平均角速度 | 描述性 | rad/s | 末端角速度均值 |
| u_std | 末端角速度波动 | 越低越好 | rad/s | 末端角速度标准差 |
| alpha_mean | 末端平均角加速度 | 描述性 | rad/s² | 末端角加速度均值 |
| alpha_std | 末端角加速度波动 | 越低越好 | rad/s² | 末端角加速度标准差 |
| sigma_px | X 方向残差抖动 | 越低越好 | m | 末端位置残差在X轴的标准差 |
| sigma_py | Y 方向残差抖动 | 越低越好 | m | 末端位置残差在Y轴的标准差 |
| sigma_pz | Z 方向残差抖动 | 越低越好 | m | 末端位置残差在Z轴的标准差 |
| sigma_p_max | 最大位置残差抖动 | 越低越好 | m | 三轴残差标准差中的最大值 |
| J_max | 末端最大 Jerk | 越低越好 | m/s³ | 末端线Jerk峰值 |
| LDLJ | 对数无量纲 Jerk | 越高越好 | log_dimless | 整体平滑性指标 |
| 规则名称 | 等级 | 判定阈值 |
|---|---|---|
| 微抖动频带 | 严重 / 中等 / 良好 | 通过分布分析判断。 |
| Jerk 尖峰 | 严重 / 中等 / 良好 |
|
| 动作抖动 | 严重 / 中等 / 良好 |
|
| 位置残差抖动 | 严重 / 中等 / 良好 |
|
指标方向说明
| 方向 | 含义 |
|---|---|
| 越高越好 | 数值越大表示质量越好（如 m_min、LDLJ）。 |
| 越低越好 | 数值越小表示质量越好（如速度、加速度、抖动类指标）。 |
| 描述性指标 | 仅作上下文参考，不直接参与风险判定。 |
| 任务相关 | 指标含义与具体任务相关，无统一阈值。 |
风险等级说明
每个维度综合评测规则后输出一个风险等级。
| 等级 | 含义 |
|---|---|
| 良好（绿色） | 当前维度整体可控，未见明显风险。 |
| 中等（橙色） | 存在一定风险，建议关注并排查。 |
| 严重（红色） | 存在高等级风险，建议优先处理后再扩展评测范围。 |
PDF报告结构
PDF报告包含以下五个章节：
- 评估综述：三维度状态与总体结论
- 关键指标概览：安全、效率、平稳性三维度的指标、规则与结论
- 典型轨迹示例：中位数样本与异常样本对比
- 高阶分析：散点诊断图
- 附录：全量指标统计、规则说明、异常样本列表
评估综述
报告首页集中展示三维度状态与总体结论，用于快速建立整体判断。
页面顶部展示数据集基本信息卡片，随后展示三个维度的评估状态，最后给出总体结论，提示当前数据集是否存在高等级风险维度及建议处理优先级。
| 信息项 | 说明 |
|---|---|
| DATASET | 数据集名称 |
| EPISODES | 轨迹总数 |
| METRICS | 评测指标数量 |
| SCOPE | 分析范围（如 State-based analysis） |
| 维度 | 状态标签 | 关注指标 | 说明 |
|---|---|---|---|
| 安全（Safety） | 良好 / 中等 / 严重 | 关节限位余量、最大线速度、关节最大角速度 | 检测越界、过快等安全风险 |
| 效率（Efficiency） | 良好 / 中等 / 严重 | 任务时长、最大冻结时长、抓取尝试数 | 检测长尾、停滞等效率问题 |
| 平稳性（Stability） | 良好 / 中等 / 严重 | 位置残差抖动、最大 Jerk、对数无量纲 Jerk、动作抖动 | 检测轨迹平滑度异常 |
关键指标概览
按安全、效率、平稳性三维度依次展开，每个维度包含以下四个部分：
- 关键指标
表13 关键指标 字段
说明
分类
所属维度（安全 / 效率 / 平稳性）
指标代码
如m_min、s_max
指标名称
中文显示名
方向
越高越好 / 越低越好
单位
物理单位
中位数
所有episode该指标的中位数
风险分位
higher_better指标为P05，lower_better指标为 P95
最小值 / 最大值
全数据集范围
- 评测规则表
表14 评测规则表 字段
说明
规则名称
如“关节限位风险”“峰值速度关注”。
等级
良好（绿色）/ 中等（橙色）/ 严重（红色）
当前值
实际计算得到的统计值
判定阈值
各等级的阈值条件
判定说明
对当前判定结果的文字解释
- 评测结论
典型轨迹示例
展示中位数样本与潜在异常样本，用于对比常规轨迹与边缘案例的差异。帮助使用者直观理解哪些 episode 是"正常"的，哪些需要重点关注。
高阶分析
提供散点诊断图，用于观察指标间的耦合关系和异常联动。通过多维指标的散点分布，发现潜在的系统性问题或异常模式。
附录
| 内容 | 说明 |
|---|---|
| 全量指标统计 | 所有指标的完整统计表 |
| 评估规则说明 | 各评测规则的详细阈值定义和判定逻辑 |
| 潜在异常样本列表 | 各维度识别出的异常episode清单 |
