# 外部模型获取与本地校验 本项目采用代码公开、模型由接收者向上游获取的方式。下载地址和参考哈希仅用于定位资源,不授予再分发权。第三方源码按各自 LICENSE 保留;非商业限制不等同于禁止再分发。 ```bash python3 scripts/external_resources.py list --scope all python3 scripts/external_resources.py check # 主 RGB-D 所需模型 python3 scripts/external_resources.py check --scope all # 加可选单目分支 python3 scripts/external_resources.py check --verify-sha256 # 对照开发快照 ``` 工具使用 Python 标准库,不自动下载、不读取 pickle 内容、不改变已有文件。缺资源时返回非零并显示上游入口。所有路径相对项目根目录。 ## 获取与放置 | 组 | 上游入口 / 下载地址 | 放置方式 | |---|---|---| | MANO | [官网](https://mano.is.tue.mpg.de/);[许可](https://mano.is.tue.mpg.de/license.html) | 自行申请后放 `third_party/hamer/_DATA/data/mano/MANO_RIGHT.pkl`;需要独立左手模型的分支再放 `MANO_LEFT.pkl` | | HaMeR | [官方下载脚本](https://github.com/geopavlakos/hamer/blob/main/fetch_demo_data.sh);[模型包](https://drive.google.com/uc?id=1mv7CUAnm73oKsEEG1xE3xH2C_oqcFSzT) | 本地解压,把 `_DATA/hamer_ckpts/` 与 `_DATA/data/mano_mean_params.npz` 放到 `third_party/hamer/_DATA/`;MANO 独立取得 | | HMP | [Dyn-HaMR 脚本](https://github.com/ZhengdiYu/Dyn-HaMR/blob/main/scripts/prepare.sh);[hmp_model.zip](https://drive.google.com/uc?id=1_rp_SMxZA6Gjm6Z49M6hXam9kjMD6-GQ) | 解压 `hmp_model/` 到 `third_party/Dyn-HaMR/_DATA/`,保留包内目录结构 | | BMC | [上游说明](https://github.com/MengHao666/Hand-BMC-pytorch);[joints.zip](https://drive.google.com/file/d/1_wV8QjmsVCMBEBhm56gFA2XTyU8VEHzk/view) | 按数据集条款取得关节数据,运行 `calculate_bmc.py`、`calculate_convex_hull.py`;把 8 个 `.npy` 放到 `third_party/Dyn-HaMR/dyn-hamr/optim/BMC/` | | WiLoR | [模型目录](https://huggingface.co/spaces/rolpotamias/WiLoR/tree/main/pretrained_models);[detector.pt](https://huggingface.co/spaces/rolpotamias/WiLoR/resolve/main/pretrained_models/detector.pt) | 保存为 `weights/detector.pt`;Dyn-HaMR 检测器路径已有相对链接,无需第二份复制 | | FoundationPose | [官方安装说明](https://github.com/NVlabs/FoundationPose#installation);[官方权重目录](https://drive.google.com/drive/folders/1DFezOAD0oD1BblsXVxqDsl8fj0qzB82i) | 将 `2023-10-28-18-33-37/`、`2024-01-11-20-02-45/` 放到 `third_party/FoundationPose/weights/`,每个目录都有 `config.yml` 和 `model_best.pth` | | HandFlow,可选 | [模型库](https://huggingface.co/mxxu00/HandFlow) | `weights/handflow_denoiser.pt`、`weights/normalization_stats.npz` | | UniDepth,可选 | [模型库](https://huggingface.co/lpiccinelli/unidepth-v2-vitl14) | `weights/unidepth-v2-vitl14/model.safetensors`,并保留上游所需配置 | BMC 八个文件为 `bone_len_max.npy`、`bone_len_min.npy`、`CONVEX_HULLS.npy`、`curvatures_max.npy`、`curvatures_min.npy`、`joint_angles.npy`、`PHI_max.npy`、`PHI_min.npy`。现有 `_DATA/BMC` 链接指向该目录。**没有验证过与本项目开发快照完全相同的预计算 BMC 直接下载地址**;上表给的是上游原始数据及生成方法。重算结果可能与参考大小/哈希不同,应明确记录数据版本、参数和新的校验值,不能伪报同一快照。 HaMeR checkpoint 中存在 `mano.v_template`、`mano.shapedirs`、`mano.J_regressor` 等序列化参数键,因此当前版本也不分发该 checkpoint 的分片。不能通过改后缀或只排除独立 MANO `.pkl` 宣称已排除模型数据。 FoundationPose 的旧参考哈希来自此前测试使用的社区镜像,未独立与官方权重比对。兼容入口 `scripts/download_foundationpose_weights.py` 现在只显示官方入口,或用 `--check` 检查本地文件,不再自动访问社区镜像。不同 NVIDIA 发行版可能采用不同模型许可,不能把新版同名模型的许可直接套到旧文件。 ## L20 与示例资产 **L20 左右手 URDF、网格和标定 JSON 已包含在仓库中,维护者已确认可随项目上传和分发。** 不属于本页要求接收者另行申请的模型权重。执行 `git lfs pull` 即可取得网格;只取 L20 网格可用: ```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)。 ## 历史版本 本次普通提交只改变当前版本:不再跟踪预训练权重、模型/统计数据及其 48 MiB 分片,并加入 `.gitignore` 与发布检查。它不会重写既有分支历史,也不会删除服务端历史 LFS 对象。 旧提交仍可能访问旧资源。若要彻底停止历史资源分发,维护者还需单独制定历史迁移、引用清理、备份与服务端 LFS 清理方案。本次没有执行强制推送或服务端对象删除。新接收者建议 `git clone --depth 1`,只拉当前版本资产。 ## 发布检查 ```bash python3 -m unittest discover -s tests -v python3 scripts/check_release_policy.py ``` 检查针对 Git 当前索引,能识别外部文件、同路径 `.part-NNN` 分片和 MANO `.pkl`。不把工作树检查等同于完整历史或任意二进制的授权审计。