liyang
ae28d55f81
Source: RGB-D -> Dyn-HaMR -> L20 retargeting -> FoundationPose -> reference repair -> SPIDER, documented in docs/PIPELINE_LATEST.md and docs/SETUP_AND_WEIGHTS.md. Adds FoundationPose and nvdiffrast upstream snapshots, requirements/pipeline_venv.txt and the FoundationPose weight manifest/downloader. Assets (Git LFS): weights/ (WiLoR detector, HandFlow denoiser, UniDepth-L), FoundationPose checkpoints, HaMeR checkpoint, Dyn-HaMR HMP model and BMC constraints, L20 URDF/meshes, the 20260915_171525 D405 recording and the two box CADs. MANO models are not redistributed (third_party/hamer/_DATA/data/mano/README.txt). Environments, caches and run outputs excluded. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
206 lines
16 KiB
Markdown
206 lines
16 KiB
Markdown
# 安装依赖、环境与权重（2026-09-17）
|
||
|
||
适用：源码快照 `hand-motion-pipeline-20260917`（由 `scripts/package_source_release.py` 生成）。链路为 **RGB-D → Dyn-HaMR → L20 重定向 → FoundationPose → 参考修复 → SPIDER**，执行顺序与每步命令见 [PIPELINE_LATEST.md](PIPELINE_LATEST.md)。本文按本机（2026-09-17）实际环境核对；**没有在干净机器上从零复现安装**，版本表是观测值，不是跨平台 lock。
|
||
|
||
## 1. 机器与系统依赖
|
||
|
||
| 项 | 本机观测 |
|
||
|---|---|
|
||
| OS / GPU / 驱动 | Ubuntu 22.04.5，RTX 3080 Laptop 16 GB，NVIDIA 驱动 595.91 |
|
||
| CUDA toolkit（nvcc） | 12.8，解包在项目内 `.cuda/usr/local/cuda-12.8`（用户级，不需要 sudo；`scripts/foundationpose_env.sh` 把 `CUDA_HOME` 指向它）。任何能提供 nvcc 12.8 的安装方式都可以，Torch 是 cu128 版所以 toolkit 主版本要对上 |
|
||
| apt 包 | `build-essential cmake ninja-build ffmpeg libeigen3-dev libosmesa6-dev libegl1-mesa-dev libgl1-mesa-dev libglfw3-dev` |
|
||
| 渲染 | 离屏 `MUJOCO_GL=osmesa`（默认）；交互回放 `glfw`；Dyn-HaMR 可视化用 EGL |
|
||
|
||
`scripts/foundationpose_env.sh` 会清空 ROS 注入的 `PYTHONPATH / LD_LIBRARY_PATH`，把 `.venv`、nvcc、编译缓存（`.cache/`）指到项目内。**所有 `.venv` 脚本都先 `source` 它**。
|
||
|
||
## 2. 环境角色（4 个解释器，不要混装）
|
||
|
||
| 角色 | 路径约定 | Python | Torch | 关键依赖（观测版本） | 谁用 |
|
||
|---|---|---|---|---|---|
|
||
| 主环境 | `.venv` | 3.11.15 | 2.7.1+cu128 / torchvision 0.22.1 | pytorch3d 0.7.9、nvdiffrast 0.4.0、mujoco 3.5.0、mujoco-warp 3.5.0、warp-lang 1.14.0、open3d 0.19.0、trimesh 4.12.2、coacd 1.0.14、kornia 0.8.3、opencv 5.0 | FoundationPose、RGB-D 预处理/里程计、Dyn-HaMR 启动与导出、配准、prepare / fix / verify / audit / smooth / render、回放（[PIPELINE_LATEST.md](PIPELINE_LATEST.md) 里除重定向和 SPIDER 外全部）；HandFlow / ViPE 分支也在这里 |
|
||
| Dyn-HaMR | `third_party/Dyn-HaMR/.dynhamr` | 3.10.12 | 2.7.0+cu128 / torchvision 0.22.0 | ultralytics 8.1.34、hydra-core 1.3.6、kornia 0.8.2、smplx 0.1.28 | `run_opt.py`（由 `scripts/run_dynhamr_rgbd_20260915.py` 内部调用） |
|
||
| 重定向 | `.dex` | 3.11.15 | 2.7.1+cu128 | dex-retargeting 0.5.0、pin 4.1.0、mujoco 3.5.0、h5py 3.16.0 | `retarget_l20_video.py`、HDF5 导出 |
|
||
| SPIDER | `.spider` | 3.11.15（兼容安装；上游 pyproject 要求 ≥ 3.12） | 2.7.1+cu128 | mujoco 3.7.0、mujoco-warp 3.7.0.1、warp-lang 1.12.1、open3d 0.19.0、loguru | `run_yesterday_spider.py`、`audit_collision_physics.py`、`check_spider_dynamics_replay.py` |
|
||
|
||
完整观测表：[requirements/runtime_observed.json](../requirements/runtime_observed.json)。`.dex` 的 MuJoCo 3.5 与 SPIDER 的 3.7 不能装进同一个环境。
|
||
|
||
## 3. 安装顺序
|
||
|
||
### 3.1 主环境 `.venv`（FoundationPose + 全部流程脚本）
|
||
|
||
```bash
|
||
python3.11 -m venv .venv
|
||
.venv/bin/python -m pip install torch==2.7.1 torchvision==0.22.1 --index-url https://download.pytorch.org/whl/cu128
|
||
.venv/bin/python -m pip install -r requirements/pipeline_venv.txt
|
||
source scripts/foundationpose_env.sh # 之后 python == .venv/bin/python，CUDA_HOME 指向 nvcc 12.8
|
||
python -m pip install --no-build-isolation "git+https://github.com/facebookresearch/pytorch3d.git@stable" # 观测 0.7.9
|
||
python -m pip install --no-build-isolation --no-deps ./third_party/nvdiffrast # 快照 0.4.0，需 nvcc
|
||
# FoundationPose C++ 旋转聚类模块（pybind11），产物 third_party/FoundationPose/mycpp/build/mycpp.cpython-311-*.so
|
||
cmake -S third_party/FoundationPose/mycpp -B third_party/FoundationPose/mycpp/build -DCMAKE_BUILD_TYPE=Release \
|
||
-Dpybind11_DIR="$FP_ROOT/.venv/lib/python3.11/site-packages/pybind11/share/cmake/pybind11" \
|
||
-DPYTHON_EXECUTABLE="$FP_ROOT/.venv/bin/python" -DPython_EXECUTABLE="$FP_ROOT/.venv/bin/python"
|
||
cmake --build third_party/FoundationPose/mycpp/build -j2
|
||
python scripts/verify_foundationpose_setup.py # GPU 光栅化 + 两个网络前向 + STL 估计器初始化 → output/foundationpose_setup/runtime_verification.json
|
||
```
|
||
|
||
- `requirements/pipeline_venv.txt` 是本机观测的 pin 列表（不含 torch / pytorch3d / nvdiffrast，这三者按上面单独装）。
|
||
- FoundationPose 上游 `requirements.txt` 建议 cu124；本机用 cu128 + 上述版本跑通，不要再按上游装一遍 torch。
|
||
- BundleSDF 的 `mycuda` / NeRF 扩展**不需要**（只跑模型法 STL 路径），未编译。
|
||
- HandFlow / ViPE 单目分支也用这个环境，但本链路不需要它们（见第 4.4 节）。详细说明：[FOUNDATIONPOSE_SETUP.md](FOUNDATIONPOSE_SETUP.md)。
|
||
|
||
### 3.2 Dyn-HaMR `.dynhamr`
|
||
|
||
```bash
|
||
python3.10 -m venv third_party/Dyn-HaMR/.dynhamr
|
||
third_party/Dyn-HaMR/.dynhamr/bin/python -m pip install torch==2.7.0 torchvision==0.22.0 --index-url https://download.pytorch.org/whl/cu128
|
||
# 其余依赖按 third_party/Dyn-HaMR/scripts/install_pip.sh 逐条执行（跳过它里面的 torch 行；该脚本钉的是旧版 torch）
|
||
```
|
||
|
||
Dyn-HaMR 自带 `third-party/hamer`（含 ViTPose）与 `third-party/Hand-BMC-pytorch-main`，都在快照里；运行时 `PYTHONPATH` 由 `scripts/run_dynhamr_rgbd_20260915.py` 设置，不需要手动 export。本快照对上游的修改（`run_opt.py`、`vis/tools.py`、`vis/viewer.py` 等 6 处 + 新增 `HMP/windowed.py`）已包含在源码里，见 `UPSTREAM_SOURCES.json` 的 `local_changes`。
|
||
|
||
### 3.3 重定向 `.dex`
|
||
|
||
```bash
|
||
python3.11 -m venv .dex
|
||
.dex/bin/python -m pip install torch==2.7.1 torchvision==0.22.1 --index-url https://download.pytorch.org/whl/cu128
|
||
.dex/bin/python -m pip install -r requirements/retarget.txt # dex-retargeting 0.5.0、mujoco 3.5.0、h5py 等
|
||
```
|
||
|
||
### 3.4 SPIDER `.spider`
|
||
|
||
上游 `third_party/spider/pyproject.toml` 要求 Python ≥ 3.12。干净机器按上游装：
|
||
|
||
```bash
|
||
python3.12 -m venv .spider
|
||
.spider/bin/python -m pip install torch==2.7.1 torchvision==0.22.1 --index-url https://download.pytorch.org/whl/cu128
|
||
.spider/bin/python -m pip install -e third_party/spider # 解析 pyproject 全部直接依赖（mujoco 3.7、mujoco-warp、warp-lang 1.12 等）
|
||
env PYTHONPATH= LD_LIBRARY_PATH= .spider/bin/python scripts/verify_spider_install.py # GPU 两世界 60 步物理冒烟
|
||
```
|
||
|
||
本机是 Python 3.11 兼容安装（`--ignore-requires-python --no-deps` 装 spider 本体，再装解析出的依赖），记录在 `requirements/spider_resolved.txt`（完整解析结果，含本机共享环境里已有的包）和 `requirements/spider_installed_local.txt`（本机实际新增的 51 个包）。这是历史记录，不是安装脚本。本快照对上游 SPIDER 的本地补丁（`examples/run_mjwp.py`、`spider/optimizers/sampling.py`、`spider/simulators/mjwp.py`：辅助弹簧力公式、接触奖励权重、重采样漏控制量、GPU 接触参数）已在源码里；`-e` 安装即生效。
|
||
|
||
## 4. 权重与外部资源
|
||
|
||
### 4.0 从代码托管平台克隆（权重已随仓库，Git LFS）
|
||
|
||
仓库 `https://gitea.robotquan.com/liyang/hand-motion-pipeline` 通过 Git LFS 带了下表中"本链路需要"的全部权重、L20 模型与录制数据（MANO 除外）。服务器单次请求上限 50 MB，超过的 10 个文件以 48 MiB 分片 `*.part-NNN` 存放，清单在 `configs/large_files.json`。克隆后先拼回：
|
||
|
||
```bash
|
||
git lfs install
|
||
git clone https://gitea.robotquan.com/liyang/hand-motion-pipeline.git && cd hand-motion-pipeline
|
||
git lfs pull # 约 6.3 GB
|
||
python3 scripts/large_files.py assemble # 拼回 hamer.ckpt / UniDepth / HandFlow / HMP / FoundationPose / detector，逐个 sha256 校验
|
||
python3 scripts/large_files.py assemble --clean # 可选：拼回后删除分片省空间
|
||
```
|
||
|
||
`third_party/Dyn-HaMR/_DATA/` 里指向 HaMeR 检查点、MANO、检测器的是相对符号链接，克隆后自动生效。之后只差 MANO（4.2 节）。
|
||
|
||
源码包只含代码、配置、文档和两个小 CAD（`docs/上半.stl`、`docs/下半.stl`）。下表其余项都要另行准备；哈希与大小见包内 `EXTERNAL_ASSETS.json`。
|
||
|
||
| 资源 | 大小 | 放置位置 | 来源 | 本链路需要 |
|
||
|---|---|---|---|---|
|
||
| Dyn-HaMR 数据包 `_DATA/`（`hamer_ckpts/`、`data/mano/`、`hmp_model/`、`BMC/`） | 787 MB | `third_party/Dyn-HaMR/_DATA/` | 上游 `scripts/prepare.sh`（Google Drive）+ HaMeR `fetch_demo_data.sh` | 是 |
|
||
| `MANO_RIGHT.pkl` | — | `third_party/Dyn-HaMR/_DATA/data/mano/` | [MANO 官网](https://mano.is.tue.mpg.de/) 注册下载，不在任何包里 | 是（双手处理按 Dyn-HaMR 代码检查左手资源） |
|
||
| WiLoR 手检测器 `detector.pt` | 52 MB | `weights/detector.pt` + `third_party/Dyn-HaMR/third-party/hamer/pretrained_models/detector.pt` | [WiLoR HF Space](https://huggingface.co/spaces/rolpotamias/WiLoR/tree/main/pretrained_models) | 是 |
|
||
| FoundationPose 权重：`2023-10-28-18-33-37/`（refiner，68 MB）、`2024-01-11-20-02-45/`（scorer，190 MB），各含 `config.yml + model_best.pth` | 247 MB | `third_party/FoundationPose/weights/` | `scripts/download_foundationpose_weights.py`（清单 `configs/foundationpose_weights_manifest.json`，SHA-256 校验） | 是 |
|
||
| L20 灵巧手模型：`L20/{LEFT,RIGHT}/linkerhand_g20_{left,right}.urdf` + `meshes/` + 标定 JSON | 36 MB | `third_party/l20_assets/` | 模型提供方交付；左右手各自的 URDF，不是镜像 | 是 |
|
||
| 录制数据 `color.mp4` + `depth/*.png` + `intrinsics.json` | 116 MB | `docs/20260915_171525/` | 自采（D405 头戴） | 是 |
|
||
| 盒子 CAD `上半.stl`（红）、`下半.stl`（蓝） | 104 KB | `docs/` | **已随源码包** | 是 |
|
||
| HandFlow 权重（`handflow_denoiser.pt`、`normalization_stats.npz`、UniDepth） | 2 GB | `weights/` | [mxxu00/HandFlow](https://huggingface.co/mxxu00/HandFlow)、HF `lpiccinelli/unidepth-v2-vitl14` | 否（HandFlow 单目分支） |
|
||
| HaMeR 独立副本 `_DATA/` | 2.6 GB | `third_party/hamer/_DATA/` | HaMeR `fetch_demo_data.sh` | 否（HandFlow 分支） |
|
||
| ViPE 模型缓存（SAM、DeAOT、GroundingDINO、UniDepth、DROID、GeoCalib、Depth-Anything） | ~4 GB | `.torch_cache/`、`.hf_cache/` | 见 4.4 | 否（单目无深度视频才需要） |
|
||
| 瓶子参数化模型 | 156 KB | `third_party/bottle_model_parametric/` | 项目附件 | 否（旧单手链路） |
|
||
|
||
### 4.1 Dyn-HaMR 数据包、MANO、检测器
|
||
|
||
```bash
|
||
cd third_party/Dyn-HaMR && bash scripts/prepare.sh && cd ../.. # 需要 gdown；下载后核对 _DATA 内四个子目录都非空
|
||
# MANO：官网下载后放 third_party/Dyn-HaMR/_DATA/data/mano/MANO_RIGHT.pkl
|
||
mkdir -p weights third_party/Dyn-HaMR/third-party/hamer/pretrained_models
|
||
curl -fL --retry 3 -C - 'https://huggingface.co/spaces/rolpotamias/WiLoR/resolve/main/pretrained_models/detector.pt' -o weights/detector.pt
|
||
cp weights/detector.pt third_party/Dyn-HaMR/third-party/hamer/pretrained_models/detector.pt
|
||
```
|
||
|
||
`prepare.sh` 还会拉旧的 DROID 资源，可按脚本逐项取舍。不能用"脚本退出码 0"代替 checkpoint 存在性检查。
|
||
|
||
### 4.2 FoundationPose 权重
|
||
|
||
```bash
|
||
source scripts/foundationpose_env.sh
|
||
python scripts/download_foundationpose_weights.py
|
||
```
|
||
|
||
官方 Google Drive 在制作快照时配额超限，清单里的 URL 是社区 Hugging Face 镜像 `gpue/foundationpose-weights`，按镜像 LFS SHA-256 校验，**未与官方文件独立比对**。有官方链接时替换清单里的 `url` 即可，哈希不变。
|
||
|
||
### 4.3 L20 模型与录制数据
|
||
|
||
由提供方 / 自己放到上表路径。`third_party/l20_assets` 与 `docs/20260915_171525` 的逐文件 SHA-256 在 `EXTERNAL_ASSETS.json`，可用来核对搬运是否完整。
|
||
|
||
### 4.4 可选：HandFlow 与 ViPE 分支
|
||
|
||
只在跑单目 RGB 视频（没有深度、没有里程计）时需要。本链路的相机位姿来自 `prepare_rgbd_20260915.py` 的 RGB-D 里程计，只借用 ViPE 的**文件格式**喂给 Dyn-HaMR，不运行 ViPE。
|
||
|
||
- HandFlow：`hf download mxxu00/HandFlow handflow_denoiser.pt normalization_stats.npz --local-dir weights`
|
||
- ViPE 权重（本快照 `configs/pipeline/default.yaml` 所需）：SAM ViT-B（`.torch_cache/hub/sam/`）、DeAOT（`.torch_cache/hub/aot/`）、GroundingDINO（HF `ShilongLiu/GroundingDINO`）、BERT（HF `google-bert/bert-base-uncased`）、UniDepth-L（HF `lpiccinelli/unidepth-v2-vitl14`）、DROID（`.torch_cache/hub/droid_slam/droid.pth`）、GeoCalib、Depth-Anything 系列。做法：设置 `configs/project_env.example.sh` 的缓存变量，联网跑一段短视频让它按需下载，全部就绪后再开 `HF_HUB_OFFLINE=1`。搬缓存要连 `snapshots/blobs/refs` 一起搬。
|
||
|
||
### 4.5 下载慢或中断
|
||
|
||
```bash
|
||
curl -L --range 0-1048575 --max-time 15 -o /dev/null -w 'HTTP=%{http_code} speed=%{speed_download} bytes/s\n' '<URL>'
|
||
```
|
||
|
||
Hugging Face 可换 `hf-mirror.com` 测速（第三方镜像）。支持 Range 时用 `curl -C -` 或 `aria2c -c -x 16 -s 16 --min-split-size=10M` 续传。拿到 HTML 错误页时文件名再对也不算成功。
|
||
|
||
## 5. 路径与环境变量
|
||
|
||
```bash
|
||
source configs/project_env.example.sh # TORCH_HOME / HF_HOME / WARP_CACHE_PATH / HAMER_CKPT / MANO_ROOT / DETECTOR_CKPT / MUJOCO_GL
|
||
source scripts/foundationpose_env.sh # .venv + nvcc + 清 ROS 干扰；跑 .venv 脚本前必 source
|
||
```
|
||
|
||
流程脚本自己的环境变量（`HF_*`、`SPIDER_*`）只改**输出**目录，序列名与输入路径写死在脚本里；换视频要改哪些常量见 [PIPELINE_LATEST.md §3](PIPELINE_LATEST.md)。
|
||
|
||
## 6. 启动前检查
|
||
|
||
```bash
|
||
source scripts/foundationpose_env.sh
|
||
python -c "import torch, pytorch3d, nvdiffrast.torch, mujoco, mujoco_warp, warp, trimesh, coacd, open3d, kornia, cv2; print(torch.cuda.is_available(), torch.__version__, mujoco.__version__)"
|
||
python scripts/verify_foundationpose_setup.py
|
||
for f in 2023-10-28-18-33-37 2024-01-11-20-02-45; do test -s third_party/FoundationPose/weights/$f/model_best.pth || echo "missing FoundationPose $f"; done
|
||
ls third_party/Dyn-HaMR/_DATA/hamer_ckpts third_party/Dyn-HaMR/_DATA/data/mano third_party/Dyn-HaMR/_DATA/hmp_model third_party/Dyn-HaMR/_DATA/BMC
|
||
test -s third_party/Dyn-HaMR/_DATA/data/mano/MANO_RIGHT.pkl
|
||
test -s third_party/Dyn-HaMR/third-party/hamer/pretrained_models/detector.pt
|
||
third_party/Dyn-HaMR/.dynhamr/bin/python -c "import torch, smplx, ultralytics; print(torch.__version__)"
|
||
.dex/bin/python -c "import dex_retargeting, pinocchio, mujoco, h5py; print('retarget ok', mujoco.__version__)"
|
||
.spider/bin/python -c "import torch, mujoco, mujoco_warp, warp, spider; print(torch.cuda.is_available(), mujoco.__version__)"
|
||
env PYTHONPATH= LD_LIBRARY_PATH= .spider/bin/python scripts/verify_spider_install.py
|
||
test -s third_party/l20_assets/L20/RIGHT/linkerhand_g20_right.urdf && test -s third_party/l20_assets/L20/LEFT/linkerhand_g20_left.urdf
|
||
test -s docs/20260915_171525/intrinsics.json && test -s docs/上半.stl && test -s docs/下半.stl
|
||
```
|
||
|
||
导入通过只是第一层；随后按 [PIPELINE_LATEST.md](PIPELINE_LATEST.md) 用 `--pilot` / 短段先跑一遍。
|
||
|
||
## 7. 源码包与上传
|
||
|
||
```bash
|
||
python3 scripts/package_source_release.py --output dist/hand-motion-pipeline-20260917
|
||
```
|
||
|
||
产物 `dist/hand-motion-pipeline-20260917/` 与同名 `.tar.gz`。包内：`scripts/ docs/ configs/ requirements/ model/ utils/ preprocessing/ visualization/`、根文件，以及 6 个上游快照 `third_party/{hamer, vipe, Dyn-HaMR, spider, FoundationPose, nvdiffrast}`（工作树内容，含本地补丁，各自 LICENSE 保留）。清单：`UPSTREAM_SOURCES.json`（上游 commit / origin / 本地改动）、`EXTERNAL_ASSETS.json`（未打包资源哈希）、`EXCLUDED_FILES.json`、`PORTABILITY_REPORT.json`（写死的本机路径与序列名）、`RELEASE_VALIDATION.json`、`SHA256SUMS`。排除：权重、`_DATA`、缓存、venv、`output/`、编译产物、录制数据、`.git`。
|
||
|
||
```bash
|
||
tar xzf dist/hand-motion-pipeline-20260917.tar.gz && cd hand-motion-pipeline-20260917
|
||
git init -b main && git add . && git commit -m "Import RGB-D hand-object pipeline: Dyn-HaMR, L20 retargeting, FoundationPose, SPIDER"
|
||
git remote add origin <仓库地址> && git push -u origin main
|
||
```
|
||
|
||
包里的 `.gitignore` 已把权重、缓存、录制数据、`output/` 挡在仓库外；大文件走平台附件或独立存储，按第 4 节路径恢复。
|
||
|
||
## 8. 已知限制
|
||
|
||
- 没有干净机器的端到端安装复现记录；版本表是本机观测。
|
||
- SPIDER 在本机是 Python 3.11 兼容安装，上游声明 ≥ 3.12。
|
||
- FoundationPose 权重来自社区镜像，未与官方文件比对。
|
||
- 脚本序列名写死为 `20260915_171525`；`PORTABILITY_REPORT.json` 列出全部此类行。
|
||
- 交付的是运动学参考与 SPIDER 物理审计结果；**未验证真机**，抓取未复现（见 PIPELINE_LATEST.md 现状）。
|