# riccardocadei/photovoltaic-detection architecture

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

- Interactive diagram: https://gitdiagram.com/riccardocadei/photovoltaic-detection
- Repository: https://github.com/riccardocadei/photovoltaic-detection

## Overview

##### Project type and purpose
- This is a data-centric machine-learning pipeline focused on binary semantic segmentation of aerial images (250×250×3) to detect rooftop areas suitable for PV installations.
- Key stages: data ingestion & labeling → preprocessing & augmentation → U-Net training → evaluation & visualization → inference/deployment.

##### File structure
Top-level components:
- labelling_tool: scripts and notebooks to crop, scan, label, verify, and move raw images and generate binary masks.
- process_data: data_loader, normalize, import_test – handle image normalization, train/val/test splits, and dataset abstractions.
- train: train.py orchestrates the training loop over the U-Net model.
- model: unet.py defines the network architecture.
- loss: loss.py and loss.ipynb compute custom losses and metrics (IoU, accuracy).
- plots: plots.py and subdirectories containing training history arrays and generated figures.
- run.py & main.ipynb: high-level scripts to glue together preprocess → train → plot → evaluate.
- documents & reference: static artifacts (reports, papers) – these are outside the core runtime pipeline but should be shown as documentation inputs.

##### README for additional insights
- Data format: PNG, RGB, pixel-wise binary masks.
- Training details: real-time augmentation, thresholding, 80/10/10 split.
- Technologies: Python 3.6, NumPy, PyTorch, scikit-learn, OpenCV, Matplotlib.
- External resources: Pre-trained models and data hosted on Google Drive.

1. Raw Data Store (folder of PNG images + blank masks)
2. Labelling Tool (scripts/notebooks – crop.py, label_images.py, etc.)
3. Preprocessing Pipeline (process_data module)
4. Model Definition (U-Net in model/unet.py)
5. Training Engine (train/train.py + run.py)
6. Loss & Metric Calculator (loss/loss.py, IoU, accuracy)
7. Visualization & Reporting (plots/plots.py, main.ipynb)
8. Output Artifacts (trained model checkpoints, plots, evaluation reports)
9. Documentation (documents folder + reference papers)

- Raw Data Store → Labelling Tool
- Labelling Tool → Labeled Dataset
- Labeled Dataset → Preprocessing Pipeline
- Preprocessing Pipeline → DataLoader (PyTorch)
- DataLoader → Training Engine
- Training Engine ↔ Model Definition (builds & updates weights)
- Training Engine → Loss & Metrics → Feedback loop (optimizer)
- After each epoch: Training Engine → Visualization (plots module)
- Final model → Output Artifacts → Optional Deployment/In-ference script
- Documentation & Reference sit aside, feeding context but not in the runtime flow

c. Architectural patterns & principles:
- Pipeline pattern (stages chained: labeling → preprocessing → training → evaluation)
- Modular separation: tooling (labelling), data processing, model, training, loss, visualization
- Configurability: hyperparameters folder / select_param.py controls learning rates, batch sizes
- Reproducibility: notebooks and run.py tie everything together

d. Key technologies & libraries:
- Data I/O: OpenCV, NumPy
- ML Framework: PyTorch (torch.utils.data.DataLoader, model/unet.py)
- Metrics: custom IoU, accuracy code in loss.py
- Visualization: Matplotlib (plots/plots.py, notebooks)
- Scripting & orchestration: Python scripts (run.py, train/train.py), Jupyter notebooks

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Stores
    RawData("Raw Data Store"):::data
    LabeledData("Labeled Dataset"):::data
    Checkpoints("Model Checkpoints"):::data
    OutputArtifacts("Output Artifacts"):::data

    %% External
    subgraph "External Resources" 
        GDrive("Google Drive"):::external
    end

    %% Data Preparation
    subgraph "Data Preparation"
        direction TB
        LabellingTool["Labelling Tool"]:::code
        subgraph "labelling_tool"
            direction TB
            Crop["crop.py"]:::code
            LabelImages["label_images.py"]:::code
            LabelTXT["label_images_from_txt.py"]:::code
            Scan["scan_images.py"]:::code
            Move["move.py"]:::code
            Verify["data-verification.ipynb"]:::notebook
        end
        Preprocessing["Preprocessing Pipeline"]:::code
        subgraph "process_data"
            direction TB
            Loader["data_loader.py"]:::code
            Normalize["normalize.py"]:::code
            ImportTest["import_test.py"]:::code
            SplitNB["spliter.ipynb"]:::notebook
            IndustrialNB["industrial.ipynb"]:::notebook
        end
    end

    %% Model Training
    subgraph "Model Training"
        direction TB
        ModelDef["Model Definition (U-Net)"]:::code
        subgraph "model"
            direction TB
            Unet["unet.py"]:::code
            ModelNB["model.ipynb"]:::notebook
        end
        TrainEngine["Training Engine"]:::code
        subgraph "train"
            direction TB
            TrainScript["train.py"]:::code
        end
        RunScript["run.py"]:::code
        HyperParam["Hyperparameter Selector"]:::code
    end

    %% Loss & Metrics
    LossMetrics["Loss & Metric Calculator"]:::code
    subgraph "loss"
        direction TB
        LossPy["loss.py"]:::code
        LossNB["loss.ipynb"]:::notebook
    end

    %% Evaluation & Reporting
    subgraph "Evaluation & Reporting"
        direction TB
        Visualization["Visualization & Reporting"]:::code
        subgraph "plots"
            direction TB
            PlotsPy["plots.py"]:::code
            AllDir["all/…"]:::data
            OtherDir["other/…"]:::data
            ResidDir["residencial/…"]:::data
        end
        MainNB["main.ipynb"]:::notebook
        Documents["Documentation & Reference"]:::external
        subgraph "documents/reference"
            direction TB
            DocsDir["documents/"]:::external
            RefDir["reference/"]:::external
        end
    end

    %% Flow
    RawData -->|input| LabellingTool
    LabellingTool -->|generate masks| LabeledData
    LabeledData -->|feeds| Preprocessing
    Preprocessing -->|produce tensors| Loader
    Loader -->|batch data| TrainEngine
    TrainEngine -->|"uses"| ModelDef
    ModelDef -->|definition| TrainEngine
    TrainEngine -->|"optimize"| LossMetrics
    LossMetrics -->|feedback| TrainEngine
    TrainEngine -->|save| Checkpoints
    TrainEngine -->|after epoch| Visualization
    Visualization -->|plots| OutputArtifacts

    GDrive -.->|download models/data| RunScript

    %% Click events
    click Crop "https://github.com/riccardocadei/photovoltaic-detection/blob/main/labelling_tool/crop.py"
    click LabelImages "https://github.com/riccardocadei/photovoltaic-detection/blob/main/labelling_tool/label_images.py"
    click LabelTXT "https://github.com/riccardocadei/photovoltaic-detection/blob/main/labelling_tool/label_images_from_txt.py"
    click Scan "https://github.com/riccardocadei/photovoltaic-detection/blob/main/labelling_tool/scan_images.py"
    click Move "https://github.com/riccardocadei/photovoltaic-detection/blob/main/labelling_tool/move.py"
    click Verify "https://github.com/riccardocadei/photovoltaic-detection/blob/main/labelling_tool/data-verification.ipynb"
    click Loader "https://github.com/riccardocadei/photovoltaic-detection/blob/main/process_data/data_loader.py"
    click Normalize "https://github.com/riccardocadei/photovoltaic-detection/blob/main/process_data/normalize.py"
    click ImportTest "https://github.com/riccardocadei/photovoltaic-detection/blob/main/process_data/import_test.py"
    click SplitNB "https://github.com/riccardocadei/photovoltaic-detection/blob/main/process_data/spliter.ipynb"
    click IndustrialNB "https://github.com/riccardocadei/photovoltaic-detection/blob/main/process_data/industrial.ipynb"
    click Unet "https://github.com/riccardocadei/photovoltaic-detection/blob/main/model/unet.py"
    click ModelNB "https://github.com/riccardocadei/photovoltaic-detection/blob/main/model/model.ipynb"
    click TrainScript "https://github.com/riccardocadei/photovoltaic-detection/blob/main/train/train.py"
    click RunScript "https://github.com/riccardocadei/photovoltaic-detection/blob/main/run.py"
    click LossPy "https://github.com/riccardocadei/photovoltaic-detection/blob/main/loss/loss.py"
    click LossNB "https://github.com/riccardocadei/photovoltaic-detection/blob/main/loss/loss.ipynb"
    click PlotsPy "https://github.com/riccardocadei/photovoltaic-detection/blob/main/plots/plots.py"
    click MainNB "https://github.com/riccardocadei/photovoltaic-detection/blob/main/main.ipynb"
    click AllDir "https://github.com/riccardocadei/photovoltaic-detection/tree/main/plots/all/"
    click OtherDir "https://github.com/riccardocadei/photovoltaic-detection/tree/main/plots/other/"
    click ResidDir "https://github.com/riccardocadei/photovoltaic-detection/tree/main/plots/residencial/"
    click HyperParam "https://github.com/riccardocadei/photovoltaic-detection/blob/main/hyperparameters/select_param.py"
    click DocsDir "https://github.com/riccardocadei/photovoltaic-detection/tree/main/documents/"
    click RefDir "https://github.com/riccardocadei/photovoltaic-detection/tree/main/reference/"

    %% Styles
    classDef code fill:#D0E8FF,stroke:#76A5AF,stroke-width:1px;
    classDef data fill:#DFF2BF,stroke:#4F8A10,stroke-width:1px,shape:cylinder;
    classDef notebook fill:#FFF2CC,stroke:#B8860B,stroke-width:1px;
    classDef external fill:#E0E0E0,stroke:#888888,stroke-dasharray: 5 5;
```
