Initial Commit

docs/architecture.md

@@ -0,0 +1,126 @@
+# Architecture Overview
+
+## System Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         SIMULATION LAYER                         │
+│  ┌──────────────────┐  ┌──────────────────┐  ┌───────────────┐ │
+│  │   Gazebo World   │  │  ArduPilot SITL  │  │    MAVROS     │ │
+│  │  (Physics, Viz)  │  │   (Autopilot)    │  │  (ROS Bridge) │ │
+│  └────────┬─────────┘  └────────┬─────────┘  └───────┬───────┘ │
+└───────────┼─────────────────────┼─────────────────────┼─────────┘
+            │                     │                     │
+            ▼                     ▼                     ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                         SENSOR LAYER                             │
+│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌──────────┐  │
+│  │  Forward   │  │  Downward  │  │    IMU     │  │  Range-  │  │
+│  │  Camera    │  │  Camera    │  │            │  │  finder  │  │
+│  └─────┬──────┘  └─────┬──────┘  └─────┬──────┘  └────┬─────┘  │
+└────────┼───────────────┼───────────────┼──────────────┼────────┘
+         │               │               │              │
+         ▼               ▼               ▼              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                       PERCEPTION LAYER                           │
+│  ┌─────────────────────┐  ┌────────────────┐  ┌──────────────┐  │
+│  │   Visual Odometry   │  │  Optical Flow  │  │  Landmark    │  │
+│  │  (ORB/SIFT/SURF)    │  │ (Lucas-Kanade) │  │  Detection   │  │
+│  └──────────┬──────────┘  └───────┬────────┘  └──────┬───────┘  │
+└─────────────┼─────────────────────┼──────────────────┼──────────┘
+              │                     │                  │
+              ▼                     ▼                  ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      LOCALIZATION LAYER                          │
+│                    ┌──────────────────────┐                      │
+│                    │   Position Estimator │                      │
+│                    │   (EKF Sensor Fusion)│                      │
+│                    └──────────┬───────────┘                      │
+└───────────────────────────────┼─────────────────────────────────┘
+                                │
+                                ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                       NAVIGATION LAYER                           │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
+│  │  Local Planner  │  │    Obstacle     │  │    Waypoint     │  │
+│  │                 │  │   Avoidance     │  │    Follower     │  │
+│  └────────┬────────┘  └────────┬────────┘  └────────┬────────┘  │
+└───────────┼────────────────────┼────────────────────┼───────────┘
+            │                    │                    │
+            ▼                    ▼                    ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                        CONTROL LAYER                             │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
+│  │  UAV Controller │  │  UGV Controller │  │ Mission Planner │  │
+│  │                 │  │                 │  │                 │  │
+│  └────────┬────────┘  └────────┬────────┘  └────────┬────────┘  │
+└───────────┼────────────────────┼────────────────────┼───────────┘
+            │                    │                    │
+            ▼                    ▼                    ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                        SAFETY LAYER                              │
+│  ┌─────────────────────────┐  ┌─────────────────────────────┐   │
+│  │   Geofence Monitor      │  │   Failsafe Handler          │   │
+│  │   (GPS-based only)      │  │   (Vision loss, battery)    │   │
+│  └─────────────────────────┘  └─────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Module Descriptions
+
+### Vision Module (`src/vision/`)
+- **camera_processor.py**: Image preprocessing, undistortion
+- **visual_odometry.py**: Feature-based pose estimation
+- **optical_flow.py**: Velocity from image flow
+- **object_detector.py**: Landmark/obstacle detection
+- **visual_servoing.py**: Vision-based control
+
+### Localization Module (`src/localization/`)
+- **position_estimator.py**: Sensor fusion for position
+- **ekf_fusion.py**: Extended Kalman Filter implementation
+- **landmark_tracker.py**: Track known visual features
+
+### Navigation Module (`src/navigation/`)
+- **local_planner.py**: Path planning in local frame
+- **obstacle_avoidance.py**: Reactive obstacle avoidance
+- **waypoint_follower.py**: Sequential waypoint navigation
+
+### Control Module (`src/control/`)
+- **uav_controller.py**: Quadcopter flight control
+- **ugv_controller.py**: Ground vehicle control
+- **mission_planner.py**: Multi-vehicle coordination
+
+### Safety Module (`src/safety/`)
+- **geofence_monitor.py**: GPS-based boundary checking
+- **failsafe_handler.py**: Emergency procedures
+
+## Data Flow
+
+```
+Camera Image → Feature Detection → Feature Matching → 
+Essential Matrix → Relative Pose → EKF Update → 
+Local Position → Navigation Controller → 
+Velocity Commands → MAVROS → ArduPilot
+```
+
+## ROS 2 Topics
+
+### Sensor Topics
+- `/uav/camera/forward/image_raw`
+- `/uav/camera/downward/image_raw`
+- `/uav/imu/data`
+- `/uav/rangefinder/range`
+
+### Perception Topics
+- `/uav/visual_odometry/pose`
+- `/uav/optical_flow/velocity`
+
+### Control Topics
+- `/uav/mavros/setpoint_position/local`
+- `/uav/mavros/setpoint_velocity/cmd_vel`
+- `/ugv/cmd_vel`
+
+### Safety Topics
+- `/geofence/status`
+- `/failsafe/active`
+