naver/must3r

MUSt3R – 用於立體3D重建的多視角網路

是什麼 – MUSt3R 是一個研究級的 Python 庫，實作了 MUSt3R 模型，這是一種用於從影像集合中重建密集 3D 幾何結構的多視角神經網路。它基於早期的 DUSt3R 架構，新增了對稱處理、多層記憶與線上相機位姿估計，使其能處理無序影像集、影片串流或即時網路攝影機輸入。

核心功能

• 任意數量視角（有序或無序）的立體風格 3D 重建。
• 線上位姿與結構估計 – 模型在建構 3D 地圖的同時預測相機位姿，支援類似 SLAM 的操作。
• 記憶機制 – 可學習的 token 記憶儲存中間幾何資訊，使網路能優化過去畫格，並為無序集合檢索相關關鍵畫格。
• 兩種模型尺寸 – 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
   # 可選 extras：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）。訓練使用模型的 causal 變體（CausalMUSt3R），以因果注意力遮罩處理 5 張影像塊，從而加速梯度計算。README 列出了重要超參數（記憶體大小、dropout 模式、混合精度、視角數量等），並展示了多 GPU 訓練的 torchrun 範例命令。

授權 MUSt3R 以 非商業授權 發布。除倉儲中的 LICENSE 外，NOTICE 檔案詳細說明了訓練資料集的限制性授權（例如「mapfree」資料集）。使用提供的檢查點前，使用者必須同意 MUSt3R 授權與資料集授權。

誰可能使用它

• 探索神經 SLAM、多視角幾何或密集重建的研究人員。
• 需要從手持相機即時生成 3D 地圖的 AR/VR 流程開發者。
• 需要一個可立即運行的立體重建示範，能同時處理有序影片串流與無序照片集合的任何人。

---

以上所有資訊均直接取自倉儲的 README；未推斷任何額外功能。