当前位置：首页 > news >正文

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

news 2025/10/25 14:45:55

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，易于集成

快速开始

安装指南

# 克隆仓库
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/ 文件夹中。

支持的基准测试

密集多视图重建基准 - 评估密集多视图度量重建
单视图图像校准基准 - 评估从单张图像预测相机内参
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任务。它实现了简单、可扩展和可重现的数据处理。

致谢

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

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/