HuggingFace镜像/Pi3
模型介绍
文件和版本
分析

🌌 pi3\\pi^3pi3: 可扩展的置换等变视觉几何学习

Paper Project Page GitHub Hugging Face Demo

$\\pi^3$无需固定参考视图即可重建视觉几何，实现稳健的最先进性能。

✨ 概述

我们提出pi3\\pi^3pi3（Pi-Cubed），这是一种新颖的前馈神经网络，通过消除对固定参考视图的需求，彻底改变了视觉几何重建。传统方法依赖于指定的参考帧，如果参考帧不理想，往往容易出现不稳定和失效的情况。

相比之下，pi3\\pi^3pi3采用了完全置换等变的架构。这使其能够从无序图像集合中直接预测仿射不变的相机姿态和尺度不变的局部点图，摆脱了参考帧的限制。这种设计使我们的模型本质上对输入顺序具有稳健性，并且高度可扩展。

我们这种简单、无偏设计的一个关键涌现特性是学习到了相机姿态流形的密集且结构化的 latent 表示。无需复杂的先验知识或训练方案，pi3\\pi^3pi3在广泛的任务上实现了最先进的性能🏆，包括相机姿态估计、单目/视频深度估计以及密集点图估计。

🚀 快速开始

1. 克隆仓库并安装依赖

首先，克隆仓库并安装所需的软件包。

git clone https://github.com/yyfz/Pi3.git
cd Pi3
pip install -r requirements.txt

2. 通过命令行运行推理

试试我们的推理示例脚本。您可以在图像目录或视频文件上运行该脚本。

如果从 Hugging Face 自动下载速度较慢，您可以从此处手动下载模型检查点，并使用 --ckpt 参数指定其本地路径。

# Run with default example video
python example.py

# Run on your own data (image folder or .mp4 file)
python example.py --data_path <path/to/your/images_dir_or_video.mp4>

可选参数：

  • --data_path：输入图像目录或视频文件的路径。（默认值：examples/skating.mp4）
    • --save_path：保存输出 .ply 点云的路径。（默认值：examples/result.ply）
    • --interval：帧采样间隔。（默认值：图像为 1，视频为 10）
    • --ckpt：自定义模型检查点文件的路径。
    • --device：用于运行推理的设备。（默认值：cuda）

3. 使用 Gradio 演示运行

您也可以启动本地 Gradio 演示以获得交互式体验。

# Install demo-specific requirements
pip install -r requirements_demo.txt

# Launch the demo
python demo_gradio.py

🛠️ 详细使用说明

模型输入与输出

该模型接收图像张量作为输入，并输出包含重建几何信息的字典。

  • 输入：形状为 B×N×3×H×WB \times N \times 3 \times H \times WB×N×3×H×W 的 torch.Tensor，像素值范围为 [0, 1]。
    • 输出：包含以下键的 dict：
      • points：通过 local points 和 camera_poses 反投影得到的全局点云（torch.Tensor，B×N×H×W×3B \times N \times H \times W \times 3B×N×H×W×3）。
      • local_points：每视角的局部点图（torch.Tensor，B×N×H×W×3B \times N \times H \times W \times 3B×N×H×W×3）。
      • conf：局部点的置信度分数（值范围为 [0, 1]，分数越高越好）（torch.Tensor，B×N×H×W×1B \times N \times H \times W \times 1B×N×H×W×1）。
      • camera_poses：相机到世界的变换矩阵（OpenCV 格式下的 4x4 矩阵）（torch.Tensor，B×N×4×4B \times N \times 4 \times 4B×N×4×4）。

示例代码片段

以下是在一批图像上运行模型的极简示例。

import torch
from pi3.models.pi3 import Pi3
from pi3.utils.basic import load_images_as_tensor # Assuming you have a helper function

# --- Setup ---
device = 'cuda' if torch.cuda.is_available() else 'cpu'
model = Pi3.from_pretrained("yyfz233/Pi3").to(device).eval()
# or download checkpoints from `https://huggingface.co/yyfz233/Pi3/resolve/main/model.safetensors`

# --- Load Data ---
# Load a sequence of N images into a tensor
# imgs shape: (N, 3, H, W).
# imgs value: [0, 1]
imgs = load_images_as_tensor('examples/skating.mp4', interval=10).to(device)

# --- Inference ---
print("Running model inference...")
# Use mixed precision for better performance on compatible GPUs
dtype = torch.bfloat16 if torch.cuda.is_available() and torch.cuda.get_device_capability()[0] >= 8 else torch.float16

with torch.no_grad():
    with torch.amp.autocast('cuda', dtype=dtype):
        # Add a batch dimension -> (1, N, 3, H, W)
        results = model(imgs[None])

print("Reconstruction complete!")
# Access outputs: results['points'], results['camera_poses'] and results['local_points'].

🙏 致谢

本研究基于多个优秀的开源项目开展。我们在此向以下项目的作者们表示衷心的感谢：

  • DUSt3R
    • CUT3R
    • VGGT

📜 引用

如果您觉得我们的研究工作对您有所帮助，敬请考虑引用：

@misc{wang2025pi3,
      title={$\\pi^3$: Scalable Permutation-Equivariant Visual Geometry Learning}, 
      author={Yifan Wang and Jianjun Zhou and Haoyi Zhu and Wenzheng Chang and Yang Zhou and Zizun Li and Junyi Chen and Jiangmiao Pang and Chunhua Shen and Tong He},
      year={2025},
      eprint={2507.13347},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2507.13347}, 
}

📄 许可证

本项目的学术用途遵循 2 条款 BSD 许可证。详情请参见 LICENSE 文件。商业用途请联系作者。