Files

61 lines
5.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 外部模型获取与本地校验
本项目采用代码公开、模型由接收者向上游获取的方式。下载地址和参考哈希仅用于定位资源,不授予再分发权。第三方源码按各自 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`。不把工作树检查等同于完整历史或任意二进制的授权审计。