Mujoco_WASM/robot_profiles/NOTICE.md

LeKiwi 碰撞数据来源与重建

当前配方：revision 4

lekiwi-full-collision.json 是 SIGRobotics-UIUC/LeKiwi 的派生模型数据，来源 revision 为 efa608d7ee5a495a4803b1d28cd0c955b4f1e033，按 Apache-2.0 分发。固定 URDF/STL SHA-256 与装配例外配置见 lekiwi-collision-source.json，生成结果也保存完整 source。

本项目修改：从 Base_08q-v1 子树的全部 18 个视觉网格离线 CoACD 得到 538 个凸包，再按装配配合区切分为 1,220 个独立碰撞凸包，包含固定焊接的舵机、安装板、相机支架及相机外壳；替代旧臂胶囊和手工分段配方。此处“整臂”不包含底盘/全向轮；它们仍使用独立简化配方。

• 使用 CoACD 1.0.14，real_metric=true、threshold=0.003、固定 seed=42、4 个 OpenMP 线程，CoACD 阶段每包最多 96 个顶点，切分后预算为 256（当前最多 167）；完整参数和版本存入 generator。3 mm 是分解参数，不是已证明的全表面误差上限。
• 输入按 URDF scale 转成米，输出保留原视觉网格局部坐标、顶点取整到 1 μm。运行时继承 visual geom 的 body/pose，不跨越两指合成凸包；碰撞体 mass=0，沿用显式惯性估计。
• 浏览器只读取生成数据，导入时校验源 STL 哈希、视觉覆盖清单和运动刚体归属；不会在线运行 CoACD，也不修改参考仓库、训练或 LeRobot 环境。
• 配方使用 1 ms 物理步长、CAD 接触 solref=".002 1"；不是加大安全超时或放宽关节范围。几何、关节过滤和这些接触参数共同形成 recipeSha256，导出 MJCF 携带 revision 与配方指纹。标记用于兼容性检查，不是防篡改签名。

相邻关节不能整对排除

MuJoCo 的默认父子过滤保持开启；显式加入 5,581 对结构凸包接触，包括 Mirror / Square 和两指指面。没有整对相邻 body 的 <exclude>。

唯一局部装配例外：一个完整凸包必须落在该关节审核过的轴承/舵机配合圆柱内，才可忽略它与直接相邻运动组的配合接触。半径分别为肩旋 23、肩俯仰/肘/夹爪 18.5、腕俯仰 16、腕旋 12.1 mm，轴向半长 55 mm；不是“中立位重叠就排除”。这些部件与外界及其他非相邻臂段仍参与碰撞。

跨越配合区边界的凸包先按内接 16 边棱柱切开（2 μm 内缩以容纳取整误差），配合区和外侧各片都保留，不挖掉对外碰撞几何。生成器检查切分体积的量化误差；单测覆盖体积保持和内部/结构区分类。否则同一个凸包跨越轴承与结构区，即使中立位不碰撞，转动后仍可能误锁轴承。CAD 审核在肩旋约 0.35 rad 发现了这种情况；修复后真实 WASM 肩旋可双向到达 ±0.942 rad，且没有配合区接触。

另外以整周旋转的轴向/径向包络保守剔除不可能相交的凸包对，保留 0.1 mm 数值余量。各关节的成员、显式接触对、配合例外/扫掠剔除数量都在 jointPolicy，改参数后必须重新审核和跑物理回归，不能只改指纹。

离线环境和重建

从仓库根目录执行，先按 示例说明 准备固定源资产：

python3 -m venv build/venvs/collision
env -u PYTHONPATH PYTHONNOUSERSITE=1 build/venvs/collision/bin/python \
  -m pip install -r examples/lekiwi/requirements-collision.txt
env -u PYTHONPATH PYTHONNOUSERSITE=1 build/venvs/collision/bin/python \
  examples/lekiwi/generate_full_collisions.py --check
# 确需写入重建数据时去掉 --check

默认源目录 build/lekiwi/URDF，缓存 build/collision-cache，均可通过 CLI 覆盖。缓存键包含源 STL 哈希、缩放、工具版本、参数与线程数；关节过滤每次重算。--check 比较完整生成结果，不改已发布 JSON；使用新的 --cache 目录可验证从零分解，而非只命中缓存。本机已完成一次无缓存重建一致性验证，不承诺任意平台/工具版本逐字节相同。

env -u PYTHONPATH PYTHONNOUSERSITE=1 build/venvs/collision/bin/python \
  -m unittest discover -s examples/lekiwi/tests -v

生成器拒绝缺失/变更源、非法缩放、退化凸包、超预算包数/顶点数及采样覆盖不合格。coverage.coacdSampleOutsidePlanesMaxM 是抽样点相对 CoACD 阶段凸包平面的诊断值，不是 Hausdorff 距离或连续全表面保证。coverage.coacdParts/parts 分别记录切分前后数量。浏览器额外从原始 STL 独立取每个视觉网格的六向极值，做 108 次球体接触探测；另测六关节双向目标扫掠、相邻连杆主体阻挡/脱离、中立位、两指空隙/物体阻挡及真实 60 秒控制性能。仍未穷举多关节配置空间。

历史数据

lekiwi-gripper-collision.json / generate_gripper_collisions.py（revision 2）和 lekiwi-arm-collision.json / generate_arm_collisions.py（revision 3）保留历史重建用途，同样源自上述 Apache-2.0 资产；当前前端不再导入它们。旧方案是 STL 平面裁剪、1 mm 接缝重叠后取凸包，并非 CoACD。

旧 MJCF（包括 revision 3）必须从原始 URDF 重新转换。自动凸分解、局部装配例外和软接触仍是近似，不保证所有薄壁间隙、任意高速动作、可靠抓取或实体标定；观察到提前接触时，应检查具名接触对与原 CAD，不能靠扩大 body 排除或关闭自碰撞掩盖。当前仅支持上述固定 LeKiwi 资产，不是任意 URDF 的免审核导入开关。

开发期强制把 qpos 写入严重重叠姿态的几何查询曾使 WASM 触及 2 GiB 内存上限并原生中止；这不是支持的控制路径，也未在此修复引擎本身。profile 的普通关节编辑入口已禁止瞬移；验收使用有界执行器运动、正常初始姿态和有限场景，不能由此承诺任意穿透初态稳定。诊断失败记录保存在 build/e2e/lekiwi-full-collision-geometry-diagnostic/。