# hwiyoung/orthophoto_maps architecture

> Architecture diagram of the GitHub repository hwiyoung/orthophoto_maps, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hwiyoung/orthophoto_maps
- Repository: https://github.com/hwiyoung/orthophoto_maps

## Overview

##### Project type and purpose
- This is a Python-based command-line mapping tool (“Orthophoto_Maps”) that ingests drone imagery (and sensor metadata) and produces geo-referenced orthophotos (GeoTIFF).
- It implements a processing pipeline: georeferencing (camera pose estimation), DEM processing, and geodata generation (image rectification & pixel resampling).

##### File structure
- Top-level scripts:
- main_dg.py – the entry point for “direct georeferencing.”
- Orthophoto.py / OrthophotoThermal.py / Orthophoto_LBA.py – specialized workflows (thermal, local bundle adjustment).
- module/ – houses core algorithmic components:
- BackprojectionResample.py, Boundary.py, EoData.py, ExifData.py, LocalBA.py, system_calibration.py, etc.
- Data/ – sample input data (drone images + sensor .txt files).
- tests/ – unit and integration tests, plus test imagery, exiftool binary, and 3D models for DEM.
- environment.yaml – Conda environment spec (Python 3.8, GIS and numeric libraries).

##### README for additional insights
- Steps enumerated:
1) Georeferencing (camera pose & 3D points)
2) DEM processing (flat plane vs. sparse point cloud)
3) Geodata generation (rectify + resample)
- Future work hints at additional modules (ray tracing, config management, GSD calculation).

a. Main components (blocks)
- Configuration Manager – parses user settings (input/output paths, sensor width, system calibration).
- Data Ingestion – loads raw images, reads EXIF/sensor data (ExifData module).
- Georeferencing Engine – computes camera pose & sparse 3D coordinates (EoData, Boundary, system_calibration modules).
- DEM Processor – generates ground plane or imports sparse point cloud (LocalBA if available).
- Orthophoto Generator –
– Rectification sub-module (BackprojectionResample)
– Pixel resampling sub-module
- Thermal Handler (OrthophotoThermal) – optional parallel path for thermal image processing.
- Output Writer – writes GeoTIFF per image to disk.
- Testing Suite – external to main pipeline, validates each module using test datasets and exiftool/exiv2.

b. Relationships and interactions
- Data flows from Configuration → Data Ingestion → Georeferencing → DEM Processor → Orthophoto Generator → Output Writer.
- Thermal path branches after Data Ingestion (if thermal workflow selected).
- LocalBA (bundle adjustment) can be invoked between Georeferencing and DEM Processor.
- Testing Suite invokes modules in isolation using mock data.

c. Architectural patterns / design principles
- Pipeline architecture: each stage takes standardized inputs & produces outputs for the next.
- Modular separation: all core algorithms live in module/; top-level scripts orchestrate.
- Dependency inversion: Common interfaces for EXIF reading, reprojection, and resampling.
- Extensibility points: thermal branch, future ray-tracing module, config manager enhancements.

d. Key technologies & libraries
- Python 3.8 (Anaconda)
- numpy, scipy (numerics)
- GDAL / rasterio (GeoTIFF I/O)
- exiftool / exiv2 (metadata extraction)
- pytest (testing)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Scripts
    subgraph "Entry Scripts"
        EP["Direct Georeferencing<br/>(main_dg.py)"]:::script
        RGB["Orthophoto Workflow<br/>(Orthophoto.py)"]:::script
        TH["Thermal Workflow<br/>(OrthophotoThermal.py)"]:::script
        LBA_Script["LBA Workflow<br/>(Orthophoto_LBA.py)"]:::optional
    end

    %% Configuration
    subgraph "Configuration"
        CM["Config Manager<br/>(environment.yaml)"]:::data
    end

    %% Core Pipeline
    EP --> CM
    EP --> DI

    %% Data Ingestion
    DI["Data Ingestion<br/>(ExifData)"]:::processing
    CM --> DI
    ET["ExifTool / Exiv2"]:::tool
    ET --> DI

    %% Georeferencing Engine
    subgraph "Georeferencing Engine"
        Eo["EoData"]:::processing
        Bnd["Boundary"]:::processing
        SC["system_calibration"]:::processing
    end
    DI --> Eo --> Bnd --> SC

    %% Optional LBA between GE and DEM
    SC --> LBA_Script
    LBA_Script -.-> DP

    %% DEM Processor
    subgraph "DEM Processor"
        LB["LocalBA"]:::processing
        LB1["lba_photoscan_run"]:::processing
        LB2["lba_photoscan_run2"]:::processing
        LB3["lba_photoscan_run3"]:::processing
    end
    SC --> LB --> LB1 --> LB2 --> LB3

    %% Orthophoto Generator
    subgraph "Orthophoto Generator"
        Rect["BackprojectionResample"]:::processing
        Res["Pixel Resampling"]:::processing
    end
    LB3 --> Rect --> Res

    %% Output Writer
    OW["Output Writer<br/>GeoTIFF Export"]:::script
    Res --> OW
    RGB --> OW
    TH --> OW
    LBA_Script --> OW

    %% Testing Suite
    TS["Testing Suite<br/>(tests/)"]:::testing
    TS --> DI
    TS --> Eo
    TS --> LB
    TS --> Rect

    %% Click Events
    click CM "https://github.com/hwiyoung/orthophoto_maps/blob/master/environment.yaml"
    click EP "https://github.com/hwiyoung/orthophoto_maps/blob/master/main_dg.py"
    click RGB "https://github.com/hwiyoung/orthophoto_maps/blob/master/Orthophoto.py"
    click TH "https://github.com/hwiyoung/orthophoto_maps/blob/master/OrthophotoThermal.py"
    click LBA_Script "https://github.com/hwiyoung/orthophoto_maps/blob/master/Orthophoto_LBA.py"
    click DI "https://github.com/hwiyoung/orthophoto_maps/blob/master/module/ExifData.py"
    click Eo "https://github.com/hwiyoung/orthophoto_maps/blob/master/module/EoData.py"
    click Bnd "https://github.com/hwiyoung/orthophoto_maps/blob/master/module/Boundary.py"
    click SC "https://github.com/hwiyoung/orthophoto_maps/blob/master/module/system_calibration.py"
    click LB "https://github.com/hwiyoung/orthophoto_maps/blob/master/module/LocalBA.py"
    click LB1 "https://github.com/hwiyoung/orthophoto_maps/blob/master/module/lba_photoscan_run.py"
    click LB2 "https://github.com/hwiyoung/orthophoto_maps/blob/master/module/lba_photoscan_run2.py"
    click LB3 "https://github.com/hwiyoung/orthophoto_maps/blob/master/module/lba_photoscan_run3.py"
    click Rect "https://github.com/hwiyoung/orthophoto_maps/blob/master/module/BackprojectionResample.py"
    click TS "https://github.com/hwiyoung/orthophoto_maps/tree/master/tests/"

    %% Styles
    classDef script fill:#daeaff,stroke:#333,stroke-width:1px
    classDef processing fill:#d0eaff,stroke:#333,stroke-width:1px
    classDef data fill:#e0ffe0,stroke:#333,stroke-width:1px
    classDef tool fill:#ffebcc,stroke:#333,stroke-width:1px,shape:parallelogram
    classDef testing fill:#f0f0f0,stroke:#999,stroke-width:1px
    classDef optional stroke-dasharray: 5 5;color:#55593b,fill:#fdfde2,stroke-width:1px
```
