OpenSR-SRGAN

PyPI	Versions	Docs & License	Tests	Reference

OpenSR-SRGAN is a comprehensive toolkit for training and evaluating super-resolution GANs on remote-sensing imagery. It packages a flexible generator/discriminator zoo, composable perceptual and reconstruction losses, and the training heuristics that make adversarial optimisation tractable—generator warm-up phases, learning-rate scheduling, adversarial-weight ramping, and more. All options are driven by concise YAML configuration files so you can explore new architectures or datasets without rewriting pipelines.

Whether you are reproducing published results, exploring new remote-sensing modalities, or trying to establish benchmarks, OpenSR-SRGAN gives you a clear and extensible foundation for multispectral super-resolution research.

This repository and the configs represent the experiences that were made with SR-GAN training for remote sensing imagery. It's neither complete nor claims to perform SOTA SR, but it implements all tweaks and tips that make training SR-GANs easier.

Why this repository?

• One configuration, many models. Swap between SRResNet, RCAB, RRDB, large-kernel attention, ESRGAN, and stochastic generators, plus standard SRGAN, PatchGAN, and ESRGAN discriminators, by editing config values.
• Loss combinations that just work. Mix pixel, spectral-angle, perceptual, total-variation, and adversarial objectives with sensible defaults for weights, schedules, and warm-up durations.
• Battle-tested training loop. PyTorch Lightning handles device placement, multi-GPU DDP, and restartable checkpoints while the repo layers in GAN-specific manual optimisation, adversarial weight ramping, gradient clipping, and learning-rate scheduling.
• Lightning 2+ training path. Training uses manual optimization (automatic_optimization=False) and a single GAN training-step implementation.
• Remote-sensing aware defaults. Normalisation, histogram matching, spectral-band handling, and Sentinel-2-oriented presets are ready-made for RGB-NIR and SWIR-style workflows and are extensible to other sensors.

What you get out of the box

Capability	Highlights
Generators & discriminators	SRResNet, RCAB, RRDB, large-kernel attention, ESRGAN, stochastic generators, standard SRGAN, PatchGAN, and ESRGAN discriminators.
Losses	Weighted combinations of L1, spectral-angle, perceptual (VGG/LPIPS), total-variation, BCE/Wasserstein, and optional relativistic adversarial losses.
Training utilities	Generator warm-up phases, on-plateau learning-rate schedules, adversarial-weight ramping, gradient clipping, and EMA tracking.
Experiment management	Weights & Biases or CSV logging, checkpointing, saved resolved configs, and Hydra experiment presets.
Datasets	Bundled example dataset for quick smoke tests plus a selector designed for custom collections.
Deployment	PyPI package (opensr-srgan) with helpers to load Lightning modules from configs or download pre-trained presets from the Hugging Face Hub.

Install in two ways

• From PyPI for inference – python -m pip install opensr-srgan installs the lightweight package that exposes load_from_config and load_inference_model. The former instantiates a Lightning module from any repo config + checkpoint path, while the latter fetches the published RGB-NIR and SWIR presets from the simon-donike/SR-GAN space on Hugging Face.
• From source for training & development – clone this repository when you want to modify architectures, retrain models, or work on new datasets. The Getting started guide covers environment setup.

Repository Tour

Path	Description
opensr_srgan/model/	Lightning module, generator and discriminator implementations, and loss definitions.
opensr_srgan/data/	Dataset wrappers and helper utilities for custom and preconfigured SR datasets.
opensr_srgan/configs/	Ready-to-run YAML presets covering common scale factors, band selections, and architecture pairings.
opensr_srgan/utils/	Logging helpers, spectral normalisation utilities, and model summary functions used across the stack.
opensr_srgan/train.py / opensr_srgan/train_hydra.py	Legacy YAML and Hydra entry points that wire configuration, data module, loggers, and the Lightning trainer together.

Typical workflow

1. Pick a configuration. Start from opensr_srgan/configs/config_training_example.yaml for a smoke test, or use a Hydra preset such as experiment=example, experiment=10m, or experiment=20m and adapt dataset paths, scale, generator, discriminator, and loss options to match your experiment.
2. Prepare datasets. Download the bundled example dataset or register your own source with the dataset selector (see Data).
3. Launch training. Run python -m opensr_srgan.train --config <path>, python -m opensr_srgan.train_hydra experiment=example, or import train from the package to instantiate the Lightning module, configure optimisers and callbacks, and start adversarial training (see Training).
4. Monitor progress. Use the included Weights & Biases logging to track perceptual losses, adversarial metrics, and validation imagery.
5. Deploy or evaluate. The Lightning module exposes predict_step for batched inference, automatically normalising inputs and matching output histograms to the low-resolution source.

Learn more

• Architecture explains how the Lightning module orchestrates generators, discriminators, and losses.
• Configuration documents every YAML field and how it influences training.
• Data details the supported datasets and how to integrate your own.
• Getting started walks through environment setup and the first training run.
• Training covers logging, callbacks, and practical tips for stable optimisation.
• Results showcases results for some generator/discriminator and dataset combinations.

ESA OpenSR

OpenSR-SRGAN is part of the ESA OpenSR ecosystem — an open framework for trustworthy super-resolution of multispectral satellite imagery. Within this initiative, this repository serves as the adversarial benchmark suite: it provides standardized GAN architectures, training procedures, and evaluation utilities that complement the other model types implemented in the project (diffusion, transformers, regression), and it interfaces with companion packages such as opensr-utils.

Citation

If you use this work, please cite:

@misc{donike2025opensrsrganflexiblesuperresolutionframework,
      title={OpenSR-SRGAN: A Flexible Super-Resolution Framework for Multispectral Earth Observation Data},
      author={Simon Donike and Cesar Aybar and Julio Contreras and Luis Gómez-Chova},
      year={2025},
      eprint={2511.10461},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2511.10461},
}