Document bundled L20 asset distribution and pin file hashes

This commit is contained in:
Codex
2026-10-29 16:35:50 +08:00
parent 56ca27ef57
commit d9814f73a0
5 changed files with 373 additions and 6 deletions
+3 -1
View File
@@ -45,6 +45,8 @@ python3 scripts/check_pipeline_resources.py
| WiLoR 检测器 | [模型目录](https://huggingface.co/spaces/rolpotamias/WiLoR/tree/main/pretrained_models) | `weights/detector.pt` |
| FoundationPose | [官方安装与权重](https://github.com/NVlabs/FoundationPose#installation) | `third_party/FoundationPose/weights/` |
**L20 左右手的 URDF、网格与标定 JSON 已随本仓库提供,维护者已确认可以随项目上传和分发,无需接收者另找模型文件夹。** 资源位于 `third_party/l20_assets/`,执行 `git lfs pull` 后即可使用;固定版本清单见 [L20 资产说明](third_party/l20_assets/README.md)。
`configs/external_resources.json` 提供下载入口、文件清单、参考大小与 SHA-256。旧 `large_files.py assemble` 只管理另行明确允许分发的分片,不能获取这些外部模型。
## 安装与运行
@@ -74,7 +76,7 @@ source scripts/foundationpose_env.sh
## 许可与其他说明
根 [LICENSE](LICENSE) 是原 HandFlow 的 MIT。第三方代码保留各自许可;FoundationPose、当前 nvdiffrast 快照、SPIDER 存在非商业使用限制。模型、数据和资产的条件不能由代码许可推定,见 [第三方说明](THIRD_PARTY_NOTICES.md)。L20 资产与标定的精确上游版本、示例数据许可仍需维护者核对,不把整个资源集合标成统一 MIT。
根 [LICENSE](LICENSE) 是原 HandFlow 的 MIT。第三方代码保留各自许可;FoundationPose、当前 nvdiffrast 快照、SPIDER 存在非商业使用限制。模型、数据和资产的条件不能由代码许可推定,见 [第三方说明](THIRD_PARTY_NOTICES.md)。L20 资产已由维护者确认随项目分发,固定版本以 [资产清单](configs/l20_assets_manifest.json) 为准;与厂商最新模型的版本对应和示例数据许可分别记录,不把整个资源集合标成统一 MIT。
当前提交移除模型载荷不等于清除了旧提交或服务端 LFS。历史清理状态见 [发布与历史边界](docs/EXTERNAL_RESOURCES.md#历史版本)。
+5 -3
View File
@@ -21,11 +21,13 @@
不要从“公开下载”“有 SHA256”“代码是 MIT”推断模型允许再次分发。FoundationPose 同名模型的新旧发行版可能有不同许可,需匹配实际文件。
## L20、示例和 CAD 的待核对项
## L20 资产发布确认、示例和 CAD
当前保留的 L20 模型和标定文件没有独立许可文件。厂商 [官方 URDF 仓库](https://github.com/linker-bot/linkerhand-urdf) 声明 Apache-2.0,但尚未将本项目中的 g20 URDF、网格和标定 JSON 与精确上游 commit 逐项对应。维护者应确认来源、保留 LICENSE/NOTICE 并说明本地修改后再对资产许可作出承诺。
项目维护者于 2026-10-29 确认,本仓库中的 L20 左右手 URDF、网格与标定 JSON 可以随项目上传和分发。它们继续作为仓库资产提供;文件版本由 [configs/l20_assets_manifest.json](configs/l20_assets_manifest.json) 的大小和 SHA256 固定,获取与使用见 [资产说明](third_party/l20_assets/README.md)。该确认针对 L20 资产,不改变 MANO 等外部模型的获取规则,也不替换已有第三方权利声明。
RGB-D 示例及盒子 CAD 的作者、公开使用条件也需明确。根 MIT 不自动覆盖来源未明确的资产;本次更新不宣称已完成所有资源的许可核准。
厂商 [官方 URDF 仓库](https://github.com/linker-bot/linkerhand-urdf) 是来源参考;尚未将本项目 g20 文件名、网格和标定与某一精确上游 commit 对应。因此用本仓库的固定资产复现,不将任意最新版厂商模型当作同一版本,也不据名称相似直接赋予新的上游许可证。
RGB-D 示例及盒子 CAD 的作者、公开使用条件仍需单独明确,L20 的发布确认不扩展到其他来源未明确的资产。
## 版本与历史
+308
View File
@@ -0,0 +1,308 @@
{
"schema_version": 1,
"asset_root": "third_party/l20_assets",
"distribution_confirmation": {
"date": "2026-10-29",
"basis": "Project maintainer confirmed these bundled L20 URDF, mesh and calibration assets may be uploaded and distributed with this repository.",
"scope": "These L20 assets only; does not change external pretrained model policy or assign a new upstream license."
},
"source_baseline": "56ca27ef57d46226344443ebf6a107237ffbaeee",
"upstream_reference": "https://github.com/linker-bot/linkerhand-urdf",
"version_boundary": "Exact upstream commit equivalence is not established. Use these bundled file hashes, not an arbitrary latest vendor model, to identify the tested asset version.",
"files": [
{
"path": "third_party/l20_assets/L20/LEFT/g20_left_G20.json",
"bytes": 111699,
"sha256": "28fed01a4d9bac3ae5ddbc1a3a158382afb9cd334774b7ad554e90ed8e8145a3",
"storage": "git"
},
{
"path": "third_party/l20_assets/L20/LEFT/linkerhand_g20_left.urdf",
"bytes": 28677,
"sha256": "b8ef22e436ab311fb61f87091b72ae717821092471d628d0ea9475b5088daa5d",
"storage": "git"
},
{
"path": "third_party/l20_assets/L20/LEFT/meshes/hand_base_link.STL",
"bytes": 3504384,
"sha256": "f5fa64265908b92a132e18fff27dc212ec21ba4872806386846374d5c91fc70a",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/LEFT/meshes/index_distal.STL",
"bytes": 993184,
"sha256": "130639135efbb5cd2773c18b481fcea45afe3bfd5dc8279a28a18a6b518779db",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/LEFT/meshes/index_metacarpals.STL",
"bytes": 153484,
"sha256": "60bc3fc552cbdc4a53fbde3e11a06fc8b0b52a0ee6ea8b730b481a6eb54cfe92",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/LEFT/meshes/index_middle.STL",
"bytes": 732584,
"sha256": "b3e46d945996e52bf0758b80f7aa1c2b99bca503b4c5b3c350e6850f78b05152",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/LEFT/meshes/index_proximal.STL",
"bytes": 881084,
"sha256": "5a561d159861170e0bc91d6a4ecb634611bcc497bb2e60440d829e5ae0b9b7f7",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/LEFT/meshes/middle_distal.STL",
"bytes": 993184,
"sha256": "a6143d000a38c7b60231b55b9e209161c7726a0410f5a7e5c48c0f41f067a006",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/LEFT/meshes/middle_metacarpals.STL",
"bytes": 153484,
"sha256": "592ce620ebba1e75ce109cf70654dc8dc2d9bb41315b6dfc902b3ed3c703f43a",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/LEFT/meshes/middle_middle.STL",
"bytes": 732584,
"sha256": "09b1b9a5bf9017d86dc543a214d263acc32c2ed4c3a474116ccdb8ab163cce89",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/LEFT/meshes/middle_proximal.STL",
"bytes": 881084,
"sha256": "115d5c2027a656d6765339a477effc251a6fb9cd26dfc56474e6b63fac64aa43",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/LEFT/meshes/pinky_distal.STL",
"bytes": 993184,
"sha256": "2d31ac67d0c2573758f0da2de4c3b773494a262845cc63659f2816bfd1fda10a",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/LEFT/meshes/pinky_metacarpals.STL",
"bytes": 153484,
"sha256": "95a7614a7495032fdec6d5bf39df04a5fec85fbe1032ea8ffad5e09e59fe287a",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/LEFT/meshes/pinky_middle.STL",
"bytes": 732584,
"sha256": "5a67a4840294f79a64b143e1cba9131811342df8c735f817708dd106699c6480",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/LEFT/meshes/pinky_proximal.STL",
"bytes": 881084,
"sha256": "5fce82ec63ecba86c656edbba8b17c5b44d51aa78df0ddb9657a465f89872206",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/LEFT/meshes/ring_distal.STL",
"bytes": 993184,
"sha256": "c82b0efd00e191a019927cf5590135f8b4d9b2c9228abfb68b12f3e0257c42aa",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/LEFT/meshes/ring_metacarpals.STL",
"bytes": 153484,
"sha256": "c90a028bf7a5da221a92d886a65cde79cf5641ff82eccd65bd6b982e17df912d",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/LEFT/meshes/ring_middle.STL",
"bytes": 732584,
"sha256": "191ddee09524ed6f7ebd447cf30fb85f894969ba161fc8c0059b6e97f70319f1",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/LEFT/meshes/ring_proximal.STL",
"bytes": 881084,
"sha256": "6a49d3ee8360028022c2ba7435ffb35fb19ffaaa3c73ddba5da16b106d86857c",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/LEFT/meshes/thumb_distal.STL",
"bytes": 1115884,
"sha256": "0812eea8d86179c70f00070e3142595e1b5cea231a5c606c78744041d7acd9ba",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/LEFT/meshes/thumb_metacarpals.STL",
"bytes": 1074384,
"sha256": "7bcb58b906bcff02d8de04f0ac90dbe6bf318cdbda52988787808b50f491d8f7",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/LEFT/meshes/thumb_metacarpals_base1.STL",
"bytes": 778384,
"sha256": "fa50f9021ae593bb37b95472a999215574ae56f63fdc5ff6edfd74b298826059",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/LEFT/meshes/thumb_metacarpals_base2.STL",
"bytes": 227384,
"sha256": "316ab10d2dae65040a78f85182635ea3b7b1f57859ef0b568ccee58d88d58129",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/LEFT/meshes/thumb_proximal.STL",
"bytes": 689584,
"sha256": "e41ea39ce8cb6673fc33b3e33e0fe2af9e82158006fccf6355ee3e49bfc5db8b",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/RIGHT/g20_right_G20.json",
"bytes": 111584,
"sha256": "314865d5bc359996bb182942fefc597f989ebfa6c9b3c97a9086acf38b0712ee",
"storage": "git"
},
{
"path": "third_party/l20_assets/L20/RIGHT/linkerhand_g20_right.urdf",
"bytes": 28687,
"sha256": "aa198155651eb7e815f1c27bc8bd9c902e969e81c1165aed756779db378e715d",
"storage": "git"
},
{
"path": "third_party/l20_assets/L20/RIGHT/linkerhand_g20_right_mj.urdf",
"bytes": 28801,
"sha256": "5a79601debec6013bda85ce65ea020878b645ca01e20440a2c56a78c3ecbee2d",
"storage": "git"
},
{
"path": "third_party/l20_assets/L20/RIGHT/meshes/hand_base_link.STL",
"bytes": 3433184,
"sha256": "79e36d4c7e9282c79601976d41144557d1928810202589e31bed335f3d308cd1",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/RIGHT/meshes/index_distal.STL",
"bytes": 984884,
"sha256": "324aa4b852e0c469bfc0c0bb9b19e0ccffc7dcb401d6a678481340588465fa26",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/RIGHT/meshes/index_metacarpals.STL",
"bytes": 151784,
"sha256": "106ad58d52420c3216ccb87865f55062d4b4b558078dda95210a085a9bbe277c",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/RIGHT/meshes/index_middle.STL",
"bytes": 805584,
"sha256": "27f9ccd91c5bdb1f6a1c42aeee4ab79e7e0aaf1e124a36999c75715b70d0aee6",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/RIGHT/meshes/index_proximal.STL",
"bytes": 883184,
"sha256": "d4f85e69dd94d56bdc4646c945ca8a237c652fd5dffba86c7b9ce1d8067ae8e1",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/RIGHT/meshes/middle_distal.STL",
"bytes": 984884,
"sha256": "688be3d9dd7fda49a8f9dbba824fedef5cf427c94e2e9e1ea96834eafbf6945a",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/RIGHT/meshes/middle_metacarpals.STL",
"bytes": 151784,
"sha256": "65bc65257a01e0ccd284dfdf3b2a66f2a865bf80faeb4da746cd1fd05114fe40",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/RIGHT/meshes/middle_middle.STL",
"bytes": 805584,
"sha256": "600b8e7486abc8a2707a5ecc66d4b5bea1dc0895c7173e911ba994f5cac30c10",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/RIGHT/meshes/middle_proximal.STL",
"bytes": 883184,
"sha256": "edd3af02319cd4a3b4e07a6f5d33d501887d5ab78625489254f289785b6f57e1",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/RIGHT/meshes/pinky_distal.STL",
"bytes": 984884,
"sha256": "3b22871d948ef80447f93866af3643ffa87cb22c1c172750fca9357f3aaa46de",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/RIGHT/meshes/pinky_metacarpals.STL",
"bytes": 151784,
"sha256": "b63d10a0e18af0169c75b85eb740c1f25123f6c4c5be0c5368afc65e8c73771f",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/RIGHT/meshes/pinky_middle.STL",
"bytes": 805584,
"sha256": "c6696bfcd2dbef8f248f86a6f45a90d5ba7b40e11cdb13a86b96347240a7b751",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/RIGHT/meshes/pinky_proximal.STL",
"bytes": 883184,
"sha256": "311ce029c4972530d3b234307f4ea6ca1789577c2786d56f969a5dfac2ef6a57",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/RIGHT/meshes/ring_distal.STL",
"bytes": 984884,
"sha256": "fca7bf31fa3f377110d31f7623e27f8c7845faedbdca7c09f98c94a28867bd69",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/RIGHT/meshes/ring_metacarpals.STL",
"bytes": 151784,
"sha256": "11797279afee7f856e472755d3a96593baea659d2ec0014edb02006ae48b5d71",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/RIGHT/meshes/ring_middle.STL",
"bytes": 805584,
"sha256": "2b3a0815e8daf95e76c9f54f84c13709a3951aa44ec6bb863facf60ba32c3c16",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/RIGHT/meshes/ring_proximal.STL",
"bytes": 883184,
"sha256": "168df91e5a5643a899556f96ca3f3b7fe8a3349436be42dfb5632c0d524f9a47",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/RIGHT/meshes/thumb_distal.STL",
"bytes": 1108484,
"sha256": "026dd2fac43c4461c5a90561ef29039f4a08802c0e47e5c422ecac2f34babe1e",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/RIGHT/meshes/thumb_metacarpals.STL",
"bytes": 1158784,
"sha256": "0a82998ece3c784bba7861b850d00ed483d93434f94f72c6298fea0917e328ca",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/RIGHT/meshes/thumb_metacarpals_base1.STL",
"bytes": 852984,
"sha256": "8416e5f826f12c4597754fbe3052983635345a76e3d98a4cdbc38ed363a9da78",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/RIGHT/meshes/thumb_metacarpals_base2.STL",
"bytes": 227884,
"sha256": "a5679a28a612ab6aa62a4f7fa1c67be42f807bba7c2ca00ba062ca2e4ef0070d",
"storage": "git-lfs"
},
{
"path": "third_party/l20_assets/L20/RIGHT/meshes/thumb_proximal.STL",
"bytes": 716984,
"sha256": "4cd7d6a283d2e5c3f6dfbd88aa1e18f9f481375d1e6b47f2c373a285184b123d",
"storage": "git-lfs"
}
]
}
+10 -2
View File
@@ -32,9 +32,17 @@ FoundationPose 的旧参考哈希来自此前测试使用的社区镜像,未
## L20 与示例资产
L20 URDF/网格/标定、RGB-D 示例和 CAD 仍是当前 Git LFS 资产。厂商 [官方 URDF 仓库](https://github.com/linker-bot/linkerhand-urdf) 声明 Apache-2.0,但当前官方 `linkerhand_l20_*.urdf` 与项目中的 `linkerhand_g20_*.urdf` 命名不同,尚未建立逐文件来源和标定映射。
**L20 左右手 URDF、网格和标定 JSON 已包含在仓库中,维护者已确认可随项目上传和分发。** 不属于本页要求接收者另行申请的模型权重。执行 `git lfs pull` 即可取得网格;只取 L20 网格可用:
维护者需核对精确来源版本、差异、LICENSE/NOTICE 和标定数据许可;不能直接用最新版官方模型替换后声称同一重定向资产。自采示例和 CAD 的作者及公开许可也需明确。见 [第三方说明](../THIRD_PARTY_NOTICES.md)。
```bash
git lfs pull --include='third_party/l20_assets/**'
```
使用 `third_party/l20_assets/L20/{LEFT,RIGHT}/`,版本清单见 [configs/l20_assets_manifest.json](../configs/l20_assets_manifest.json),操作说明见 [L20 README](../third_party/l20_assets/README.md)。清单覆盖 49 个文件,含 44 个 LFS 网格和 5 个 Git 管理的 URDF/标定文件,约 37.54 MB。
厂商 [官方仓库](https://github.com/linker-bot/linkerhand-urdf) 作为来源参考;其当前 l20 文件名与本项目 g20 文件名不同,未验证精确上游 commit 对应。复现时以本仓库文件哈希为准,不用最新版厂商模型自动替换。
RGB-D 示例和 CAD 也保留在当前资产中,但其作者与公开使用条件需单独记录,L20 的确认不扩展到其他资源。见 [第三方说明](../THIRD_PARTY_NOTICES.md)。
## 历史版本
+47
View File
@@ -0,0 +1,47 @@
# 本项目使用的 L20 资产
项目维护者已于 2026-10-29 确认,这套 L20 左右手 URDF、网格与标定 JSON 可以随本项目上传和分发。文件已经包含在仓库中,不需要另找个人文件夹或下载未经匹配的厂商新版本。
## 获取
在项目根目录执行:
```bash
git lfs install
git lfs pull --include='third_party/l20_assets/**'
```
URDF 和标定 JSON 由普通 Git 管理;44 个网格由 Git LFS 管理。完整固定版本为 49 个文件、37,540,844 字节,见 [资产清单](../../configs/l20_assets_manifest.json)。此处的计数不包含本说明文件。
| 资产 | 路径 |
|---|---|
| 左手 URDF | `L20/LEFT/linkerhand_g20_left.urdf` |
| 右手 URDF | `L20/RIGHT/linkerhand_g20_right.urdf` |
| 右手模型变体 | `L20/RIGHT/linkerhand_g20_right_mj.urdf` |
| 左手标定 | `L20/LEFT/g20_left_G20.json` |
| 右手标定 | `L20/RIGHT/g20_right_G20.json` |
| 左右手网格 | `L20/{LEFT,RIGHT}/meshes/*.STL` |
主重定向脚本按侧别读取对应原 URDF,保留线性 mimic 关系;标定 JSON 的非线性映射与 URDF mimic 不是同一模型,不能据文件可下载就认定已验证硬件控制。
## 校验固定版本
在项目根目录运行,逐文件检查大小与 SHA256:
```bash
python3 - <<'PY'
from pathlib import Path
import hashlib, json
manifest = json.loads(Path('configs/l20_assets_manifest.json').read_text())
for item in manifest['files']:
path = Path(item['path'])
assert path.is_file(), f'Missing: {path}; run git lfs pull'
assert path.stat().st_size == item['bytes'], f'Wrong size or LFS pointer: {path}'
assert hashlib.sha256(path.read_bytes()).hexdigest() == item['sha256'], f'Wrong SHA256: {path}'
print(f"PASS {len(manifest['files'])} L20 asset files")
PY
```
## 来源与范围
厂商参考入口为 [linker-bot/linkerhand-urdf](https://github.com/linker-bot/linkerhand-urdf)。本项目 g20 命名资产与厂商当前 l20 命名资产的精确 commit 对应尚未核定,复现依据是本仓库的文件清单。发布确认记录的是本项目 L20 资产上传和分发范围,不赋予其他模型新的许可;已有第三方权利声明继续保留。全项目说明见 [THIRD_PARTY_NOTICES.md](../../THIRD_PARTY_NOTICES.md)。