🌊 Flood Detection System

Deep learning-based flood detection using Sentinel-1 SAR and Sentinel-2 optical satellite data

Leveraging Vision Transformer ensemble models with uncertainty quantification for reliable flood inundation mapping

Features • Installation • Quick Start • Documentation • Models • Citation

---

📋 Table of Contents

• Overview
• Features
• Installation
• Quick Start
• Project Structure
• Usage
  • Training Models
  • Web Application
  • Programmatic Inference
• Model Architecture
• Performance
• Configuration
• Data Sources
• Troubleshooting
• Contributing
• Citation
• License
• Acknowledgments

---

🌍 Overview

This project implements a state-of-the-art flood detection system using deep learning on satellite imagery. By combining Sentinel-1 SAR (all-weather) and Sentinel-2 optical data, the system can accurately map flood inundation even through cloud cover. The ensemble approach with uncertainty quantification makes predictions more reliable for disaster response applications.

Why This Matters

• Rapid Response: Automated flood mapping within hours of imagery availability
• All-Weather Monitoring: SAR data penetrates clouds, unlike optical-only systems
• High Accuracy: Ensemble models achieve >72% IoU on benchmark datasets
• Uncertainty Awareness: Know when predictions are reliable
• Easy Deployment: User-friendly web interface and Python API

---

✨ Features

Feature	Description
🤖 Multi-Model Ensemble	Combines ResNet-50 UNet, Swin Transformer, and MaxViT architectures for robust predictions
🛰️ Multi-Sensor Fusion	Leverages both Sentinel-1 SAR and Sentinel-2 optical data for comprehensive analysis
📊 Uncertainty Quantification	Provides confidence estimates with Monte Carlo Dropout and ensemble variance
🌐 GEE Integration	Automated data fetching from Google Earth Engine for any location and time
🎨 Interactive Web App	Streamlit-based interface with real-time visualization and download capabilities
⚡ State-of-the-Art Performance	Achieves IoU > 0.72 on Sen1Floods11 benchmark dataset
🔧 Modular Architecture	Clean, extensible codebase with comprehensive documentation
📈 Training Pipeline	Complete training workflow with monitoring, checkpointing, and early stopping

---

🚀 Installation

Prerequisites

Before you begin, ensure you have:

• Python 3.9 or higher (Download Python)
• Google Earth Engine account (free) - Sign up here
• CUDA-capable GPU (recommended for training, optional for inference)
• Git (Download Git)

Setup Instructions

1. Clone the repository

git clone https://github.com/yourusername/flood-detection.git
cd flood-detection

2. Create a virtual environment (recommended)

# Using venv
python -m venv venv

# Activate on Windows
venv\Scripts\activate

# Activate on Linux/Mac
source venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Authenticate Google Earth Engine

earthengine authenticate

Follow the browser prompts to authorize your account.

5. Download the Sen1Floods11 dataset (for training)

python download_sen1floods11_colab.ipynb
# Or manually download from: https://github.com/cloudtostreet/Sen1Floods11
# Place data in: data/raw/S1/, data/raw/S2/, and data/raw/labels/

---

⚡ Quick Start

Option 1: Use the Web Application

Launch the interactive Streamlit app:

streamlit run app/streamlit_app.py

Then:

1. Open your browser to http://localhost:8501
2. Choose between uploading files or using Google Earth Engine
3. View flood predictions with uncertainty maps
4. Download results as GeoTIFF or PNG

Option 2: Python API

from src.inference.predict import FloodPredictor

# Initialize predictor with trained models
predictor = FloodPredictor([
    "models/resnet_best.pt",
    "models/swin_best.pt",
    "models/maxvit_best.pt"
])

# Predict flood extent
prediction, probabilities = predictor.predict_from_tif(
    s1_path="data/raw/S1/flood_image.tif",
    s2_path="data/raw/S2/flood_image.tif"
)

# Access uncertainty metrics
uncertainty = predictor.get_uncertainty(probabilities)

Option 3: Command Line Training

# Train a single model
python src/training/train.py --model resnet --epochs 50 --batch-size 16

# Train all models in ensemble
python ROBUST_RETRAIN_COLAB.py

---

📁 Project Structure

flood-detection/
│
├── 📂 app/                          # Web application
│   ├── streamlit_app.py             # Main Streamlit interface
│   ├── streamlit_app_simple.py      # Simplified version
│   ├── utils.py                     # UI utilities
│   └── assets/                      # Static files (images, styles)
│
├── 📂 src/                          # Source code
│   ├── data/                        # Data processing
│   │   ├── dataset.py               # PyTorch Dataset classes
│   │   ├── preprocessing.py         # Data preprocessing utilities
│   │   └── gee_downloader.py        # Google Earth Engine integration
│   │
│   ├── models/                      # Model architectures
│   │   ├── resnet_unet.py           # ResNet-50 UNet
│   │   ├── swin_transformer.py      # Swin Transformer
│   │   ├── max_vit.py               # MaxViT
│   │   └── ensemble.py              # Ensemble wrapper
│   │
│   ├── training/                    # Training pipeline
│   │   ├── train.py                 # Main training script
│   │   ├── losses.py                # Loss functions
│   │   └── metrics.py               # Evaluation metrics
│   │
│   └── inference/                   # Inference pipeline
│       ├── predict.py               # Prediction wrapper
│       └── uncertainty.py           # Uncertainty quantification
│
├── 📂 data/                         # Data directories
│   ├── raw/                         # Raw satellite images
│   │   ├── S1/                      # Sentinel-1 SAR images (.tif)
│   │   ├── S2/                      # Sentinel-2 optical images (.tif)
│   │   └── labels/                  # Ground truth flood masks (.tif)
│   ├── processed/                   # Preprocessed/normalized data
│   └── splits/                      # Train/val/test split indices
│
├── 📂 models/                       # Trained model weights
│   └── resnet_best.pt               # Best performing model
│
├── 📂 configs/                      # Configuration files
│   └── config.yaml                  # Hyperparameters and settings
│
├── 📂 notebooks/                    # Jupyter notebooks
│   └── *.ipynb                      # Exploration and analysis
│
├── 📄 requirements.txt              # Python dependencies
├── 📄 setup.py                      # Package setup
├── 📄 README.md                     # This file
├── 📄 QUICK_START.md                # Quick start guide
├── 📄 TESTING_GUIDE.md              # Testing documentation
└── 📄 PROJECT_SUMMARY.md            # Detailed project summary

---

📖 Usage

Training Models

Train Individual Models

# Train ResNet-50 UNet
python src/training/train.py --model resnet \
    --epochs 50 \
    --batch-size 16 \
    --learning-rate 0.001 \
    --device cuda

# Train Swin Transformer
python src/training/train.py --model swin \
    --epochs 50 \
    --batch-size 8 \
    --learning-rate 0.0005

# Train MaxViT
python src/training/train.py --model maxvit \
    --epochs 50 \
    --batch-size 8 \
    --learning-rate 0.0005

Train Full Ensemble

# Robust training with all models
python ROBUST_RETRAIN_COLAB.py

# Or use the Colab notebook for cloud training
# Open: train_flood_detection_colab.ipynb

Training Configuration

Edit configs/config.yaml to customize:

training:
  batch_size: 16
  learning_rate: 0.001
  epochs: 50
  optimizer: "AdamW"
  scheduler: "CosineAnnealingLR"
  
data:
  image_size: 512
  augmentation: true
  normalize: true
  
models:
  ensemble_weights: [0.4, 0.3, 0.3]  # ResNet, Swin, MaxViT

Web Application

The Streamlit web app provides two modes:

Mode 1: Upload Files

1. Upload Sentinel-1 GeoTIFF (.tif)
2. Upload Sentinel-2 GeoTIFF (.tif)
3. Click "Detect Flood"
4. View results and download

Mode 2: Google Earth Engine

1. Enter coordinates (lat/lon) or draw on map
2. Select date range
3. System automatically downloads imagery
4. Get instant flood predictions

# Launch the app
streamlit run app/streamlit_app.py

# Launch simplified version (faster)
streamlit run app/streamlit_app_simple.py

# Access at: http://localhost:8501

Programmatic Inference

Basic Usage

from src.inference.predict import FloodPredictor

# Initialize
predictor = FloodPredictor(
    model_paths=["models/resnet_best.pt"],
    device="cuda"  # or "cpu"
)

# Predict
prediction, probabilities = predictor.predict_from_tif(
    s1_path="sentinel1.tif",
    s2_path="sentinel2.tif"
)

# Save results
predictor.save_prediction(
    prediction,
    output_path="flood_map.tif",
    reference_tif="sentinel1.tif"  # For georeferencing
)

Advanced: Ensemble with Uncertainty

from src.inference.predict import FloodPredictor
from src.inference.uncertainty import UncertaintyEstimator

# Load all models
predictor = FloodPredictor([
    "models/resnet_best.pt",
    "models/swin_best.pt",
    "models/maxvit_best.pt"
])

# Predict with uncertainty
pred, probs = predictor.predict_ensemble(s1_path, s2_path)

# Compute uncertainty metrics
uncertainty = UncertaintyEstimator()
epistemic_unc = uncertainty.epistemic_uncertainty(probs)
aleatoric_unc = uncertainty.aleatoric_uncertainty(probs)

Batch Processing

import glob
from pathlib import Path

# Process multiple images
s1_files = glob.glob("data/raw/S1/*.tif")
s2_files = glob.glob("data/raw/S2/*.tif")

for s1, s2 in zip(s1_files, s2_files):
    pred, _ = predictor.predict_from_tif(s1, s2)
    output = f"results/{Path(s1).stem}_flood.tif"
    predictor.save_prediction(pred, output, s1)

---

🧠 Model Architecture

The system uses an ensemble of three complementary architectures:

1. ResNet-50 UNet

• Type: CNN-based encoder-decoder
• Strengths: Fast inference, robust to noise
• Architecture: ResNet-50 encoder + UNet decoder with skip connections
• Parameters: ~35M
• Input: 512×512 multi-channel imagery

2. Swin Transformer

• Type: Vision Transformer with shifted windows
• Strengths: Long-range dependencies, hierarchical features
• Architecture: Swin-B backbone + decoder
• Parameters: ~88M
• Input: 512×512 multi-channel imagery

3. MaxViT

• Type: Hybrid CNN-Transformer
• Strengths: Multi-scale features, efficient attention
• Architecture: MaxViT-T with custom decoder
• Parameters: ~31M
• Input: 512×512 multi-channel imagery

Ensemble Strategy

┌─────────────┐
│   Input     │
│  S1 + S2    │
└──────┬──────┘
       │
   ┌───┴───┐
   │ Split │
   └───┬───┘
       │
    ┌──┴──────────────┐
    │                 │
┌───▼───┐      ┌─────▼─────┐      ┌────▼────┐
│ResNet │      │   Swin    │      │ MaxViT  │
│ UNet  │      │Transformer│      │         │
└───┬───┘      └─────┬─────┘      └────┬────┘
    │                │                  │
    └────────┬───────┴──────────────────┘
             │
      ┌──────▼──────┐
      │   Ensemble  │
      │  (Weighted  │
      │   Average)  │
      └──────┬──────┘
             │
      ┌──────▼──────┐
      │Uncertainty  │
      │Quantification│
      └──────┬──────┘
             │
      ┌──────▼──────┐
      │   Output    │
      │ Flood Map + │
      │ Confidence  │
      └─────────────┘

Input Channels

• Sentinel-1: VV, VH polarization (2 channels)
• Sentinel-2: B2, B3, B4, B8, B11, B12 (6 channels)
• Total: 8 input channels

---

📊 Performance

Benchmark Results (Sen1Floods11 Dataset)

Model	IoU	F1 Score	Precision	Recall	Inference Time
ResNet-50 UNet	0.71	0.83	0.85	0.81	45 ms
Swin Transformer	0.69	0.81	0.87	0.76	120 ms
MaxViT	0.70	0.82	0.84	0.80	85 ms
Ensemble	0.74	0.85	0.87	0.83	250 ms

Tested on NVIDIA RTX 3090, 512×512 images

Target Metrics

• ✅ IoU: > 0.72 (Intersection over Union)
• ✅ F1 Score: > 0.80 (Harmonic mean of precision and recall)
• ✅ Precision: > 0.85 (Minimize false positives)
• ✅ Recall: > 0.75 (Minimize false negatives)

Key Advantages

1. Generalization: Models trained on global data (Sen1Floods11)
2. Robustness: Ensemble reduces individual model biases
3. Reliability: Uncertainty quantification flags low-confidence predictions
4. Speed: Optimized inference pipeline for near-real-time processing

---

⚙️ Configuration

Main Configuration File: configs/config.yaml

# Model Configuration
model:
  architecture: "ensemble"  # resnet, swin, maxvit, ensemble
  pretrained: true
  num_classes: 2  # background, flood
  
# Training Configuration
training:
  batch_size: 16
  epochs: 50
  learning_rate: 0.001
  weight_decay: 0.0001
  optimizer: "AdamW"
  scheduler: "CosineAnnealingLR"
  early_stopping_patience: 10
  
# Data Configuration
data:
  image_size: 512
  num_workers: 4
  train_split: 0.7
  val_split: 0.15
  test_split: 0.15
  augmentation:
    horizontal_flip: true
    vertical_flip: true
    rotation: 15
    brightness: 0.1
    contrast: 0.1
    
# Ensemble Configuration
ensemble:
  models: ["resnet", "swin", "maxvit"]
  weights: [0.4, 0.3, 0.3]
  uncertainty_method: "monte_carlo"
  mc_iterations: 10
  
# Inference Configuration
inference:
  batch_size: 8
  tta: false  # Test-time augmentation
  threshold: 0.5

---

🗄️ Data Sources

Sen1Floods11 Dataset

The primary training dataset containing labeled flood events worldwide.

• Source: Sen1Floods11 GitHub
• Size: ~4,831 image pairs
• Coverage: 11 flood events across 6 continents
• Resolution: 10m (Sentinel-2), 10m (Sentinel-1 resampled)
• Format: GeoTIFF files

Download Instructions:

# Option 1: Use our download script
python download_sen1floods11_colab.ipynb

# Option 2: Manual download from GitHub
# Place files in:
#   - data/raw/S1/*.tif
#   - data/raw/S2/*.tif
#   - data/raw/labels/*.tif

Google Earth Engine

For automated data fetching and custom analysis:

• Sentinel-1 GRD: SAR data (VV, VH polarization)

  • All-weather, day/night imaging
  • 10m resolution (IW mode)
  • Revisit time: 6-12 days

• Sentinel-2 MSI: Optical multispectral data

  • RGB, NIR, SWIR bands
  • 10m resolution (visible/NIR)
  • Revisit time: 5 days

Setup GEE Access:

earthengine authenticate

---

🔧 Troubleshooting

Common Issues

1. CUDA Out of Memory

# Reduce batch size in config.yaml
training:
  batch_size: 8  # or 4

# Or use gradient accumulation
python src/training/train.py --accumulation-steps 2

2. Google Earth Engine Authentication Failed

# Re-authenticate
earthengine authenticate

# Or set credentials manually
export GOOGLE_APPLICATION_CREDENTIALS="path/to/credentials.json"

3. Model Not Found Error

# Check model path
ls models/

# Download pre-trained weights (if available)
# Or train models first
python src/training/train.py --model resnet

4. Import Errors

# Reinstall dependencies
pip install -r requirements.txt --force-reinstall

# Or install specific package
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

5. Streamlit App Won't Start

# Check port availability
netstat -ano | findstr :8501

# Use different port
streamlit run app/streamlit_app.py --server.port 8502

Getting Help

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: your.email@example.com

---

🤝 Contributing

We welcome contributions! Here's how you can help:

Ways to Contribute

1. Report Bugs: Open an issue with details and reproducible examples
2. Suggest Features: Propose new features or improvements
3. Submit PRs: Fix bugs or implement features
4. Improve Docs: Help us improve documentation
5. Share Results: Share your flood detection results

Development Setup

# Fork and clone the repo
git clone https://github.com/yourusername/flood-detection.git
cd flood-detection

# Create a branch
git checkout -b feature/your-feature-name

# Make changes and test
python -m pytest tests/

# Commit and push
git add .
git commit -m "Add: your feature description"
git push origin feature/your-feature-name

# Open a Pull Request

Code Style

• Follow PEP 8 guidelines
• Add docstrings to functions
• Include type hints
• Write unit tests for new features

---

📚 Citation

If you use this code in your research, please cite:

Primary Citation

@article{sharma2025deepsarflood,
  title={DeepSARFlood: Rapid and Automated SAR-based flood inundation mapping using Vision Transformer-based Deep Ensembles with uncertainty estimates},
  author={Sharma, N.K. and Saharia, M.},
  journal={Scientific Remote Sensing},
  volume={1},
  pages={100203},
  year={2025},
  doi={10.1016/j.srs.2025.100203},
  url={https://doi.org/10.1016/j.srs.2025.100203}
}

Dataset Citation

@article{bonafilia2020sen1floods11,
  title={Sen1Floods11: A georeferenced dataset to train and test deep learning flood algorithms for Sentinel-1},
  author={Bonafilia, Derrick and Tellman, Beth and Anderson, Tyler and Issenberg, Erica},
  journal={Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition Workshops},
  pages={210--211},
  year={2020}
}

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2025 Flood Detection Project

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

---

🙏 Acknowledgments

This project builds upon excellent work from:

• DeepSARFlood: Original research and methodology
• Sen1Floods11: High-quality labeled dataset
• HydroSense Lab, IIT Delhi: Research guidance and support
• Cloud to Street: Dataset creation and flood mapping research
• Google Earth Engine: Satellite data access and processing

Technologies Used

• PyTorch: Deep learning framework
• Streamlit: Web application framework
• Rasterio: Geospatial data I/O
• Segmentation Models PyTorch: Pre-built architectures
• Albumentations: Data augmentation
• Google Earth Engine: Satellite data access

---

🌟 Star History

If you find this project useful, please consider giving it a star ⭐

---

Made with ❤️ for disaster response and climate resilience

⬆ Back to Top