@@ -64,56 +64,78 @@ with large_file_processing(
6464The one-call API always executes once and closes raster handles. The class also
6565has ` 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
172195are excluded. Generic PyTorch models retain native file band order and channel count; adapters
173196with declared spectral inputs select named or explicitly indexed bands.
174197SAFE 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
177201channel counts may differ from input counts. LDSR-S2 expects Sentinel-2 RGB/NIR
178202inputs; use a model suited to mosaics for S2GM data.
179203
0 commit comments