# DROID-SLAM: Deep Visual SLAM - Dockerized Implementation

A containerized implementation of DROID-SLAM for seamless deployment and reproducible research.

Table of Contents

• Overview
• Features
• Quick Start
• Installation
• Running Demos
• Using Your Own Data
• Reconstruction Visualization
• Pose Extraction
• Evaluation
• Troubleshooting
• Citation

Overview

DROID-SLAM is a deep learning approach to visual SLAM that works with monocular, stereo, and RGB-D cameras. This repository provides a Docker-based implementation that eliminates complex dependency issues and ensures reproducible environments.

This repository is based on the original research by Zachary Teed and Jia Deng: DROID-SLAM: Deep Visual SLAM for Monocular, Stereo, and RGB-D Cameras

Features

✅ Docker-based deployment - Handles all complex dependencies ✅ Pre-built with CUDA 11.8 - Optimized for modern NVIDIA GPUs ✅ GPU-accelerated inference - Fast processing with minimal memory usage ✅ Asynchronous processing - Frontend/backend separate processes ✅ Multi-GPU support - Scale across multiple GPUs ✅ Full reconstruction saving - Export poses, depths, and images ✅ Standalone pose extraction - Extract poses without complex dependencies ✅ Visualization tools - Built-in 3D reconstruction viewer

Quick Start

Prerequisites

• NVIDIA GPU with at least 11GB memory (for inference)
• NVIDIA Docker Runtime installed
• Docker version 20.10 or higher

1. Build the Docker Image

# Clone the repository with submodules
git clone --recursive https://github.com/YOUR_USERNAME/DROID-SLAM.git
cd DROID-SLAM

# Build the Docker image (this will take some time)
docker build -t droid-slam .

2. Download Pre-trained Model

# The Docker image includes download scripts
# You can also download manually:
# wget https://www.dropbox.com/s/1cde90w92v5iz2j/droid.pth

3. Run a Demo (Example)

# Create output directory
mkdir -p output

# Run DROID-SLAM on sample data (EuRoC format)
docker run --gpus all --rm -it \
  --user $(id -u):$(id -g) \
  -v "$(pwd)/output:/workspace/output" \
  -v "$(pwd)/data/sample/rgb:/workspace/output_frames" \
  -v "$(pwd)/calibration_file.txt:/workspace/calibration_file.txt" \
  -v "$(pwd)/droid.pth:/workspace/droid.pth" \
  droid-slam bash -c "QT_QPA_PLATFORM=offscreen python /workspace/demo.py \
    --imagedir=/workspace/output_frames \
    --calib=/workspace/calibration_file.txt \
    --disable_vis \
    --weights /workspace/droid.pth \
    --reconstruction_path=/workspace/output/reconstruction.pth"

Installation

Option 1: Docker (Recommended)

The Docker approach handles all dependencies automatically:

# Build from scratch (if not using pre-built image)
docker build -t droid-slam .

# Or pull pre-built image
docker pull yourrepo/droid-slam:latest

Option 2: Local Installation (Advanced)

If you prefer local installation:

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Install visualization tools
pip install moderngl moderngl-window

# Install third-party modules
pip install thirdparty/lietorch
pip install thirdparty/pytorch_scatter

# Install DROID backends
pip install -e .

Running Demos

Download Model and Sample Data

# Download pre-trained model
./tools/download_model.sh

# Download sample datasets
./tools/download_sample_data.sh

Basic Demo Commands

# ETH3D Example
docker run --gpus all --rm -it \
  -v "$(pwd)/data/sfm_bench/rgb:/workspace/output_frames" \
  -v "$(pwd)/calib/eth.txt:/workspace/calibration_file.txt" \
  -v "$(pwd)/output:/workspace/output" \
  droid-slam bash -c "python /workspace/demo.py \
    --imagedir=/workspace/output_frames \
    --calib=/workspace/calibration_file.txt \
    --reconstruction_path=/workspace/output/reconstruction.pth"

# EuRoC Example (with start frame)
docker run --gpus all --rm -it \
  -v "$(pwd)/data/mav0/cam0/data:/workspace/output_frames" \
  -v "$(pwd)/calib/euroc.txt:/workspace/calibration_file.txt" \
  -v "$(pwd)/output:/workspace/output" \
  droid-slam bash -c "python /workspace/demo.py \
    --imagedir=/workspace/output_frames \
    --calib=/workspace/calibration_file.txt \
    --t0=150 \
    --reconstruction_path=/workspace/output/reconstruction.pth"

# TUM-RGBD Example
docker run --gpus all --rm -it \
  -v "$(pwd)/data/rgbd_dataset_freiburg3_cabinet/rgb:/workspace/output_frames" \
  -v "$(pwd)/calib/tum3.txt:/workspace/calibration_file.txt" \
  -v "$(pwd)/output:/workspace/output" \
  droid-slam bash -c "python /workspace/demo.py \
    --imagedir=/workspace/output_frames \
    --calib=/workspace/calibration_file.txt \
    --reconstruction_path=/workspace/output/reconstruction.pth"

Asynchronous and Multi-GPU Inference

For better performance or memory-intensive datasets:

# Asynchronous mode (separate frontend/backend processes)
docker run --gpus all --rm -it \
  -v "$(pwd)/data_sample:/workspace/output_frames" \
  -v "$(pwd)/calibration_file.txt:/workspace/calibration_file.txt" \
  -v "$(pwd)/output:/workspace/output" \
  droid-slam bash -c "python /workspace/demo.py \
    --imagedir=/workspace/output_frames \
    --calib=/workspace/calibration_file.txt \
    --asynchronous \
    --frontend_device cuda:0 \
    --backend_device cuda:1 \
    --disable_vis \
    --reconstruction_path=/workspace/output/reconstruction.pth"

Note: Asynchronous mode typically produces better results but is non-deterministic.

Using Your Own Data

Prepare Your Data

1. Image Directory: Place your image sequence in a directory
2. Calibration File: Create a text file with camera parameters

Calibration File Format

fx fy cx cy [k1 k2 p1 p2 [ k3 [ k4 k5 k6 ]]]

-fx, fy: Focal lengths -cx, cy: Principal points -k1, k2, p1, p2: Radial and tangential distortion (optional) -k3, k4, k5, k6: Additional distortion parameters (optional)

Run on Your Data

# Prepare your data structure
your_data/
├── images/
│   ├── frame_001.jpg
│   ├── frame_002.jpg
│   └── ...
└── calib.txt

# Create output directory
mkdir -p output

# Run DROID-SLAM
docker run --gpus all --rm -it \
  --user $(id -u):$(id -g) \
  -v "$(pwd)/output:/workspace/output" \
  -v "$(pwd)/your_data/images:/workspace/output_frames" \
  -v "$(pwd)/your_data/calib.txt:/workspace/calibration_file.txt" \
  -v "$(pwd)/droid.pth:/workspace/droid.pth" \
  droid-slam bash -c "QT_QPA_PLATFORM=offscreen python /workspace/demo.py \
    --imagedir=/workspace/output_frames \
    --calib=/workspace/calibration_file.txt \
    --disable_vis \
    --weights /workspace/droid.pth \
    --reconstruction_path=/workspace/output/reconstruction.pth"

Reconstruction Visualization

After running with--reconstruction_path, you can visualize the results:

View 3D Reconstruction

# View 3D reconstruction with PyTorch3D
docker run --gpus all --rm -it \
  -v "$(pwd)/output/reconstruction.pth:/workspace/reconstruction.pth" \
  -v "$(pwd)/output:/workspace/output" \
  droid-slam bash -c "python /workspace/view_reconstruction.py \
    /workspace/reconstruction.pth --save_path=/workspace/output/visualization"

Extract Camera Poses

We provide a standalone pose extraction script that works without importing the complexlietorch library:

# Extract camera poses as NumPy array
docker run --gpus all --rm -it \
  -v "$(pwd)/output/reconstruction.pth:/workspace/reconstruction.pth" \
  -v "$(pwd)/output:/workspace/output" \
  -v "$(pwd)/extract_droid_poses.py:/workspace/extract_droid_poses.py" \
  droid-slam bash -c "python /workspace/extract_droid_poses.py \
    --input /workspace/reconstruction.pth \
    --output /workspace/output/poses.npy"

Understanding the Output

The extracted poses are saved as a NumPy array with the following properties:

• Shape:[N, 7] (where N is the number of frames)
• Format:[qw, qx, qy, qz, tx, ty, tz] for each frame -qw, qx, qy, qz: Quaternion (rotation) -tx, ty, tz: Translation vector (position)

Loading Poses in Python

import numpy as np

# Load extracted poses
poses = np.load('output/poses.npy')
print(f"Loaded {poses.shape[0]} poses")
print(f"Pose shape: {poses.shape}")
print(f"First frame pose: {poses[0]}")

# Example: Extract rotation and translation
quaternions = poses[:, :4]  # [N, 4]
translations = poses[:, 4:] # [N, 3]

# Example: Convert to transformation matrix
def quat_to_transformation_matrix(q, t):
    """Convert quaternion and translation to 4x4 transformation matrix."""
    qw, qx, qy, qz = q
    # Normalize quaternion
    q_norm = np.sqrt(qw**2 + qx**2 + qy**2 + qz**2)
    qw, qx, qy, qz = q / q_norm
    
    # Create rotation matrix from quaternion
    R = np.array([
        [1-2*(qy**2+qz**2), 2*(qx*qy-qz*qw), 2*(qx*qz+qy*qw)],
        [2*(qx*qy+qz*qw), 1-2*(qx**2+qz**2), 2*(qy*qz-qx*qw)],
        [2*(qx*qz-qy*qw), 2*(qy*qz+qx*qw), 1-2*(qx**2+qy**2)]
    ])
    
    # Create transformation matrix
    T = np.eye(4)
    T[:3, :3] = R
    T[:3, 3] = t
    
    return T

# Convert first pose to transformation matrix
T = quat_to_transformation_matrix(poses[0, :4], poses[0, 4:])
print("First pose transformation matrix:")
print(T)

Evaluation

We provide evaluation scripts for various datasets:

TartanAir (Mono + Stereo)

# Download test data
./tools/download_tartanair_test.sh

# Monocular evaluation
python evaluation_scripts/test_tartanair.py \
  --datapath data/tartanair_test/mono \
  --gt_path data/tartanair_test/mono_gt \
  --disable_vis

# Stereo evaluation
python evaluation_scripts/test_tartanair.py \
  --datapath data/tartanair_test/stereo \
  --gt_path data/tartanair_test/stereo_gt \
  --stereo --disable_vis

EuRoC (Mono + Stereo)

# Download dataset
./tools/download_euroc.sh

# Monocular evaluation (single GPU)
./tools/evaluate_euroc.sh

# Multi-GPU evaluation
./tools/evaluate_euroc.sh --asynchronous --frontend_device cuda:0 --backend_device cuda:1

# Stereo evaluation
./tools/evaluate_euroc.sh --stereo

TUM-RGBD (Monocular)

# Download dataset
./tools/download_tum.sh

# Single GPU evaluation
./tools/evaluate_tum.sh

# Multi-GPU evaluation
./tools/evaluate_tum.sh --asynchronous --frontend_device cuda:0 --backend_device cuda:1

ETH3D (RGB-D)

# Download dataset
./tools/download_eth3d.sh

# RGB-D evaluation
./tools/evaluate_eth3d.sh > eth3d_results.txt
python evaluation_scripts/parse_results.py eth3d_results.txt

Command Line Arguments

###demo.py Arguments

| | Argument | Type | Default | Description | | |----------|------|---------|-------------| |--imagedir| | str | - | Path to image directory | | |--calib| | str | - | Path to calibration file | | |--t0| | int | 0 | Starting frame number | | |--stride| | int | 3 | Frame stride for sampling | | |--weights| | str | droid.pth | Path to pre-trained weights | | |--buffer| | int | 512 | Buffer size | | |--disable_vis| | flag | False | Disable visualization | | |--asynchronous| | flag | False | Enable asynchronous processing | | |--frontend_device| | str | cuda | Frontend GPU device | | |--backend_device| | str | cuda | Backend GPU device | | |--reconstruction_path| | str | - | Path to save reconstruction | | |--beta| | float | 0.3 | Weight for translation/rotation | | |--filter_thresh| | float | 2.4 | Motion threshold for keyframes | | |--warmup| | int | 8 | Number of warmup frames | | |--keyframe_thresh| | float | 4.0 | Threshold for new keyframes | | |--frontend_thresh| | float | 16.0 | Frontend optimization distance | | |--frontend_window| | int | 25 | Frontend optimization window | | |--upsample| | flag | False | Upsample depth maps | |

###extract_droid_poses.py Arguments

| | Argument | Type | Default | Description | | |----------|------|---------|-------------| |--input| | str | - | Path to input .pth reconstruction file | | |--output| | str | - | Path to save output .npy poses file | |

Troubleshooting

Common Issues

1. CUDA Out of Memory

   # Reduce buffer size
   --buffer=256
   # Use frame stride
   --stride=5
   # Use multi-GPU
   --frontend_device cuda:0 --backend_device cuda:1

2. Permission Errors

   # Add user flag to docker run
   --user $(id -u):$(id -g)
   # Create output directory with permissions
   mkdir -p output && chmod 777 output

3. Display Issues

   # Disable visualization in Docker
   --disable_vis
   # Or set Qt platform
   QT_QPA_PLATFORM=offscreen

4. Module Import Errors

   # Rebuild Docker image
   docker build -t droid-slam --no-cache .
   # Or check submodule updates
   git submodule update --init --recursive

GPU Requirements

| | Use Case | Minimum GPU Memory | Recommended | | |----------|-------------------|-------------| | | Inference (Demo) | 11GB | RTX 2080 Ti or better | | | | EuRoC Evaluation | 8GB | GTX 1080 Ti or better | | | | TartanAir Evaluation | 24GB | RTX 3090 or better | | | | Training | 24GB (×4) | 4× RTX 3090 or better | |

Docker Performance Tips

# Mount with performance optimization
-v "$(pwd)/data:/workspace/data:cached"

# Use GPU sharing for multiple containers
--gpus all --shm-size=1g

# Limit GPU memory if needed
--gpus '"device=0,device=1"' --memory=24g

Citation

If you use this work in your research, please cite:

@article{teed2021droid,
  title={DROID-SLAM: Deep Visual SLAM for Monocular, Stereo, and RGB-D Cameras},
  author={Teed, Zachary and Deng, Jia},
  journal={Advances in neural information processing systems},
  year={2021}
}

Acknowledgments

• Original research by Zachary Teed and Jia Deng
• Dataset providers: TartanAir, EuRoC, TUM-RGBD, and ETH3D
• Evaluation tools from evo and tartanair_tools

License

This project is licensed under the BSD-3-Clause License - see the LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

---

Need Help?

• Check the Issues page
• Read the original paper
• Join our Discord community (link coming soon)

Note: This repository is focused on inference. For training scripts and datasets, please refer to the original DROID-SLAM repository.