# Docker Deployment
Source: https://docs.neuronav.io/configuration/docker
Deploy Neuronav SLAM SDK using Docker for consistent, reproducible environments
Deploy the SDK with Docker for the fastest, most consistent setup across all platforms.
## Quick Start
The repository includes ready-to-use scripts:
```bash theme={null}
# Clone repository
git clone https://github.com/neuronav-io/neuronav-slam-sdk.git
cd neuronav-slam-sdk
# Build Docker image
./docker_build.sh
# Run container with camera access
./docker_run.sh
# Inside container, test SLAM
python3 examples/minimal_slam.py
```
## What's Included
The Docker image automatically provides:
* ROS2 Humble
* RTAB-Map SLAM
* Intel RealSense drivers
* OAK-D Pro (DepthAI) drivers
* All Python dependencies
## Manual Docker Commands
If you prefer manual control over the provided scripts:
**Build the image:**
```bash theme={null}
docker build -t neuronav-slam .
```
**Run with camera access:**
```bash theme={null}
docker run -it --rm \
--privileged \
--network host \
-v /dev:/dev \
-v $(pwd):/workspace \
neuronav-slam
```
**Run with visualization:**
```bash theme={null}
# Allow X11 connections
xhost +local:docker
# Run with display
docker run -it --rm \
--privileged \
--network host \
-v /dev:/dev \
-e DISPLAY=$DISPLAY \
-v /tmp/.X11-unix:/tmp/.X11-unix \
neuronav-slam
# Restore X11 security
xhost -local:docker
```
## Docker Compose
For running SLAM as a service:
```yaml theme={null}
# docker-compose.yml
version: '3.8'
services:
slam:
build: .
image: neuronav-slam:latest
privileged: true
network_mode: host
volumes:
- /dev:/dev
- ./data:/data
environment:
- ROS_DOMAIN_ID=1
- DISPLAY=${DISPLAY}
command: python3 /workspace/examples/minimal_slam.py
restart: unless-stopped
```
Run with:
```bash theme={null}
docker-compose up
```
## Common Use Cases
**Save maps to host:**
```bash theme={null}
docker run -it --rm \
--privileged \
-v /dev:/dev \
-v $(pwd)/maps:/maps \
neuronav-slam
```
**Development with live code updates:**
```bash theme={null}
docker run -it --rm \
--privileged \
-v /dev:/dev \
-v $(pwd):/workspace \
neuronav-slam bash
# Inside container
pip3 install -e /workspace # Changes reflect immediately
```
## Troubleshooting
**Camera not accessible:**
```bash theme={null}
# Verify camera is connected
lsusb | grep -E "Intel|Luxonis"
# Ensure privileged mode
docker run --privileged -v /dev:/dev neuronav-slam
```
**Visualization not working:**
```bash theme={null}
# Allow X11 connections
xhost +local:docker
# Verify DISPLAY variable
echo $DISPLAY
```
**ROS2 topics not visible:**
```bash theme={null}
# Use host network mode
docker run --network host neuronav-slam
```
## Next Steps
Run your first SLAM
Code examples
Customize settings
# Configuration
Source: https://docs.neuronav.io/configuration/overview
Configure sensors and SLAM algorithms using Python dataclasses with ready-to-use presets
Configure sensors and SLAM algorithms using Python dataclasses. Choose from presets or customize your own.
## Quick Presets
Ready-to-use configurations for common scenarios:
For high-speed navigation (drones, fast robots).
```python theme={null}
from neuronav import SensorConfig, SlamConfig
# Sensor: Low latency
sensor_config = SensorConfig(
rgb_width=640,
rgb_height=480,
fps=60, # High FPS
enable_imu=True
)
# SLAM: Fast processing
slam_config = SlamConfig(
custom_params={
"Rtabmap/DetectionRate": "2.0", # Process less frames
"Vis/MaxFeatures": "500", # Less features
"RGBD/LinearUpdate": "0.2", # Update less often
"RGBD/AngularUpdate": "0.2"
}
)
```
For high-quality 3D reconstruction.
```python theme={null}
# Sensor: High resolution
sensor_config = SensorConfig(
rgb_width=1920,
rgb_height=1080,
depth_width=1280,
depth_height=720,
fps=30
)
# SLAM: Maximum quality
slam_config = SlamConfig(
custom_params={
"Rtabmap/DetectionRate": "0", # Process all frames
"Vis/MaxFeatures": "2000", # More features
"Grid/3D": "true", # 3D occupancy grid
"Grid/CellSize": "0.01" # 1cm voxels
}
)
```
For battery-powered devices.
```python theme={null}
# Sensor: Minimal processing
sensor_config = SensorConfig(
rgb_width=640,
rgb_height=480,
fps=15, # Low FPS
enable_imu=False # Save power
)
# SLAM: Efficient settings
slam_config = SlamConfig(
enable_loop_closing=False, # Save CPU
custom_params={
"Rtabmap/MemoryThr": "300", # Limit memory
"Vis/MaxFeatures": "300"
}
)
```
## Sensor Configuration
Full `SensorConfig` dataclass with all options:
```python theme={null}
from neuronav import SensorConfig
config = SensorConfig(
# Device selection
device_id="123456", # Camera serial number (optional)
# Resolution settings
rgb_width=1280, # Color image width
rgb_height=720, # Color image height
depth_width=640, # Depth image width
depth_height=480, # Depth image height
# Performance
fps=30, # Frames per second
# Features
enable_imu=True, # Use IMU if available
enable_ir=False, # IR projector/illuminator
# Advanced parameters
custom_params={
"exposure": "auto", # or specific value in microseconds
"gain": "16", # Sensor gain
"laser_power": "150", # 0-360 for RealSense
"temporal_filter": "true", # Smooth depth over time
"spatial_filter": "true", # Smooth depth spatially
"hole_filling": "true" # Fill depth holes
}
)
```
## SLAM Configuration
Full `SlamConfig` dataclass explained:
```python theme={null}
from neuronav import SlamConfig
config = SlamConfig(
# ROS2 Topics (usually auto-configured)
rgb_topic="/camera/color/image_raw",
depth_topic="/camera/depth/image_raw",
camera_info_topic="/camera/color/camera_info",
imu_topic="/imu/data",
odom_topic="/odom",
# Frame IDs
robot_base_frame="base_link",
global_frame="map",
odom_frame="odom",
# Core features
enable_loop_closing=True, # Detect and close loops
enable_visualization=False, # RTAB-Map GUI
map_publish_frequency_ms=1000, # Map update rate
# Docker settings
use_gpu=False,
ros_domain_id=0,
# RTAB-Map parameters
custom_params={
# Detection
"Rtabmap/DetectionRate": "1.0", # Hz, 0=no limit
"Rtabmap/MemoryThr": "0", # Max nodes, 0=unlimited
# Visual features
"Vis/FeatureType": "6", # 6=ORB, 0=SURF, 11=SuperPoint
"Vis/MaxFeatures": "1000", # Features per image
# Loop closure
"Rtabmap/LoopThr": "0.11", # Loop closure threshold
"RGBD/ProximityBySpace": "true",
# Optimization
"Optimizer/Strategy": "1", # 0=TORO, 1=g2o, 2=GTSAM
"RGBD/OptimizeFromGraphEnd": "false"
}
)
```
## Usage Examples
### Fast Processing
```python theme={null}
sensor = RealSenseSensor(SensorConfig(
rgb_width=640,
rgb_height=480,
fps=30
))
slam = RTABMapSLAM(SlamConfig(
custom_params={
"Rtabmap/DetectionRate": "2.0",
"Vis/MaxFeatures": "500"
}
))
run_slam(sensor, slam)
```
### High Accuracy
```python theme={null}
sensor = RealSenseSensor(SensorConfig(
rgb_width=1920,
rgb_height=1080,
fps=30
))
slam = RTABMapSLAM(SlamConfig(
custom_params={
"Rtabmap/DetectionRate": "0",
"Vis/MaxFeatures": "2000"
}
))
run_slam(sensor, slam)
```
## Docker Deployment
```bash theme={null}
# Build
./docker_build.sh
# Run
./docker_run.sh
# Or use docker-compose
docker-compose up
```
## Visualization
Enable web-based 3D visualization:
```python theme={null}
run_slam(sensor, slam, visualize=True)
# Open http://localhost:8765
```
# Troubleshooting
Source: https://docs.neuronav.io/configuration/troubleshooting
Solve common issues with camera detection, frame rates, tracking, and performance
## Common Issues
### Camera Not Detected
```bash theme={null}
# Check USB devices
lsusb
# Check permissions
sudo usermod -a -G dialout $USER
# Restart udev
sudo udevadm control --reload-rules
```
### Low Frame Rate
* Reduce resolution
* Check USB 3.0 connection
* Disable unnecessary processing
### SLAM Lost Tracking
* Improve lighting
* Reduce motion speed
* Enable IMU fusion
* Check for feature-rich environment
### High CPU Usage
```python theme={null}
config = SensorConfig(
rgb_width=640,
rgb_height=480,
fps=15
)
```
## Debug Tools
### Check Topics
```bash theme={null}
python debug_topics.py
```
### Monitor Performance
```bash theme={null}
# CPU usage
htop
# GPU usage
nvidia-smi
# Memory
free -h
```
## Getting Help
* GitHub Issues: [Report bugs](https://github.com/neuronav-io/neuronav-slam-sdk/issues)
* Documentation: Check specific sensor/algorithm pages
* Email: [eldaniz@neuronav.io](mailto:eldaniz@neuronav.io)
# Basic SLAM
Source: https://docs.neuronav.io/examples/basic-slam
Essential examples to get started with SLAM in 2 lines of code
Get started quickly with these essential SLAM examples.
## Minimal Example
The simplest possible SLAM application:
```python theme={null}
#!/usr/bin/env python3
from neuronav import RealSenseSensor, run_slam, RTABMapSLAM
sensor = RealSenseSensor()
slam = RTABMapSLAM()
run_slam(sensor, slam)
```
## With Visualization
Enable 3D visualization in your browser:
```python theme={null}
#!/usr/bin/env python3
from neuronav import RealSenseSensor, run_slam, RTABMapSLAM
sensor = RealSenseSensor()
slam = RTABMapSLAM()
print("Open http://localhost:8765 in your browser")
run_slam(sensor, slam, visualize=True)
```
## Using OAK-D Pro
Switch to OAK-D Pro camera:
```python theme={null}
#!/usr/bin/env python3
from neuronav import OAKDSensor, run_slam, RTABMapSLAM
sensor = OAKDSensor()
slam = RTABMapSLAM()
run_slam(sensor, slam, visualize=True)
```
## Custom Configuration
Configure sensor and SLAM parameters:
```python theme={null}
#!/usr/bin/env python3
from neuronav import RealSenseSensor, SensorConfig, RTABMapSLAM, SlamConfig, run_slam
# Configure sensor
sensor_config = SensorConfig(
rgb_width=1280,
rgb_height=720,
fps=30,
enable_imu=True
)
# Configure SLAM
slam_config = SlamConfig(
enable_loop_closing=True,
custom_params={
"Vis/MaxFeatures": "1000",
"Vis/MinInliers": "20"
}
)
sensor = RealSenseSensor(sensor_config)
slam = RTABMapSLAM(slam_config)
run_slam(sensor, slam, visualize=True)
```
## Save and Load Maps
Work with persistent maps:
```python theme={null}
#!/usr/bin/env python3
from neuronav import RealSenseSensor, RTABMapSLAM, run_slam
import os
MAP_FILE = "my_map.db"
sensor = RealSenseSensor()
slam = RTABMapSLAM()
# Load existing map if available
if os.path.exists(MAP_FILE):
slam.load_map(MAP_FILE)
# Run SLAM
try:
run_slam(sensor, slam, duration=60)
finally:
slam.save_map(MAP_FILE)
```
## Running Examples
**Clone and run:**
```bash theme={null}
git clone https://github.com/neuronav-io/neuronav-slam-sdk.git
cd neuronav-slam-sdk/examples
python3 minimal_slam.py
```
**With Docker:**
```bash theme={null}
docker run -it --rm --privileged -v /dev:/dev \
neuronav-slam python3 /workspace/examples/minimal_slam.py
```
## Next Steps
Advanced examples and use cases
Detailed configuration options
Add your own camera
Solve common issues
# Custom SLAM
Source: https://docs.neuronav.io/examples/custom-slam
Advanced SLAM examples for complex scenarios and custom implementations
Advanced examples for specialized SLAM use cases and custom implementations.
## Multiple Cameras
Run SLAM with multiple cameras simultaneously:
```python theme={null}
#!/usr/bin/env python3
from neuronav import RealSenseSensor, SensorConfig, run_slam, RTABMapSLAM, SlamConfig
import threading
import subprocess
def run_camera(device_id, name):
"""Run SLAM for a single camera"""
print(f"Starting {name} with device {device_id}")
config = SensorConfig(device_id=device_id)
sensor = RealSenseSensor(config)
slam_config = SlamConfig(ros_domain_id=int(device_id[-1]))
slam = RTABMapSLAM(slam_config)
run_slam(sensor, slam)
# Find connected cameras
result = subprocess.run(
["rs-enumerate-devices", "-s"],
capture_output=True,
text=True
)
serials = [line.strip() for line in result.stdout.splitlines() if line]
print(f"Found {len(serials)} cameras: {serials}")
# Run each camera in a thread
threads = []
for i, serial in enumerate(serials):
thread = threading.Thread(
target=run_camera,
args=(serial, f"Camera_{i}")
)
thread.start()
threads.append(thread)
for thread in threads:
thread.join()
```
## Pose Monitoring
Monitor robot pose in real-time with callbacks:
```python theme={null}
#!/usr/bin/env python3
from neuronav import RealSenseSensor, RTABMapSLAM, run_slam
import numpy as np
class PoseMonitor:
def __init__(self):
self.poses = []
self.last_pose = None
def on_new_pose(self, position, quaternion):
"""Called when new pose is available"""
self.poses.append({
'position': position.copy(),
'quaternion': quaternion.copy()
})
if self.last_pose is not None:
distance = np.linalg.norm(position - self.last_pose)
if distance > 0.01: # Moved at least 1cm
print(f"Position: {position}, Distance: {distance:.3f}m")
self.last_pose = position.copy()
def save_trajectory(self, filename="trajectory.npy"):
"""Save trajectory to file"""
np.save(filename, self.poses)
print(f"Saved {len(self.poses)} poses to {filename}")
sensor = RealSenseSensor()
slam = RTABMapSLAM()
monitor = PoseMonitor()
slam.register_pose_callback(monitor.on_new_pose)
try:
run_slam(sensor, slam, duration=30)
finally:
monitor.save_trajectory()
```
## Sensor Switching
Dynamically switch between different sensors:
```python theme={null}
#!/usr/bin/env python3
from neuronav import RealSenseSensor, OAKDSensor, run_slam, RTABMapSLAM
import sys
# Get sensor type from command line
sensor_type = sys.argv[1] if len(sys.argv) > 1 else "realsense"
# Create appropriate sensor
if sensor_type == "realsense":
sensor = RealSenseSensor()
print("Using Intel RealSense")
elif sensor_type == "oakd":
sensor = OAKDSensor()
print("Using OAK-D Pro")
else:
print(f"Unknown sensor: {sensor_type}")
sys.exit(1)
slam = RTABMapSLAM()
run_slam(sensor, slam, visualize=True)
```
**Usage:**
```bash theme={null}
python sensor_switch.py realsense
python sensor_switch.py oakd
```
## Performance Profiles
### Fast Navigation
Optimized for high-speed robots:
```python theme={null}
#!/usr/bin/env python3
from neuronav import RealSenseSensor, SensorConfig, RTABMapSLAM, SlamConfig, run_slam
# Fast sensor config
sensor = RealSenseSensor(SensorConfig(
rgb_width=640,
rgb_height=480,
fps=60,
enable_imu=True
))
# Fast SLAM config
slam = RTABMapSLAM(SlamConfig(
custom_params={
"Rtabmap/DetectionRate": "2.0",
"Vis/MaxFeatures": "500",
"RGBD/LinearUpdate": "0.2",
"RGBD/AngularUpdate": "0.2"
}
))
run_slam(sensor, slam)
```
### High-Quality Mapping
Maximum quality 3D reconstruction:
```python theme={null}
#!/usr/bin/env python3
from neuronav import RealSenseSensor, SensorConfig, RTABMapSLAM, SlamConfig, run_slam
# High-res sensor
sensor = RealSenseSensor(SensorConfig(
rgb_width=1920,
rgb_height=1080,
depth_width=1280,
depth_height=720,
fps=30
))
# Quality SLAM
slam = RTABMapSLAM(SlamConfig(
custom_params={
"Rtabmap/DetectionRate": "0",
"Vis/MaxFeatures": "2000",
"Grid/3D": "true",
"Grid/CellSize": "0.01"
}
))
run_slam(sensor, slam, visualize=True)
```
## Custom SLAM Backend
Implement your own SLAM algorithm:
```python theme={null}
#!/usr/bin/env python3
from neuronav import BaseSLAM, RealSenseSensor, run_slam
import numpy as np
class CustomSLAM(BaseSLAM):
"""Custom SLAM implementation"""
def __init__(self):
super().__init__()
self.trajectory = []
self.map_points = []
def process_frame(self, rgb_image, depth_image, timestamp):
"""Process incoming sensor data"""
# Your custom SLAM logic here
pose = self.estimate_pose(rgb_image, depth_image)
self.trajectory.append(pose)
# Extract and store map points
points = self.extract_features(rgb_image, depth_image)
self.map_points.extend(points)
return pose
def estimate_pose(self, rgb, depth):
"""Estimate camera pose"""
# Implement your pose estimation
return np.eye(4)
def extract_features(self, rgb, depth):
"""Extract 3D features"""
# Implement your feature extraction
return []
def get_pose(self):
"""Return current pose"""
if self.trajectory:
return self.trajectory[-1]
return np.eye(4)
def save_map(self, filename):
"""Save map to file"""
np.savez(filename,
trajectory=self.trajectory,
map_points=self.map_points)
# Use custom SLAM
sensor = RealSenseSensor()
slam = CustomSLAM()
run_slam(sensor, slam, visualize=True)
```
## Loop Closure Detection
Configure aggressive loop closure for large environments:
```python theme={null}
#!/usr/bin/env python3
from neuronav import RealSenseSensor, RTABMapSLAM, SlamConfig, run_slam
slam_config = SlamConfig(
enable_loop_closing=True,
custom_params={
# Loop closure detection
"Rtabmap/LoopRatio": "0.8",
"Rtabmap/LoopThr": "0.11",
# Memory management
"Rtabmap/TimeThr": "0",
"Rtabmap/MemoryThr": "0",
# Feature matching
"Vis/MaxFeatures": "1500",
"Vis/MinInliers": "15",
# Global optimization
"RGBD/OptimizeFromGraphEnd": "true",
"Optimizer/Robust": "true"
}
)
sensor = RealSenseSensor()
slam = RTABMapSLAM(slam_config)
run_slam(sensor, slam, visualize=True)
```
## Next Steps
Simple examples to get started
Detailed configuration reference
Sensor integration guide
Common issues and solutions
# Installation
Source: https://docs.neuronav.io/getting-started/installation
Complete installation guide for Neuronav SLAM SDK with Docker and native setup
Choose your installation method based on your needs. Docker is recommended for the fastest setup.
## Quick Setup with Provided Scripts
The SDK includes scripts for easy Docker deployment with all dependencies pre-configured.
```bash theme={null}
# 1. Clone the repository
git clone https://github.com/neuronav-io/neuronav-slam-sdk.git
cd neuronav-slam-sdk
# 2. Build Docker image
./docker_build.sh
# 3. Run container with camera access
./docker_run.sh
```
## What's Included
The Docker image automatically installs:
* ROS2 Humble
* RTAB-Map SLAM
* Intel RealSense drivers
* OAK-D Pro (DepthAI) drivers
* All Python dependencies
## Verify Installation
Inside the container:
```bash theme={null}
# Test SDK import
python3 -c "from neuronav import RealSenseSensor; print('✅ SDK ready!')"
# Test camera detection
realsense-viewer # For RealSense cameras
```
## Manual Docker Setup
If you prefer manual control:
```bash theme={null}
# Build image
docker build -t neuronav-slam .
# Run with camera access
docker run -it --rm \
--privileged \
--network host \
-v /dev:/dev \
-v $(pwd):/workspace \
-e DISPLAY=$DISPLAY \
-v /tmp/.X11-unix:/tmp/.X11-unix \
neuronav-slam
```
**Windows Users**: Use WSL2 with Ubuntu 22.04 and follow the Docker instructions above.
## Step 1: Install System Dependencies
```bash theme={null}
# Update system
sudo apt update && sudo apt upgrade -y
# Install essential tools
sudo apt install -y curl git python3-pip build-essential cmake
```
## Step 2: Install ROS2 Humble
```bash theme={null}
# Add ROS2 repository
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key \
-o /usr/share/keyrings/ros-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] \
http://packages.ros.org/ros2/ubuntu $(lsb_release -cs) main" | \
sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null
# Install ROS2
sudo apt update
sudo apt install ros-humble-desktop ros-dev-tools -y
# Setup environment
echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
source ~/.bashrc
```
## Step 3: Install RTAB-Map SLAM
```bash theme={null}
# RTAB-Map and required packages
sudo apt install -y \
ros-humble-rtabmap-ros \
ros-humble-imu-filter-madgwick \
ros-humble-foxglove-bridge \
ros-humble-image-transport-plugins
```
## Step 4: Install Camera Drivers
**For Intel RealSense:**
```bash theme={null}
# Add Intel repository
sudo mkdir -p /etc/apt/keyrings
curl -sSf https://librealsense.intel.com/Debian/librealsense.pgp | \
sudo tee /etc/apt/keyrings/librealsense.pgp > /dev/null
echo "deb [signed-by=/etc/apt/keyrings/librealsense.pgp] \
https://librealsense.intel.com/Debian/apt-repo $(lsb_release -cs) main" | \
sudo tee /etc/apt/sources.list.d/librealsense.list
# Install
sudo apt update
sudo apt install -y \
librealsense2-dkms \
librealsense2-utils \
ros-humble-realsense2-camera
```
**For OAK-D Pro:**
```bash theme={null}
# Install DepthAI
pip3 install depthai opencv-python
sudo apt install -y ros-humble-depthai-ros
# Setup udev rules
echo 'SUBSYSTEM=="usb", ATTRS{idVendor}=="03e7", MODE="0666"' | \
sudo tee /etc/udev/rules.d/80-depthai.rules
sudo udevadm control --reload-rules && sudo udevadm trigger
```
## Step 5: Install Neuronav SDK
```bash theme={null}
# Clone repository
git clone https://github.com/neuronav-io/neuronav-slam-sdk.git
cd neuronav-slam-sdk
# Install SDK
pip3 install -e .
```
## Step 6: Verify Installation
```bash theme={null}
# Test SDK
python3 -c "from neuronav import RealSenseSensor; print('✅ SDK ready!')"
# Test camera
realsense-viewer # For RealSense
```
**WSL2 Users**: Follow these instructions inside your Ubuntu 22.04 WSL2 distribution. You'll need USBIPD to connect cameras.
## Troubleshooting
**Camera not detected:**
```bash theme={null}
# Check USB connection
lsusb | grep -E "Intel|Luxonis"
# Add user to video group
sudo usermod -a -G video $USER
# Log out and back in
```
**ROS2 not found:**
```bash theme={null}
# Source ROS2 environment
source /opt/ros/humble/setup.bash
echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
```
For more help, see the [full troubleshooting guide](/configuration/troubleshooting).
## What's Next?
Run your first SLAM
See code examples
Customize settings
# Introduction
Source: https://docs.neuronav.io/getting-started/introduction
Build real-time 3D mapping and localization into your robotics projects with just 2 lines of Python code
Neuronav SLAM SDK is a Python library that makes SLAM (Simultaneous Localization and Mapping) accessible to everyone. We handle the complexity of ROS2, sensor drivers, and SLAM algorithms so you can focus on building your application.
## 2-Line Simplicity
```python theme={null}
sensor = RealSenseSensor()
run_slam(sensor, RTABMapSLAM())
```
Built on battle-tested RTAB-Map with loop closure and global optimization
Intel RealSense and OAK-D Pro cameras supported out of the box
## Traditional SLAM vs Neuronav SDK
| Traditional SLAM | Neuronav SDK |
| ---------------------------- | -------------------------------- |
| Install and configure ROS2 ❌ | Install SDK ✅ |
| Set up camera drivers ❌ | Run 2 lines of code ✅ |
| Configure SLAM parameters ❌ | |
| Handle topic remapping ❌ | |
| Manage process lifecycle ❌ | |
| **Time to first map: Days** | **Time to first map: 2 minutes** |
## How It Works
```mermaid theme={null}
graph LR
A[Your Code] --> B[Neuronav SDK]
B --> C[Camera Driver]
B --> D[SLAM Algorithm]
B --> E[3D Visualization]
C --> F[Point Cloud]
D --> G[Robot Pose]
D --> H[3D Map]
```
## Use Cases
* **Autonomous Navigation** - Mobile robots that need to map and navigate
* **Drone Mapping** - Create 3D maps of buildings and environments
* **AR/VR Tracking** - Track headset position in 3D space
* **3D Reconstruction** - Scan objects and environments
* **Research** - Quickly prototype SLAM applications
## Supported Hardware
**Depth Cameras**
* Intel RealSense D435i, D455, D415
* Luxonis OAK-D Pro, OAK-D Pro W
* [Add your own sensor](/sensors/custom-sensors) in under 20 minutes
**Computing Platforms**
* Ubuntu 20.04/22.04
* Docker containers
## Get Started
Run SLAM in 2 minutes
Detailed setup guide
Code examples
# Quick Start
Source: https://docs.neuronav.io/getting-started/quickstart
Get up and running with Neuronav SLAM SDK in 2 minutes - no ROS2 expertise required
Get your first SLAM system running in 2 minutes with just 2 lines of Python code.
## Prerequisites
* Ubuntu 20.04/22.04 (or Windows 11 with WSL2)
* Python 3.8+
* Intel RealSense or OAK-D Pro camera
* SDK installed ([see installation guide](/getting-started/installation))
## Your First SLAM Application
**1. Create a new Python file**
```bash theme={null}
touch my_first_slam.py
```
**2. Add these 2 lines**
```python theme={null}
from neuronav import RealSenseSensor, run_slam, RTABMapSLAM
sensor = RealSenseSensor()
run_slam(sensor, RTABMapSLAM())
```
**3. Run it**
```bash theme={null}
python3 my_first_slam.py
```
That's it! Your robot is now creating a 3D map in real-time.
## With 3D Visualization
Add `visualize=True` to see the map being built:
```python theme={null}
from neuronav import RealSenseSensor, run_slam, RTABMapSLAM
sensor = RealSenseSensor()
run_slam(sensor, RTABMapSLAM(), visualize=True)
```
Open [http://localhost:8765](http://localhost:8765) in your browser to view the live 3D map.
## Using OAK-D Pro Camera
Simply change the sensor:
```python theme={null}
from neuronav import OAKDSensor, run_slam, RTABMapSLAM
sensor = OAKDSensor()
run_slam(sensor, RTABMapSLAM())
```
## What's Next?
Customize sensor and SLAM settings
See advanced use cases
Integrate custom cameras
# Custom Sensors
Source: https://docs.neuronav.io/sensors/custom-sensors
Add support for any depth camera in under 20 minutes with the SensorBase interface
The Neuronav SDK is designed to be easily extensible. You can add support for any depth camera by implementing the `SensorBase` interface. This guide shows you how to integrate new sensors in under 20 minutes.
## Quick Start Template
Here's a complete template for adding a new sensor:
```python theme={null}
from neuronav.sensors.base import SensorBase, SensorConfig
from typing import Dict, Optional
import subprocess
import time
class MyCustomSensor(SensorBase):
"""Custom sensor implementation for [Your Camera Name]"""
def __init__(self, config: Optional[SensorConfig] = None):
self.config = config or SensorConfig()
self.process = None
def configure(self, config: SensorConfig):
"""Store configuration for later use"""
self.config = config
def start(self):
"""Start the sensor driver and begin publishing data"""
# Launch your camera's ROS2 driver
cmd = [
"ros2", "run", "your_camera_package", "your_camera_node",
"--ros-args",
"-p", f"width:={self.config.rgb_width}",
"-p", f"height:={self.config.rgb_height}",
"-p", f"fps:={self.config.fps}"
]
# Add device-specific parameters
if self.config.device_id:
cmd.extend(["-p", f"device_id:={self.config.device_id}"])
# Launch the process
self.process = subprocess.Popen(cmd)
time.sleep(2) # Wait for initialization
def stop(self):
"""Stop the sensor and clean up resources"""
if self.process:
self.process.terminate()
self.process.wait(timeout=5)
self.process = None
def get_sensor_name(self) -> str:
"""Return the name of your sensor"""
return "MyCustomSensor"
def get_ros_topics(self) -> Dict[str, str]:
"""Return the mapping of data types to ROS2 topics"""
return {
"rgb": "/camera/color/image_raw",
"depth": "/camera/depth/image_raw",
"camera_info": "/camera/color/camera_info",
"imu": "/imu/data" # Optional
}
# Context manager support
def __enter__(self):
self.start()
return self
def __exit__(self, exc_type, exc_val, exc_tb):
self.stop()
```
## Step-by-Step Guide
### Step 1: Understand Your Camera
Before implementing, gather information about your camera:
* Camera model and manufacturer
* ROS2 driver package name (or if you need to create one)
* Published ROS2 topics
* Configuration parameters
* USB/network connection requirements
* SDK/driver installation steps
### Step 2: Create Sensor Class
Create a new file `neuronav/sensors/your_camera.py`:
```python theme={null}
from neuronav.sensors.base import SensorBase, SensorConfig
from typing import Dict, Optional
import subprocess
import os
import time
class YourCameraSensor(SensorBase):
"""
Support for [Your Camera Name]
This sensor provides RGB-D data from [manufacturer] cameras.
Requires [dependencies] to be installed.
"""
def __init__(self, config: Optional[SensorConfig] = None):
"""
Initialize the sensor with optional configuration
Args:
config: SensorConfig object with camera parameters
"""
self.config = config or SensorConfig()
self.processes = [] # List to track multiple processes
self._validate_config()
def _validate_config(self):
"""Validate and set default configuration"""
# Set camera-specific defaults
if not self.config.custom_params:
self.config.custom_params = {}
# Example: Set default exposure if not specified
if "exposure" not in self.config.custom_params:
self.config.custom_params["exposure"] = "auto"
```
### Step 3: Implement Core Methods
#### Configure Method
```python theme={null}
def configure(self, config: SensorConfig):
"""
Configure the sensor with new settings
Args:
config: New configuration to apply
"""
self.config = config
self._validate_config()
# If sensor is running, restart with new config
if self.processes:
self.stop()
self.start()
```
#### Start Method
```python theme={null}
def start(self):
"""Start the sensor driver and related processes"""
# 1. Launch the main camera driver
driver_cmd = self._build_driver_command()
driver_process = subprocess.Popen(
driver_cmd,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE
)
self.processes.append(driver_process)
# 2. Launch additional nodes if needed (e.g., IMU filter)
if self.config.enable_imu:
imu_cmd = self._build_imu_command()
imu_process = subprocess.Popen(imu_cmd)
self.processes.append(imu_process)
# 3. Wait for initialization
time.sleep(3)
# 4. Verify the sensor started correctly
if not self._verify_topics():
raise RuntimeError(f"{self.get_sensor_name()} failed to start")
def _build_driver_command(self):
"""Build the command to launch the camera driver"""
cmd = [
"ros2", "launch", "your_camera_package", "camera.launch.py"
]
# Add parameters
params = [
f"rgb_width:={self.config.rgb_width}",
f"rgb_height:={self.config.rgb_height}",
f"depth_width:={self.config.depth_width}",
f"depth_height:={self.config.depth_height}",
f"fps:={self.config.fps}"
]
# Add custom parameters
for key, value in self.config.custom_params.items():
params.append(f"{key}:={value}")
cmd.extend(params)
return cmd
def _verify_topics(self, timeout=5):
"""Verify that expected topics are being published"""
import time
start_time = time.time()
while time.time() - start_time < timeout:
# Check if topics exist (implement actual check)
# This is a simplified example
result = subprocess.run(
["ros2", "topic", "list"],
capture_output=True,
text=True
)
topics = self.get_ros_topics()
if topics["rgb"] in result.stdout:
return True
time.sleep(0.5)
return False
```
#### Stop Method
```python theme={null}
def stop(self):
"""Stop all sensor processes gracefully"""
for process in self.processes:
if process.poll() is None: # Process is still running
process.terminate()
try:
process.wait(timeout=5)
except subprocess.TimeoutExpired:
process.kill() # Force kill if needed
process.wait()
self.processes.clear()
```
#### Get Methods
```python theme={null}
def get_sensor_name(self) -> str:
"""Return human-readable sensor name"""
return "Your Camera Name"
def get_ros_topics(self) -> Dict[str, str]:
"""
Return the mapping of data types to ROS2 topics
Returns:
Dictionary mapping data types to topic names
"""
# Adjust these to match your camera's actual topics
base_namespace = "/your_camera"
topics = {
"rgb": f"{base_namespace}/color/image_raw",
"depth": f"{base_namespace}/depth/image_raw",
"camera_info": f"{base_namespace}/color/camera_info"
}
# Add IMU topic if enabled
if self.config.enable_imu:
topics["imu"] = f"{base_namespace}/imu/data"
return topics
```
### Step 4: Handle Special Cases
#### Multiple Processes
Some cameras require multiple nodes:
```python theme={null}
def start(self):
"""Start multiple processes for the sensor"""
# 1. Start the camera driver
driver_process = self._start_driver()
self.processes.append(driver_process)
# 2. Start depth processing node
depth_process = self._start_depth_processor()
self.processes.append(depth_process)
# 3. Start synchronization node
sync_process = self._start_synchronizer()
self.processes.append(sync_process)
# 4. Start IMU filter if needed
if self.config.enable_imu:
imu_process = self._start_imu_filter()
self.processes.append(imu_process)
def _start_driver(self):
"""Start the main camera driver"""
cmd = ["ros2", "run", "camera_pkg", "camera_node"]
return subprocess.Popen(cmd)
def _start_depth_processor(self):
"""Start depth processing node"""
cmd = ["ros2", "run", "depth_pkg", "depth_node"]
return subprocess.Popen(cmd)
def _start_synchronizer(self):
"""Start RGB-D synchronization"""
cmd = [
"ros2", "run", "rtabmap_sync", "rgbd_sync",
"--ros-args",
"--remap", "rgb/image:=/camera/color/image",
"--remap", "depth/image:=/camera/depth/image",
"--remap", "rgb/camera_info:=/camera/color/info"
]
return subprocess.Popen(cmd)
```
#### Topic Remapping
If your camera uses different topic names:
```python theme={null}
def get_ros_topics(self) -> Dict[str, str]:
"""Handle non-standard topic names"""
# Your camera's actual topics
camera_topics = {
"rgb": "/my_camera/rgb/image",
"depth": "/my_camera/depth_registered/image",
"camera_info": "/my_camera/rgb/camera_info",
"imu": "/my_camera/imu/raw"
}
# The SDK will handle remapping to standard names
return camera_topics
```
#### Network Cameras
For IP/network cameras:
```python theme={null}
class NetworkCameraSensor(SensorBase):
def __init__(self, config: Optional[SensorConfig] = None):
super().__init__(config)
self.camera_ip = config.custom_params.get("ip_address", "192.168.1.1")
self.camera_port = config.custom_params.get("port", 8080)
def start(self):
"""Start network camera stream"""
cmd = [
"ros2", "run", "network_camera", "stream_node",
"--ros-args",
"-p", f"camera_ip:={self.camera_ip}",
"-p", f"camera_port:={self.camera_port}",
"-p", f"username:={self.config.custom_params.get('username', '')}",
"-p", f"password:={self.config.custom_params.get('password', '')}"
]
self.process = subprocess.Popen(cmd)
```
### Step 5: Add to Package
Update `neuronav/sensors/__init__.py`:
```python theme={null}
from .base import SensorBase, SensorConfig
from .realsense import RealSenseSensor
from .oakd import OAKDSensor
from .your_camera import YourCameraSensor # Add your sensor
__all__ = [
'SensorBase',
'SensorConfig',
'RealSenseSensor',
'OAKDSensor',
'YourCameraSensor' # Export it
]
```
Update main `neuronav/__init__.py`:
```python theme={null}
from .sensors import (
SensorBase,
SensorConfig,
RealSenseSensor,
OAKDSensor,
YourCameraSensor # Add here too
)
```
### Step 6: Test Your Sensor
Create a test script:
```python theme={null}
#!/usr/bin/env python3
"""Test script for custom sensor integration"""
from neuronav import YourCameraSensor, run_slam, RTABMapSLAM
from neuronav.sensors import SensorConfig
import time
def test_basic():
"""Test basic sensor functionality"""
print("Testing basic sensor startup...")
sensor = YourCameraSensor()
sensor.start()
print(f"Sensor name: {sensor.get_sensor_name()}")
print(f"Topics: {sensor.get_ros_topics()}")
time.sleep(5)
sensor.stop()
print("✓ Basic test passed")
def test_with_config():
"""Test sensor with custom configuration"""
print("\nTesting with configuration...")
config = SensorConfig(
rgb_width=1280,
rgb_height=720,
fps=30,
enable_imu=True,
custom_params={
"exposure": "8000",
"gain": "100"
}
)
sensor = YourCameraSensor(config)
sensor.start()
time.sleep(5)
sensor.stop()
print("✓ Configuration test passed")
def test_with_slam():
"""Test sensor with SLAM"""
print("\nTesting with SLAM...")
sensor = YourCameraSensor()
slam = RTABMapSLAM()
# Run for 10 seconds
run_slam(sensor, slam, duration=10)
print("✓ SLAM test passed")
if __name__ == "__main__":
test_basic()
test_with_config()
test_with_slam()
print("\n✅ All tests passed!")
```
## Testing Checklist
Before considering your sensor integration complete:
* Basic startup/shutdown works
* Configuration parameters are applied
* All expected topics are published
* Topic data is at expected rate
* Works with `run_slam()` function
* Handles disconnection gracefully
* Multiple sensors can run simultaneously
* Memory/CPU usage is reasonable
* Documentation is complete
## Next Steps
Run SLAM with your new sensor
Contribute your sensor to the SDK
Learn about advanced configuration
Debug common integration issues
## Contributing Your Sensor
If you've successfully integrated a new sensor, consider contributing it back to the community:
1. Fork the [Neuronav SDK repository](https://github.com/neuronav-io/neuronav-slam-sdk)
2. Add your sensor implementation
3. Include documentation and examples
4. Submit a pull request
We'd love to expand our sensor support!
# Supported Sensors
Source: https://docs.neuronav.io/sensors/overview
Compare and configure Intel RealSense and OAK-D Pro depth cameras for SLAM
The SDK supports popular depth cameras out of the box, with automatic driver management and topic remapping.
## Sensor Comparison
| Feature | RealSense D435i | RealSense D455 | RealSense D415 | OAK-D Pro | OAK-D Pro W |
| ------------------ | --------------- | ------------------ | ------------------ | --------------- | ----------- |
| **Price** | \~\$350 | \~\$450 | \~\$300 | \~\$400 | \~\$500 |
| **Range** | 0.2-10m | 0.4-20m | 0.3-10m | 0.2-15m | 0.2-20m |
| **FOV** | 87°×58° | 87°×58° | 69°×42° | 80°×55° | 150°×100° |
| **IMU** | Yes | Yes | No | Yes | Yes |
| **Best For** | Indoor robots | Outdoor/long range | Precision scanning | AI applications | Outdoor AI |
| **Global Shutter** | No | Yes | No | No | No |
## Intel RealSense
The most popular choice for SLAM applications. Three models supported:
### D435i - Balanced Performance
Best for general indoor robotics.
```python theme={null}
from neuronav import RealSenseSensor, SensorConfig
# Basic usage - auto-detects camera
sensor = RealSenseSensor()
# Optimized for navigation
config = SensorConfig(
rgb_width=848, # D435's optimal width
rgb_height=480,
fps=30,
enable_imu=True, # Use built-in IMU
custom_params={
"laser_power": "150", # Balance range/power
"temporal_filter": "true"
}
)
sensor = RealSenseSensor(config)
# Multiple cameras
sensor1 = RealSenseSensor(SensorConfig(device_id="123456"))
sensor2 = RealSenseSensor(SensorConfig(device_id="789012"))
```
### D455 - Extended Range
Best for outdoor and large spaces.
```python theme={null}
# Outdoor configuration
outdoor_config = SensorConfig(
rgb_width=1280,
rgb_height=720,
fps=30,
custom_params={
"laser_power": "360", # Maximum for sunlight
"exposure": "auto"
}
)
```
### D415 - High Accuracy
Best for 3D scanning and close-range work.
```python theme={null}
# Precision scanning
scan_config = SensorConfig(
rgb_width=1920,
rgb_height=1080,
fps=15, # Lower FPS for quality
custom_params={
"depth_confidence": "1" # Higher accuracy
}
)
```
## OAK-D Pro
Luxonis OAK-D Pro and Pro W with on-device AI.
```python theme={null}
from neuronav import OAKDSensor, SensorConfig
# Basic usage
sensor = OAKDSensor()
# With configuration
config = SensorConfig(
rgb_width=1280,
rgb_height=720,
fps=30
)
sensor = OAKDSensor(config)
```
## Configuration Options
```python theme={null}
@dataclass
class SensorConfig:
device_id: Optional[str] = None # Camera serial number
rgb_width: int = 640 # RGB resolution
rgb_height: int = 480
depth_width: int = 640 # Depth resolution
depth_height: int = 480
fps: int = 30 # Frame rate
enable_imu: bool = True # Use IMU if available
enable_ir: bool = False # IR projector
custom_params: Dict = None # Sensor-specific params
```
## Common Settings
### Fast Navigation
```python theme={null}
config = SensorConfig(rgb_width=640, rgb_height=480, fps=60)
```
### High Quality
```python theme={null}
config = SensorConfig(rgb_width=1920, rgb_height=1080, fps=30)
```
### Low Power
```python theme={null}
config = SensorConfig(rgb_width=640, rgb_height=480, fps=15)
```