yyfz/Pi4
机器学习用一个模型前向同时重建 4D 场景几何与相机运动,面向三维视觉与图形研究。
项目介绍
π⁴ 是一个约 0.5B 参数的基础模型,在一次前向中同时完成场景几何重建与运动估计。输入可以是单张图片、无序图像集合或不带相机标定的视频,输出局部点图、相机位姿、稠密 2D/3D 轨迹、动态掩码和置信度等结果。项目面向三维视觉、场景重建和视频跟踪方向的研究者。
模型训练时最多使用 64 个视角,但项目报告称可以对上千张输入图像做联合重建与跟踪。仓库提供 Hugging Face 权重、查看导出结果的浏览器界面,以及自动处理归一化、推理精度和梯度关闭的 Python API。
快速使用
准备 Linux x86-64 环境、Python 3.11、支持 BF16 的 NVIDIA GPU 和兼容 CUDA 12.6 的驱动,并在仓库根目录执行:
conda create -n pi4 python=3.11 -y
conda activate pi4
python -m pip install --upgrade pip
python -m pip install -r requirements-cu126.txt
python -m pip check
python -c "import torch; assert torch.cuda.is_available(), 'CUDA is not available'; print(torch.__version__, torch.version.cuda)"
这会安装 PyTorch 2.12.1 + CUDA 12.6、Triton 3.7.1 和固定版本的 FlexGEMM 后端,需要 Git 和 C 编译器。其他 CUDA 构建与检查项见安装说明。
对自带的花样滑冰片段运行重建与跟踪:
python example.py examples/figure_skating.mp4 \
--output outputs/quickstart \
--query-frame 0 --stride 1 --max-frames 150 --viewer
示例会自动从 Hugging Face 下载并缓存检查点,也可以用 --weights 传入本地文件。随后启动浏览器查看:
python viewer/serve.py outputs/quickstart --port 8080
打开服务打印的地址,即可旋转观察重建场景、查看相机运动和点轨迹,或将序列与 RGB 输入并排播放。查看导出结果不需要 GPU 或模型权重。使用 Python API 时,用 load_images 加载帧,整理为 [0, 1] 的浮点 RGB,形状为 [B, T, 3, H, W] 且高宽能被 16 整除,再传入 query_frame 调用模型;省略 query_frame 则只做几何推理。张量形状、坐标约定和导出格式见推理指南。
使用约束
- 推理需要支持 BF16 的 NVIDIA GPU;150 帧配置在 A800 80 GB 上实测峰值显存 12.03 GiB,小显存需减少帧数,完整 750 帧演示需要明显更多显存。
- 跟踪至少需要两张图像。
- 自带片段为 512 × 288 或 288 × 512,
--stride在加载时对帧采样。 - 点图和相机平移使用模型原生尺度,3D 轨迹已在预测的度量世界坐标中。
- 原始 Pi4 代码与模型权重采用 CC BY-NC 4.0 许可,不允许商业使用;第三方组件沿用各自上游许可。
HotRepo 点评
Pi4 进入新项目榜首日,积累了 117 星和 3 个 fork,在 2026-11-18 首次与末次 Star 观测之间约一小时的窗口内新增 12 星。对一个没有站内讨论记录、也没有更早排名历史的研究型发布来说,这是很强的开局。0.5B 的模型规模、Hugging Face 权重和不依赖 GPU 的查看器降低了尝试 4D 重建的门槛,但非商业许可限制了生产环境使用。
本文由 AI 根据项目 README 生成,更新于 ,以项目官方文档为准。