dust3r

Official implementation of DUSt3R: Geometric 3D Vision Made Easy
[Project page], [DUSt3R arxiv]

Make sure to also check our other works:
Grounding Image Matching in 3D with MASt3R: DUSt3R with a local feature head, metric pointmaps, and a more scalable global alignment!
Pow3R: Empowering Unconstrained 3D Reconstruction with Camera and Scene Priors: DUSt3R with known depth / focal length / poses.
MUSt3R: Multi-view Network for Stereo 3D Reconstruction: Multi-view predictions (RGB SLAM/SfM) without any global alignment.

@inproceedings{dust3r_cvpr24,
      title={DUSt3R: Geometric 3D Vision Made Easy}, 
      author={Shuzhe Wang and Vincent Leroy and Yohann Cabon and Boris Chidlovskii and Jerome Revaud},
      booktitle = {CVPR},
      year = {2024}
}

@misc{dust3r_arxiv23,
      title={DUSt3R: Geometric 3D Vision Made Easy}, 
      author={Shuzhe Wang and Vincent Leroy and Yohann Cabon and Boris Chidlovskii and Jerome Revaud},
      year={2023},
      eprint={2312.14132},
      archivePrefix={arXiv},
      primaryClass={cs.CV}
}

Table of Contents

• Table of Contents
• License
• Get Started
  • Installation
  • Checkpoints
  • Interactive demo
  • Interactive demo with docker
• Usage
• Training
  • Datasets
  • Demo
  • Our Hyperparameters

License

The code is distributed under the CC BY-NC-SA 4.0 License. See LICENSE for more information.

# Copyright (C) 2024-present Naver Corporation. All rights reserved.
# Licensed under CC BY-NC-SA 4.0 (non-commercial use only).

Get Started

Installation

1. Clone DUSt3R.

git clone --recursive https://github.com/naver/dust3r
cd dust3r
# if you have already cloned dust3r:
# git submodule update --init --recursive

1. Create the environment, here we show an example using conda.

conda create -n dust3r python=3.11 cmake=3.14.0
conda activate dust3r 
conda install pytorch torchvision pytorch-cuda=12.1 -c pytorch -c nvidia  # use the correct version of cuda for your system
pip install -r requirements.txt
# Optional: you can also install additional packages to:
# - add support for HEIC images
# - add pyrender, used to render depthmap in some datasets preprocessing
# - add required packages for visloc.py
pip install -r requirements_optional.txt

1. Optional, compile the cuda kernels for RoPE (as in CroCo v2).

# DUST3R relies on RoPE positional embeddings for which you can compile some cuda kernels for faster runtime.
cd croco/models/curope/
python setup.py build_ext --inplace
cd ../../../

Checkpoints

You can obtain the checkpoints by two ways:

1. You can use our huggingface_hub integration: the models will be downloaded automatically.

2. Otherwise, We provide several pre-trained models:

Modelname	Training resolutions	Head	Encoder	Decoder
DUSt3R_ViTLarge_BaseDecoder_224_linear.pth	224x224	Linear	ViT-L	ViT-B
DUSt3R_ViTLarge_BaseDecoder_512_linear.pth	512x384, 512x336, 512x288, 512x256, 512x160	Linear	ViT-L	ViT-B
DUSt3R_ViTLarge_BaseDecoder_512_dpt.pth	512x384, 512x336, 512x288, 512x256, 512x160	DPT	ViT-L	ViT-B

You can check the hyperparameters we used to train these models in the section: Our Hyperparameters

To download a specific model, for example DUSt3R_ViTLarge_BaseDecoder_512_dpt.pth:

mkdir -p checkpoints/
wget https://download.europe.naverlabs.com/ComputerVision/DUSt3R/DUSt3R_ViTLarge_BaseDecoder_512_dpt.pth -P checkpoints/

For the checkpoints, make sure to agree to the license of all the public training datasets and base checkpoints we used, in addition to CC-BY-NC-SA 4.0. Again, see section: Our Hyperparameters for details.

Interactive demo

In this demo, you should be able run DUSt3R on your machine to reconstruct a scene. First select images that depicts the same scene.

You can adjust the global alignment schedule and its number of iterations.

[!NOTE] If you selected one or two images, the global alignment procedure will be skipped (mode=GlobalAlignerMode.PairViewer)

Hit "Run" and wait. When the global alignment ends, the reconstruction appears. Use the slider "min_conf_thr" to show or remove low confidence areas.

python3 demo.py --model_name DUSt3R_ViTLarge_BaseDecoder_512_dpt

# Use --weights to load a checkpoint from a local file, eg --weights checkpoints/DUSt3R_ViTLarge_BaseDecoder_512_dpt.pth
# Use --image_size to select the correct resolution for the selected checkpoint. 512 (default) or 224
# Use --local_network to make it accessible on the local network, or --server_name to specify the url manually
# Use --server_port to change the port, by default it will search for an available port starting at 7860
# Use --device to use a different device, by default it's "cuda"

Interactive demo with docker

To run DUSt3R using Docker, including with NVIDIA CUDA support, follow these instructions:

1. Install Docker: If not already installed, download and install docker and docker compose from the Docker website.

2. Install NVIDIA Docker Toolkit: For GPU support, install the NVIDIA Docker toolkit from the Nvidia website.

3. Build the Docker image and run it: cd into the ./docker directory and run the following commands:

cd docker
bash run.sh --with-cuda --model_name="DUSt3R_ViTLarge_BaseDecoder_512_dpt"

Or if you want to run the demo without CUDA support, run the following command:

cd docker
bash run.sh --model_name="DUSt3R_ViTLarge_BaseDecoder_512_dpt"

By default, demo.py is lanched with the option --local_network.
Visit http://localhost:7860/ to access the web UI (or replace localhost with the machine's name to access it from the network).

run.sh will launch docker-compose using either the docker-compose-cuda.yml or docker-compose-cpu.ym config file, then it starts the demo using entrypoint.sh.

Usage

…

Training

In this section, we present a short demonstration to get started with training DUSt3R.

Datasets

At this moment, we have added the following training datasets:

• CO3Dv2 - Creative Commons Attribution-NonCommercial 4.0 International
• ARKitScenes - Creative Commons Attribution-NonCommercial-ShareAlike 4.0
• ScanNet++ - non-commercial research and educational purposes
• BlendedMVS - Creative Commons Attribution 4.0 International License
• WayMo Open dataset - Non-Commercial Use
• Habitat-Sim
• MegaDepth
• StaticThings3D
• WildRGB-D

For each dataset, we provide a preprocessing script in the datasets_preprocess directory and an archive containing the list of pairs when needed. You have to download the datasets yourself from their official sources, agree to their license, download our list of pairs, and run the preprocessing script.

Links:

ARKitScenes pairs
ScanNet++ v1 pairs
ScanNet++ v2 pairs
BlendedMVS pairs
WayMo Open dataset pairs
Habitat metadata
MegaDepth pairs
StaticThings3D pairs

[!NOTE] They are not strictly equivalent to what was used to train DUSt3R, but they should be close enough.

Demo

For this training demo, we're going to download and prepare a subset of CO3Dv2 - Creative Commons Attribution-NonCommercial 4.0 International and launch the training code on it. The demo model will be trained for a few epochs on a very small dataset. It will not be very good.

…

Our Hyperparameters

Here are the commands we used for training the models:

…