# ioannispol/underwateru-net architecture

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

- Interactive diagram: https://gitdiagram.com/ioannispol/underwateru-net
- Repository: https://github.com/ioannispol/underwateru-net

## Overview

##### Project Type and Purpose
- This is a specialized deep learning project focused on underwater image segmentation using an adapted U-Net model that includes attention mechanisms.
- The README emphasizes its use for accurate segmentation of underwater images by addressing challenges such as lighting inconsistencies and suspended particles.

##### Analyzing the File Structure
- • Underwater Neural Network Modules: The folder “underwater_unet” contains the core model components (e.g., model.py and unet_blocks.py) where the tailored U-Net architecture is implemented.
- • Utility Functions: The “utils” directory includes a variety of helper modules for loading data, computing dice scores (a common segmentation metric), image conversion, renaming, and visualizing the network. These bolster the segmentation pipeline and post-/pre-processing.
- • Training and Inference Scripts: Files like train.py and prediction.py indicate dedicated entry points for training the network model and making predictions.
- • Web Application: The file webapp.py suggests an interface or API for interacting with the model, possibly exposing image segmentation as a service.
- • Data Handling: The “scripts” directory holds scripts for downloading data (download_data.sh), handling updates (git_update.sh), and contains a dataset archive (dataset.zip). This ensures reproducibility and easy setup.
- • Testing: A “tests” directory indicates robust unit tests across model components and utility functions.
- • Environment & Dev Tools: The presence of Dockerfile, .devcontainer, GitHub workflows, and configuration files (setup.cfg, setup.py, pre-commit, etc.) shows a commitment to consistent development and deployment practices.
- • Notebooks: The “notebooks” folder provides example usage and exploratory experiments, contributing to documentation and reproducibility.

##### Main Components
a. Data Input & Preprocessing:
- Scripts for downloading data and data-related utilities from the “scripts” and “utils” directories.
- Preprocessing pipelines that prepare underwater images for segmentation.
b. Core Model Architecture:
- “underwater_unet” module representing the tailored U-Net with attention gates. Show components like the attention gate module (which processes inputs g and x using convolutions, ReLU, and sigmoid activations).
c. Training Pipeline:
- The “train.py” script that launches the training process, tapping into data preprocessing, model definition, and evaluation.
d. Inference & Prediction:
- “prediction.py” and possibly “webapp.py”, which are used to deploy the model for segmentation tasks.
- The web application (webapp.py) for user interaction with the developed deep learning model.
e. Utilities and Visualization:
- “utils” components for visualization (network_visualisation and network_vizualisation_matplotlib) and evaluation metrics (dice_score).
f. Testing and Validation:
- The “tests” folder to ensure the integrity of the data loading, model functionality, and utility operations.
g. Environment & Deployment:
- Docker container setup (.devcontainer and Dockerfile) and continuous integration (GitHub workflows), ensuring environment consistency and smooth deployments.

##### Architectural Patterns & Design Principles
- Modularity: The project is modular (separation between core model, utilities, training, and web deployment) which can be visually depicted as isolated but interacting modules.
- Pipeline Flow: Show a clear data flow from raw image input, processing, segmentation (model & attention), and output segmentation masks.
- Environment Consistency: Indicate usage of containerization for reproducibility.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data & Preprocessing Layer"
        A1["Data Download (download_data.sh)"]
        A2["Data Update (git_update.sh)"]
        A3["Data Utilities (data_load + others)"]
        A4["Visualization & Metrics (utils)"]
    end

    subgraph "Core Model & Training Layer"
        B2["Training Pipeline (train.py)"]
        B1["U-Net Model (model.py)"]
        B1b["U-Net Blocks (unet_blocks.py)"]
    end

    subgraph "Inference & Deployment Layer"
        C1["Prediction Service (prediction.py)"]
        C2["Web Application Interface (webapp.py)"]
    end

    subgraph "Supporting Infrastructure"
        D1["Testing Suite (tests)"]
        D2["Env & CI/CD (Docker, DevContainers, CI configs)"]
    end

    %% Data & Preprocessing to Training
    A1 --> B2
    A2 --> B2
    A3 --> B2
    A4 --> B2

    %% Training Pipeline to Core Model components
    B2 --> B1
    B2 --> B1b

    %% Core Model components to Inference & Deployment
    B1 --> C1
    B1 --> C2
    B1b --> C1
    B1b --> C2

    %% Supporting Infrastructure connections (dotted lines)
    D1 -.-> A3
    D1 -.-> B1
    D1 -.-> B2
    D2 -.-> B2
    D2 -.-> C2

    %% Click Events
    click A1 "https://github.com/ioannispol/underwateru-net/blob/main/scripts/download_data.sh"
    click A2 "https://github.com/ioannispol/underwateru-net/blob/main/scripts/git_update.sh"
    click A3 "https://github.com/ioannispol/underwateru-net/blob/main/utils/data_load.py"
    click A4 "https://github.com/ioannispol/underwateru-net/blob/main/utils/network_visualisation.py"
    click B1 "https://github.com/ioannispol/underwateru-net/blob/main/underwater_unet/model.py"
    click B1b "https://github.com/ioannispol/underwateru-net/blob/main/underwater_unet/unet_blocks.py"
    click B2 "https://github.com/ioannispol/underwateru-net/blob/main/train.py"
    click C1 "https://github.com/ioannispol/underwateru-net/blob/main/prediction.py"
    click C2 "https://github.com/ioannispol/underwateru-net/blob/main/webapp.py"
    click D1 "https://github.com/ioannispol/underwateru-net/tree/main/tests/"
    click D2 "https://github.com/ioannispol/underwateru-net/tree/main/Dockerfile"

    %% Styles
    classDef dataColor fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef modelColor fill:#ABEBC6,stroke:#229954,stroke-width:2px;
    classDef inferenceColor fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef infraColor fill:#FADBD8,stroke:#C0392B,stroke-width:2px;

    class A1,A2,A3,A4 dataColor;
    class B1,B1b,B2 modelColor;
    class C1,C2 inferenceColor;
    class D1,D2 infraColor;
```
