chenlin
f3a8a38acd
web-platform-ci / Standalone decision service (no cloud credentials) (push) Has been cancelled
web-platform-ci / TypeScript, lint, unit, build (push) Has been cancelled
web-platform-ci / Playwright E2E (push) Has been cancelled
lekiwi-compatibility / cpu-compatibility (push) Has been cancelled
web-platform-ci / Standalone decision service (no cloud credentials) (pull_request) Has been cancelled
web-platform-ci / TypeScript, lint, unit, build (pull_request) Has been cancelled
web-platform-ci / Playwright E2E (pull_request) Has been cancelled
lekiwi-compatibility / cpu-compatibility (pull_request) Has been cancelled
集成同源 BYOK 会话隔离、精简模型设置、官方订阅入口和 HTTPS 发布运维；保留本地训练/调参与控制能力。同步 npm 版本及 CHANGELOG，记录公网真实 API 验收仍待用户凭据。
59 lines
7.1 KiB
Markdown
59 lines
7.1 KiB
Markdown
# LeKiwi 碰撞数据来源与重建
|
||
|
||
## 当前配方：revision 4
|
||
|
||
`lekiwi-full-collision.json` 是 [SIGRobotics-UIUC/LeKiwi](https://github.com/SIGRobotics-UIUC/LeKiwi) 的派生模型数据，来源 revision 为 `efa608d7ee5a495a4803b1d28cd0c955b4f1e033`，按 [Apache-2.0](LeKiwi.LICENSE.txt) 分发。固定 URDF/STL SHA-256 与装配例外配置见 `lekiwi-collision-source.json`，生成结果也保存完整 `source`。
|
||
|
||
`lekiwi-reference.urdf` 是同一固定版本的未修改原始 URDF（SHA-256 与 `lekiwi-v1.json` 一致），同样按上述 Apache-2.0 分发；`lekiwi-source-meshes.json` 记录它引用的全部 45 个网格的原始字节哈希。两者用于浏览器机械语义等价校验，不是新机构的碰撞生成数据。未将用户 `New_urdf` 中的新机械臂 STL 纳入本仓库。
|
||
|
||
本项目修改：从 `Base_08q-v1` 子树的**全部 18 个视觉网格**离线 CoACD 得到 538 个凸包，再按装配配合区切分为 1,220 个独立碰撞凸包，包含固定焊接的舵机、安装板、相机支架及相机外壳；替代旧臂胶囊和手工分段配方。此处“整臂”不包含底盘/全向轮；它们仍使用独立简化配方。
|
||
|
||
- 使用 [CoACD](https://github.com/SarahWeiii/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`，改参数后必须重新审核和跑物理回归，不能只改指纹。
|
||
|
||
### 离线环境和重建
|
||
|
||
从仓库根目录执行，先按 [示例说明](../examples/lekiwi/README.md) 准备固定源资产：
|
||
|
||
```bash
|
||
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` 目录可验证从零分解，而非只命中缓存。本机已完成一次无缓存重建一致性验证，不承诺任意平台/工具版本逐字节相同。
|
||
|
||
```bash
|
||
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 秒控制性能。仍未穷举多关节配置空间。
|
||
|
||
### 完整轮视觉：visual revision 1
|
||
|
||
A 模型三个 314,244 面的原始 STL 无减面转换为内容寻址 OBJ，保持坐标/绕序与来源哈希。完整 CAD 视觉挂接到既有理想轮轴，不增加质量或接触；被动滚子、惯性及上述 collision revision 4 不变。简化轮毂/滚子移至碰撞诊断显示组，旧缺轮 MJCF 必须从原始 URDF 重新转换。资产仍按原 Apache-2.0 来源分发，并非新的 SO101 机构验证。导出、软件渲染限制及测试证据见 [完整网格说明](../docs/lekiwi-mesh-compatibility.md)。
|
||
|
||
### 历史数据
|
||
|
||
`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 的免审核导入开关；机械变体与新拓扑的边界见 [URDF 变体说明](../docs/lekiwi-urdf-compatibility.md)。
|
||
|
||
开发期强制把 qpos 写入严重重叠姿态的几何查询曾使 WASM 触及 2 GiB 内存上限并原生中止；这不是支持的控制路径，也未在此修复引擎本身。profile 的普通关节编辑入口已禁止瞬移；验收使用有界执行器运动、正常初始姿态和有限场景，不能由此承诺任意穿透初态稳定。诊断失败记录保存在 `build/e2e/lekiwi-full-collision-geometry-diagnostic/`。
|