Low-Resource Oil-Spill Segmentation with Component Diffusion

An experimental pipeline for learning oil-spill mask morphology from very small SAR datasets, composing diffusion-generated masks into scenes, rendering synthetic SAR image/mask pairs, and training semantic-segmentation models on the result.

Pipeline

real masks → component diffusion → synthetic masks
           → SAR rendering on clean backgrounds
           → synthetic image/mask banks
           → segmentation training and evaluation

This repository keeps only the latest reproducibility path used by the project: the v12.7c component-diffusion model, its subset runners, the v2 SAR renderer, and the newer segmentation training scripts. Historical versions, notebooks, datasets, checkpoints, and large generated outputs are omitted.

Repository layout

.
├── src/
│   ├── component_diffusion.py
│   ├── sar_renderer.py
│   └── segmentation_trainer.py
├── scripts/
│   ├── train_diffusion_models.py
│   ├── generate_spill_masks.py
│   └── train_segmentation_benchmarks.py
├── plots/
├── data/
├── requirements.txt
└── README.md

Installation

Python 3.10 or 3.11 and an NVIDIA GPU are recommended. Create an isolated environment from the repository root:

python -m venv .venv

Activate it on Linux/macOS:

source .venv/bin/activate

Or on Windows PowerShell:

.\.venv\Scripts\Activate.ps1

Install dependencies:

python -m pip install --upgrade pip
pip install -r requirements.txt

For a CUDA-enabled PyTorch build, use the installation command matching your CUDA version from the official PyTorch installation guide before installing the remaining requirements.

Data

Data availability: The data used in this study will be made publicly available once the paper is published. Until then, see data/README.md for the expected directory structure. The subset root must contain folders such as subset_001, subset_003, and subset_010, each with paired images/ and masks/ directories.

Run the pipeline

Run all commands from the repository root.

1. Train component-diffusion models

The following smoke-test command trains one subset and disables Weights & Biases logging:

python scripts/train_diffusion_models.py \
  --subsets_root data/subsets \
  --only subset_010 \
  --epochs 10 \
  --seeds 0 \
  --wandb_mode disabled

For the full experiment, remove --only, use the paper-scale epoch count, and select the desired seeds:

python scripts/train_diffusion_models.py \
  --subsets_root data/subsets \
  --epochs 2000 \
  --seeds 0,1,2 \
  --wandb_mode disabled

Outputs are written under runs/v12_7c_componentdiff/.

2. Sample synthetic masks

python scripts/generate_spill_masks.py \
  --checkpoints_root runs/v12_7c_componentdiff \
  --out_dir runs/v12_7c_generated_masks \
  --num_gen 1000 \
  --seeds 0 \
  --wandb_mode disabled

The sampler expects a trained checkpoint for each selected subset. Use --only subset_010 for a single-bank run.

3. Render synthetic SAR pairs

The renderer expects the generated masks after quality control in per-bank kept_masks/ directories and a directory of clean SAR background patches:

python src/sar_renderer.py \
  --qc_mask_root runs/v12_7c_generated_masks_qc \
  --background_root data/clean_background \
  --out_root data/synthetic_banks \
  --num_synth_per_bank 500

Each output bank contains matching images/ and masks/ directories plus a CSV file recording generation metadata.

4. Train segmentation models

Train all supported architectures across all synthetic banks:

python scripts/train_segmentation_benchmarks.py \
  --synthetic_root data/synthetic_banks \
  --val_img_dir data/validation/images \
  --val_mask_dir data/validation/masks \
  --test_img_dir data/test/images \
  --test_mask_dir data/test/masks \
  --models unetplusplus,deeplabv3plus,linknet,pspnet \
  --epochs 100 \
  --use_val_threshold_sweep \
  --deterministic \
  --wandb_mode disabled

Use --dry_run with any multi-run driver to inspect commands before launching long experiments. Run python <script> --help for the complete option list.

Representative results

Reproducibility notes

• Pass --deterministic and fixed seeds where supported.
• Training and generation are GPU-intensive; the short command above is only a functional smoke test, not a reproduction of final results.
• Weights & Biases is optional at runtime. Keep --wandb_mode disabled, or set a project/entity to enable experiment tracking.
• The dataset download link and paper citation will be added when the paper is published.
• Authorship and license information should be finalized before the repository is made public.

License

No license has been selected yet. Until one is added, the code remains under standard copyright and should not be treated as open-source.