# kimzed/hiatus_change_detection architecture

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

- Interactive diagram: https://gitdiagram.com/kimzed/hiatus_change_detection
- Repository: https://github.com/kimzed/hiatus_change_detection

## Overview

##### Project Type and Purpose
- This is a research/experimental machine learning project implemented in PyTorch.
- Its goal is to detect landscape changes over time in 3D data through unsupervised domain adaptation.
- The README explains that the code deals with dataset loading, pre-processing raw rasters, training models, and evaluating performance using various visualization techniques as well as ground truth comparisons.

##### Analysis of the File Structure
- Top-level scripts like main.py, train.py, and evaluation scripts (evaluate.py, model_evaluation.py) indicate the presence of distinct phases (data preparation, training, evaluation).
- The presence of frejus_dataset.py and pre_processing.py clearly defines the data ingestion and transformation layer.
- Files such as model.py, loss.py, metrics.py, and utils.py encapsulate the machine learning logic – from model architecture to loss computation and auxiliary functions.
- The evaluation_models directory contains subdirectories (e.g., AE_Mmodal and AE_Mmodal+DAN+split) which presumably host pre-trained or alternative model architectures to be loaded and compared during evaluation.

##### Main Components of the System
a. Data Layer:
- Dataset Loader: Represented by frejus_dataset.py which loads the Fréjus dataset.
- Pre-processing: Captured by pre_processing.py to prepare raw rasters.
- Ground Truth Preparation: Provided by ground_truth.py to specify expected outcomes.
b. Model Building and Training:
- Model Definition: model.py holds the network architecture(s).
- Training Loop: train.py and main.py (as the main driver) combine to orchestrate training processes using parameters like epoch count and learning rate.
- Loss and Metrics: loss.py and metrics.py define the optimization objective and performance measures.
- Utility Functions: utils.py is used for various shared helper tasks.
c. Evaluation and Analysis:
- Model Evaluation: model_evaluation.py and evaluate.py drive the testing and visualization routines.
- Evaluation Models: The evaluation_models directory holds different architectural variations available for comparison.
- Visualization and Performance Assessment: Explained in the README as part of the output for exploration and study.

##### Relationships and Interactions
- Data flows from the raw dataset through frejus_dataset.py and pre_processing.py to produce the input for model training.
- Training scripts (main.py, train.py) consume processed data, call model.py to build the network architecture, use loss and metrics (loss.py and metrics.py) for learning signal, and may use utils.py for support.
- The main script serves as a command-line entry point, with additional configuration (e.g., command-line arguments like epochs, learning rate) that modulate overall behavior.

##### Architectural Patterns/Design Principles
- Modular Separation: Each phase (data ingestion, processing, training, evaluation) has its own dedicated module/script.
- Configurability: The use of main.py with command-line flags shows an emphasis on configurable execution.
- Extensibility: Storing various models in evaluation_models and having separate components (training versus evaluation) allows easy experimentation with different architectures or change detection algorithms.
- Dependency on External Libraries: The README highlights that the project requires a specific conda environment including geospatial packages and PyTorch.

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Dependency
    CE["Conda Environment (Geo & PyTorch)"]:::external

    %% Data Layer
    subgraph "Data Layer"
        DL["Data Loader"]:::dataLayer
        PP["Pre-processor"]:::dataLayer
        GT["Ground Truth Generator"]:::dataLayer
    end

    %% Training Module
    subgraph "Training Module"
        MD["Model Definition"]:::training
        MDL["Main Driver"]:::training
        TL["Training Loop"]:::training
        LC["Loss Computation"]:::training
        MC["Metrics Calculation"]:::training
        AU["Auxiliary Utilities"]:::utility
    end

    %% Evaluation Module
    subgraph "Evaluation Module"
        EV1["Evaluation & Visualization"]:::evaluation
        EV2["Model Evaluation"]:::evaluation
        
        %% Evaluation Models subgraph inside Evaluation Module
        subgraph "Evaluation Models"
            EMDir["Evaluation Models"]:::evaluation
            M1["AE_Mmodal"]:::evaluation
            M2["AE_Mmodal+DAN+split"]:::evaluation
        end
    end

    %% Data Flow Connections for Data Layer to Training Module
    DL -->|"processes"| PP
    PP -->|"sends data"| MDL

    %% Connection from Training Module components
    MDL -->|"initiates"| TL
    MD -->|"provides architecture"| TL
    TL -->|"computes loss"| LC
    TL -->|"calculates"| MC
    TL -->|"utilizes"| AU

    %% Connection from Ground Truth and Training to Evaluation Module
    GT -->|"supplies ground_truth"| EV1
    TL -->|"triggers evaluation"| EV1

    %% Flow within Evaluation Module
    EV1 -->|"detailed evaluation"| EV2
    EV1 -->|"loads"| EMDir
    EMDir -->|"offers models"| EV2
    EMDir --> M1
    EMDir --> M2

    %% External Dependency connections
    CE --- DL
    CE --- MDL
    CE --- EV1

    %% Click Events
    click DL "https://github.com/kimzed/hiatus_change_detection/blob/master/frejus_dataset.py"
    click PP "https://github.com/kimzed/hiatus_change_detection/blob/master/pre_processing.py"
    click GT "https://github.com/kimzed/hiatus_change_detection/blob/master/ground_truth.py"
    click MD "https://github.com/kimzed/hiatus_change_detection/blob/master/model.py"
    click MDL "https://github.com/kimzed/hiatus_change_detection/blob/master/main.py"
    click TL "https://github.com/kimzed/hiatus_change_detection/blob/master/train.py"
    click LC "https://github.com/kimzed/hiatus_change_detection/blob/master/loss.py"
    click MC "https://github.com/kimzed/hiatus_change_detection/blob/master/metrics.py"
    click AU "https://github.com/kimzed/hiatus_change_detection/blob/master/utils.py"
    click EV1 "https://github.com/kimzed/hiatus_change_detection/blob/master/evaluate.py"
    click EV2 "https://github.com/kimzed/hiatus_change_detection/blob/master/model_evaluation.py"
    click EMDir "https://github.com/kimzed/hiatus_change_detection/tree/master/evaluation_models"
    click M1 "https://github.com/kimzed/hiatus_change_detection/tree/master/evaluation_models/AE_Mmodal"
    click M2 "https://github.com/kimzed/hiatus_change_detection/tree/master/evaluation_models/AE_Mmodal+DAN+split"

    %% Styles
    classDef dataLayer fill:#9fcae3,stroke:#0277bd,stroke-width:2px;
    classDef training fill:#a8d08d,stroke:#388e3c,stroke-width:2px;
    classDef evaluation fill:#f4b183,stroke:#f57c00,stroke-width:2px;
    classDef utility fill:#e0e0e0,stroke:#9e9e9e,stroke-width:2px;
    classDef external fill:#fff176,stroke:#fbc02d,stroke-width:2px;
```
