hand-motion-pipeline/docs/SETUP_AND_WEIGHTS.md

安装依赖、环境与权重（2026-09-17）

适用：源码快照 hand-motion-pipeline-20260917（由 scripts/package_source_release.py 生成）。链路为 RGB-D → Dyn-HaMR → L20 重定向 → FoundationPose → 参考修复 → SPIDER，执行顺序与每步命令见 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 里除重定向和 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。.dex 的 MuJoCo 3.5 与 SPIDER 的 3.7 不能装进同一个环境。

3. 安装顺序

3.1 主环境 .venv（FoundationPose + 全部流程脚本）

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。

3.2 Dyn-HaMR .dynhamr

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

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。干净机器按上游装：

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。克隆后先拼回：

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 官网 注册下载，不在任何包里	是（双手处理按 Dyn-HaMR 代码检查左手资源）
WiLoR 手检测器 detector.pt	52 MB	weights/detector.pt + third_party/Dyn-HaMR/third-party/hamer/pretrained_models/detector.pt	WiLoR HF Space	是
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、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、检测器

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 权重

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 下载慢或中断

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. 路径与环境变量

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。

6. 启动前检查

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 用 --pilot / 短段先跑一遍。

7. 源码包与上传

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。

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 现状）。