COLMAP Docker

Configurable Docker setup to run COLMAP for 3D reconstruction based on video files or images. This setup leverages NVIDIA GPUs for accelerated processing.

Prerequisites

• Docker with Docker Compose support
• NVIDIA Docker runtime (for GPU acceleration)
• Linux system (tested on Ubuntu 22.04; Windows may require modifications)

Usage

Clone this repository

git clone git@github.com:fabianpfitzner/colmap_docker.git
cd colmap_docker

Important: Add execute permissions to the run script:

chmod +x drone-reconstruction/scripts/run.sh

Setup your project

1. Navigate to drone-reconstruction/projects/ and create a directory for your project
2. Navigate inside your project directory and create a videos/ directory
3. Copy all videos of your project into the videos/ directory. These will be used for the COLMAP reconstruction
4. OPTIONAL: Repeat steps 2-3 for additional projects

Your folder structure should look like this:

projects/
    ├─ your_project/
    │  └─ videos/
    │     ├─ proj_video_1.mp4
    │     ├─ proj_video_2.mp4
    │     └─ ...
    ├─ optional_other_project/
    │  └─ videos/
    │     ├─ other_proj_video_1.mp4
    │     ├─ other_proj_video_2.mp4
    │     └─ ...
    └─ ...

Configure frame extraction (optional)

You can control how many frames are extracted from videos by modifying the --x_frame parameter in drone-reconstruction/scripts/run.sh.

Every n-th frame will be extracted. For example, to extract every 30th frame:

python /home/drone-reconstruction/scripts/video2img.py --x_frame 30

Lower values extract more frames (higher quality but slower processing), while higher values extract fewer frames (faster but potentially lower quality reconstruction).

Configure docker-compose.yml

IMPORTANT: Before running, you must configure drone-reconstruction/docker/docker-compose.yml

1. Configure User Permissions

Set the Docker container user to match your host machine's UID and GID. This ensures proper file ownership for bind-mounted volumes.

1. Get your UID and GID:

   id

2. Update the user field in docker-compose.yml:

   user: <your_UID>:<your_GID>

2. Configure CPU Resources

Specify which CPU cores the container can use:

cpuset: "0-63"  # Example: uses cores 0-63

3. Configure GPU Resources

Specify which GPU(s) the container can access:

environment:
  - NVIDIA_VISIBLE_DEVICES=0  # Use GPU 0, or "all" for all GPUs

Run Docker container

Navigate to drone-reconstruction/docker/ and run:

docker compose up

This will build and start the container. The process will:

1. Extract frames from all video files in each project
2. Run COLMAP reconstruction for each project sequentially

IMPORTANT - Container Management:

• DO NOT press Ctrl+C to stop the container, as this may corrupt the process
• To detach from the running container: simply close the terminal window
• To reattach and view progress: run docker attach <container-name> in a new terminal
• To safely detach from an attached terminal: press Ctrl+P, then Ctrl+Q

Obtaining results

Results are automatically available on your host system via bind mounts in the drone-reconstruction/projects/ directory.

Each project directory will contain:

• extracted_frames/ - Individual frames extracted from videos
• colmap/ - COLMAP reconstruction results, including:
  • database.db - Feature database
  • sparse/ - Sparse 3D reconstruction
  • dense/ - Dense reconstruction and point cloud (fused.ply)

Before running again

Important cleanup steps before reusing project folders:

1. Delete the colmap/ directory if you want to re-run reconstruction
2. Delete the extracted_frames/ directory if you want to re-extract frames with different settings
   • If extracted_frames/ already exists and contains files, frame extraction will be skipped
3. Remove old project folders that are no longer needed to avoid unnecessary processing

Troubleshooting

• If the container fails to start, verify that NVIDIA Docker runtime is properly installed
• Ensure your UID/GID in docker-compose.yml matches your host user
• Check that the specified GPU index exists on your system
• Verify that video files have .mp4 or .MP4 extensions