# 安装依赖、环境与权重（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 现状）。