Pi3

🚀 🌌 $\pi^3$: Scalable Permutation-Equivariant Visual Geometry Learning

$\pi^3$は、固定された参照ビューを必要とせずに視覚的な幾何学を再構築し、堅牢で最先端の性能を達成する新しいニューラルネットワークです。

$\\pi^3$は固定された参照ビューなしで視覚的な幾何学を再構築し、堅牢で最先端の性能を達成します。

✨ 概要

$\pi^3$ (Pi-Cubed) という新しいフィードフォワードニューラルネットワークを導入します。このネットワークは、固定された参照ビューを必要としないことで、視覚的な幾何学の再構築を革新します。指定された参照フレームに依存する従来の方法は、参照が最適でない場合、不安定性や失敗につながりやすい傾向があります。

対照的に、$\pi^3$は完全に順列等変なアーキテクチャを採用しています。これにより、順序付けされていない画像セットからアフィン不変のカメラポーズとスケール不変の局所点マップを直接予測でき、参照フレームの制約から解放されます。この設計により、モデルは本質的に入力の順序に対して堅牢であり、高い拡張性を備えています。

シンプルでバイアスのないこの設計の重要な特性の1つは、カメラポーズ多様体の密で構造化された潜在表現を学習することです。複雑な事前知識やトレーニングスキームを使用せずに、$\pi^3$はカメラポーズ推定、単眼/ビデオ深度推定、および密な点マップ推定などの幅広いタスクで最先端の性能を達成します🏆。

🚀 クイックスタート

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

🛠️ 詳細な使い方

モデルの入力と出力

モデルは画像のテンソルを入力として受け取り、再構築された幾何学を含む辞書を出力します。

• 入力: 画素値が[0, 1]の範囲にある、形状が$B \times N \times 3 \times H \times W$のtorch.Tensor。
• 出力: 以下のキーを持つ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("Running model inference...")
# 互換性のある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("Reconstruction complete!")
# 出力にアクセス: 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}, 
}

📄 ライセンス

学術的な使用の場合、このプロジェクトは2条項BSDライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。商用利用の場合は、作者にご連絡ください。