ResilientGeoDrone

3-Staged Python Script Which Utilizes Provided Digital Aerial Photogrammetry To Create High Quality Point Clouds For Use In Geospatial Analysis Of Forest Canopies.

Program Uses WebODM As The Main Software Facilitator For Point Cloud Generation, With Custom Python-Based Gap Detection Algorithms For Advanced Forestry Analysis. The End-To-End Pipeline Processes Raw UAV Imagery Into Actionable Ecological Insights Through An Intuitive PyQt5 GUI Or Command Line Interface

---

📑 Table of Contents

1. 📂 Directory Structure
2. 🏃 Quick Start
3. 🔍 The Breakdown
   • Architecture Diagram
   • Core Components
   • Stage-Specific Components
   • Stage 1: Preprocessing Digital Aerial Photographs
   • Stage 2: WebODM Point-Cloud Generation
   • Stage 3: Gap Detection and Geospatial Analysis
   • Stage 4: Output Packaging
4. 🌟 Features
5. 🏗️ Additional Documentation

---

📂 Directory Structure

.
├── README.md # Project overview and team introduction
├── run_qgis_setup.bat # Batch script for setting up QGIS environment
├── setup.py # Setup script for the project
├── requirements.txt # Project dependencies
├── main.py # Main application script (likely launches the GUI)
├── .gitignore # Specifies intentionally untracked files
├── config/ # Configuration files
│   ├── config.yaml # Main configuration for the pipeline
│   └── default_config.yaml # Default configuration settings
├── data/ # UAV imagery and output datasets
│   ├── raw/ # Placeholder for raw UAV image data (user-provided)
│   ├── processed/ # Intermediate processed data (e.g., validated images, temporary files)
│   │   └── (timestamped_subfolders_during_processing)/
│   └── output/ # Final output data from pipeline runs
│       ├── point_cloud/ # Point cloud related outputs (DSM, DTM, Orthophotos, CHM, reports from WebODM)
│       │   └── (timestamped_task_subfolders)/ # Each subfolder for a processing task
│       │       ├── dsm.tif
│       │       ├── dtm.tif
│       │       ├── orthophoto.tif
│       │       ├── chm.tif
│       │       └── report.pdf 
│       └── analysis/ # Geospatial analysis outputs (gap polygons, statistics)
│           └── (timestamped_task_subfolders)/
│               ├── gaps.geojson
│               └── gap_analysis_report.txt
├── logs/ # Log files from application runs
│   └── resilient_geodrone.log # Main log file
├── src/ # Source code for the application
│   ├── __init__.py
│   ├── front_end/ # PyQt5 GUI components
│   │   ├── __init__.py
│   │   ├── client_window.py # Main application window
│   │   ├── drag_drop_widget.py # Widget for image input
│   │   ├── pipeline_worker.py # QThread for running pipeline tasks
│   │   ├── progress_bar.py # Custom progress bar widget
│   │   ├── result_dialog.py # Dialog for showing results (likely obsolete or integrated)
│   │   ├── result_viewer.py # Widget for viewing pipeline outputs
│   │   └── settings_window.py # Window for application settings
│   ├── preprocessing/ # Scripts for UAV image preprocessing
│   │   ├── __init__.py
│   │   ├── batch_processor.py # Processes batches of images
│   │   ├── image_validator.py # Validates image properties
│   │   └── quality_metrics.py # Calculates image quality metrics
│   ├── point_cloud/ # Scripts for point cloud generation
│   │   ├── __init__.py
│   │   ├── cloud_processor.py # Processes outputs from WebODM (CHM generation etc.)
│   │   └── webodm_client.py # Client for interacting with WebODM API
│   ├── geospatial/ # Scripts for geospatial analysis
│   │   ├── __init__.py
│   │   └── gap_detector.py # Performs gap detection analysis
│   └── utils/ # Utility scripts
│       ├── __init__.py
│       ├── config_loader.py # Loads and manages YAML configuration
│       ├── file_handler.py # Handles file and directory operations
│       └── logger.py # Sets up and provides logging services
├── tests/ # Unit and integration tests
│   ├── __init__.py
│   ├── conftest.py # Pytest fixtures and configuration
│   ├── pytest.ini # Pytest configuration file
│   ├── data/ # Test data (e.g., sample images, mock config files)
│   │   └── (various_test_files_and_folders)/
│   └── unit/ # Unit tests for individual modules
│       ├── __init__.py
│       ├── test_batch_processor.py
│       ├── test_config_loader.py
│       ├── test_file_handler.py
│       ├── test_gap_detector.py
│       ├── test_image_validator.py
│       ├── test_logger.py
│       ├── test_pipeline_worker.py
│       ├── test_quality_metrics.py
│       ├── test_result_viewer.py
│       ├── test_settings_window.py
│       └── test_webodm.py
└── gap_detection/ # Standalone or experimental gap detection scripts (separate from src/geospatial)
    ├── gap_detection_demo.py
    ├── gap_renderer.py
    └── requirements_gap.txt

---

🏃 Quick Start

1. Clone Repository

git clone https://github.com/Resilient-Forestry-Capstone/Resilient_Geo_Drone.git
cd Resilient_Geo_Drone/ResilientGeoDrone

2. Create Virtual Environment (Optional)

# Create virtual environment
python -m venv venv


# Activate virtual environment
venv\Scripts\activate              # Windows
source venv/bin/activate           # macOS/Linux

Alternative: Run Without Activation

Instead of activating the virtual environment, you can run directly:

# Install dependencies without activation
venv\Scripts\python.exe -m pip install -r requirements.txt        # Windows
venv/bin/python -m pip install -r requirements.txt                # macOS/Linux

# Run the application
venv\Scripts\python.exe main.py                                   # Windows
venv/bin/python main.py                                           # macOS/Linux

# View help and CLI options
venv\Scripts\python.exe main.py --help                            # Windows
venv/bin/python main.py --help                                    # macOS/Linux

3. Install Dependencies

pip install -r requirements.txt

4. Setup WebODM

Install Docker Desktop first

# Clone and start WebODM
git clone https://github.com/OpenDroneMap/WebODM --depth 1
cd WebODM
./webodm.sh start

Create an account at http://localhost:8000

5. Configure Application

nano config/config.yaml      # Linux/macOS
notepad config/config.yaml   # Windows

6. Run Pipeline

GUI Mode (Recommended):

python main.py


# OR


python main.py --gui

CLI Mode:

# View all CLI options and examples
python main.py --help


# Quick example - process drone images
python main.py --input ./drone_images --output ./results

7. View Results

GUI: Click "View Results" button to browse processed files

CLI: Check your output directory (Determined In Your config.yaml) for DSM, DTM, CHM, and analysis files (formatted like YYYYMMDD_HHMMSS/)

---

🔍 The Breakdown:

Architecture Diagram

The Process Will Be Initialized With A Raw Digital Aerial Image-Set As One Of The Main Inputted Arguments--With The Other Being A Provided Environmental Tag For Fine-Tuning Of Parameters For The WebODM Software.

The System Can Be Accessed Through Either CLI Or Our Modern PyQt5-Based GUI Interface. The GUI Provides Drag-and-Drop Functionality For Image Sets, Real-Time Progress Visualization, Environment Selection, And Parameter Customization Through An Intuitive Settings Interface.

After The Setup Script Initializes The Environment, Our main.py Launches The GUI Interface Or Pipeline Backend Based On The Context. The PipelineWorker Class (A QThread Subclass) Manages The Execution Of Our 3-Stage Pipeline. In Our Architecture, There Are Several Key Components:

Core Components

A Logger Class LoggerSetup: Provides Detailed, Timestamped Logs Across All Pipeline Stages. Allows Users And Developers To Know Who, What, Where, And Why Specific Operations Are Going On.

A Config Loader ConfigLoader: For Our Tunable Parameters For Our User Through A YAML-Formatted Settings File. Applied To Allow Users Freedom To Change Specific Parameters Throughout Codebase's Lifetime.

A File Handler FileHandler: Orchestrates File Operations And Directory Management Throughout Runtime. Mainly Being Utilized To Allow A More Modifiable, Debuggable, And Dynamic Means Of File Management Than Simple Operations In-Line.

Stage-Specific Components

A Batch Image Processor `BatchProcessor`: Preprocesses And Validates Raw Drone Imagery For Usage In Point-Cloud Generation With Multiple Worker Threads. Performs Quality Control Checks Including Resolution, Blur Detection, And Brightness Assessment.

A API Interfacer With WebODM WebODMClient: Interfaces With WebODM For Our Point-Cloud Generation, Including Adaptive Parameter Tuning Based On Environmental Conditions. Manages The Asynchronous Processing Of Image Sets Through A REST API And Provides Progress Monitoring. As Well As Post-Processes WebODM Point-Cloud Outputs To Generate Canopy Height Models (CHMs) By Computing The Difference Between Digital Surface Models (DSMs) And Digital Terrain Models (DTMs). This Layer Converts Raw Point-Cloud Data Into Forest-Specific Metrics.

A Gap Detector GapDetector: Analyzes The Canopy Height Models To Automatically Identify, Measure, And Characterize Forest Gaps. The Gap Detection Algorithm Uses Configurable Height Thresholds And Morphological Operations To Create Vector Polygons Of Gap Areas With Associated Metrics.

Stage 1: Preprocessing Digital Aerial Photographs

The Pipeline Begins By Creating Timestamped Output Directories Through The FileHandler. In Stage 1, The System Collects All Digital Aerial Photographs From The Input Directory And Passes Them Through The BatchProcessor. This Component:

• Validates Image Formats Against User-Configured Acceptable Types
  
• Checks Resolution Against Minimum Requirements
  
• Applies Blur Detection Algorithms To Filter Out Blurry Images
  
• Assesses Image Brightness To Ensure Adequate Lighting
  
• Processes Images In Parallel Using Multiple Worker Threads For Efficiency
  
• Outputs A Collection Of Valid Images Ready For Point Cloud Generation
  

The GUI Displays Real-Time Progress During This Stage And Indicates Any Issues With Specific Images.

Stage 2: WebODM Point-Cloud Generation

With A Valid Image Set, The Pipeline Proceeds To WebODM Processing. The WebODMClient Component:

• Establishes A Connection With The Running WebODM Instance
  
• Creates A Project And Task With Environment-Specific Parameters (Sunny, Rainy, Foggy, Night)
  
• Uploads Images And Initializes Processing With Optimized Settings
  
• Asynchronously Polls The WebODM API For Task Status And Progress
  
• Downloads Generated Assets Including DSM, DTM And Orthophoto Files
  
• Generates A Canopy Height Model (CHM) By Computing DSM-DTM Difference
  
• Creates Timestamped Output Directories For All WebODM Products
  

This Stage Features Robust Error Handling And Progress Updates, With The GUI Reflecting The Real-Time Status Of The WebODM Processing Tasks.

Stage 3: Gap Detection and Geospatial Analysis

Once The Point Cloud And CHM Are Generated, The GapDetector Module Performs Advanced Analysis:

• Loads And Processes The CHM To Identify Areas Below User-Specified Tree Height Thresholds
  
• Applies Configurable Morphological Operations (Dilation, Erosion, Smoothing) To Refine Gap Identification
  
• Filters Gaps By Size Parameters To Focus On Ecologically Significant Openings
  
• Generates Vector Polygons For Each Identified Gap With Rich Metadata
  
• Calculates Gap Metrics Including Area, Perimeter, And Shape Characteristics
  
• Creates Visualizations Of Gaps Overlaid On The CHM Or Orthophoto
  
• Exports Results To GIS-Compatible Formats (GeoJSON, Shapefiles)
  
• Generates Statistical Summaries Of Gap Distribution And Characteristics
  

The GUI Shows Progress During This Stage And Visualizes Results Upon Completion.

Stage 4: Output Packaging

In The Final Stage, The Pipeline Organizes All Outputs Into A Structured Format:

• Creates A Comprehensive Results Package In The Designated Output Directory
  
• Generates A Summary YAML File With Pipeline Statistics And Metadata
  
• Provides Direct Access To Vector Layers For Further GIS Analysis
  
• Includes Quality Reports And Visualizations For Quick Assessment
  
• All Results Are Accessible Through The Result Viewer In The GUI
  

The Output Is Organized In Timestamped Folders For Clear Tracking Of Different Processing Runs.

---

🌟 Features:

Main View:

Main View (Pipeline Progress):

Results Viewer (Low Contour):

Results Viewer (High Contour):

Settings Window (Preprocessing Tab):

Settings Window (Logs Tab):

Settings Window (Point Cloud Tab):

Settings Window (Geospatial Tab):

---

🏗️ Additional Documentation:

Project Documents (.docx):

Project Document
Scope Document
Design Document

Architecture/Codebase Documents (.ipynb):

ResilientGeoDrone User Manual
ResilientGeoDrone Documentation

Workflow Diagram Document (.drawio):

ResilientGeoDrone Flow Diagram