EXPERIMENT RECORD
物理验证协议

# 物体生成的 physical validation

生成 harness 的输出应当是一份带适用范围和证据的物理资产。验收分四层：结构有效、动力学自洽、任务功能有效、与实物一致。每项检查单独输出 PASS / FAIL / UNVERIFIED / NOT_APPLICABLE；未执行的项目不能算通过。初始落地通过，也不能替代杯子容纳、瓶盖旋拧等功能检查。

## 必须做哪些测试

| 测试组 | 怎么测试 | 记录什么 | 判定依据 |
| --- | --- | --- | --- |
| 1. 文件与结构 | 在目标引擎加载；解析全部依赖、单位、坐标、部件、碰撞与关节图 | 未解析资源；米/kg/角度约定；刚体/关节/碰撞数量；加载或 cooking 错误 | 资源闭合，单位一致，所需部件存在；缺失可动瓶盖不能进入拧盖测试 |
| 2. 视觉和碰撞几何 | 显示碰撞体叠加；检查凸包/分解误差；用不同位置与尺寸的球、夹指、插入件探测孔洞/空腔 | 表面误差、最小间隙、阻挡位置、实际接触对象和穿透 | 碰撞近似必须保留任务需要的空间；外观相同不保证空腔可用 |
| 3. 质量、重心、惯量 | 比较源规范/manifest 与引擎读数；检查质量正值、主惯量正值和三角不等式；核对重心坐标框架及估计方法 | m、COM、I、单位、来源、导出差异、物理可实现性 | 参数自洽是基础；真实准确性必须另与称重、重心/惯量测量比较 |
| 4. 被动刚体行为 | 无接触自由落体；不同高度/姿态落地；静置；必要时倾斜支撑面 | z/v 对时间、接触、最大/持续穿透、弹跳、漂移、最终速度、NaN/爆炸 | 无接触阶段与重力一致；接触后的误差限按物体尺度和任务公差设定 |
| 5. 受力响应 | 接触关闭、重力关闭，施加已知线性/角冲量；再在接触环境做推/拉/转动 | 已施加力/转矩、持续时间、线速度、角速度、必要时能量/动量 | 自由刚体比较 Δv=J/m、主轴上 Δω=L/I；带接触时使用完整动力学或实测响应作为参考 |
| 6. 接触材料 | 平面滑移、逐渐倾斜的稳定薄滑块、球体落地弹跳；按材质/姿态重复 | 起滑阈值、滑移减速度、停止距离、弹跳高度/速度、接触力 | 无倾覆的倾斜实验可估 μs≈tanθ；平面滑移可估 μd≈−a/g；需实测视频/轨迹判断现实误差 |
| 7. 关节与机构 | 全限位扫描；正反向运动；有限驱动达到目标；检查部件互穿、卡死、摩擦/阻力；螺旋关系与脱离 | 轴/锚点/限位、运动路径、穿透、目标误差、力矩、z–θ、释放条件 | 运动方向和机构功能匹配任务。瓶盖需要导程、啮合、取盖；真实开盖还需启动力矩/密封阻力等测量 |
| 8. 任务交互探针 | 容纳/插入、双指抓取与提起、开门/抽屉、旋拧、稳定放置 | 接触对、滑脱、物体/夹具状态、任务终态、失败原因 | 检查真实求解器产生的动作；夹具、理想抓取或机构近似必须明确记录 |
| 9. 数值与覆盖 | 多 seed、初始姿态、高度、参数范围；步长/求解设置对比；必要时匹配条件下跨引擎复验 | 每个试验的参数与结果、失败分布、轨迹/终态差异、运行成本 | 先确认测试本身能检出已知错误；不能把一个 seed 或一个引擎通过写成普遍有效 |

几何对齐不仅要看 AABB。一个填满杯子内部的凸包可以通过加载、正质量和落地检查，但会挡住需要放入杯中的物体。对剪刀、瓶盖、抽屉等对象，可动部件和连接关系也是物理结构的一部分。

重心/惯量从均匀碰撞体推算时应标为估计。空心杯、带水瓶和多材料工具不能简单用包围盒密度作为真实材料密度。本库当前扫描资产的惯量和重心仍是均匀包围盒代理，质量使用论文标称值，摩擦未实测。

## 本机已经执行的测试与素材

| 项目 | 当前实际结果 | 证据 |
| --- | --- | --- |
| 12 个 YCB 的原始基础落地 | MuJoCo / PhysX 均 12/12；PhysX 停稳速度取原生 tensor | `outputs/asset-library/*validation*.json`、`physx-tensor/result.json` |
| 扩展刚体测试 | 质量/惯量一致性、惯量可实现性、自由落体、线性/角冲量、无接触步长对照；12 个资产均通过这些组 | `outputs/physical-validation/extended/<id>/result.json` |
| 六次随机姿态/高度落地 | 10/12 资产通过；香蕉和锤子的部分试验超出 15mm 接触穿透上限，保留失败 | 同上；每条 trial 保留姿态、接触、最大穿透和终速 |
| 空腔功能探针 | 同一 YCB 杯子视觉：单凸包挡住球；64 个 CoACD 凸部件允许本次球体落入 | `mug-contact/result.json`、对比 MP4、两份 MJCF 和三种 USD |
| 铰链正负例 | 相同合成几何和相同有限力矩：错误轴约 0.047°，正确轴约 54.2°，目标 57.3°、允差 4.6° | `hinge-motion/result.json`、原生对比 MP4 |
| 瓶盖功能及机器人案例 | 螺旋关系、实际手指接触、脱离和抬升；原名义案例已通过 | `outputs/bottle-cap-demo/delivery/physics/` |
| 新的 code-policy 数据 | 3 个独立初始关节扰动试验，全部完成；共 20,844 条 240Hz 状态–动作–下一状态记录 | `outputs/physical-validation/rollout-admission.json` 及其引用目录 |
| 实物拟合 | 尚未提供对应实物称重/重心/摩擦/开盖力矩/受力轨迹 | UNVERIFIED，不能填成零误差 |

15mm 是这轮粗刚体压力测试的上限，用于发现问题，不是“足够真实”的通用标准。毫米级插入/夹持必须用相应更小的几何和接触公差。无接触的 2ms/1ms 对照也不能代替接触场景的步长收敛检查。

杯子修复案例验证了一个固定杯夹具中的 9mm 半径球体探针。CoACD 的 64 件上限使部分形状的全局凹度目标未满足；把手穿入、薄壁抓取及其他探针仍需继续测。修复后的 USD 已做结构检查，当前功能视频来自 MuJoCo，尚未单独对这个新多凸体版本执行 PhysX 动态测试。

## 数值阈值和测量来源

当前可运行 extended suite 的阈值写入每次 `result.json`：

- manifest–引擎质量相对误差 ≤1e−6；惯量 rtol 1e−5 / atol 1e−10。
- 主惯量有限、正值，Imax ≤另外两个主惯量之和（含浮点余量）。
- 100ms 无接触下落，与 ½gt² 的绝对位移差 <2mm。
- 接触/重力关闭的线性和主轴角冲量响应相对差 <2%。
- 六次 seed 固定的 yaw/小倾斜/40–100mm 高度落地：有限状态、有接触、最大穿透 <15mm，5s 后 v<0.05m/s、ω<0.5rad/s。
- 无接触 2ms/1ms 响应速度差 <0.02（各自单位）。

这些首先检查模型自洽与数值实现。真实参数拟合应使用独立实物参考，并记录实际测量条件、重复次数、传感器误差和容许误差。摩擦/弹跳还要注意引擎参数含义：MuJoCo 的接触软硬由其接触模型参数控制，不能把 PhysX 的 restitution 数字直接复制后就声称响应一致。

## 接入生成–诊断–修订循环

```text
输入/参考/检索资产
  → 几何与物理编译
  → 结构检查 + 适用的动力学/机构/交互测试
  → 失败 JSON（部件/状态/指标/阈值/可复现输入）
  → Coding Agent 修改参数、碰撞体、关节或部件
  → 新资产版本与相同协议复验
  → 通过的任务范围 + 尚未验证项目 + 原始证据
```

失败反馈应指向具体原因。例如：`cup cavity blocked by a single convex hull` 应修复碰撞拓扑；错误铰链应修复轴/锚点与方向；线性响应与 m 不符应核对单位/导出；真实开盖力矩不符应辨识阻力或接触模型。渲染只帮助诊断外观，不替代上述指标。

保留三种资产状态：`STRUCTURE_VALID`、`DYNAMICS_SELF_CONSISTENT`、`TASK_VALIDATED(task, fixture, conditions)`。现实一致性再附 `REAL_WORLD_FIT(measurements, errors)`；缺少实物参考时保持未验证。

## 命令

```powershell
.\Run-WorldFoundry.cmd object validate --asset ycb-025_mug --suite extended
.\Run-WorldFoundry.cmd object validate --asset ycb-025_mug --engine both --suite extended
.\Run-WorldFoundry.cmd asset describe bottle-nongfu-500ml
.\Run-WorldFoundry.cmd task rollout --count 3 --seed 20261013
```

`asset describe` 提供静态 USD 的部件姿态、AABB、质量/惯量、关节图、碰撞体和材料；运行中使用求解器状态。`task rollout` 以实际任务判定、完整记录、关节限位和实际手指–瓶盖接触筛选数据，记录 privileged 3D 来源。数据含仿真教师信息，物理资产本身未实测校准的字段依然保留。

## 技术依据

- [OpenUSD MassAPI](https://openusd.org/release/api/class_usd_physics_mass_a_p_i.html)：质量/惯量/重心的资产表达。
- [Isaac Sim physics fundamentals](https://docs.isaacsim.omniverse.nvidia.com/latest/physics/simulation_fundamentals.html)：刚体、碰撞与近似的引擎工作流。
- [MuJoCo computation](https://mujoco.readthedocs.io/en/stable/computation/index.html)：动力学、接触模型和状态/力的含义。
- [CoACD](https://github.com/SarahWeiii/CoACD)：本次扫描网格碰撞分解方法。
- [Code as Policies](https://code-as-policies.github.io/)：程序、反馈逻辑和控制 API 组成机器人策略的参考；当前本地案例是带 privileged 3D 的程序控制与数据记录，并非原论文完整复现。


## 2026-10-16 原生机器人夹爪的功能验证

R1 Lite 官方 USD 的可视网格和质量/惯量可以正常导入，但手指使用 `convexHull` 时，凹形连杆的空隙被单凸包填平。任务中两指都能报告接触，罐头却被压在顶部，不能按要求抬起。因此“有双指接触”本身不构成抓取成功。

同一 RoboDojo 场景、0.9 倍罐头、80 g 估计质量、Astra 11 步计划、原生 IK/PD 下：

| 功能测量 | 原单凸包 | 原手指网格凸分解 |
| --- | ---: | ---: |
| 最大罐头抬升 | 5.95 mm，FAIL | 158.42 mm，PASS |
| 双指接触步数 | 678 | 1966 |
| 放置距目标中心 | 244.95 mm，FAIL | 0.236 mm，PASS |
| 总任务 | FAIL | PASS |

对照来自 `outputs/robodojo-r1lite/task-v1/result.json` 与 `task-v2/result.json`。分解最多 32 个凸体/手指，视觉网格不变；没有以抓取焊接、物体电机或轨迹写入替代接触。第一次失败持续保留。最终统一入口另运行一轮，落点误差 0.263 mm、4920 条连续状态转移，原始检查在对应 task run 内。

机器人任务验收必须同时检查：接近时的几何可达性、闭合后的有效夹持、实际物体抬升、搬运期接触、完整落点占用范围、释放后的支撑高度/线角速度、机械臂退回与关节限位。渲染只重放实际动力学轨迹。罐头质量、接触摩擦和机器人执行器增益未实物拟合；不能把本例误差写成真实机器人精度。

R1 Lite 源一致性检查还发现两个相机的 diagonalInertia 为 USD `(0,0,0)` 自动推断标记。不能把它当成实测惯量，也不能简单解释成实际零惯量。原始“全部必须显式正数”静态 gate 的 FAIL 保留在 robot-source-audit.json；原生重载检查另读取 PhysX 实际惯量张量，报告有效正定性与自动估计来源。语义依据：https://openusd.org/release/api/class_usd_physics_mass_a_p_i.html 。