🚀 🌌 π³：可扩展的排列等变视觉几何学习

π³是一种新颖的前馈神经网络，它通过消除对固定参考视图的需求，革新了视觉几何重建。传统方法依赖指定参考帧，若参考不佳则易不稳定或失败，而π³采用全排列等变架构，能从无序图像集直接预测仿射不变相机位姿和尺度不变局部点图，对输入顺序具有鲁棒性且高度可扩展，在众多视觉几何任务中实现了先进性能。

🚀 快速开始

1. 克隆仓库并安装依赖

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

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

2. 从命令行运行推理

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

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

# 使用默认示例视频运行
python example.py

# 在你自己的数据（图像文件夹或.mp4文件）上运行
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演示以获得交互式体验。

# 安装演示特定的依赖项
pip install -r requirements_demo.txt

# 启动演示
python demo_gradio.py

✨ 主要特性

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

相比之下，π³采用了完全排列等变的架构。这使得它能够从无序的图像集中直接预测仿射不变的相机位姿和尺度不变的局部点图，摆脱了参考帧的限制。这种设计使我们的模型本质上对输入顺序具有鲁棒性，并且高度可扩展。

我们这种简单、无偏设计的一个关键新兴特性是学习相机位姿流形的密集结构化潜在表示。无需复杂的先验知识或训练方案，π³在广泛的任务中，包括相机位姿估计、单目/视频深度估计和密集点图估计，都实现了最先进的性能 🏆。

📚 详细文档

模型输入与输出

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

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

示例代码片段

以下是一个在一批图像上运行模型的最小示例。

import torch
from pi3.models.pi3 import Pi3
from pi3.utils.basic import load_images_as_tensor # 假设你有一个辅助函数

# --- 设置 ---
device = 'cuda' if torch.cuda.is_available() else 'cpu'
model = Pi3.from_pretrained("yyfz233/Pi3").to(device).eval()
# 或者从 `https://huggingface.co/yyfz233/Pi3/resolve/main/model.safetensors` 下载检查点

# --- 加载数据 ---
# 将N张图像序列加载到一个张量中
# imgs形状: (N, 3, H, W)。
# imgs值: [0, 1]
imgs = load_images_as_tensor('examples/skating.mp4', interval=10).to(device)

# --- 推理 ---
print("正在运行模型推理...")
# 在兼容的GPU上使用混合精度以获得更好的性能
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):
        # 添加一个批次维度 -> (1, N, 3, H, W)
        results = model(imgs[None])

print("重建完成！")
# 访问输出: results['points']、results['camera_poses'] 和 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}, 
}

📄 许可证

对于学术用途，本项目采用双条款BSD许可证。详情请参阅LICENSE文件。对于商业用途，请联系作者。