Extension setup扩展环境

For the published wheel, start with the 0.0.5 installation guide. The repository paths and manual source instructions below apply to source checkouts.

已发布 wheel 请先按0.0.5 安装引导操作。下方仓库路径和手工源码步骤适用于源码副本。

Optional wheel featureswheel 可选功能

Basic installation does not install all optional frameworks. Prepare only the feature you need, or let its supported first-use entry prepare it. Extras such as wapr[det2d] provide helper dependencies; they do not replace feature preparation. Examples 01, 08, 09 and 12 prepare detection dependencies before use; importing these examples alone does not install optional features. Ultralytics is not a core pip dependency. If preparation is declined or incompatible, the feature stops before importing its optional framework. Inspect compatibility before installation:

基础安装不会安装全部可选框架。只准备需要的功能，或由支持首次使用准备的入口触发。wapr[det2d] 等 extras 提供辅助依赖，不代替功能准备。示例 01、08、09、12 会先准备检测依赖再使用，仅导入这些示例不会启动可选安装；Ultralytics 不属于 pip 基础依赖。准备被拒绝或环境不兼容时，对应功能会在导入可选框架前停止。可先检查兼容性：

python -m wapr.bootstrap --feature det2d --check
python -m wapr.bootstrap --feature det2d
python -m wapr.bootstrap --feature sam3d
python -m wapr.bootstrap --feature robot

SAM3D can reuse a compatible environment; incompatible environments are routed to an independent Python 3.11 environment. Model access is separate: provide your own authorized Hugging Face account or local weights. WAPR does not provide access credentials. Examples 11 and 12 both default to cracker; mustard images elsewhere show recorded examples.

SAM3D 可以复用兼容环境；不兼容时使用独立 Python 3.11 环境。模型权限需单独准备：使用自己的已授权 Hugging Face 账户或本地权重，WAPR 不提供访问凭据。示例 11、12 默认均为 cracker；其他页面的 mustard 图片属于已录制展示。

Use --feature compatible to attempt the optional features supported by the current environment. Unsupported features are reported. Changes to existing dependencies require approval; inspect the proposed changes before accepting.

使用 --feature compatible 可尝试准备当前环境支持的可选功能；不支持的功能会报告原因。更换已有依赖需要确认，请先查看变更内容。

After installing the detection and pose environment, prepare only the extra dependencies needed by the application you use.

完成检测与位姿环境安装后，再按需准备以下应用的额外依赖。

Reconstruction物体重建

For manual source installation only, prepare a compatible reconstruction environment; do not install incompatible reconstruction dependencies into the WAPR environment. The base installer does not prepare these models. The source, checkpoint and compatibility requirements are listed below. Reconstruction uses Linux, CUDA and the EGL renderer; SAM 3D Objects^[3] specifies at least 32 GB of GPU memory.

仅手工源码安装：准备兼容的重建环境，不要向 WAPR 环境安装不兼容的重建依赖。基础安装脚本不准备这些模型，下方集中列出源码、权重与兼容要求。重建使用 Linux、CUDA 和 EGL 渲染器；SAM 3D Objects^[3] 要求至少 32 GB 显存。

UniPose9D^[5] is resolved from third_party/UniPose9D/, including infer/ and checkpoints/{last.ckpt,config.yaml}. Place full tracking sequences under datasets/YCBInEOAT/, full BOP data under datasets/bop/, and Qwen2.5-VL-3B-Instruct^[7] under assets/weights/Qwen2.5-VL-3B-Instruct/. These paths are anchored to the release directory, independently of the shell working directory. Existing environment overrides remain optional; relative overrides use that same release directory.

UniPose9D^[5] 默认从 third_party/UniPose9D/ 读取 infer/ 及 checkpoints/{last.ckpt,config.yaml}。完整跟踪序列放在 datasets/YCBInEOAT/，完整 BOP 数据放在 datasets/bop/，Qwen2.5-VL-3B-Instruct^[7] 放在 assets/weights/Qwen2.5-VL-3B-Instruct/。路径均由发布目录定位，不依赖启动目录；已有环境变量覆盖仍可使用，其相对路径也由发布目录定位。

git clone https://github.com/qq456cvb/UniPose9D.git third_party/UniPose9D
git -C third_party/UniPose9D checkout f8e020919e7303da580f428e5600e7db78438377
git -C third_party/UniPose9D lfs pull --include=checkpoints/last.ckpt
hf download Qwen/Qwen2.5-VL-3B-Instruct --local-dir assets/weights/Qwen2.5-VL-3B-Instruct

Download the selected upstream revisions and model files into these directories before running the examples. Git LFS is required for UniPose9D. SAM 3D access requires the upstream model agreement. Reconstruction stages write under outputs/reconstruction_stages/.

先将所选上游源码与模型文件下载到上述目录，再运行示例。UniPose9D 需要 Git LFS；SAM 3D 需按上游模型协议申请访问。重建阶段输出统一放在 outputs/reconstruction_stages/。

Obtain the SAM 3D checkpoints from the upstream gated model repository after receiving access; the repository's code checkout alone is insufficient. UniPose9D stores last.ckpt with Git LFS, so a small text pointer is not a usable checkpoint. The native SAM 2^[2] file above is distinct from assets/weights/det2d/sam2.1_l.pt, which uses the Ultralytics^[1] weight format. Keep the MoGe^[4] checkpoint version paired with this pipeline; replacing it with a newer MoGe model changes the input to SAM 3D and needs its own evaluation.

SAM 3D 权重需先取得上游受控模型仓库访问权限，再按其说明下载；仅检出源码不能运行。UniPose9D 的 last.ckpt 通过 Git LFS 保存，体积很小的文本指针不能当作权重使用。上述官方 SAM 2^[2] 实现的权重与采用 Ultralytics^[1] 格式的 assets/weights/det2d/sam2.1_l.pt 不同。MoGe^[4] 权重应与此 SAM 3D 流程匹配；更换 MoGe 模型会改变生成模型的输入，需要评测其影响。

The source helper clones the tested SAM 2 and SAM 3D Objects revisions when absent and applies the WAPR compatibility patch. It checks existing checkouts without replacing another revision. The patch preserves deferred gsplat imports, texture-bake controls and hole filling, and a depth-edge fallback. Run the helper from the release root; the equivalent manual commands follow for offline or controlled installations.

源码准备脚本在目录缺失时检出已测试的 SAM 2 与 SAM 3D Objects 版本，并应用 WAPR 兼容补丁；对于已有源码，只检查版本，不替换其他检出。补丁包含延后加载 gsplat、控制纹理烘焙并补齐空纹素，以及深度边缘计算的兼容实现。从项目根目录运行下列脚本；其后列出等效的手动命令，供离线或受控安装使用。

conda activate wapr
python wapr/tools/prepare_reconstruction_sources.py

This helper prepares source trees; it does not install their Python dependencies or download gated checkpoints. Install the packages in the same Python environment used by WAPR and follow the SAM 3D Objects setup for GPU-specific components. Its upstream environment uses PyTorch^[9] 2.5.1 with CUDA 12.1, while the WAPR reference environment uses PyTorch 2.8.0 with CUDA 12.8. WAPR does not force those exact versions onto an existing GPU environment. Match compiled packages such as PyTorch3D^[13] to the PyTorch and CUDA versions actually selected. The reconstruction configuration uses NumPy^[10] 1.26.4, PyTorch 2.8.0+cu128, PyTorch3D 0.7.8+pt2.8.0cu128, and xatlas^[15] 0.0.11.

该脚本只准备源码，不安装 Python 依赖，也不下载受控权重。附加包须安装到运行 WAPR 的同一 Python 环境；GPU 专用组件参照 SAM 3D Objects 官方安装说明。上游环境采用 PyTorch^[9] 2.5.1 / CUDA 12.1，WAPR 参考环境使用 PyTorch 2.8.0 / CUDA 12.8，但不要求已有 GPU 环境替换为这些精确版本；PyTorch3D^[13] 等编译包须与最终选择的 PyTorch 和 CUDA 版本一致。重建环境配置使用 NumPy^[10] 1.26.4、PyTorch 2.8.0+cu128、PyTorch3D 0.7.8+pt2.8.0cu128 和 xatlas^[15] 0.0.11。

The reconstruction reference environment uses NumPy 1.26.4, satisfying SAM 2’s NumPy ≥ 1.24.4 requirement. Keep the source revisions and compatibility patch specified here. Install the dependencies for the reconstruction preset you choose, run the preflight below, and verify an inference call before processing a sequence.

重建参考环境使用 NumPy 1.26.4，满足 SAM 2 的 NumPy ≥ 1.24.4 要求。保留本页指定的源码版本与兼容补丁，按所选重建预设准备依赖，再运行下方预检，并在处理序列前验证一次推理。

The tested source revisions are SAM 2 2b90b9f and SAM 3D Objects f91db41. Existing compatible checkouts need no second patch application.

已测试的源码版本分别为 SAM 2 2b90b9f 与 SAM 3D Objects f91db41。已有兼容源码无需再次打补丁。

git clone https://github.com/facebookresearch/sam2.git third_party/sam2
git -C third_party/sam2 checkout 2b90b9f5ceec907a1c18123530e92e794ad901a4
git clone https://github.com/facebookresearch/sam-3d-objects.git third_party/sam-3d-objects
git -C third_party/sam-3d-objects checkout f91db411c50efee93d8db7aeb323885650f6f722
git -C third_party/sam-3d-objects apply ../../wapr/tools/patches/sam3d_wapr_compat.patch

Once the files below are in place, run the read-only preflight from the release root. It reports missing assets, incompatible NumPy, a Git LFS pointer instead of a checkpoint, and links to weights outside this directory. READY means the files and runtime prerequisites were found; it does not replace an inference run.

备齐以下文件后，从项目根目录运行只读预检。它会报告缺失资源、不兼容的 NumPy、尚未下载的 Git LFS 指针，以及指向项目外的权重链接。READY 表示文件和运行前提已找到，仍需实际推理验证。

RECON_DATA_ROOT=/path/to/YCBInEOAT python wapr/tools/check_reconstruction_setup.py

Robot simulation机器人仿真

Use the existing Conda environment wapr with Python 3.10. The robot examples require ManiSkill^[11], SAPIEN^[12] rendering and motion-planning dependencies. The recorded episodes used ManiSkill 3.0.1. Run these commands from the release directory:

使用已有的 Python 3.10 Conda 环境 wapr。机器人示例需要 ManiSkill^[11]、SAPIEN^[12] 渲染及运动规划依赖，录制回合使用 ManiSkill 3.0.1。在发布目录下运行：

conda activate wapr
python -m pip install 'mani_skill==3.0.1'
python wapr/tools/check_robot_setup.py
python wapr/tools/check_robot_render.py

The setup check reads packages, engine files, task meshes, and saved inputs without starting a simulation. Its ROBOT_EXAMPLE_* lines identify optional missing assets. The render check creates one PickCube frame and closes the environment; use it to test the graphics stack before a long episode. A missing system libvulkan.so.1 is a warning rather than proof of failure because SAPIEN can use its bundled loader. The render check is decisive.

环境检查只读取包、引擎、任务网格和已保存输入，不启动仿真；ROBOT_EXAMPLE_* 行列出各专题资源是否就绪。渲染检查创建一帧 PickCube 图像后关闭环境，可在长回合前验证图形栈。系统找不到 libvulkan.so.1 只是一条提示：SAPIEN 也可能使用内置加载器，应以实际渲染检查为准。

Example 14 needs ManiSkill's Bridge^[16] assets. Download them with ManiSkill's asset command, then check that the carrot and eggplant collision meshes exist under ~/.maniskill/data/tasks/bridge_v2_real2sim_dataset/custom/models/. The current script reads this default location directly. If you set MS_ASSET_DIR to another directory, update BRIDGE_ROOT at the top of examples/14_bridge_tasks.py to the matching task directory.

示例 14 需要 ManiSkill 的 Bridge^[16] 资源。用其资源命令下载，再检查 ~/.maniskill/data/tasks/bridge_v2_real2sim_dataset/custom/models/ 下是否有胡萝卜和茄子的碰撞网格。当前脚本直接读取这个默认位置；若通过 MS_ASSET_DIR 改了资源根目录，还需在 examples/14_bridge_tasks.py 顶部同步修改 BRIDGE_ROOT。

python -m mani_skill.utils.download_asset bridge_v2_real2sim
python wapr/tools/check_robot_setup.py

Optional performance experiments可选性能实验

The inference/renderer comparison additionally needs ONNX Runtime^[14] GPU and nvdiffrast^[8] in the same Python 3.10 environment. The recorded versions are ONNX Runtime 1.23.2 and nvdiffrast 0.3.3.1. Follow the official CUDA/cuDNN compatibility instructions and nvdiffrast installation instructions for the installed PyTorch/CUDA stack. These are optional benchmark dependencies, outside the default estimator installation.

推理与渲染后端对照还需在同一 Python 3.10 环境中准备 ONNX Runtime^[14] GPU 与 nvdiffrast^[8]，记录版本分别为 1.23.2 与 0.3.3.1。按官方 CUDA/cuDNN 兼容说明与 nvdiffrast 安装说明匹配当前 PyTorch/CUDA 栈。这些仅用于可选性能实验，不属于默认估计器依赖。