MapAnything: 通用前馈式度量3D重建

MapAnything: 通用前馈式度量3D重建

项目主页 | 论文 | 🤗 在线演示

作者团队

Meta 和 卡内基梅隆大学 的联合研究团队

主要贡献者：Nikhil Keetha、Norman Müller、Johannes Schönberger、Lorenzo Porzi、Yuchen Zhang、Tobias Fischer、Arno Knapitsch、Duncan Zauss、Ethan Weber、Nelson Antunes、Jonathon Luiten、Manuel Lopez-Antequera、Samuel Rota Bulò、Christian Richardt、Deva Ramanan、Sebastian Scherer、Peter Kontschieder

项目简介

MapAnything 是一个简单的端到端训练的 Transformer 模型，能够根据各种输入类型（图像、校准参数、姿态或深度）直接回归场景的分解度量3D几何。单个前馈模型支持超过12种不同的3D重建任务，包括：

• 多图像SfM（运动恢复结构）
• 多视图立体视觉
• 单目度量深度估计
• 配准
• 深度补全等

主要特点

• 🚀 通用性强：支持12+种3D重建任务
• 🎯 灵活输入：接受图像、相机内参、姿态、深度等任意组合
• ⚡ 高效推理：单次前馈，无需繁琐的优化步骤
• 📈 可扩展：支持2-2000张图像输入
• 🔧 即插即用：简单API，易于集成

目录

• 快速开始
• 安装指南
• 基础用法
• 高级功能
• 交互式演示
• [COLMAP & GSplat支持](#COLMAP & GSplat支持)
• 训练指南
• 基准测试
• 模型下载
• 许可证
• 引用

快速开始

安装指南

# 克隆仓库
git clone https://github.com/facebookresearch/map-anything.git
cd map-anything

# 创建并激活conda环境
conda create -n mapanything python=3.12 -y
conda activate mapanything

# 可选：根据系统安装特定版本的 torch、torchvision 和 torchaudio

# 安装 MapAnything
pip install -e .

# 安装所有可选依赖
pip install -e ".[all]"

# 安装预提交钩子
pre-commit install

注意：我们没有固定特定版本的 PyTorch 或 CUDA。请根据您的系统自行安装合适的 PyTorch 版本。

基础用法

仅使用图像进行度量3D重建

# 可选：配置内存优化
import os
os.environ["PYTORCH_CUDA_ALLOC_CONF"] = "expandable_segments:True"

# 必要的导入
import torch
from mapanything.models import MapAnything
from mapanything.utils.image import load_images

# 获取推理设备
device = "cuda" if torch.cuda.is_available() else "cpu"

# 初始化模型 - 需要互联网访问或预下载的 huggingface hub 缓存
# 使用 Apache 2.0 许可的模型：使用 "facebook/map-anything-apache"
model = MapAnything.from_pretrained("facebook/map-anything").to(device)

# 从文件夹或路径列表加载和预处理图像
images = "path/to/your/images/"  # 或 ["path/to/img1.jpg", "path/to/img2.jpg", ...]
views = load_images(images)

# 运行推理
predictions = model.infer(
    views,  # 输入视图
    memory_efficient_inference=False,  # 牺牲速度换取更多视图（140GB内存可支持多达2000个视图）
    use_amp=True,  # 使用混合精度推理（推荐）
    amp_dtype="bf16",  # bf16推理（推荐；如果不支持bf16则回退到fp16）
    apply_mask=True,  # 对密集几何输出应用遮罩
    mask_edges=True,  # 使用法线和深度移除边缘伪影
    apply_confidence_mask=False,  # 过滤低置信度区域
    confidence_percentile=10,  # 移除底部10%置信度的像素
)

# 访问每个视图的结果 - 完整的度量输出列表
for i, pred in enumerate(predictions):
    # 几何输出
    pts3d = pred["pts3d"]  # 世界坐标系中的3D点 (B, H, W, 3)
    pts3d_cam = pred["pts3d_cam"]  # 相机坐标系中的3D点 (B, H, W, 3)
    depth_z = pred["depth_z"]  # 相机坐标系中的Z深度 (B, H, W, 1)
    depth_along_ray = pred["depth_along_ray"]  # 沿射线的深度 (B, H, W, 1)
    
    # 相机输出
    ray_directions = pred["ray_directions"]  # 相机坐标系中的射线方向 (B, H, W, 3)
    intrinsics = pred["intrinsics"]  # 恢复的针孔相机内参 (B, 3, 3)
    camera_poses = pred["camera_poses"]  # OpenCV坐标系cam2world姿态 (B, 4, 4)
    cam_trans = pred["cam_trans"]  # cam2world平移 (B, 3)
    cam_quats = pred["cam_quats"]  # cam2world四元数 (B, 4)
    
    # 质量和遮罩
    confidence = pred["conf"]  # 每像素置信度分数 (B, H, W)
    mask = pred["mask"]  # 组合有效性遮罩 (B, H, W, 1)
    non_ambiguous_mask = pred["non_ambiguous_mask"]  # 非歧义区域 (B, H, W)
    
    # 缩放
    metric_scaling_factor = pred["metric_scaling_factor"]  # 应用的度量缩放 (B,)
    
    # 原始输入
    img_no_norm = pred["img_no_norm"]  # 用于可视化的去归一化输入图像 (B, H, W, 3)

高级功能

使用多模态输入

MapAnything 支持灵活组合几何输入以增强度量重建：

# MapAnything 极其灵活，支持任意输入组合
views_example = [
    {
        # 视图0：图像 + 校准参数
        "img": image,  # (H, W, 3) - [0, 255]
        "intrinsics": intrinsics,  # (3, 3)
    },
    {
        # 视图1：图像 + 校准参数 + 深度
        "img": image,
        "intrinsics": intrinsics,
        "depth_z": depth_z,  # (H, W)
        "is_metric_scale": torch.tensor([True], device=device),
    },
    {
        # 视图2：图像 + 校准参数 + 深度 + 姿态
        "img": image,
        "intrinsics": intrinsics,
        "depth_z": depth_z,
        "camera_poses": camera_poses,  # (4, 4) OpenCV cam2world
        "is_metric_scale": torch.tensor([True], device=device),
    },
]

# 预处理输入并运行推理
from mapanything.utils.image import preprocess_inputs
processed_views = preprocess_inputs(views_example)
predictions = model.infer(processed_views)

支持的输入组合示例

• 示例1：图像 + 相机内参
• 示例2：图像 + 内参 + 深度
• 示例3：图像 + 内参 + 相机姿态
• 示例4：图像 + 射线方向 + 深度（替代内参）
• 示例5：完整多模态（图像 + 内参 + 深度 + 姿态）
• 示例6：自适应混合输入（不同视图使用不同输入）

交互式演示

🌐 在线演示

无需安装即可试用：🤗 Hugging Face Demo

💻 本地Gradio应用

# 安装应用依赖
pip install -e ".[gradio]"

# 本地启动应用
python scripts/gradio_app.py

🎮 Rerun 3D可视化

使用 Rerun 进行交互式3D可视化：

# 终端1：启动 Rerun 服务器
rerun --serve --port 2004 --web-viewer-port 2006

# 终端2：运行 MapAnything 演示
python scripts/demo_images_only_inference.py \
    --image_folder /path/to/your/images \
    --viz \
    --save_glb \
    --output_path /path/to/output.glb

# 终端3：在 http://127.0.0.1:2006 打开网页查看器

COLMAP & GSplat支持

COLMAP导出

MapAnything的预测可以直接转换为COLMAP格式：

# 安装COLMAP相关依赖
pip install -e ".[colmap]"

# 仅前馈预测
python scripts/demo_colmap.py --scene_dir=/YOUR/SCENE_DIR/ --memory_efficient_inference

# 带束调整优化
python scripts/demo_colmap.py --scene_dir=/YOUR/SCENE_DIR/ --memory_efficient_inference --use_ba

# 使用减少的参数进行更快的处理
python scripts/demo_colmap.py --scene_dir=/YOUR/SCENE_DIR/ --memory_efficient_inference --use_ba \
    --max_query_pts=2048 --query_frame_num=5

图像应存储在 /YOUR/SCENE_DIR/images/ 中。重建结果将保存在 /YOUR/SCENE_DIR/sparse/ 中。

高斯泼溅训练

导出的COLMAP文件可以直接用于 gsplat 进行高斯泼溅训练：

cd <path_to_gsplat>
python examples/simple_trainer.py default \
    --data_factor 1 \
    --data_dir /YOUR/SCENE_DIR/ \
    --result_dir /YOUR/RESULT_DIR/

数据处理

详细的数据处理说明请参见 数据处理README。

训练指南

我们提供了全面的训练说明、脚本和配置来重现MapAnything并训练自定义模型。详见 训练README，包括：

• 论文中使用的所有13个训练数据集的设置和处理
• 带内存优化技巧的快速入门示例
• 论文中所有主要模型和消融实验的训练脚本
• 支持对其他几何估计模型（如MoGe-2、VGGT、π³）进行微调

基准测试

我们提供了全面的基准测试脚本和说明。所有原始基准测试脚本都在 /bash_scripts/benchmarking/ 文件夹中。

支持的基准测试

1. 密集多视图重建基准 - 评估密集多视图度量重建
2. 单视图图像校准基准 - 评估从单张图像预测相机内参
3. RobustMVD基准 - 使用RobustMVD基准进行评估

模型下载

我们在 Hugging Face Hub 上发布了两个预训练的 MapAnything 模型变体：

模型变体

模型	许可证	用途	性能
facebook/map-anything	CC-BY-NC 4.0	研究和学术用途	最佳性能
facebook/map-anything-apache	Apache 2.0	商业友好	优秀性能

两个模型支持相同的API和功能，唯一的区别是训练数据组成和相应的许可条款。

检查点格式转换

将HuggingFace检查点转换为训练/基准测试框架期望的格式：

# 转换默认CC-BY-NC模型
python scripts/convert_hf_to_benchmark_checkpoint.py \
    --output_path checkpoints/facebook_map-anything.pth

# 转换Apache 2.0模型（商业用途）
python scripts/convert_hf_to_benchmark_checkpoint.py \
    --apache \
    --output_path checkpoints/facebook_map-anything-apache.pth

核心组件

🌍 UniCeption

UniCeption 是一个包含模块化、可配置组件的库，用于组装端到端网络。

🌍 WAI数据格式

WAI 是一个统一的数据格式，用于所有3D、4D和空间AI任务。它实现了简单、可扩展和可重现的数据处理。

相关工作

使用 UniCeption 和 WAI 的其他项目：

• 🚀 UFM: 通过流实现统一密集对应的简单路径
• 🚀 FlowR: 从稀疏到密集的3D重建流

致谢

感谢以下项目的开源代码：

• DUSt3R
• MASt3R
• RayDiffusion
• MoGe
• VGGSfM
• VGGT
• MaRePo
• DINOv2

许可证

代码许可

本代码采用开源 Apache 2.0 许可证。

模型许可

• 研究用途 ：使用 facebook/map-anything（CC-BY-NC 4.0 许可）
• 商业用途 ：使用 facebook/map-anything-apache（Apache 2.0 许可）

引用

如果您觉得我们的仓库有用，请考虑给我们一个星标 ⭐ 并在您的工作中引用我们的论文：

@inproceedings{keetha2025mapanything,
  title={{MapAnything}: Universal Feed-Forward Metric {3D} Reconstruction},
  author={Nikhil Keetha and Norman M\"{u}ller and Johannes Sch\"{o}nberger and 
          Lorenzo Porzi and Yuchen Zhang and Tobias Fischer and Arno Knapitsch and 
          Duncan Zauss and Ethan Weber and Nelson Antunes and Jonathon Luiten and 
          Manuel Lopez-Antequera and Samuel Rota Bul\`{o} and Christian Richardt and 
          Deva Ramanan and Sebastian Scherer and Peter Kontschieder},
  booktitle={arXiv},
  year={2025}
}

常见问题

Q: MapAnything 和其他3D重建方法有什么区别？

A: MapAnything 是一个通用的端到端模型，支持多种3D重建任务，无需任务特定的调整或优化。它可以灵活处理各种输入组合，从纯图像到带有校准、深度和姿态的完整多模态输入。

Q: 需要什么硬件配置？

A: 推荐使用CUDA支持的GPU。对于大规模重建（2000张图像），建议使用140GB以上的GPU内存。对于小规模任务，普通GPU即可满足需求。

Q: 可以用于商业项目吗？

A: 是的，使用 facebook/map-anything-apache 模型变体，它采用Apache 2.0许可证，适合商业用途。

Q: 支持哪些输入格式？

A: MapAnything 支持常见的图像格式（JPG、PNG等），并可以接受相机内参矩阵、深度图、相机姿态等多种几何输入。

Q: 如何处理自己的数据？

A: 请参考数据处理README了解如何准备和处理自定义数据集。

联系我们

• 🌐 项目主页
• 📝 论文
• 💬 GitHub Issues
• 🤗 Hugging Face

---

MapAnything - 让3D重建变得简单而强大 🚀

MapAnything 快速参考指南

📌 项目概述

MapAnything 是 Meta AI 研究院发布的通用3D重建模型，能够从各种输入（图像、相机参数、深度、姿态等）直接重建场景的3D几何结构。

核心优势

• ✅ 一个模型，12+种任务：SfM、MVS、深度估计、配准等
• ✅ 灵活输入：支持2-2000张图像，可选相机参数
• ✅ 端到端推理：无需繁琐的优化步骤
• ✅ 开源友好：提供Apache 2.0许可的商业版本

🚀 快速安装

# 1. 克隆项目（使用代理）
git clone https://bgithub.xyz/facebookresearch/map-anything.git
cd map-anything

# 2. 创建环境
conda create -n mapanything python=3.12 -y
conda activate mapanything

# 3. 安装PyTorch（根据CUDA版本选择）
pip install torch torchvision torchaudio

# 4. 安装MapAnything
pip install -e ".[all]" --break-system-packages

💡 三分钟上手

最简单用法：从图像重建3D

import torch
from mapanything.models import MapAnything
from mapanything.utils.image import load_images

# 1. 加载模型
model = MapAnything.from_pretrained("facebook/map-anything").cuda()

# 2. 加载图像
views = load_images("path/to/images/")  # 文件夹路径

# 3. 运行推理
predictions = model.infer(views, use_amp=True)

# 4. 获取结果
for pred in predictions:
    depth = pred["depth_z"]           # 深度图
    points3d = pred["pts3d"]          # 3D点云
    camera_pose = pred["camera_poses"] # 相机姿态
    intrinsics = pred["intrinsics"]   # 相机内参

使用额外输入提升精度

# 如果有相机内参
views = [{
    "img": image,
    "intrinsics": K_matrix,  # 3x3 内参矩阵
}]

# 如果有深度信息
views = [{
    "img": image,
    "intrinsics": K_matrix,
    "depth_z": depth_map,
    "is_metric_scale": torch.tensor([True])
}]

# 如果有相机姿态
views = [{
    "img": image,
    "camera_poses": pose_matrix,  # 4x4 变换矩阵
    "is_metric_scale": torch.tensor([True])
}]

🎮 可视化工具

方法1：Web界面（推荐）

pip install -e ".[gradio]"
python scripts/gradio_app.py
# 打开 http://localhost:7860

方法2：Rerun 3D查看器

# 终端1
rerun --serve --port 2004 --web-viewer-port 2006

# 终端2
python scripts/demo_images_only_inference.py \
    --image_folder /your/images \
    --viz --save_glb

# 浏览器访问 http://127.0.0.1:2006

方法3：导出到COLMAP

pip install -e ".[colmap]"
python scripts/demo_colmap.py --scene_dir=/your/scene/
# 结果保存在 /your/scene/sparse/

📊 支持的任务矩阵

任务	输入要求	典型应用
多视图重建	2+张图像	3D扫描、建模
深度估计	单张图像	AR/VR、自动驾驶
相机标定	单张图像	摄影测量
姿态估计	2+张图像	SLAM、定位
深度补全	图像+稀疏深度	激光雷达融合
3D配准	多视图+姿态	点云对齐

🔧 性能优化技巧

内存优化

# 大量图像时使用
os.environ["PYTORCH_CUDA_ALLOC_CONF"] = "expandable_segments:True"

# 启用内存高效模式
predictions = model.infer(
    views,
    memory_efficient_inference=True,  # 速度换内存
    use_amp=True,                     # 混合精度
    amp_dtype="bf16"                  # 使用bf16
)

批处理策略

• <10张图像：直接推理
• 10-100张图像 ：使用 memory_efficient_inference=True
• 100-2000张图像：分批处理或使用140GB+ GPU

📦 模型选择

使用场景	推荐模型	许可证
学术研究	facebook/map-anything	CC-BY-NC 4.0
商业应用	facebook/map-anything-apache	Apache 2.0

# 商业版本
model = MapAnything.from_pretrained("facebook/map-anything-apache")

🛠️ 常见问题解决

1. CUDA内存不足

# 降低批大小
model.infer(views, memory_efficient_inference=True)

# 或分批处理
batch_size = 4
for i in range(0, len(views), batch_size):
    batch = views[i:i+batch_size]
    predictions = model.infer(batch)

2. 网络下载模型失败

# 使用镜像
export HF_ENDPOINT=https://hf-mirror.com

# 或手动下载
huggingface-cli download facebook/map-anything --local-dir ./models/
model = MapAnything.from_pretrained("./models/")

3. 依赖安装失败

# 分步安装核心依赖
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118
pip install huggingface_hub hydra-core opencv-python-headless
pip install -e . --no-deps --break-system-packages

📚 进阶功能

与Gaussian Splatting集成

# 1. 导出COLMAP格式
python scripts/demo_colmap.py --scene_dir=/scene/ --use_ba

# 2. 训练Gaussian Splatting
cd gsplat
python examples/simple_trainer.py default \
    --data_dir /scene/ \
    --result_dir /results/

自定义训练

# 准备数据集（WAI格式）
python data_processing/prepare_dataset.py --dataset custom

# 训练模型
python train.py \
    --config configs/mapanything_base.yaml \
    --dataset custom \
    --output_dir ./checkpoints/

🔗 重要链接

• 📝 完整中文文档
• 🌐 项目官网
• 🤗 在线演示
• 📄 学术论文
• 💻 GitHub仓库

📊 基准测试结果

数据集	指标	MapAnything	VGGT	DUSt3R
ETH3D	相对误差	0.16	0.20	0.23
ScanNet++	内点率	92%	87%	85%
TartanAir	深度精度	0.95	0.91	0.89

💬 社区支持

• 问题反馈 ：GitHub Issues
• 技术讨论 ：Discussions
• 模型下载 ：Hugging Face

---

提示 ：这是一个快速参考指南。完整文档请查看中文README或官方文档。