# UAV-UGV Gazebo SITL Simulation
## GPS-Denied Navigation with Geofencing

A complete simulation environment for UAV (drone) and UGV (ground vehicle) development using **GPS-denied navigation** with vision-based localization, while maintaining GPS-based geofencing for safety.

## Key Feature: GPS-Denied Navigation

**Navigation Mode**: All vehicles navigate using **relative positioning** only:
- Visual odometry from cameras
- Optical flow sensors
- IMU integration
- Visual landmark tracking
- Local coordinate frames

**GPS Usage**: GPS is ONLY used for:
- Geofencing (safety boundaries)
- Initial position reference (optional)
- NOT used for waypoint navigation
- NOT used for position control

This simulates real-world GPS-denied environments like:
- Indoor spaces
- Urban canyons
- GPS-jammed areas
- Under bridges/tunnels

## Features

- **Iris quadcopter** with dual cameras (forward + downward)
- **Ground vehicle (UGV)** with vision sensors
- **Visual odometry** - camera-based position estimation
- **Optical flow** - velocity estimation from downward camera
- **Landmark navigation** - visual feature tracking
- **GPS geofencing** - safety boundaries only
- **Single command launch** - everything runs from one script
- **NVIDIA GPU acceleration** support
- **Python virtual environment** for isolated dependencies
- **GPS-denied worlds** - indoor and urban environments

## System Requirements

- **Ubuntu 22.04 LTS** (or 24.04 with ROS 2 Jazzy)
- **Python 3.10+**
- **ROS 2 Humble** (or Jazzy for Ubuntu 24.04)
- 8GB RAM minimum (16GB recommended)
- NVIDIA GPU recommended

### WSL2 Support (Windows)

This project supports **Windows Subsystem for Linux (WSL2)**:
- Windows 10 (21H2+) or Windows 11
- WSL2 with Ubuntu 22.04
- GUI support via WSLg (Windows 11) or VcXsrv (Windows 10)
- See [WSL Setup Guide](docs/wsl_setup_guide.md) for detailed instructions

## Quick Start

### Linux (Native)

```bash
# 1. Clone repository
cd ~/ros2_ws/src
git clone https://git.sirblob.co/SirBlob/simulation.git uav_ugv_simulation
cd uav_ugv_simulation

# 2. Run setup (installs everything)
bash setup.sh

# 3. Restart terminal or reload bash
source ~/.bashrc

# 4. Activate virtual environment and run
source activate_venv.sh
bash scripts/run_simulation.sh
```

### WSL2 (Windows)

```bash
# 1. Clone repository
cd ~
git clone https://git.sirblob.co/SirBlob/simulation.git uav_ugv_simulation
cd uav_ugv_simulation

# 2. Run WSL-specific setup
bash scripts/setup_wsl.sh

# 3. Restart terminal
exit
# Reopen WSL terminal

# 4. Run simulation
cd ~/uav_ugv_simulation
source activate_venv.sh
bash scripts/run_simulation.sh

# If graphics are slow, use software rendering:
bash scripts/run_simulation.sh --software-render
```

## GPS-Denied Navigation Architecture

```
┌─────────────────────────────────────────────────────┐
│              Vision Sensors                         │
│  Forward Camera + Downward Camera + Optical Flow    │
└─────────────────┬───────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────┐
│         Visual Odometry & Feature Tracking          │
│  Estimates relative position from camera motion     │
└─────────────────┬───────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────┐
│         Position Estimator (EKF Fusion)             │
│  Fuses: Visual Odom + Optical Flow + IMU            │
│  Output: Local position estimate (relative)         │
└─────────────────┬───────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────┐
│            Navigation Controller                     │
│  Commands: "Move 5m forward, 3m right"              │
│  (Relative coordinates only, NO GPS waypoints)      │
└─────────────────────────────────────────────────────┘

         SEPARATE SAFETY LAYER (GPS-based):
┌─────────────────────────────────────────────────────┐
│              Geofence Monitor                        │
│  GPS position → Check against boundaries            │
│  If outside: Emergency RTL or hold                  │
└─────────────────────────────────────────────────────┘
```

## Navigation Modes

### 1. **Vision-Only Mode** (Default)
- Uses camera for all position estimates
- Suitable for structured environments
- Requires good lighting and visual features

### 2. **Optical Flow Mode**
- Uses downward camera for velocity
- Works well at low altitudes
- Good for hovering and slow flight

### 3. **Hybrid Mode**
- Combines visual odometry + optical flow + IMU
- Most robust approach
- Recommended for complex missions

## Geofencing Configuration

Edit `config/geofence_params.yaml`:

```yaml
geofence:
  enabled: true
  use_gps: true  # GPS ONLY for geofence
  
  # Define boundaries (GPS coordinates)
  fence_type: "polygon"  # or "circle"
  
  # Polygon fence (lat/lon points)
  polygon_points:
    - {lat: 47.397742, lon: 8.545594}  # Point 1
    - {lat: 47.398242, lon: 8.545594}  # Point 2
    - {lat: 47.398242, lon: 8.546094}  # Point 3
    - {lat: 47.397742, lon: 8.546094}  # Point 4
  
  # Or circle fence
  center_lat: 47.397742
  center_lon: 8.545594
  radius_meters: 100
  
  # Actions on breach
  action: "RTL"  # Return to launch
  max_altitude: 50  # meters
```

## Example Mission (Relative Coordinates)

```python
# Example: Navigate to visual landmark

# Define mission in RELATIVE coordinates
mission_waypoints = [
    {"x": 0, "y": 0, "z": 5},      # Takeoff to 5m
    {"x": 10, "y": 0, "z": 5},     # Move 10m forward
    {"x": 10, "y": 5, "z": 5},     # Move 5m right
    {"x": 0, "y": 5, "z": 5},      # Return to start (offset)
    {"x": 0, "y": 0, "z": 5},      # Back to takeoff point
    {"x": 0, "y": 0, "z": 0},      # Land
]

# GPS is NEVER used for these waypoints
# Position estimated from visual odometry
```

## Project Structure

- `launch/` - ROS 2 launch files
- `worlds/` - Gazebo world files (indoor, urban)
- `models/` - Robot models (Iris with cameras, UGV)
- `src/vision/` - Visual odometry, optical flow
- `src/localization/` - Position estimation, sensor fusion
- `src/navigation/` - Path planning (relative coordinates)
- `src/safety/` - Geofencing (GPS-based)
- `config/` - Configuration files

## Documentation

- [Setup Guide](docs/setup_guide.md) - Linux installation
- [WSL Setup Guide](docs/wsl_setup_guide.md) - Windows WSL2 installation
- [Usage Guide](docs/usage.md)
- [Architecture Overview](docs/architecture.md)
- [GPS-Denied Navigation](docs/gps_denied_navigation.md)
- [Troubleshooting](docs/troubleshooting.md)

## Key Differences from GPS Navigation

| Aspect | GPS Navigation | This Project (GPS-Denied) |
|--------|---------------|---------------------------|
| Position Source | GPS satellites | Visual odometry + sensors |
| Waypoint Type | GPS coordinates | Relative coordinates (x,y,z) |
| Reference Frame | Global (lat/lon) | Local (relative to start) |
| Indoor Capability | No | Yes |
| Drift | Minimal | Accumulates over time |
| Geofencing | GPS-based | GPS-based (safety only) |
| Use Cases | Outdoor, open sky | Indoor, urban, GPS-jammed |

## Running Different Scenarios

```bash
# Indoor warehouse (no GPS available)
bash scripts/run_simulation.sh --world worlds/indoor_warehouse.world

# Urban canyon (degraded GPS)
bash scripts/run_simulation.sh --world worlds/urban_canyon.world

# Open outdoor (GPS available but not used for nav)
bash scripts/run_simulation.sh --world worlds/empty_custom.world
```

## License

MIT License

## Contributing

Contributions welcome! Please ensure all navigation remains GPS-denied (except geofencing).