Reloc3r 512

🚀 Reloc3r: 汎用的、高速かつ高精度なビジュアルローカライゼーションのための相対カメラポーズ回帰の大規模トレーニング

Reloc3rは、事前学習された2ビュー相対カメラポーズ回帰ネットワークとマルチビューモーション平均化モジュールを組み合わせた、シンプルで効果的なカメラポーズ推定フレームワークです。約800万のポーズ付き画像ペアでトレーニングされ、驚くほど良好なパフォーマンスと汎化能力を達成し、リアルタイムで高品質なカメラポーズ推定を行うことができます。

論文: https://huggingface.co/papers/2412.08376 コード: https://github.com/ffrivera0/reloc3r

🚀 クイックスタート

Reloc3rを使用することで、撮影した画像や動画のカメラポーズを推定することができます。以下のセクションでは、インストール方法、使用例、評価方法、トレーニング方法などについて説明します。

✨ 主な機能

• 事前学習された2ビュー相対カメラポーズ回帰ネットワークとマルチビューモーション平均化モジュールを組み合わせたカメラポーズ推定フレームワーク
• 約800万のポーズ付き画像ペアでトレーニングされ、良好なパフォーマンスと汎化能力を持つ
• リアルタイムで高品質なカメラポーズ推定を行うことができる

📦 インストール

1. Reloc3rをクローンします。

git clone --recursive https://github.com/ffrivera0/reloc3r.git
cd reloc3r
# すでにreloc3rをクローンしている場合は以下を実行
# git submodule update --init --recursive

2. condaを使用して環境を作成します。

conda create -n reloc3r python=3.11 cmake=3.14.0
conda activate reloc3r 
conda install pytorch torchvision pytorch-cuda=12.1 -c pytorch -c nvidia  # システムに合ったcudaバージョンを使用
pip install -r requirements.txt
# オプション: HEIC画像のサポートを追加する場合は以下を実行
pip install -r requirements_optional.txt

3. オプション: RoPE用のcudaカーネルをコンパイルします。

# Reloc3rはRoPE位置埋め込みに依存しており、高速な実行時間のためにいくつかのcudaカーネルをコンパイルすることができます。
cd croco/models/curope/
python setup.py build_ext --inplace
cd ../../../

4. オプション: チェックポイント Reloc3r-224/Reloc3r-512 をダウンロードします。事前学習されたモデルの重みは、以下の評価コードやデモコードを実行する際に自動的にダウンロードされます。

💻 使用例

基本的な使用法

相対ポーズ推定

wild_relpose.py のデモコードを試してみることができます。論文で使用したいくつかの画像ペアを用意しています。

# 引数を自分のパスに置き換えてください
python wild_relpose.py --v1_path ./data/wild_images/zurich0.jpg --v2_path ./data/wild_images/zurich1.jpg --output_folder ./data/wild_images/

相対ポーズを可視化するには、以下のコマンドを実行します。

# 引数を自分のパスに置き換えてください
python visualization.py --mode relpose --pose_path ./data/wild_images/pose2to1.txt

ビジュアルローカライゼーション

wild_visloc.py のデモコードは、自分で撮影した動画のサンプルフレームから絶対カメラポーズを推定します。

⚠️ 重要提示

このデモでは、最初と最後のフレームをデータベースとして使用しています。これには、すべての画像間に重複する領域が必要です。このデモは直線運動には対応していません。いくつかの動画を例として用意しています。

# 引数を自分のパスに置き換えてください
python wild_visloc.py --video_path ./data/wild_video/ids.MOV --output_folder ./data/wild_video

絶対ポーズを可視化するには、以下のコマンドを実行します。

# 引数を自分のパスに置き換えてください
python visualization.py --mode visloc --pose_folder ./data/wild_video/ids_poses/

📚 ドキュメント

相対カメラポーズ推定の評価

ScanNet1500とMegaDepth1500での評価を再現するには、ここからデータセットをダウンロードし、./data/ に解凍します。その後、以下のスクリプトを実行します。論文に示された結果と同様の結果が得られます。

bash scripts/eval_relpose.sh

💡 使用建议

より高速な推論速度を実現するには、--amp=1 を設定します。これにより、fp16 での評価が可能になり、RTX 4090でReloc3r-512を使用した場合、速度が24 FPS から 40 FPS に向上し、精度の損失はありません。

ビジュアルローカライゼーションの評価

Cambridgeでの評価を再現するには、ここからデータセットをダウンロードし、./data/cambridge/ に解凍します。その後、以下のスクリプトを実行します。論文に示された結果と同様の結果が得られます。

bash scripts/eval_visloc.sh

トレーニング

トレーニングデータの処理には DUSt3R を参考にしています。以下のデータセットをダウンロードします: CO3Dv2, ScanNet++, ARKitScenes, BlendedMVS, MegaDepth, DL3DV, RealEstate10K。

各データセットについて、datasets_preprocess ディレクトリに前処理スクリプトを用意しており、必要に応じてペアのリストを含むアーカイブを用意しています。データセットは公式ソースから自分でダウンロードし、ライセンスに同意して前処理スクリプトを実行する必要があります。

RTX 3090 GPUでScanNet++を使用してReloc3rをトレーニングするサンプルスクリプトを用意しています。

bash scripts/train_small.sh

8台のH800 GPUでReloc3r-512をトレーニングするには、以下のスクリプトを実行します。

bash scripts/train.sh

💡 使用建议

これらはReloc3rのトレーニングに使用されたものと厳密には同等ではありませんが、十分に近い結果が得られるはずです。

📄 ライセンス

本プロジェクトのライセンスについては、各データセットの公式ソースを参照してください。

📚 引用

本研究があなたの研究に役立った場合は、以下のように引用を考慮してください。

@article{reloc3r,
  title={Reloc3r: Large-Scale Training of Relative Camera Pose Regression for Generalizable, Fast, and Accurate Visual Localization},
  author={Dong, Siyan and Wang, Shuzhe and Liu, Shaohui and Cai, Lulu and Fan, Qingnan and Kannala, Juho and Yang, Yanchao},
  journal={arXiv preprint arXiv:2412.08376},
  year={2024}
}

謝辞

本実装はいくつかの素晴らしいリポジトリに基づいています。

• Croco
• DUSt3R

それぞれの著者にコードをオープンソース化してくれたことに感謝します。

TODOリスト

• [x] 事前学習された重みと推論コードを公開する。
• [x] ScanNet1500、MegaDepth1500、およびCambridgeデータセットの評価コードを公開する。
• [x] 自分で撮影した画像や動画のサンプルコードを公開する。
• [x] トレーニングコードとデータを公開する。
• [ ] 他のデータセットの評価コードを公開する。
• [ ] ビジュアルローカライゼーションの高速化バージョンを公開する。
• [ ] Gradioデモを公開する。