Pi3

🚀 🌌 π³：可擴展的排列等變視覺幾何學習

π³是一種新穎的前饋神經網絡，它通過消除對固定參考視圖的需求，革新了視覺幾何重建。傳統方法依賴指定參考幀，若參考不佳則易不穩定或失敗，而π³採用全排列等變架構，能從無序圖像集直接預測仿射不變相機位姿和尺度不變局部點圖，對輸入順序具有魯棒性且高度可擴展，在眾多視覺幾何任務中實現了先進性能。

🚀 快速開始

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文件。對於商業用途，請聯繫作者。