How sar-rice/xm-unet works
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.