Files
hand-motion-pipeline/docs/SETUP_AND_WEIGHTS.md
T

20 KiB
Raw Blame History

安装依赖、环境与权重(2026-09-17)

部署指引更新:2026-10-27。本文是完整 RGB-D 流程的安装入口;根目录 requirements.txt、setup_env.sh、setup_vipe_env.sh 仅用于旧 HandFlow / ViPE 分支。先按第 4.0 节准备资源,再安装四个环境并执行第 6 节检查。

适用:源码快照 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,从这个环境发现 NVIDIA 包头文件。toolkit 优先使用调用者设置的 CUDA_HOME,其次使用项目内 toolkit,再从 PATH 的 nvcc 定位;缺失时明确报错。GPU 编译架构默认由 PyTorch 检测,显式设置的 TORCH_CUDA_ARCH_LIST 会保留。无需复制开发者的 Python 环境。所有 .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
# nvcc 不在 PATH 中时,先 export CUDA_HOME=/path/to/your/cuda-toolkit
source scripts/foundationpose_env.sh            # 默认使用 .venv/bin/python,检查本机 nvcc
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_LFS_SKIP_SMUDGE=1 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/check_pipeline_resources.py --prepare-example --recording-only
mkdir -p output

资源检查命令会为嵌套录制创建缺失的相对链接,将 docs/20260915_171525/20260915_171525/{color.mp4,depth/} 暴露到脚本读取的外层目录;已有文件不覆盖、源数据不移动。标准布局不改动;未拉取的 LFS 指针和缺失深度帧会报错。

third_party/Dyn-HaMR/_DATA/ 保留资源相对软链接,MANO 目标目录尚无模型。LFS 拉取与组装后,还需按第 4.1 节准备 MANO,在目标机器安装环境、构建扩展。assemble --clean 仅是可选的本地磁盘整理操作,日常部署可保留分片。

当前 Git LFS 仓库与源码压缩包是两种交付方式。 仓库已包含主流程权重、L20、录制与 CAD;package_source_release.py 导出的源码包仅含代码、配置、文档和小 CAD,其他资源需另行恢复。下表列资源位置与来源,不表示 Git LFS 接收方必须重复下载。EXTERNAL_ASSETS.json 是原源码包资源记录,当前分片校验以 configs/large_files.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,以及需要独立左手模型时的 MANO_LEFT.pkl — third_party/hamer/_DATA/data/mano/(Dyn-HaMR 软链接共用) MANO 官网 自行取得;未上传 是(左手文件按分支准备)
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、检测器

Git LFS 部署无需重新运行上游下载脚本覆盖已有资源。 完成第 4.0 节后,将按 MANO 官方条件取得的模型放入共享目录:

third_party/hamer/_DATA/data/mano/MANO_RIGHT.pkl
third_party/hamer/_DATA/data/mano/MANO_LEFT.pkl   # 使用独立左手模型的分支需要

third_party/Dyn-HaMR/_DATA/data/mano 是指向这里的相对软链接,默认 MANO_ROOT 也指向这里。修改 MANO_ROOT 只影响支持该变量的入口,不能替代 Dyn-HaMR 固定目录或其软链接。模型不在 Git / LFS 中,无需上传开发者主目录或完整 Python 环境。

python3 scripts/check_pipeline_resources.py
# 使用独立左手模型的分支:
python3 scripts/check_pipeline_resources.py --require-left-mano

以下下载方式只用于不含资源的源码包部署或缺失资源恢复;先保留已有资源,按需执行:

cd third_party/Dyn-HaMR && bash scripts/prepare.sh && cd ../..      # 需要 gdown;下载后核对 _DATA 内四个子目录都非空
# MANO:按上方说明放到 third_party/hamer/_DATA/data/mano/
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 权重

Git LFS 拉取并组装成功后可跳过本节下载;以下用于源码包部署或缺失文件恢复。

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 模型与录制数据

Git LFS 仓库已包含左右手 URDF、网格、标定文件和示例录制。先拉取 LFS,再执行第 4.0 节示例准备命令。只有源码包部署需要单独恢复这些资源,原资源哈希见 EXTERNAL_ASSETS.json。自己的录制使用 docs/<seq>/{color.mp4,depth/,intrinsics.json} 布局,并按 PIPELINE 适配序列、帧数和 CAD 映射。

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
# nvcc 不在 PATH 中时,先 export CUDA_HOME=/path/to/your/cuda-toolkit
source scripts/foundationpose_env.sh      # .venv + nvcc + 清 ROS 干扰;跑 .venv 脚本前必 source

流程脚本自己的环境变量(HF_*、SPIDER_*)只改输出目录,序列名与输入路径写死在脚本里;换视频要改哪些常量见 PIPELINE_LATEST.md §3。

HANDFLOW_PYTHON 可指定环境脚本所用主 Python,默认 .venv/bin/python;其他显式解释器路径仍需按部署对应。旧 run_handflow_15886123.py、export_camera_delivery.py 已要求 --input /path/to/source.mp4。项目不依赖开发者的主目录或下载目录。上游示例路径及迁移边界见 PORTABILITY.md。

6. 启动前检查

python3 scripts/check_pipeline_resources.py
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

本节生成的是源码包,运行资源不在包内。按第 4 节恢复资源,或直接使用当前带 Git LFS 资源的仓库。当前云端 LFS 跟踪规则与源码包排除规则不同,不能用源码包说明判断云端是否有权重。

8. 已知限制

  • 没有干净机器的端到端安装复现记录;版本表是本机观测。
  • SPIDER 在本机是 Python 3.11 兼容安装,上游声明 ≥ 3.12。
  • FoundationPose 权重来自社区镜像,未与官方文件比对。
  • 脚本序列名写死为 20260915_171525;PORTABILITY_REPORT.json 列出全部此类行。
  • 交付的是运动学参考与 SPIDER 物理审计结果;未验证真机,抓取未复现(见 PIPELINE_LATEST.md 现状)。