Fast3R: Towards 3D Reconstruction of 1000+ Images in One Forward Pass 的官方实现，CVPR 2025

Jianing Yang, Alexander Sax, Kevin J. Liang, Mikael Henaff, Hao Tang, Ang Cao, Joyce Chai, Franziska Meier, Matt Feiszli

安装

# clone project
git clone https://github.com/facebookresearch/fast3r
cd fast3r

# create conda environment
conda create -n fast3r python=3.11 cmake=3.14.0 -y
conda activate fast3r

# install PyTorch (adjust cuda version according to your system)
conda install pytorch torchvision torchaudio pytorch-cuda=12.4 nvidia/label/cuda-12.4.0::cuda-toolkit -c pytorch -c nvidia

# install requirements
pip install -r requirements.txt

# install fast3r as a package (so you can import fast3r and use it in your own project)
pip install -e .

注意：请确保不要像 DUSt3R 那样安装 cuROPE 模块，否则会破坏 Fast3R 的预测结果。

演示

使用以下命令运行演示：

python fast3r/viz/demo.py

这将自动从 Hugging Face 模型 下载预训练模型权重和配置。

该演示是一个 Gradio 界面，您可以上传图像或视频，并可视化 3D 重建和相机姿态估计。

fast3r/viz/demo.py 也可作为使用模型进行推理的示例。

点击此处查看示例：可视化置信度热力图 + 逐帧播放 + 渲染 GIF

在自己的项目中使用 Fast3R

要在自己的项目中使用 Fast3R，您可以从 fast3r.models.fast3r 导入 Fast3R 类，并将其作为常规的 PyTorch 模型使用。

import torch
from fast3r.dust3r.utils.image import load_images
from fast3r.dust3r.inference_multiview import inference
from fast3r.models.fast3r import Fast3R
from fast3r.models.multiview_dust3r_module import MultiViewDUSt3RLitModule

# --- Setup ---
# Load the model from Hugging Face
model = Fast3R.from_pretrained("jedyang97/Fast3R_ViT_Large_512")  # If you have networking issues, try pre-download the HF checkpoint dir and change the path here to a local directory
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
model = model.to(device)

# Create a lightweight lightning module wrapper for the model.
# This provides functions to estimate camera poses, evaluate 3D reconstruction, etc.
lit_module = MultiViewDUSt3RLitModule.load_for_inference(model)

# Set model to evaluation mode
model.eval()
lit_module.eval()

# --- Load Images ---
# Provide a list of image file paths. Images can come from different cameras and aspect ratios.
filelist = ["path/to/image1.jpg", "path/to/image2.jpg", "path/to/image3.jpg"]
images = load_images(filelist, size=512, verbose=True)

# --- Run Inference ---
# The inference function returns a dictionary with predictions and view information.
output_dict, profiling_info = inference(
    images,
    model,
    device,
    dtype=torch.float32,  # or use torch.bfloat16 if supported
    verbose=True,
    profiling=True,
)

# --- Estimate Camera Poses ---
# This step estimates the camera-to-world (c2w) poses for each view using PnP.
poses_c2w_batch, estimated_focals = MultiViewDUSt3RLitModule.estimate_camera_poses(
    output_dict['preds'],
    niter_PnP=100,
    focal_length_estimation_method='first_view_from_global_head'
)
# poses_c2w_batch is a list; the first element contains the estimated poses for each view.
camera_poses = poses_c2w_batch[0]

# Print camera poses for all views.
for view_idx, pose in enumerate(camera_poses):
    print(f"Camera Pose for view {view_idx}:")
    print(pose.shape)  # np.array of shape (4, 4), the camera-to-world transformation matrix

# --- Extract 3D Point Clouds for Each View ---
# Each element in output_dict['preds'] corresponds to a view's point map.
for view_idx, pred in enumerate(output_dict['preds']):
    point_cloud = pred['pts3d_in_other_view'].cpu().numpy()
    print(f"Point Cloud Shape for view {view_idx}: {point_cloud.shape}")  # shape: (1, 368, 512, 3), i.e., (1, Height, Width, XYZ)

训练

使用 configs/experiment/ 中选定的实验配置来训练模型

python fast3r/train.py experiment=super_long_training/super_long_training

您可以按照 Hydra override syntax 从命令行覆盖任何参数：

python fast3r/train.py experiment=super_long_training/super_long_training trainer.max_epochs=20 trainer.num_nodes=2

若要使用 Slurm 提交多节点训练作业，请使用以下命令：

python scripts/slurm/submit_train.py --nodes=<NODES> --experiment=<EXPERIMENT>

训练完成后，您可以使用 lightning checkpoint 通过以下命令运行演示：

python fast3r/viz/demo.py --is_lightning_checkpoint --checkpoint_dir=/path/to/super_long_training_999999

评估

要在 3D 重建 (3D reconstruction) 或相机位姿估计 (camera pose estimation) 任务上进行评估，请运行：

python fast3r/eval.py eval=<eval_config>

<eval_config> 可以是 configs/eval/ 中的任何评估配置。例如：

• ablation_recon_better_inference_hp/ablation_recon_better_inference_hp 评估在 DTU、7-Scenes 和 Neural-RGBD 数据集上的 3D 重建效果。
• eval_cam_pose/eval_cam_pose_10views 评估在 CO3D 数据集上 10 个视角的相机位姿估计效果。

要在 RealEstate10K 数据集上评估相机位姿，请运行：

python scripts/fast3r_re10k_pose_eval.py  --subset_file scripts/re10k_test_1800.txt

要在 Tanks and Temples、ETH-3D、DTU 和 ScanNet 数据集上评估多视图深度估计 (multi-view depth estimation)，请遵循 robustmvd 的数据下载和准备指南，将该仓库的 requirements.txt 安装到当前的 conda 环境 (conda environment) 中，然后运行：

python scripts/robustmvd_eval.py

数据集预处理

请遵循 DUSt3R 的数据预处理说明 来准备训练和评估所需的数据。预处理后的数据与此仓库中的 多视图数据加载器 (multi-view dataloaders) 兼容。

对于用于评估的 DTU、7-Scene 和 NRGBD 数据集的预处理，我们遵循 Spann3r 的数据处理说明。

常见问题

• Q: 启动演示时出现 httpcore.ConnectError: All connection attempts failed？
  • 参见 #34。将示例视频下载到本地目录。
• Q: BlendedMVS 的数据预处理中，缺少 train_list.txt？
  • 参见 #33。
• Q: 如何加载检查点 (checkpoint) 以微调 (fine-tune) Fast3R？
  • 参见 #25
• Q: 在 Windows 上运行演示？(TypeError: cannot pickle '_thread.RLock' object)
  • 参见 #28。似乎还需要更多工作才能使演示与 Windows 兼容——我们希望社区能贡献一个 Pull Request (PR)！
• Q: 点云 (point cloud) 输出完全混乱？
  • 参见 #21。请确保未安装 cuROPE 模块。
• Q: 我的 GPU (图形处理器) 不支持 FlashAttention / No available kernel. Aborting execution？
  • 参见 #17。改用 attn_implementation=pytorch_auto 选项。
• Q: TypeError: Fast3R.__init__() missing 3 required positional arguments: 'encoder_args', 'decoder_args', and 'head_args'
  • 参见 #7。这是由于在某些国家（如中国）从 Huggingface 下载模型时的网络问题导致的——请使用有效的网络配置预先下载模型检查点 (checkpoint)，并使用本地路径加载模型。

许可证

代码和模型均根据 FAIR NC Research License 许可。

贡献

请参阅 贡献指南 和 行为准则。

引用

@InProceedings{Yang_2025_Fast3R,
    title={Fast3R: Towards 3D Reconstruction of 1000+ Images in One Forward Pass},
    author={Jianing Yang and Alexander Sax and Kevin J. Liang and Mikael Henaff and Hao Tang and Ang Cao and Joyce Chai and Franziska Meier and Matt Feiszli},
    booktitle={Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition (CVPR)},
    month={June},
    year={2025},
}

致谢

Fast3R 建立在一些杰出的开源项目基础之上。我们衷心感谢这些项目及其社区的贡献，他们的努力极大地推动了该领域的发展并使这项工作成为可能。

• DUSt3R
• Spann3R
• Viser
• Lightning-Hydra-Template

星标历史

Fast3R 快速上手指南

Fast3R 是 CVPR 2025 提出的开源项目，旨在实现单次前向传播处理 1000+ 图像的 3D 重建。本指南帮助开发者快速完成环境搭建与基础使用。

1. 环境准备

• 系统要求: Linux / macOS / Windows (Windows 下 Demo 可能存在兼容性问题，建议优先使用 Linux)
• Python 版本: 3.11
• 深度学习框架: PyTorch (推荐 CUDA 12.4)
• 其他依赖: CMake (>= 3.14.0), Conda

2. 安装步骤

请按照以下顺序执行命令。

克隆项目

git clone https://github.com/facebookresearch/fast3r
cd fast3r

创建 Conda 环境

conda create -n fast3r python=3.11 cmake=3.14.0 -y
conda activate fast3r

安装 PyTorch

根据您的系统 CUDA 版本调整命令（示例为 CUDA 12.4）：

conda install pytorch torchvision torchaudio pytorch-cuda=12.4 nvidia/label/cuda-12.4.0::cuda-toolkit -c pytorch -c nvidia

安装依赖包

pip install -r requirements.txt
pip install -e .

⚠️ 重要提示: 请勿安装 cuROPE 模块（类似 DUSt3R 中的做法），否则会导致 Fast3R 预测错误。

💡 国内网络优化: 由于模型权重托管于 Hugging Face，国内用户可能面临下载缓慢或失败的问题。建议在运行 Demo 或代码前，先手动下载模型文件至本地目录，并在代码中指定本地路径加载。

3. 基本使用

方式一：运行 Gradio Demo (可视化)

此命令会自动从 Hugging Face 下载预训练模型和配置，并启动 Web 界面。

python fast3r/viz/demo.py

在浏览器打开链接后，您可以上传图片或视频，实时查看 3D 重建结果及相机位姿估计。

方式二：代码集成 (Inference)

若需在项目中调用 Fast3R，可参考以下示例代码。

import torch
from fast3r.dust3r.utils.image import load_images
from fast3r.dust3r.inference_multiview import inference
from fast3r.models.fast3r import Fast3R
from fast3r.models.multiview_dust3r_module import MultiViewDUSt3RLitModule

# --- 初始化 ---
# 加载模型 (如有网络问题，请改为本地路径)
model = Fast3R.from_pretrained("jedyang97/Fast3R_ViT_Large_512")
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
model = model.to(device)

# 创建轻量级 Lightning 模块包装器
lit_module = MultiViewDUSt3RLitModule.load_for_inference(model)

# 设置评估模式
model.eval()
lit_module.eval()

# --- 加载图像 ---
# 提供图像文件路径列表
filelist = ["path/to/image1.jpg", "path/to/image2.jpg", "path/to/image3.jpg"]
images = load_images(filelist, size=512, verbose=True)

# --- 推理 ---
output_dict, profiling_info = inference(
    images,
    model,
    device,
    dtype=torch.float32,  # 或根据硬件支持使用 torch.bfloat16
    verbose=True,
    profiling=True,
)

# --- 估计相机位姿 ---
poses_c2w_batch, estimated_focals = MultiViewDUSt3RLitModule.estimate_camera_poses(
    output_dict['preds'],
    niter_PnP=100,
    focal_length_estimation_method='first_view_from_global_head'
)
camera_poses = poses_c2w_batch[0]

# 打印所有视图的相机位姿
for view_idx, pose in enumerate(camera_poses):
    print(f"Camera Pose for view {view_idx}:")
    print(pose.shape)  # np.array shape (4, 4)

# --- 提取点云 ---
for view_idx, pred in enumerate(output_dict['preds']):
    point_cloud = pred['pts3d_in_other_view'].cpu().numpy()
    print(f"Point Cloud Shape for view {view_idx}: {point_cloud.shape}")