ORB_SLAM3 Docker

Docker environment for ORB-SLAM3 with ROS Noetic on Ubuntu 20.04, featuring browser-based GUI visualization over SSH.

Note: For ROS Melodic with Ubuntu 18, checkout commit #8fde91d

Features

• Live Camera Streaming: Network-based camera streaming for macOS/Windows/Linux (NEW)
• Two variants: CPU-based (Xorg Nouveau) and NVIDIA CUDA-based
• Browser-based GUI: View SLAM visualization remotely via web browser (noVNC)
• ROS Noetic integration: Full ROS desktop environment
• Pre-configured dependencies: OpenCV 4.4.0, Pangolin v0.6, Eigen3

Quick Start

1. Choose Your Container Variant

Check GPU availability:

nvidia-smi  # If this shows output, you have NVIDIA GPU available

For CPU-only systems:

./build_container_cpu.sh

For NVIDIA GPU systems (requires nvidia-docker):

./build_container_cuda.sh

The build script will:

• Pull the Docker image
• Create and start the container
• Clone and compile ORB-SLAM3
• Start VNC server for browser access

2. Download Test Dataset

Option A - Quick sample (MH01):

./download_dataset_sample.sh

Option B - Manual download (MH02):

mkdir -p Datasets/EuRoC
wget -O Datasets/EuRoC/MH_02_easy.zip http://robotics.ethz.ch/~asl-datasets/ijrr_euroc_mav_dataset/machine_hall/MH_02_easy/MH_02_easy.zip
unzip Datasets/EuRoC/MH_02_easy.zip -d Datasets/EuRoC/MH02

3. Run SLAM Examples

Live Camera Streaming (Works on macOS/Windows/Linux):

# Terminal 1 (host) - Stream camera
python3 stream_camera_host.py --camera 0

# Terminal 2 (container) - Run SLAM
docker exec -it orbslam3 bash
cd /ORB_SLAM3
Examples/Monocular/mono_python_stream Vocabulary/ORBvoc.txt 8888

Run with dataset:

docker exec -it orbslam3 bash
cd /ORB_SLAM3/Examples
bash ./euroc_examples.sh

Run with USB camera (Linux only):

docker exec -it orbslam3 bash
cd /ORB_SLAM3
./run_usb_slam.sh 0  # Camera device ID (default: 0)

Note: Initialization takes a few minutes on first run. Live camera streaming works on all platforms; direct USB access requires Linux host.

4. View GUI Visualization

Local access (Docker running on your machine):

• Open browser to http://localhost:6080
• Password: orbslam

Remote access (Docker on remote server):

# On your local machine
./setup_ssh_tunnel.sh user@remote-server
# Then open http://localhost:6080 in browser

Advanced Usage

Code Development

Use VS Code Remote Development (recommended) or Sublime Text:

docker exec -it orbslam3 bash
subl /ORB_SLAM3

Manual VNC Control

Start VNC server:

docker exec -d orbslam3 /vnc_startup.sh

Manual SSH tunnel:

ssh -L 6080:localhost:6080 -L 5900:localhost:5900 user@remote-server

VNC ports:

• 6080: noVNC web interface (browser)
• 5900: VNC server (traditional VNC clients)

Container Management

Access container shell:

docker exec -it orbslam3 bash

Rebuild ORB-SLAM3:

# Inside container
cd /ORB_SLAM3
./build.sh

Stop/remove container:

docker stop orbslam3
docker rm orbslam3

---

Changelog from Original Project

This Docker setup includes the following enhancements over the base ORB-SLAM3:

Live Camera Streaming (October 2024)

• Network-Based Streaming: Camera access on macOS/Windows via TCP streaming (solves Docker USB limitations)
• Python Stream Server: stream_camera_host.py runs on host to capture and stream camera frames
• C++ Stream Receiver: mono_python_stream executable receives frames in container via port 8888
• Cross-Platform Support: Works on macOS, Windows, and Linux without direct USB passthrough
• JPEG Compression: Efficient frame transfer with configurable quality and resolution
• Port Mapping: Automatic TCP port 8888 mapping for host-container communication

Browser-Based Visualization

• VNC Server Integration: x11vnc with virtual display (Xvfb)
• noVNC Web Interface: Access GUI through browser at http://localhost:6080
• SSH Tunnel Support: Remote visualization over SSH with helper script
• Automatic Startup: VNC server launches automatically during container build

Container Improvements

• ROS Noetic Upgrade: Updated from ROS Melodic (Ubuntu 18) to ROS Noetic (Ubuntu 20.04)
• Dual Variants: Separate CPU and CUDA container images for optimal performance
• Port Exposure: Exposed ports 5900 (VNC), 6080 (noVNC), and 8888 (camera stream)
• Virtual Display: Configured DISPLAY=:99 for headless GUI rendering

Build Process

• Automated Camera Setup: Stream receiver builds automatically during container setup
• Enhanced Feedback: Build scripts verify all components and show clear instructions
• USB Camera Example: Automatic build of mono_usb_camera for direct USB on Linux
• Build Verification: Post-build checks ensure streaming components are ready

Dependencies

• Pre-built Images: OpenCV 4.4.0 and Pangolin v0.6 compiled in base images
• VNC Stack: x11vnc, Xvfb, Fluxbox, noVNC, websockify
• Python Support: OpenCV Python bindings for host-side camera capture
• Development Tools: Sublime Text, supervisor for process management

---

Troubleshooting

Camera streaming not connecting:

# Check available cameras
python3 stream_camera_host.py --list

# Verify SLAM receiver is running first
docker exec orbslam3 ps aux | grep mono_python_stream

# Try different camera index
python3 stream_camera_host.py --camera 1

Camera already in use:

• Close other applications using camera (Zoom, Skype, etc.)
• On macOS: Check camera permissions in System Preferences → Security & Privacy

"Tracking Lost" messages:

• Move camera slower and more smoothly
• Ensure good lighting and textured surfaces
• Avoid blank walls, mirrors, or reflective surfaces
• Keep camera steady during initialization

VNC not starting:

docker exec -d orbslam3 /vnc_startup.sh

Check VNC logs:

docker exec orbslam3 cat /var/log/vnc.log

Container not found:

# Rebuild container
./build_container_cpu.sh  # or build_container_cuda.sh

GUI not displaying:

• Verify VNC is running: docker exec orbslam3 ps aux | grep vnc
• Check ports: docker port orbslam3
• Ensure SSH tunnel is active for remote access