# sar-rice/xm-unet architecture

> Architecture diagram of the GitHub repository sar-rice/xm-unet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sar-rice/xm-unet
- Repository: https://github.com/sar-rice/xm-unet

## Overview

##### Project type and purpose
- This is a research‐oriented, explainable deep‐learning pipeline (XM-UNet) for segmenting rice fields from SAR (tif) images.
- It provides scripts to prepare datasets, train a lightweight UNet variant, and run inference on full SAR images.

##### File structure
Top-level components:
- Data/             ← raw SAR tifs and example test files
- configs/          ← configuration definitions (config_setting.py)
- dataprepare/      ← dataset‐splitting script (Prepare_your_dataset.py)
- engine.py         ← training/testing engine (training loop, metrics, logging)
- loader.py         ← PyTorch Dataset and DataLoader wrappers
- models/           ← model definitions (XM_UNet, XAI explainability module, sandglass, vmamba)
- train.py          ← entry point for model training
- predict.py        ← entry point for inference on large SAR datasets
- utils.py          ← helper functions (e.g., image I/O, visualization)
- figures/          ← model architecture illustration
- README.md         ← project overview and usage instructions

##### Key insights from README
- The pipeline runs under Python 3.8 + PyTorch 1.13 + GDAL + multiple ML libraries.
- You prepare a dataset folder (images/masks), split via Prepare_your_dataset.py, then train with train.py, then predict with predict.py.
- Outputs (trained checkpoints, prediction tifs/pngs) land in ./results/.

##### Main components
A. Data Ingestion & Storage
- Raw SAR imagery (Data/Kenya/*.tif, Data/Test/*.tif)
- Ground-truth masks (png) in user dataset folder

B. Data Preparation
- dataprepare/Prepare_your_dataset.py
- Splits into train/val/test sets, organizes into images/ and masks/ subfolders

C. Configuration Layer
- configs/config_setting.py
- Defines hyperparameters, file paths, training/testing flags

D. Data Loader
- loader.py
- Implements PyTorch Dataset + DataLoader abstractions

E. Model Definitions
- models/XM_UNet.py ← core UNet variant (0.19M params)
- models/XAI.py ← explainability modules
- models/sandglass.py, vmamba.py ← auxiliary architectures

F. Engine (Training & Evaluation)
- engine.py
- Contains training loop, loss computation, metric logging, checkpointing

G. Utilities
- utils.py
- I/O helpers (GDAL wrappers), image preprocessing, metric calculations

H. Entry Points
- train.py ← calls config → loader → engine → models → results
- predict.py ← loads checkpoint → large‐image tiling → sliding inference → save tifs

I. External Dependencies & Environment
- Python 3.8, PyTorch, GDAL, timm, mamba_ssm, CUDA backend

##### Relationships & Data Flow
1. Raw Data → Data Preparation → Split datasets
2. Configs + Prepared Data → Data Loader → batched tensors
3. Loader feeds Engine → uses Model definitions → training → checkpoints
4. Trained model + Loader → Predict pipeline → large‐image inference → result images
5. Utils used throughout for I/O and postprocessing

##### Architectural patterns & design principles
- Modular separation: data prep, config, loader, model, engine, utils
- Single responsibility per module
- Pipeline pattern: staged data → train → infer
- Experiment reproducibility via config files and fixed directory conventions

##### Details
- Interconnection of config_setting.py to both train.py and predict.py.
- That Prepare_your_dataset.py writes its splits into a folder structure consumed by loader.py.
- That engine.py writes checkpoints and metrics under ./results/.
- External Python environment block to remind that all modules execute within the same conda env.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Preparation"
        raw1[/"Kenya_Rice_2022.tif"/]:::storage
        raw2[/"example.tif"/]:::storage
        raw3[/"testdata.tif"/]:::storage
        prep["Prepare_your_dataset.py: split datasets"]:::code
        config["config_setting.py: hyperparameters"]:::code
        raw1 --> prep
        raw2 --> prep
        raw3 --> prep
        prep --> preparedData["Prepared Data"]:::storage
    end

    subgraph "Training Pipeline"
        config --> loader["loader.py: PyTorch Dataset/DataLoader"]:::code
        loader --> engine["engine.py: training loop"]:::code
        subgraph "Model Definitions"
            unet["XM_UNet.py: core model"]:::code
            xai["XAI.py: explainability module"]:::code
            sg["sandglass.py: auxiliary"]:::code
            vm["vmamba.py: auxiliary"]:::code
            unet --- xai
            unet --- sg
            unet --- vm
        end
        engine --> unet
        engine --> utils["utils.py: helpers"]:::code
        engine --> results["results/ checkpoints & metrics"]:::storage
    end

    subgraph "Inference Pipeline"
        predict["predict.py: inference"]:::entry
        predict --> loader
        loader --> unet
        loader --> utils
        predict --> inferenceOut["Result TIFFs/PNGs"]:::storage
        config --> predict
    end

    train["train.py: training entry"]:::entry
    train --> config
    train --> loader
    train --> engine

    external["Python 3.8 + PyTorch + GDAL + GPU"]:::external
    external --> config
    external --> prep
    external --> loader
    external --> engine
    external --> predict

    readme["README.md"]:::doc
    figures["figures/"]:::doc

    click prep "https://github.com/sar-rice/xm-unet/blob/main/dataprepare/Prepare_your_dataset.py"
    click config "https://github.com/sar-rice/xm-unet/blob/main/configs/config_setting.py"
    click loader "https://github.com/sar-rice/xm-unet/blob/main/loader.py"
    click unet "https://github.com/sar-rice/xm-unet/blob/main/models/XM_UNet.py"
    click xai "https://github.com/sar-rice/xm-unet/blob/main/models/XAI.py"
    click sg "https://github.com/sar-rice/xm-unet/blob/main/models/sandglass.py"
    click vm "https://github.com/sar-rice/xm-unet/blob/main/models/vmamba.py"
    click engine "https://github.com/sar-rice/xm-unet/blob/main/engine.py"
    click utils "https://github.com/sar-rice/xm-unet/blob/main/utils.py"
    click train "https://github.com/sar-rice/xm-unet/blob/main/train.py"
    click predict "https://github.com/sar-rice/xm-unet/blob/main/predict.py"
    click readme "https://github.com/sar-rice/xm-unet/blob/main/README.md"
    click figures "https://github.com/sar-rice/xm-unet/tree/main/figures/"

    classDef storage fill:#ADD8E6,stroke:#000
    classDef code fill:#90EE90,stroke:#000
    classDef entry fill:#FFA500,stroke:#000
    classDef external fill:#D3D3D3,stroke:#000
    classDef doc fill:#FFFFE0,stroke:#000
```
