Skip to content

Commit ecd3bef

Browse files
committed
Add all-band SEN2SR with LDSR-S2 backbone and dedicated model examples
1 parent 027fdef commit ecd3bef

24 files changed

Lines changed: 902 additions & 136 deletions

‎.github/workflows/ci.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ jobs:
6565
python -m pip install -e '.[dev,cog]'
6666
fi
6767
- name: Syntax check
68-
run: python -m compileall opensr_utils setup.py demo.py tests examples
68+
run: python -m compileall opensr_utils setup.py tests examples
6969
- name: Shell syntax check
7070
run: bash -n run_batch.sh
7171
- name: Behavior and CPU integration tests
@@ -84,5 +84,5 @@ jobs:
8484
if-no-files-found: ignore
8585
- name: Check test quality
8686
run: >-
87-
python -m ruff check opensr_utils tests examples setup.py demo.py
88-
&& python -m ruff format --check opensr_utils tests examples setup.py demo.py
87+
python -m ruff check opensr_utils tests examples setup.py
88+
&& python -m ruff format --check opensr_utils tests examples setup.py

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ inf_1.py
88
inf_2.py
99
TODO.md
1010
demo_local.py
11+
demo.py
1112
.ruff_cache/
1213

1314
# images

‎MANIFEST.in‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
include demo.py
21
include run_batch.sh
32
recursive-include examples *.py *.md
43
recursive-include tests *.py *.md
54
include .github/constraints-oldest.txt
5+
exclude demo.py

‎README.md‎

Lines changed: 64 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -64,56 +64,78 @@ with large_file_processing(
6464
The one-call API always executes once and closes raster handles. The class also
6565
has `close()` for callers who do not use a context manager.
6666

67-
## SEN2SR and ESA SRGAN
67+
## Model examples
6868

69-
The named loaders return adapters for the models' actual inference contracts:
70-
71-
| Name | Supported pretrained model | Python | Input/output |
72-
| --- | --- | --- | --- |
73-
| `SEN2SR` | SEN2SRLite `NonReference_RGBN_x4` | 3.10–3.14 | Four RGB/NIR bands, 4× scale. |
74-
| `ESASRGAN` or `SRGAN` | ESA OpenSR SRGAN `RGB-NIR` preset | 3.12–3.14 | Four RGB/NIR bands, 4× scale. |
75-
| `LDSRS2` | ESA LDSR-S2 | Upstream package compatibility | Four RGB/NIR bands, 4× scale. |
69+
Runnable examples live in **[examples/](examples/README.md)**. Each script has
70+
`--help`, device selection, batching, tiling and output options. Start with
71+
Python 3.12–3.14 and install the extra for your chosen model:
7672

7773
```bash
78-
python -m pip install 'opensr-utils[sen2sr]'
79-
python -m pip install 'opensr-utils[srgan]'
80-
```
74+
python -m pip install 'opensr-utils[sen2sr-ldsr]' # SEN2SR + LDSR-S2 backbone
75+
python -m pip install 'opensr-utils[model]' # LDSR-S2 RGB-NIR alone
76+
python -m pip install 'opensr-utils[srgan]' # ESA SRGAN RGB-NIR
8177

82-
```python
83-
from opensr_utils import super_resolve
78+
# All ten supported Sentinel-2 bands, with LDSR-S2 as the RGB-NIR backbone.
79+
python examples/run_sen2sr.py scene.SAFE.zip --device cuda --output results/all_bands.tif
80+
81+
# Separate four-band RGB-NIR diffusion example.
82+
python examples/run_ldsrs2.py scene.SAFE.zip --device cuda --output results/rgbn.tif
8483

85-
super_resolve('scene.SAFE', 'SEN2SR', 'results/sen2sr.tif', batch_size=1)
86-
super_resolve('scene.SAFE', 'ESASRGAN', 'results/srgan.tif', batch_size=4)
84+
# Four-band ESA SRGAN example.
85+
python examples/run_esasrgan.py scene.tif --device cuda --output results/srgan.tif
86+
87+
# Interpolation and advanced generic options.
88+
python examples/run_model.py --help
89+
python examples/run_model.py scene.tif --model none --factor 1 --output results/check.tif
8790
```
8891

89-
SEN2SRLite expects fixed 128×128 tiles. The adapter replicate-pads smaller edge
90-
windows and crops predictions back to their true footprint. Larger windows are
91-
rejected clearly. The four-band adapter does not load the ten-band/full Mamba
92-
variants. The ESA SRGAN adapter preserves the official `predict_step` path,
93-
including histogram matching and EMA behavior; pass the adapter rather than an
94-
unwrapped upstream Lightning module to retain those semantics. All adapters use
95-
normalized values, explicit scales and named output bands.
92+
| Example | Model and bands | Scale |
93+
| --- | --- | --- |
94+
| `run_sen2sr.py` | SEN2SRLite all-band fusion with an **LDSR-S2 RGB-NIR backbone**. Input/output: **B02, B03, B04, B05, B06, B07, B08, B8A, B11, B12**. | 10 m reference grid → 2.5 m |
95+
| `run_ldsrs2.py` | LDSR-S2 alone. Input/output: **B04, B03, B02, B08** (RGB-NIR). | 4× |
96+
| `run_esasrgan.py` | ESA SRGAN `RGB-NIR` preset. Input/output: **B04, B03, B02, B08**. | 4× |
97+
98+
“All bands” means the ten bands supported by SEN2SR; B01, B09 and B10 are not
99+
model inputs. The all-band example retains SEN2SR's learned red-edge/SWIR fusion
100+
stages and replaces its RGB-NIR generator with LDSR-S2. For SAFE/S2GM folders,
101+
it explicitly resamples native 20 m bands onto the RGB 10 m reference grid using
102+
windowed nearest-neighbor reads, then applies the learned model. It writes ten
103+
labeled bands at 2.5 m, preserving the georeferenced footprint and validity mask.
104+
No full intermediate stack is needed.
96105

97-
SAFE/S2GM model inputs select and order the required **B04, B03, B02, B08** bands,
98-
ignoring other spectral channels. GeoTIFF band descriptions can identify those
99-
bands automatically; otherwise provide four native RGB/NIR channels or explicit
100-
1-based indexes, for example `band_indexes=[4, 5, 2, 1]` (`--bands 4 5 2 1` on CLI).
101-
Output GeoTIFFs retain the adapter's spectral band names.
106+
The generic named `SEN2SR` loader still defaults to its four-band RGB-NIR
107+
variant for compatibility. The all-band example explicitly selects
108+
`variant="main", backbone="ldsrs2"`.
102109

103-
See **[model demos and download instructions](examples/README.md)** for automatic
104-
and offline use of official weights. The instruction script has complete help:
110+
The same composition is available in Python:
105111

106-
```bash
107-
python demo.py --help
108-
python demo.py scene.tif --model none --factor 1 --output results/check.tif
109-
python examples/run_sen2sr.py scene.SAFE.zip --batch-size 1 --output results/sen2sr.tif
110-
python examples/run_esasrgan.py scene.tif --batch-size 4 --output results/srgan.tif
112+
```python
113+
from opensr_utils import super_resolve
114+
from opensr_utils.model_utils import get_model
115+
116+
# Downloads SEN2SR fusion artifacts and the LDSR-S2 backbone on first use.
117+
model = get_model("SEN2SR", variant="main", backbone="ldsrs2", device="cpu")
118+
output = super_resolve(
119+
"scene.SAFE.zip", model, "results/all_bands.tif",
120+
device="auto", batch_size=1, resample_inputs=True,
121+
)
122+
123+
# LDSR-S2 alone produces only R, G, B and NIR.
124+
from opensr_utils.model_utils.ldsrs2 import load_ldsrs2
125+
126+
rgbn_model = load_ldsrs2()
127+
output_rgbn = super_resolve("scene.SAFE.zip", rgbn_model, "results/rgbn.tif")
111128
```
112129

113-
`demo.py` performs no inference on import and accepts device/GPU selection,
114-
checkpoints, configs, download/cache controls, band indexes, tiling, batching,
115-
overwrite, retention and previews. `--device cuda:1` is a convenience for selecting
116-
a single GPU; `--device cuda --gpus 0 1` selects multiple GPUs.
130+
Standalone GeoTIFFs must already share a grid. Band descriptions select and order
131+
model channels automatically; unlabeled inputs must use the order in the table,
132+
or supply `--bands` / `band_indexes` explicitly. Fixed 128×128 model tiles are
133+
replicate-padded and cropped for smaller edge windows. The SRGAN adapter retains
134+
the official histogram matching and EMA inference path.
135+
136+
See [examples/README.md](examples/README.md) for local weights, offline inference
137+
and diffusion sampling options. The root `demo.py` is a local, ignored scratch
138+
script; published examples, tests and source distributions use `examples/`.
117139

118140
## Command line
119141

@@ -151,6 +173,7 @@ processing failures report a diagnostic and return a nonzero exit status.
151173
| `num_workers` / `--num-workers` | `0` | Increase for parallel raster reads when I/O limits throughput. |
152174
| `prefetch_factor` / `--prefetch-factor` | `2` | Positive batches per worker; ignored with zero workers. |
153175
| `output_units` / `--output-units` | Model units, otherwise `normalized` | Explicit prediction units, described below. |
176+
| `resample_inputs` (Python) | `False` | Explicitly map folder bands to the selected reference grid; enabled by the all-band SEN2SR example. |
154177
| `band_indexes` / `--bands` | Model descriptions or native order | Select 1-based channels from a file in model input order. |
155178
| `checkpoint` / `--checkpoint` | Download official preset | Local SEN2SR MLSTAC directory/export or ESA SRGAN weights. |
156179
| `model_config` / `--config` | Preset config | ESA SRGAN YAML accompanying local weights. |
@@ -172,8 +195,9 @@ spectral channels on the selected grid. Auxiliary bands such as AOT, WVP and TCI
172195
are excluded. Generic PyTorch models retain native file band order and channel count; adapters
173196
with declared spectral inputs select named or explicitly indexed bands.
174197
SAFE discovery prefers 10 m common bands. Bands on other-sized grids are omitted;
175-
same-sized bands with different transforms or CRSs are rejected. No implicit
176-
reprojection occurs. Models must accept the discovered channels; model output
198+
same-sized bands with different transforms or CRSs are rejected. Set
199+
`resample_inputs=True` explicitly to read folder bands on the selected reference
200+
grid, as in the all-band example; default discovery performs no reprojection. Models must accept the discovered channels; model output
177201
channel counts may differ from input counts. LDSR-S2 expects Sentinel-2 RGB/NIR
178202
inputs; use a model suited to mosaics for S2GM data.
179203

‎examples/README.md‎

Lines changed: 83 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,64 +1,104 @@
11
# Model examples
22

3-
These scripts use the same tiled, georeferenced pipeline as the public API.
4-
They support CPU and CUDA inference. Model downloads happen only when a model
5-
is selected and `--no-download` is absent.
3+
The examples run the public tiled pipeline and write labeled, georeferenced
4+
uint16 GeoTIFFs. Run any script with `--help` before downloading weights. Use
5+
Python 3.12–3.14 to install all model families in one environment.
66

7-
## SEN2SR RGB-NIR
7+
## All-band SEN2SR with an LDSR-S2 backbone
88

9-
The supported adapter is SEN2SRLite `NonReference_RGBN_x4`: a 4x model trained
10-
on fixed 128x128 low-resolution tiles. Smaller edge tiles are padded and
11-
cropped by the adapter. It expects channels in `B04, B03, B02, B08` order.
12-
For an unlabeled BGRN GeoTIFF, select that order explicitly with the root demo:
9+
`run_sen2sr.py` combines SEN2SRLite's learned red-edge/SWIR fusion with **LDSR-S2
10+
as its RGB-NIR backbone**. It reads and writes ten bands in this exact order:
11+
12+
```text
13+
B02 B03 B04 B05 B06 B07 B08 B8A B11 B12
14+
```
15+
16+
B01, B09 and B10 are outside the upstream model's supported bands. Native
17+
SAFE/S2GM folders can contain both 10 m and 20 m sources: windowed
18+
nearest-neighbor reads map them to the RGB 10 m reference grid before SEN2SR's
19+
learned 20 m → 10 m → 2.5 m stages. The output has ten bands at 2.5 m. Standalone
20+
GeoTIFFs must already have a common grid; descriptions select bands by name, or
21+
use `--bands` with ten 1-based indexes in the order above.
22+
23+
```bash
24+
python -m pip install 'opensr-utils[sen2sr-ldsr]' huggingface_hub
25+
26+
# Automatic SEN2SR fusion and LDSR-S2 backbone downloads.
27+
python examples/run_sen2sr.py scene.SAFE.zip --device cuda --output sen2sr_all.tif
28+
29+
# Diffusion batch size defaults to 1. Sampling steps control inference cost;
30+
# omit this option to use the backbone's configured quality/speed settings.
31+
python examples/run_sen2sr.py aligned_10band.tif --sampling-steps 20 \
32+
--batch-size 1 --device cuda --output sen2sr_all.tif
33+
34+
# Download every fusion artifact, including the 20m/10m fusion weights.
35+
hf download tacofoundation/SEN2SR --include 'SEN2SRLite/main/**' \
36+
--local-dir models/SEN2SR
37+
hf download simon-donike/RS-SR-LTDF opensr-ldsrs2_v1_0_0.ckpt \
38+
--local-dir models/LDSRS2
39+
```
40+
41+
The LDSR-S2 checkpoint also needs a matching configuration. Obtain
42+
[config_10m.yaml from opensr-model](https://github.com/ESAOpenSR/opensr-model/blob/main/opensr_model/configs/config_10m.yaml)
43+
and save it as `models/LDSRS2/config_10m.yaml`. Keep the checkpoint/config pair
44+
from the same model release. Fully offline inference then uses:
1345

1446
```bash
15-
python -m pip install 'opensr-utils[sen2sr]' huggingface_hub
16-
17-
# Automatic model-artifact download and CPU inference.
18-
python examples/run_sen2sr.py input.SAFE.zip --output sen2sr.tif
19-
python examples/run_sen2sr.py input.tif --device cuda --output sen2sr.tif
20-
21-
# Optional offline cache. The directory contains the downloaded mlm.json.
22-
hf download tacofoundation/SEN2SR \
23-
--include 'SEN2SRLite/NonReference_RGBN_x4/**' \
24-
--local-dir models/SEN2SRLite_RGBN
25-
python examples/run_sen2sr.py input.SAFE.zip \
26-
--checkpoint models/SEN2SRLite_RGBN/SEN2SRLite/NonReference_RGBN_x4 \
27-
--no-download --output sen2sr.tif
28-
29-
# If a standalone raster is stored as B, G, R, N, reorder it to R, G, B, N.
30-
python demo.py input_bgrn.tif --model sen2sr --bands 3 2 1 4 \
31-
--output sen2sr.tif
47+
python examples/run_sen2sr.py scene.SAFE.zip --device cuda --no-download \
48+
--checkpoint models/SEN2SR/SEN2SRLite/main \
49+
--backbone-checkpoint models/LDSRS2/opensr-ldsrs2_v1_0_0.ckpt \
50+
--backbone-config models/LDSRS2/config_10m.yaml --output sen2sr_all.tif
3251
```
3352

34-
SEN2SR documentation: <https://github.com/ESAOpenSR/SEN2SR>.
53+
This composes the official [SEN2SR](https://github.com/ESAOpenSR/SEN2SR) fusion
54+
model with [LDSR-S2](https://github.com/ESAOpenSR/opensr-model). Smaller windows
55+
are replicate-padded to 128×128 and cropped after inference. All Fourier masks
56+
and diffusion device state follow CPU/CUDA placement.
3557

36-
## SRGAN / ESASRGAN RGB-NIR
58+
## LDSR-S2 RGB-NIR only
3759

38-
The supported preset is the 4-band RGB-NIR generator. Install the published
39-
extra (Python 3.12 through 3.14), then choose either automatic or local
40-
artifacts:
60+
`run_ldsrs2.py` runs the diffusion model alone and writes four bands in
61+
**B04, B03, B02, B08** (R, G, B, NIR) order at 4× scale. SAFE/S2GM inputs select
62+
those bands automatically. For an unlabeled B, G, R, NIR GeoTIFF, use
63+
`--bands 3 2 1 4`.
4164

4265
```bash
43-
python -m pip install 'opensr-utils[srgan]>=0.5.1'
66+
python -m pip install 'opensr-utils[model]'
67+
python examples/run_ldsrs2.py scene.SAFE.zip --device cuda --output ldsrs2_rgbn.tif
68+
python examples/run_ldsrs2.py input_bgrn.tif --bands 3 2 1 4 \
69+
--device cpu --output ldsrs2_rgbn.tif
70+
71+
# Reuse the local checkpoint/config pair downloaded above.
72+
python examples/run_ldsrs2.py scene.SAFE.zip --device cuda --no-download \
73+
--checkpoint models/LDSRS2/opensr-ldsrs2_v1_0_0.ckpt \
74+
--config models/LDSRS2/config_10m.yaml --output ldsrs2_rgbn.tif
75+
```
4476

45-
# Automatic preset download and CPU/GPU inference.
46-
python examples/run_esasrgan.py input.tif --output esasrgan.tif
77+
`--sampling-steps` overrides the backbone's configured diffusion steps. CPU is
78+
supported but diffusion inference benefits substantially from CUDA.
79+
80+
## ESA SRGAN RGB-NIR
81+
82+
`run_esasrgan.py` uses the official four-band `RGB-NIR` preset, including its
83+
histogram matching and EMA inference path. Its optional package supports Python
84+
3.12–3.14.
85+
86+
```bash
87+
python -m pip install 'opensr-utils[srgan]' huggingface_hub
4788
python examples/run_esasrgan.py input.tif --device cuda --output esasrgan.tif
4889

49-
# Offline local checkpoint and matching configuration.
5090
hf download simon-donike/SR-GAN config_RGB-NIR.yaml RGB-NIR_4band_inference.ckpt \
5191
--local-dir models/SR-GAN
52-
python examples/run_esasrgan.py input.tif \
92+
python examples/run_esasrgan.py input.tif --no-download \
5393
--checkpoint models/SR-GAN/RGB-NIR_4band_inference.ckpt \
54-
--config models/SR-GAN/config_RGB-NIR.yaml --no-download \
55-
--output esasrgan.tif
94+
--config models/SR-GAN/config_RGB-NIR.yaml --output esasrgan.tif
5695
```
5796

58-
SRGAN documentation: <https://srgan.opensr.eu/api-reference/inference/>.
59-
Source: <https://github.com/ESAOpenSR/SRGAN>.
97+
Upstream [inference documentation](https://srgan.opensr.eu/api-reference/inference/)
98+
and [source](https://github.com/ESAOpenSR/SRGAN).
6099

61-
Both examples accept `--device`, `--batch-size`, `--window-size`, `--overlap`,
62-
`--eliminate-border-px`, and `--overwrite`. The model scale is 4x by default;
63-
use `--factor` for a compatible checkpoint with another scale. OpenSR-Utils
64-
normalizes model inputs to [0, 1] and writes uint16 GeoTIFF products.
100+
All dedicated examples accept `--device`, `--batch-size`, `--window-size`,
101+
`--overlap`, `--eliminate-border-px`, and `--overwrite`. `run_model.py` exposes
102+
additional generic controls for interpolation, multiple GPUs, previews,
103+
diagnostic runs and retaining predictions. Examples are safe to import and
104+
`--help` does not import Torch or download model artifacts.

‎examples/run_ldsrs2.py‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
#!/usr/bin/env python3
2+
"""Super-resolve only Sentinel-2 RGB-NIR (B04, B03, B02, B08) with LDSR-S2."""
3+
4+
from __future__ import annotations
5+
6+
import argparse
7+
from pathlib import Path
8+
import sys
9+
10+
11+
def main(argv=None) -> int:
12+
parser = argparse.ArgumentParser(description=__doc__)
13+
parser.add_argument(
14+
"input", type=Path, help="GeoTIFF, SAFE directory/archive, or S2GM folder"
15+
)
16+
parser.add_argument("-o", "--output", type=Path)
17+
parser.add_argument(
18+
"--checkpoint", type=Path, help="Local LDSR-S2 checkpoint (requires --config)"
19+
)
20+
parser.add_argument("--config", type=Path, help="Matching LDSR-S2 YAML")
21+
parser.add_argument(
22+
"--download", action=argparse.BooleanOptionalAction, default=True
23+
)
24+
parser.add_argument(
25+
"--sampling-steps", type=int, help="Override the model's diffusion steps"
26+
)
27+
parser.add_argument(
28+
"--bands", type=int, nargs=4, help="1-based GeoTIFF indexes in R,G,B,NIR order"
29+
)
30+
parser.add_argument("--device", default="auto", choices=("auto", "cpu", "cuda"))
31+
parser.add_argument("--batch-size", type=int, default=1)
32+
parser.add_argument(
33+
"--window-size",
34+
type=int,
35+
nargs=2,
36+
default=(128, 128),
37+
metavar=("WIDTH", "HEIGHT"),
38+
)
39+
parser.add_argument("--overlap", type=int, default=12)
40+
parser.add_argument("--eliminate-border-px", type=int, default=2)
41+
parser.add_argument("--overwrite", action="store_true")
42+
args = parser.parse_args(argv)
43+
if (args.checkpoint is None) != (args.config is None):
44+
parser.error("--checkpoint and --config must be supplied together")
45+
if not args.download and args.checkpoint is None:
46+
parser.error("--no-download requires --checkpoint and --config")
47+
48+
# Keep --help independent of Torch and optional model installations.
49+
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
50+
from opensr_utils import super_resolve
51+
from opensr_utils.model_utils.ldsrs2 import load_ldsrs2
52+
53+
model = load_ldsrs2(
54+
checkpoint=args.checkpoint,
55+
config_path=args.config,
56+
sampling_steps=args.sampling_steps,
57+
download=args.download,
58+
)
59+
output = super_resolve(
60+
args.input,
61+
model,
62+
args.output,
63+
device=args.device,
64+
batch_size=args.batch_size,
65+
window_size=tuple(args.window_size),
66+
overlap=args.overlap,
67+
eliminate_border_px=args.eliminate_border_px,
68+
band_indexes=args.bands,
69+
overwrite=args.overwrite,
70+
)
71+
print(output)
72+
return 0
73+
74+
75+
if __name__ == "__main__":
76+
raise SystemExit(main())

0 commit comments

Comments
 (0)