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；未推断任何额外功能。