naver/must3r

MUSt3R – ステレオ3D再構成のためのマルチビューネットワーク

何であるか – MUSt3Rは、MUSt3Rモデルを実装する研究用のPythonライブラリです。これは、複数の画像から密な3Dジオメトリを再構成するためのマルチビュー神経ネットワークです。以前のDUSt3Rアーキテクチャを基盤とし、対称処理、マルチレイヤーメモリ、オンラインカメラポーズ推定を追加することで、順序のない画像セット、ビデオストリーム、またはライブウェブカメラ入力を処理できるようにしています。

主な機能

• 任意の視点数（順序あり・順序なし）からのステレオスタイル3D再構成。
• オンラインポーズおよび構造推定 – モデルは3Dマップを構築しながらカメラポーズを予測し、SLAMのような動作を可能にします。
• メモリ機構 – 学習可能なトークンメモリが中間的なジオメトリを保存し、過去のフレームを精緻化し、順序のないコレクション向けに関連するキーフレームを取得できます。
• 2種類のモデルサイズ – 224ピクセル版（ViT-Lエンコーダ、ViT-Bデコーダ）は高速プロトタイピングに、512ピクセル版は高品質な結果に適しています。
• リトリーバルモード – 軽量な「トレーニング不要」エンコーダ＋コードブックを使用して、入力の順序が不明な場合に一致するキーフレームを検索できます。

入手方法

1. 環境の作成（Python 3.11、CMake ≥ 3.14）。READMEではmicromambaを推奨していますが、conda/virtualenvのいずれでも問題ありません。
2. PyTorchのインストール（2.7.0）：GPUに合ったCUDAビルドを使用してください。
3. オプションですが推奨：メモリ効率の高いアテンションのためにxformersをインストールしてください。
4. リポジトリから直接パッケージをインストールします：

   pip install must3r@git+https://github.com/naver/must3r.git
   # pillow-heif、curopeなど、任意の追加機能を指定可能
   

5. 開発用にはリポジトリをクローンし、サブモジュールをインストールし、補助的なasmkおよびオプションのRoPE CUDAカーネル（curope）をビルドできます。

事前学習済みチェックポイント

モデル	解像度	エンコーダ	デコーダ	ダウンロード
MUSt3R_224_cvpr.pth	224×224	ViT‑L	ViT‑B	リンク
MUSt3R_512_cvpr.pth	512×384 … 512×160	ViT‑L	ViT‑B	リンク
MUSt3R_512.pth（ファインチューニング済み）	上記と同様	ViT‑L	ViT‑B	リンク

順序のない画像モード用に、リトリーバル専用の重み（*_retrieval_trainingfree.pth）とコードブック（*_retrieval_codebook.pkl）も提供されています。

デモインターフェース

• Gradio + viser（オフライン） – python demo.py …（またはインストールされたmust3r_demoエントリポイント）を実行します。画像はGradio UI経由でアップロードされ、3D再構成結果はリアルタイムでviserウェブビューアにストリーミングされます。解像度、ミックスドプレシジョン（--amp bf16|fp16）、ローカルネットワークへの公開可否などを選択できます。
• ライブビジュアルオドメトリ（オンライン）デモ – python slam.py …（インストール済みのmust3r_slam）。ウェブカメラ、動画ファイル、またはフレームフォルダに対応します。キーフレーム選択、ポーズ追跡、Open3Dで可視化された3Dポイントクラウドを表示します。メモリのリフレッシュ、キーフレーム間隔、焦点距離推定、GPU加速RoPEカーネルなどの高度なフラグで制御可能です。

トレーニング リポジトリには完全なトレーニングパイプライン（train.py、eval.py）が含まれています。トレーニングでは、5枚の画像ブロックを因果的アテンションマスクで処理するcausalバージョンのモデル（CausalMUSt3R）を使用しており、勾配計算を高速化します。READMEには重要なハイパーパラメータ（メモリサイズ、ドロップアウトモード、ミックスドプレシジョン、視点数など）がリストアップされており、マルチGPUトレーニング用のtorchrunコマンドのサンプルも示されています。

ライセンス MUSt3Rは非営利ライセンスの下でリリースされています。リポジトリのLICENSEに加え、NOTICEファイルにはトレーニングデータセット（例：「mapfree」データセット）の制限付きライセンスが詳細に記載されています。提供されるチェックポイントを使用するには、MUSt3Rライセンスおよびデータセットライセンスの両方に同意する必要があります。

誰が使うべきか

• ニューラルSLAM、マルチビュー幾何、または密な再構成を研究している研究者。
• 手持ちカメラからの即時3Dマッピングが必要なAR/VRパイプラインを開発する開発者。
• 順序付きビデオストリームと順序のない写真コレクションの両方を扱える、すぐに使えるステレオ再構成デモが必要な人。

---

上記のすべての情報はリポジトリのREADMEから直接引用しており、追加の機能は推測されていません。