From fd29b5cd2a052deb85ab8d7ded4122de4f8e689b Mon Sep 17 00:00:00 2001 From: Thomas Tilak Date: Tue, 29 Sep 2026 09:01:36 +1100 Subject: [PATCH 1/7] Fix SAFE/S2GM band selection picking up auxiliary rasters (AOT/WVP/TCI). --- opensr_utils/pipeline.py | 10 ++++++++-- tests/test_pipeline_helpers.py | 30 ++++++++++++++++++++++++++++++ 2 files changed, 38 insertions(+), 2 deletions(-) diff --git a/opensr_utils/pipeline.py b/opensr_utils/pipeline.py index 22a8fb0..03a8f6f 100644 --- a/opensr_utils/pipeline.py +++ b/opensr_utils/pipeline.py @@ -353,7 +353,9 @@ def safe_band_name(path): used = set(lr_file_dict.values()) for path in jp2s: if path not in used: - lr_file_dict[safe_band_name(path)] = path + name = safe_band_name(path) + if name.startswith("B") and name[1:].isalnum(): + lr_file_dict[name] = path if not lr_file_dict: raise FileNotFoundError(f"No usable SAFE bands found in {self.root}.") @@ -407,7 +409,11 @@ def safe_band_name(path): lr_file_dict[label] = by_name[band_name] used = set(lr_file_dict.values()) for band_name, path in by_name.items(): - if path not in used: + if ( + path not in used + and band_name.startswith("B") + and band_name[1:].isalnum() + ): lr_file_dict[band_name] = path self.image_meta["lr_file_dict"] = lr_file_dict diff --git a/tests/test_pipeline_helpers.py b/tests/test_pipeline_helpers.py index 9114e9d..dd10906 100644 --- a/tests/test_pipeline_helpers.py +++ b/tests/test_pipeline_helpers.py @@ -438,3 +438,33 @@ def test_write_to_file_creates_placeholder_from_prediction_index( with rasterio.open(runner.placeholder_filepath) as src: assert (src.width, src.height, src.count) == (9, 6, 2) assert src.dtypes == ("uint16", "uint16") + + +def test_safe_band_selection_excludes_auxiliary_rasters(write_raster, tmp_path): + safe = tmp_path / "S2A_TEST.SAFE" + granule = safe / "GRANULE" / "L1C_TEST" / "IMG_DATA" / "R10m" + granule.mkdir(parents=True) + for band in ("B02", "B03", "B04", "B08", "AOT", "WVP", "TCI"): + write_raster( + granule / f"T_TEST_{band}_10m.jp2", + data=np.ones((1, 16, 16), dtype=np.uint16), + width=16, + height=16, + ) + (safe / "manifest.safe").write_text("") + + runner = pipeline.large_file_processing( + root=str(safe), + model=None, + window_size=(8, 8), + factor=2, + overlap=4, + eliminate_border_px=0, + device="cpu", + batch_size=1, + num_workers=0, + prefetch_factor=0, + ) + + assert runner.image_meta["bands"] == 4 + assert set(runner.image_meta["lr_file_dict"]) == {"R", "G", "B", "NIR"} From 298ebfce56894f2e892107897185ce7eb300ae7b Mon Sep 17 00:00:00 2001 From: Simon Donike Date: Thu, 22 Oct 2026 14:57:19 +0200 Subject: [PATCH 2/7] refr. 1st step --- .github/workflows/ci.yml | 12 +- .gitignore | 1 + pyproject.toml | 11 +- tests/README.md | 75 ++++++++++ tests/conftest.py | 64 +++++++- tests/test_band_selection.py | 137 +++++++++++++++++ tests/test_cli.py | 128 ++++++++++++++++ tests/test_datamodule.py | 128 +++++++++++++++- tests/test_imports.py | 63 +++++++- tests/test_model_loader.py | 134 +++++++++-------- tests/test_pipeline_helpers.py | 82 +++++++++-- tests/test_pipeline_integration.py | 200 +++++++++++++++++++++++++ tests/test_prepare_model.py | 221 +++++++++++++++++++++++++++- tests/test_reading_utils.py | 104 ++++++++++++- tests/test_result_analysis.py | 54 ++++++- tests/test_tiling_contract.py | 55 +++++++ tests/test_transform_to_cog.py | 67 ++++++++- tests/test_writing_utils.py | 229 ++++++++++++++++++++++++++++- 18 files changed, 1660 insertions(+), 105 deletions(-) create mode 100644 tests/README.md create mode 100644 tests/test_band_selection.py create mode 100644 tests/test_pipeline_integration.py create mode 100644 tests/test_tiling_contract.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ff3f4c6..980695f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -12,13 +12,15 @@ jobs: - uses: actions/setup-python@v5 with: python-version: "3.12" - - name: Install test runner - run: python -m pip install --upgrade pip pytest + - name: Install CPU PyTorch + run: python -m pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu - name: Install package - run: python -m pip install --no-deps -e . + run: python -m pip install -e '.[dev,cog]' - name: Syntax check run: python -m compileall opensr_utils setup.py demo.py tests - name: Shell syntax check run: bash -n run_batch.sh - - name: Import tests - run: pytest -q + - name: Behavior and CPU integration tests + run: python -m pytest -q + - name: Check test quality + run: python -m ruff check tests && python -m ruff format --check tests diff --git a/.gitignore b/.gitignore index bce3f9f..7f1dfa2 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,7 @@ images_other/ inference.py inf_1.py inf_2.py +TODO.md # images *.tif diff --git a/pyproject.toml b/pyproject.toml index 6d65dc4..4f5decf 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,4 +1,13 @@ # pyproject.toml [build-system] requires = ["setuptools>=68", "wheel"] -build-backend = "setuptools.build_meta" \ No newline at end of file +build-backend = "setuptools.build_meta" + +[tool.pytest.ini_options] +testpaths = ["tests"] +addopts = "-ra --strict-markers" +xfail_strict = true +markers = [ + "integration: exercises the real CPU inference or COG pipeline on local rasters", + "known_bug: desired behavior blocked by a documented defect (strict xfail)", +] diff --git a/tests/README.md b/tests/README.md new file mode 100644 index 0000000..cc189e2 --- /dev/null +++ b/tests/README.md @@ -0,0 +1,75 @@ +# Behavior tests + +These tests define observable contracts for future refactors. They use small +local rasters, known pixel values and deterministic models rather than pretrained +weights. HTTP requests through `requests` are blocked by an autouse fixture; +model-loading tests mock the download/checkpoint boundary. No GPU is required. + +## Run locally + +Use a virtual environment with Python and the package's runtime dependencies: + +```bash +python -m pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu +python -m pip install -e '.[dev,cog]' +python -m pytest -q +``` + +In the current workspace the prepared environment is `/work/envs/opensr`: + +```bash +/work/envs/opensr/bin/python -m pytest -q +``` + +Runtime dependencies are required: collection should fail if they are missing, +rather than allowing CI to pass by skipping most tests. CI runs the full suite +on CPU. To select cases: + +```bash +python -m pytest -m integration -q +python -m pytest -m 'not integration and not known_bug' -q +python -m pytest -m known_bug --runxfail -q +python -m ruff check tests +python -m ruff format --check tests +``` + +`known_bug` tests define desired behavior that production code does not yet +provide. They use strict `xfail`: fixing the behavior causes CI to fail until the +marker is removed. Failure types are constrained to the reproduced defect. +`--runxfail` disables those markers to expose the actual failures. The defect +backlog and remaining design decisions are in [TODO.md](../TODO.md). + +## Contracts and scope + +| Area | Contract | +| --- | --- | +| Construction | Validate arguments before creating files; inference is explicit by default. | +| Band selection | Common channels are R/G/B/NIR; preserve additional spectral channels on the selected grid; ignore auxiliary files. | +| Input values | Read as float32, divide by 10000 and clamp to [0,1]; retain file channel order. | +| Tiling | Deterministic, unique, bounded windows cover every pixel, including narrow images and final edges. | +| Sampling/batching | Every index appears exactly once across ranks; never pad distributed inference or drop a final partial batch. | +| Model execution | Evaluation/inference mode; output channels may differ from input channels; dimensions obey the scale factor. | +| Patch persistence | NPY and compressed NPZ carry uint16 predictions and manifests with consistent LR/HR coordinates and channel metadata. | +| Blending | All three profiles handle valid zero values, preserve outer borders and support symmetric horizontal/vertical overlaps. | +| Output | Preserve CRS and spatial footprint; compare real tiled output against independently calculated expected pixels. | +| File safety | Protect source data and existing outputs; reject incomplete products; retain diagnostics after failures. | +| CLI/model loader | Forward options, reject malformed arguments, validate HTTP responses and stop after failed loading stages. | +| Auxiliary tools | Cold imports avoid loading ML dependencies or writing files; COGs and excerpts retain pixels and spatial metadata. | + +The full CPU inference tests use nearest-neighbor models so expected output is +computed independently with NumPy repeats. A one-DN absolute tolerance accounts +for float32 weighted accumulation followed by integer casting. Array/layout and +manifest tests otherwise check exact values or explicit numerical tolerances. + +SAFE discovery fixtures use GeoTIFF payloads with `.jp2` filenames; Rasterio +detects the actual format. They exercise naming, resolution preference and band +selection, not JP2 codec support. COG conversion uses the real converter and +validator. Distributed manifest tests simulate rank state and on-disk shards; +they do not replace multi-process/GPU testing. + +Prefer new tests at public boundaries, using hand-calculated expectations and +failure-preservation checks. Mock external services and rank/process context; +keep the raster I/O, models, persistence and stitching real where inexpensive. +Use `pipeline_factory` / `dataset_factory` for automatic raster-handle cleanup. +Keep unresolved units, nodata and debug-output choices in the backlog until +their intended behavior is decided. diff --git a/tests/conftest.py b/tests/conftest.py index f24a87a..614e5ec 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -6,6 +6,8 @@ import pytest +os.environ.setdefault("MPLBACKEND", "Agg") + class DummyRunner(SimpleNamespace): def __init__(self, **kwargs): @@ -22,6 +24,17 @@ def clean_rank_env(monkeypatch): monkeypatch.delenv(name, raising=False) +@pytest.fixture(autouse=True) +def block_http(monkeypatch): + """Network/model downloads belong behind a mocked boundary in this suite.""" + import requests + + def unexpected_request(*args, **kwargs): + pytest.fail("Unexpected HTTP request: mock model downloads in tests") + + monkeypatch.setattr(requests.sessions.Session, "request", unexpected_request) + + @pytest.fixture def dummy_runner(): return DummyRunner() @@ -41,8 +54,8 @@ def _write_raster( crs: str = "EPSG:4326", nodata=0, ): - np = pytest.importorskip("numpy") - rasterio = pytest.importorskip("rasterio") + import numpy as np + import rasterio from rasterio.transform import from_origin path = Path(path) @@ -75,6 +88,53 @@ def _write_raster( return _write_raster +@pytest.fixture +def pipeline_factory(): + """Build CPU runners without inference; close raster handles after each test.""" + from opensr_utils.pipeline import large_file_processing + + runners = [] + + def make(root, **overrides): + options = dict( + model=None, + window_size=(8, 8), + factor=2, + overlap=4, + eliminate_border_px=0, + device="cpu", + batch_size=2, + num_workers=0, + prefetch_factor=0, + auto_run=False, + cleanup=False, + ) + options.update(overrides) + runner = large_file_processing(root=str(root), **options) + runners.append(runner) + return runner + + yield make + for runner in runners: + runner.datamodule.dataset.close() + + +@pytest.fixture +def dataset_factory(): + from opensr_utils.data_utils.datamodule import PredictionDataset + + datasets = [] + + def make(**kwargs): + dataset = PredictionDataset(**kwargs) + datasets.append(dataset) + return dataset + + yield make + for dataset in datasets: + dataset.close() + + @pytest.fixture def safe_folder(tmp_path): root = tmp_path / "S2A_TEST.SAFE" / "GRANULE" / "L1C_TEST" / "IMG_DATA" diff --git a/tests/test_band_selection.py b/tests/test_band_selection.py new file mode 100644 index 0000000..356ad2b --- /dev/null +++ b/tests/test_band_selection.py @@ -0,0 +1,137 @@ +"""Band discovery is a public input contract, independent of model inference.""" + +from __future__ import annotations + + +import numpy as np +import pytest +from rasterio.transform import from_origin + + +def band_path(root, input_type, band, resolution=10): + if input_type == "SAFE": + return ( + root + / "GRANULE" + / "L2A_TEST" + / "IMG_DATA" + / f"R{resolution}m" + / f"T_TEST_{band}_{resolution}m.jp2" + ) + return root / f"{band}.tif" + + +@pytest.fixture(params=["SAFE", "S2GM"]) +def spectral_scene(request, tmp_path, write_raster): + input_type = request.param + root = tmp_path / ("scene.SAFE" if input_type == "SAFE" else "scene_S2GM") + root.mkdir() + for band, value in {"B02": 2000, "B03": 3000, "B04": 4000, "B08": 8000}.items(): + # GeoTIFF content with SAFE naming tests discovery without a JP2 encoder. + write_raster( + band_path(root, input_type, band), data=np.full((1, 16, 16), value) + ) + return root, input_type + + +def test_common_bands_have_rgb_nir_labels_and_values(spectral_scene, pipeline_factory): + root, _ = spectral_scene + runner = pipeline_factory(root) + assert runner.image_meta["bands"] == 4 + assert set(runner.image_meta["lr_file_dict"]) == {"R", "G", "B", "NIR"} + np.testing.assert_allclose( + runner.datamodule.dataset[0]["image"][:, 0, 0], [0.4, 0.3, 0.2, 0.8] + ) + + +@pytest.mark.parametrize("auxiliary", ["AOT", "WVP", "TCI", "SCL", "MSK_CLDPRB"]) +def test_auxiliary_files_are_not_counted_or_opened( + spectral_scene, auxiliary, pipeline_factory +): + root, input_type = spectral_scene + path = band_path(root, input_type, auxiliary) + path.parent.mkdir(parents=True, exist_ok=True) + path.write_bytes(b"Auxiliary file must never be opened as a spectral band") + runner = pipeline_factory(root) + assert runner.image_meta["bands"] == 4 + assert str(path) not in runner.image_meta["lr_file_dict"].values() + + +@pytest.mark.parametrize("band", ["B01", "B05", "B8A", "B11", "B12"]) +def test_additional_spectral_bands_on_the_selected_grid_are_kept( + spectral_scene, band, pipeline_factory, write_raster +): + root, input_type = spectral_scene + path = write_raster(band_path(root, input_type, band), width=16, height=16) + runner = pipeline_factory(root) + assert runner.image_meta["bands"] == 5 + assert runner.image_meta["lr_file_dict"][band] == str(path) + assert runner.datamodule.dataset[0]["image"].shape == (5, 8, 8) + + +def test_bands_with_other_dimensions_are_excluded( + spectral_scene, pipeline_factory, write_raster +): + root, input_type = spectral_scene + write_raster(band_path(root, input_type, "B11", 20), width=8, height=8) + runner = pipeline_factory(root) + assert runner.image_meta["bands"] == 4 + assert "B11" not in runner.image_meta["lr_file_dict"] + + +def test_safe_prefers_ten_meter_copy_of_common_bands( + tmp_path, write_raster, pipeline_factory +): + root = tmp_path / "scene.SAFE" + for resolution, size in [(20, 8), (10, 16), (60, 3)]: + for band in ("B02", "B03", "B04", "B08"): + write_raster( + band_path(root, "SAFE", band, resolution), width=size, height=size + ) + runner = pipeline_factory(root) + assert (runner.image_meta["width"], runner.image_meta["height"]) == (16, 16) + assert runner.image_meta["bands"] == 4 + assert all("_10m.jp2" in p for p in runner.image_meta["lr_file_dict"].values()) + + +def test_safe_without_usable_bands_has_a_clear_error(tmp_path, pipeline_factory): + root = tmp_path / "empty.SAFE" + path = band_path(root, "SAFE", "AOT") + path.parent.mkdir(parents=True) + path.write_bytes(b"ignored") + with pytest.raises(FileNotFoundError, match="No usable SAFE bands"): + pipeline_factory(root) + + +@pytest.mark.known_bug +@pytest.mark.xfail( + reason="S2GM auxiliary-only input leaks StopIteration instead of a useful error", + raises=StopIteration, +) +def test_s2gm_without_usable_bands_has_a_clear_error( + tmp_path, write_raster, pipeline_factory +): + root = tmp_path / "empty_S2GM" + write_raster(root / "AOT.tif") + with pytest.raises(FileNotFoundError, match="[Bb]ands"): + pipeline_factory(root) + + +@pytest.mark.known_bug +@pytest.mark.xfail( + reason="Band grid validation currently checks dimensions only", + raises=pytest.fail.Exception, +) +@pytest.mark.parametrize("mismatch", ["transform", "crs"]) +def test_same_size_bands_on_different_grids_are_rejected( + spectral_scene, mismatch, write_raster, pipeline_factory +): + root, input_type = spectral_scene + options = ( + {"transform": from_origin(100, 200, 1, 1)} + if mismatch == "transform" + else {"crs": "EPSG:3857"} + ) + write_raster(band_path(root, input_type, "B11"), width=16, height=16, **options) + with pytest.raises(ValueError, match="(?i)grid|transform|crs|align"): + pipeline_factory(root) diff --git a/tests/test_cli.py b/tests/test_cli.py index ff3f917..7010987 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -3,6 +3,8 @@ import sys import types +import pytest + from opensr_utils import cli @@ -112,3 +114,129 @@ def fail(device="cpu"): output = capsys.readouterr().out assert "Could not load LDSR-S2 model" in output assert "download failed" in output + + +@pytest.mark.parametrize( + "argv", + [ + [], + ["input.tif"], + ["input.tif", "unknown"], + ["input.tif", "None", "--device", "tpu"], + ["input.tif", "None", "--window_size", "8"], + ["input.tif", "None", "--factor", "1.5"], + ["input.tif", "None", "--gpus"], + ["input.tif", "None", "--not_an_option"], + ], +) +def test_invalid_cli_arguments_fail_before_starting_pipeline(monkeypatch, capsys, argv): + calls = [] + install_fake_pipeline(monkeypatch, calls) + monkeypatch.setattr(sys, "argv", ["opensr-run", *argv]) + with pytest.raises(SystemExit) as exc: + cli.main() + assert exc.value.code == 2 + assert calls == [] + assert "usage:" in capsys.readouterr().err + + +def test_cli_help_succeeds_without_running_inference(monkeypatch, capsys): + calls = [] + install_fake_pipeline(monkeypatch, calls) + monkeypatch.setattr(sys, "argv", ["opensr-run", "--help"]) + with pytest.raises(SystemExit) as exc: + cli.main() + assert exc.value.code == 0 + assert calls == [] + help_text = capsys.readouterr().out + assert "--overwrite" in help_text + assert "--keep_temp" in help_text + + +def test_cli_passes_all_explicit_processing_options_and_runs_once(monkeypatch): + calls = [] + install_fake_pipeline(monkeypatch, calls) + monkeypatch.setattr( + sys, + "argv", + [ + "opensr-run", + "path with spaces/input.tif", + "None", + "--factor", + "1", + "--window_size", + "16", + "24", + "--overlap", + "6", + "--eliminate_border_px", + "2", + "--batch_size", + "7", + "--num_workers", + "3", + "--prefetch_factor", + "4", + "--save_preview", + "--debug", + "--overwrite", + "--delete_input_zip", + "--compressed_patches", + "--keep_temp", + ], + ) + cli.main() + assert [name for name, _ in calls] == ["init", "run"] + assert calls[0][1] == dict( + root="path with spaces/input.tif", + model=None, + factor=1, + window_size=(16, 24), + overlap=6, + eliminate_border_px=2, + device="cpu", + gpus=None, + batch_size=7, + num_workers=3, + prefetch_factor=4, + save_preview=True, + debug=True, + cleanup=False, + overwrite=True, + delete_input_zip=True, + compressed_patches=True, + ) + + +def test_cli_propagates_pipeline_errors(monkeypatch): + calls = [] + install_fake_pipeline(monkeypatch, calls) + module = sys.modules["opensr_utils.pipeline"] + + def fail(**kwargs): + raise FileExistsError("output exists") + + monkeypatch.setattr(module, "large_file_processing", fail) + monkeypatch.setattr(sys, "argv", ["opensr-run", "input.tif", "None"]) + with pytest.raises(FileExistsError): + cli.main() + + +@pytest.mark.known_bug +@pytest.mark.xfail( + reason="CLI returns success when model loading fails", raises=pytest.fail.Exception +) +def test_model_loading_failure_returns_nonzero_exit_status(monkeypatch): + install_fake_pipeline(monkeypatch, []) + get_models = types.ModuleType("opensr_utils.model_utils.get_models") + + def fail(device): + raise RuntimeError("download failed") + + get_models.get_ldsrs2 = fail + monkeypatch.setitem(sys.modules, "opensr_utils.model_utils.get_models", get_models) + monkeypatch.setattr(sys, "argv", ["opensr-run", "input.tif", "LDSRS2"]) + with pytest.raises(SystemExit) as exc: + cli.main() + assert exc.value.code != 0 diff --git a/tests/test_datamodule.py b/tests/test_datamodule.py index e437a0f..a9bc2f7 100644 --- a/tests/test_datamodule.py +++ b/tests/test_datamodule.py @@ -4,10 +4,8 @@ import pytest -np = pytest.importorskip("numpy") -torch = pytest.importorskip("torch") -pytest.importorskip("rasterio") -pytest.importorskip("pytorch_lightning") +import numpy as np +import torch from rasterio.windows import Window # noqa: E402 @@ -194,3 +192,125 @@ def test_prediction_datamodule_uses_sharded_sampler_under_ddp( assert isinstance(loader.sampler, datamodule.ShardedInferenceSampler) assert list(loader.sampler) == [3, 4] + + +@pytest.mark.parametrize("size", [0, 1, 2, 7, 31]) +@pytest.mark.parametrize("world", [1, 2, 3, 8]) +def test_sampler_covers_each_index_exactly_once_and_balances_shards(size, world): + samplers = [ + datamodule.ShardedInferenceSampler(size, rank=r, world_size=world) + for r in range(world) + ] + shards = [list(sampler) for sampler in samplers] + assert [i for shard in shards for i in shard] == list(range(size)) + assert max(map(len, shards)) - min(map(len, shards)) <= 1 + assert [len(s) for s in samplers] == [len(s) for s in shards] + assert all(list(sampler) == shard for sampler, shard in zip(samplers, shards)) + + +@pytest.mark.parametrize("rank,world", [(-1, 2), (0, 0), (0, -1), (2, 2)]) +def test_sampler_rejects_impossible_rank_world_pairs(rank, world): + with pytest.raises(ValueError): + datamodule.ShardedInferenceSampler(5, rank=rank, world_size=world) + + +@pytest.mark.parametrize("input_type", ["file", "SAFE", "S2GM"]) +def test_dataset_clips_reflectance_and_preserves_spatial_values( + input_type, dataset_factory, write_raster, tmp_path +): + values = np.array([[-200, 0, 1000], [5000, 10000, 15000]], dtype=np.int16) + path = write_raster(tmp_path / "signed.tif", data=values, dtype="int16") + dataset = dataset_factory( + input_type=input_type, + root=str(path), + windows=[Window(0, 0, 3, 2)], + lr_file_dict={"R": str(path)}, + ) + image = dataset[0]["image"] + np.testing.assert_allclose(image.numpy(), [[[0, 0, 0.1], [0.5, 1, 1]]]) + assert image.dtype == torch.float32 + with datamodule.rasterio.open(path) as src: + np.testing.assert_array_equal(src.read(1), values) + + +@pytest.mark.parametrize("count", [1, 2, 4, 7, 13]) +def test_file_dataset_preserves_every_band_in_native_order( + count, dataset_factory, write_raster, tmp_path +): + data = np.arange(count * 3 * 5, dtype=np.uint16).reshape(count, 3, 5) * 10 + path = write_raster(tmp_path / "multiband.tif", data=data) + dataset = dataset_factory( + input_type="file", + root=str(path), + lr_file_dict={}, + windows=[Window(2, 1, 3, 2)], + ) + np.testing.assert_allclose( + dataset[0]["image"], data[:, 1:3, 2:5] / 10000, atol=1e-7 + ) + + +@pytest.mark.parametrize("input_type", ["SAFE", "S2GM"]) +def test_dictionary_dataset_rejects_empty_bands(input_type, dataset_factory, tmp_path): + dataset = dataset_factory( + input_type=input_type, + root=str(tmp_path), + windows=[Window(0, 0, 1, 1)], + lr_file_dict={}, + ) + with pytest.raises(ValueError, match="No input bands"): + dataset[0] + + +def test_dataset_can_be_read_after_pickling_and_closing_original( + dataset_factory, write_raster, tmp_path +): + path = write_raster(tmp_path / "input.tif") + original = dataset_factory( + input_type="file", root=str(path), windows=[Window(1, 2, 2, 3)], lr_file_dict={} + ) + before = original[0] + restored = pickle.loads(pickle.dumps(original)) + try: + original.close() + original.close() # Closing twice must be safe. + assert restored[0]["meta"] == before["meta"] + torch.testing.assert_close(restored[0]["image"], before["image"]) + torch.testing.assert_close(original[0]["image"], before["image"]) + finally: + restored.close() + + +@pytest.mark.parametrize("size,batch_size", [(0, 2), (1, 4), (5, 2), (5, 3)]) +def test_prediction_loader_never_drops_or_reorders_windows( + size, batch_size, write_raster, tmp_path +): + path = write_raster(tmp_path / "input.tif", width=8, height=2) + dm = datamodule.PredictionDataModule( + input_type="file", + root=str(path), + windows=[Window(i, 0, 1, 1) for i in range(size)], + lr_file_dict={}, + batch_size=batch_size, + num_workers=0, + prefetch_factor=2, + ) + dm.setup() + try: + batches = list(dm.predict_dataloader()) + assert [int(i) for batch in batches for i in batch["meta"]["index"]] == list( + range(size) + ) + assert sum(batch["image"].shape[0] for batch in batches) == size + finally: + dm.dataset.close() + + +def test_initialized_distributed_rank_takes_precedence_over_environment(monkeypatch): + monkeypatch.setenv("LOCAL_RANK", "0") + monkeypatch.setenv("WORLD_SIZE", "99") + monkeypatch.setattr(datamodule.torch.distributed, "is_available", lambda: True) + monkeypatch.setattr(datamodule.torch.distributed, "is_initialized", lambda: True) + monkeypatch.setattr(datamodule.torch.distributed, "get_rank", lambda: 3) + monkeypatch.setattr(datamodule.torch.distributed, "get_world_size", lambda: 4) + assert datamodule._infer_rank_world() == (3, 4) diff --git a/tests/test_imports.py b/tests/test_imports.py index 78b4b34..020b2d8 100644 --- a/tests/test_imports.py +++ b/tests/test_imports.py @@ -1,11 +1,62 @@ +"""Import contracts must be tested before any ML imports in a fresh interpreter.""" + import importlib +import os +from pathlib import Path +import subprocess +import sys + +import pytest + + +@pytest.mark.parametrize( + "module", + [ + "opensr_utils", + "opensr_utils.data_utils", + "opensr_utils.model_utils", + "opensr_utils.cli", + "opensr_utils.data_utils.transform_to_cog", + ], +) +def test_imports_are_lightweight_and_have_no_filesystem_side_effects(module, tmp_path): + source_root = str(Path(__file__).resolve().parents[1]) + environment = { + **os.environ, + "PYTHONPATH": source_root, + "PYTHONDONTWRITEBYTECODE": "1", + } + script = """ +import importlib, pathlib, sys +before = pathlib.Path.cwd() +importlib.import_module(sys.argv[1]) +heavy = {'torch', 'numpy', 'rasterio', 'matplotlib', 'opensr_model', 'rio_cogeo', 'requests'} +assert not heavy.intersection(sys.modules), heavy.intersection(sys.modules) +assert pathlib.Path.cwd() == before +assert not list(before.iterdir()) +""" + result = subprocess.run( + [sys.executable, "-c", script, module], + cwd=tmp_path, + env=environment, + capture_output=True, + text=True, + timeout=30, + ) + assert result.returncode == 0, result.stderr + assert result.stdout == "" + +@pytest.mark.parametrize( + "module", ["opensr_utils", "opensr_utils.data_utils", "opensr_utils.model_utils"] +) +def test_unknown_public_attribute_raises_attribute_error(module): + with pytest.raises(AttributeError, match="has no attribute"): + getattr(importlib.import_module(module), "nonexistent_public_api") -def test_top_level_import_is_lightweight(): - mod = importlib.import_module("opensr_utils") - assert hasattr(mod, "__version__") +def test_top_level_version_is_available(): + import opensr_utils -def test_cog_helper_has_no_import_time_side_effects(): - mod = importlib.import_module("opensr_utils.data_utils.transform_to_cog") - assert hasattr(mod, "process_tree") + assert isinstance(opensr_utils.__version__, str) + assert opensr_utils.__version__ diff --git a/tests/test_model_loader.py b/tests/test_model_loader.py index 0556962..41084d1 100644 --- a/tests/test_model_loader.py +++ b/tests/test_model_loader.py @@ -1,63 +1,81 @@ +"""Model loading mocks the HTTP/checkpoint boundary and never downloads weights.""" + from __future__ import annotations -import importlib +import importlib.util +from pathlib import Path import sys import types from types import SimpleNamespace - - -def test_get_ldsrs2_downloads_config_and_loads_checkpoint(monkeypatch): - calls = {} - - class FakeResponse: - text = "ckpt_version: fake-v1" - - def raise_for_status(self): - calls["raised"] = True - - fake_requests = types.ModuleType("requests") - - def get(url, timeout): - calls["url"] = url - calls["timeout"] = timeout - return FakeResponse() - - fake_requests.get = get - - class FakeOmegaConf: - @staticmethod - def load(stream): - calls["config_text"] = stream.read() - return SimpleNamespace(ckpt_version="fake-v1") - - fake_omegaconf = types.ModuleType("omegaconf") - fake_omegaconf.OmegaConf = FakeOmegaConf - - fake_opensr_model = types.ModuleType("opensr_model") - - class FakeSRLatentDiffusion: - def __init__(self, config, device): - self.config = config - self.device = device - self.loaded = None - - def load_pretrained(self, version): - self.loaded = version - - fake_opensr_model.SRLatentDiffusion = FakeSRLatentDiffusion - - monkeypatch.setitem(sys.modules, "requests", fake_requests) - monkeypatch.setitem(sys.modules, "omegaconf", fake_omegaconf) - monkeypatch.setitem(sys.modules, "opensr_model", fake_opensr_model) - sys.modules.pop("opensr_utils.model_utils.get_models", None) - - module = importlib.import_module("opensr_utils.model_utils.get_models") - model = module.get_ldsrs2(device="cuda:0") - - assert calls["url"].endswith("/opensr_model/configs/config_10m.yaml") - assert calls["timeout"] == 30 - assert calls["raised"] is True - assert calls["config_text"] == "ckpt_version: fake-v1" - assert model.device == "cuda:0" - assert model.loaded == "fake-v1" - sys.modules.pop("opensr_utils.model_utils.get_models", None) +from unittest.mock import Mock + +import pytest + + +@pytest.fixture +def loader(monkeypatch): + response = Mock(text="ckpt_version: fake-v1") + get = Mock(return_value=response) + config = SimpleNamespace(ckpt_version="fake-v1") + load_config = Mock(return_value=config) + model = Mock() + construct = Mock(return_value=model) + for name, attrs in { + "requests": {"get": get}, + "omegaconf": {"OmegaConf": SimpleNamespace(load=load_config)}, + "opensr_model": {"SRLatentDiffusion": construct}, + }.items(): + module = types.ModuleType(name) + module.__dict__.update(attrs) + monkeypatch.setitem(sys.modules, name, module) + # Keep mocked imports out of the real module cache and package attributes. + path = ( + Path(__file__).resolve().parents[1] / "opensr_utils/model_utils/get_models.py" + ) + spec = importlib.util.spec_from_file_location("isolated_model_loader", path) + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return SimpleNamespace( + module=module, + get=get, + response=response, + config=config, + load_config=load_config, + model=model, + construct=construct, + ) + + +@pytest.mark.parametrize("device", ["cpu", "cuda:0", "cuda:2"]) +def test_model_loader_validates_response_and_loads_requested_checkpoint(loader, device): + assert loader.module.get_ldsrs2(device=device) is loader.model + args, kwargs = loader.get.call_args + assert args[0].endswith("/opensr_model/configs/config_10m.yaml") + assert kwargs["timeout"] > 0 + loader.response.raise_for_status.assert_called_once_with() + assert loader.load_config.call_args.args[0].getvalue() == "ckpt_version: fake-v1" + loader.construct.assert_called_once_with(loader.config, device=device) + loader.model.load_pretrained.assert_called_once_with("fake-v1") + + +@pytest.mark.parametrize( + "stage", ["request", "http_status", "config", "constructor", "checkpoint"] +) +def test_model_loading_errors_propagate_and_stop_later_stages(loader, stage): + operations = [ + loader.get, + loader.response.raise_for_status, + loader.load_config, + loader.construct, + loader.model.load_pretrained, + ] + index = ["request", "http_status", "config", "constructor", "checkpoint"].index( + stage + ) + error = RuntimeError(f"{stage} failed") + operations[index].side_effect = error + with pytest.raises(RuntimeError) as exc: + loader.module.get_ldsrs2() + assert exc.value is error + for operation in operations[index + 1 :]: + operation.assert_not_called() diff --git a/tests/test_pipeline_helpers.py b/tests/test_pipeline_helpers.py index dd10906..95ee1b3 100644 --- a/tests/test_pipeline_helpers.py +++ b/tests/test_pipeline_helpers.py @@ -4,10 +4,7 @@ import pytest -np = pytest.importorskip("numpy") -pytest.importorskip("rasterio") -pytest.importorskip("torch") -pytest.importorskip("pytorch_lightning") +import numpy as np from rasterio.transform import from_origin # noqa: E402 @@ -87,8 +84,8 @@ def test_large_file_processing_can_prepare_without_running(write_raster, tmp_pat def test_large_file_processing_runs_small_image_factor_three_two_band_model( write_raster, tmp_path ): - torch = pytest.importorskip("torch") - rasterio = pytest.importorskip("rasterio") + import torch + import rasterio class TwoBandUpsampler(torch.nn.Module): def forward(self, x): @@ -127,8 +124,8 @@ def forward(self, x): def test_large_file_processing_runs_factor_one_tiled_identity_model( write_raster, tmp_path ): - torch = pytest.importorskip("torch") - rasterio = pytest.importorskip("rasterio") + import torch + import rasterio class FirstBandIdentity(torch.nn.Module): def forward(self, x): @@ -243,7 +240,8 @@ def test_create_image_windows_cover_pixels_without_underlapping( def test_create_placeholder_file_writes_scaled_geotiff(tmp_path): - rasterio = pytest.importorskip("rasterio") + import rasterio + runner = blank_runner() runner.temp_folder = str(tmp_path / "temp_unit") runner.placeholder_filepath = str(tmp_path / "sr_placeholder.tif") @@ -292,7 +290,8 @@ def test_create_placeholder_file_skips_existing_readable_file(tmp_path): def test_create_placeholder_file_can_use_prediction_output_metadata(tmp_path): - rasterio = pytest.importorskip("rasterio") + import rasterio + runner = blank_runner() runner.temp_folder = str(tmp_path / "temp_unit") runner.placeholder_filepath = str(tmp_path / "sr_placeholder.tif") @@ -404,12 +403,11 @@ def fake_ddp_safe_stitch(self, **kwargs): assert calls[0][1]["profile"] == "sigmoid" -def test_write_to_file_creates_placeholder_from_prediction_index( - monkeypatch, tmp_path -): +def test_write_to_file_creates_placeholder_from_prediction_index(monkeypatch, tmp_path): from opensr_utils.data_utils import writing_utils - rasterio = pytest.importorskip("rasterio") + import rasterio + runner = blank_runner() runner.overwrite = True runner.trainer = type("Trainer", (), {"is_global_zero": True})() @@ -468,3 +466,59 @@ def test_safe_band_selection_excludes_auxiliary_rasters(write_raster, tmp_path): assert runner.image_meta["bands"] == 4 assert set(runner.image_meta["lr_file_dict"]) == {"R", "G", "B", "NIR"} + + +@pytest.mark.parametrize( + "options", + [ + {"window_size": "8,8"}, + {"window_size": (8, 8, 8)}, + {"window_size": (-1, 8)}, + {"window_size": (8.0, 8)}, + {"overlap": -2}, + {"overlap": 4.0}, + {"overlap": 8}, + {"eliminate_border_px": -2}, + {"eliminate_border_px": 2.0}, + {"factor": True}, + {"factor": False}, + {"factor": -1}, + {"factor": 2.5}, + {"factor": "2"}, + {"device": "cuda:0"}, + {"device": "mps"}, + {"batch_size": -1}, + {"batch_size": 1.5}, + {"num_workers": 1.5}, + {"prefetch_factor": -1}, + {"prefetch_factor": "2"}, + {"gpus": [-1]}, + {"gpus": ["0"]}, + {"gpus": [0.0]}, + ], +) +def test_invalid_options_fail_before_creating_any_files( + tmp_path, pipeline_factory, options +): + with pytest.raises((ValueError, TypeError)): + pipeline_factory(tmp_path / "input.tif", **options) + assert not list(tmp_path.iterdir()) + + +@pytest.mark.parametrize( + "device,gpus,expected", + [ + ("cpu", None, None), + ("cpu", [0, 1], None), + ("cuda", None, [0]), + ("cuda", 2, [2]), + ("cuda", (1, 3), [1, 3]), + ], +) +def test_device_selection_normalizes_gpu_ids_without_running_inference( + device, gpus, expected, write_raster, pipeline_factory, tmp_path +): + path = write_raster(tmp_path / "input.tif") + runner = pipeline_factory(path, device=device, gpus=gpus) + assert runner.gpus == expected + assert runner.device == device diff --git a/tests/test_pipeline_integration.py b/tests/test_pipeline_integration.py new file mode 100644 index 0000000..6d4f397 --- /dev/null +++ b/tests/test_pipeline_integration.py @@ -0,0 +1,200 @@ +"""Tiny real CPU runs check pixels as well as metadata and lifecycle behavior.""" + +from pathlib import Path + +import numpy as np +import pytest +import rasterio +import torch +from affine import Affine + +pytestmark = pytest.mark.integration + + +class Nearest(torch.nn.Module): + def __init__(self, factor, channels): + super().__init__() + self.factor = factor + self.channels = channels + + def forward(self, x): + return torch.nn.functional.interpolate( + x[:, : self.channels], scale_factor=self.factor, mode="nearest" + ) + + +@pytest.mark.parametrize( + "height,width,factor,channels,window,overlap,discard,compressed", + [ + (3, 5, 1, 1, (8, 8), 0, 0, False), + (11, 17, 1, 2, (8, 8), 4, 0, False), + (11, 17, 2, 4, (8, 8), 4, 0, False), + (13, 19, 3, 2, (12, 10), 6, 2, True), + (1, 19, 2, 1, (8, 8), 4, 0, True), + (19, 1, 2, 2, (8, 8), 4, 0, False), + ], +) +def test_tiled_inference_matches_whole_image_and_preserves_georeferencing( + height, + width, + factor, + channels, + window, + overlap, + discard, + compressed, + write_raster, + pipeline_factory, + tmp_path, +): + data = (np.arange(4 * height * width).reshape(4, height, width) * 7 % 10001).astype( + np.uint16 + ) + # Include valid zero-valued predictions at internal and external boundaries. + data[:, ::3, ::2] = 0 + transform = Affine(10, 0, 600000, 0, -10, 5100000) + path = write_raster( + tmp_path / "input.tif", data=data, crs="EPSG:32632", transform=transform + ) + runner = pipeline_factory( + path, + model=Nearest(factor, channels), + factor=factor, + window_size=window, + overlap=overlap, + eliminate_border_px=discard, + compressed_patches=compressed, + ) + output = runner.run() + expected = np.repeat(np.repeat(data[:channels], factor, axis=1), factor, axis=2) + with rasterio.open(path) as original, rasterio.open(output) as result: + assert result.shape == (height * factor, width * factor) + assert result.count == channels + assert result.dtypes == ("uint16",) * channels + assert result.crs == original.crs + assert result.transform.almost_equals(transform * Affine.scale(1 / factor)) + np.testing.assert_allclose(tuple(result.bounds), tuple(original.bounds)) + # Float32 accumulation followed by integer casting may lose one DN. + np.testing.assert_allclose(result.read(), expected, atol=1, rtol=0) + with rasterio.open(path) as original: + np.testing.assert_array_equal(original.read(), data) + assert output == runner.final_sr_path + assert not Path(runner.placeholder_filepath).exists() + + +@pytest.mark.known_bug +@pytest.mark.xfail( + reason="Upscaling divides affine a/e but leaves rotation/shear b/d unchanged", + raises=AssertionError, +) +def test_upscaling_rotated_raster_preserves_its_spatial_footprint( + write_raster, pipeline_factory, tmp_path +): + transform = Affine(10, 2, 600000, 1, -10, 5100000) + path = write_raster(tmp_path / "rotated.tif", transform=transform) + runner = pipeline_factory(path) + with rasterio.open(runner.run()) as result: + assert result.transform.almost_equals(transform * Affine.scale(0.5)) + + +def test_construction_only_prepares_and_does_not_invoke_model_or_touch_output( + write_raster, + pipeline_factory, + tmp_path, +): + class MustNotRun(torch.nn.Module): + def forward(self, x): + pytest.fail("Construction must not start inference") + + path = write_raster(tmp_path / "input.tif") + final = tmp_path / "sr.tif" + final.write_bytes(b"existing output") + runner = pipeline_factory(path, model=MustNotRun()) + assert final.read_bytes() == b"existing output" + assert not Path(runner.placeholder_filepath).exists() + assert not list(Path(runner.temp_folder).iterdir()) + with pytest.raises(FileExistsError): + runner.run() + assert final.read_bytes() == b"existing output" + + +def test_successful_cleanup_preserves_input_logs_and_unrelated_files( + write_raster, pipeline_factory, tmp_path +): + path = write_raster(tmp_path / "input.tif") + unrelated = tmp_path / "temp_other_run" + unrelated.mkdir() + sentinel = unrelated / "important.txt" + sentinel.write_text("keep") + runner = pipeline_factory(path, cleanup=True) + assert Path(runner.run()).is_file() + assert not Path(runner.temp_folder).exists() + assert Path(runner.log_dir).is_dir() + assert path.exists() + assert sentinel.read_text() == "keep" + + +def test_model_failure_preserves_input_and_diagnostics( + write_raster, pipeline_factory, tmp_path +): + class Fails(torch.nn.Module): + def forward(self, x): + raise RuntimeError("inference failed deliberately") + + path = write_raster(tmp_path / "input.tif") + before = path.read_bytes() + runner = pipeline_factory(path, model=Fails(), cleanup=True) + with pytest.raises(RuntimeError, match="inference failed deliberately"): + runner.run() + assert path.read_bytes() == before + assert Path(runner.temp_folder).exists() + assert Path(runner.log_dir).exists() + assert not Path(runner.final_sr_path).exists() + + +def test_real_inference_disables_gradients_and_training_layers( + write_raster, pipeline_factory, tmp_path +): + class ChecksInference(torch.nn.Module): + def forward(self, x): + assert not self.training + assert not torch.is_grad_enabled() + return x + + path = write_raster(tmp_path / "input.tif") + runner = pipeline_factory(path, model=ChecksInference(), factor=1) + assert Path(runner.run()).is_file() + + +def test_explicit_overwrite_replaces_old_output_with_readable_result( + write_raster, pipeline_factory, tmp_path +): + path = write_raster(tmp_path / "input.tif", data=np.full((1, 8, 8), 2000)) + final = tmp_path / "sr.tif" + final.write_bytes(b"previous output") + runner = pipeline_factory(path) + assert runner.run(overwrite=True) == str(final) + with rasterio.open(final) as result: + np.testing.assert_array_equal(result.read(), np.full((1, 16, 16), 2000)) + + +@pytest.mark.known_bug +@pytest.mark.xfail( + reason="Stitcher deletes patches every 50 tiles even with cleanup=False", + raises=AssertionError, +) +def test_keep_temp_preserves_every_prediction_for_reproducibility( + write_raster, pipeline_factory, tmp_path +): + path = write_raster(tmp_path / "input.tif", width=16, height=16) + runner = pipeline_factory( + path, + model=Nearest(1, 1), + factor=1, + window_size=(2, 2), + overlap=0, + cleanup=False, + ) + runner.run() + patches = list(Path(runner.temp_folder).glob("*.npy")) + assert len(patches) == len(runner.image_meta["image_windows"]) diff --git a/tests/test_prepare_model.py b/tests/test_prepare_model.py index 8de16c7..3a8893b 100644 --- a/tests/test_prepare_model.py +++ b/tests/test_prepare_model.py @@ -1,13 +1,12 @@ from __future__ import annotations +import json from types import SimpleNamespace import pytest -np = pytest.importorskip("numpy") -torch = pytest.importorskip("torch") -pytest.importorskip("rasterio") -pytest.importorskip("pytorch_lightning") +import numpy as np +import torch from rasterio.windows import Window # noqa: E402 @@ -171,9 +170,7 @@ def forward(self, x): model.predict_step( { "image": torch.full((1, 1, 2, 2), 0.25, dtype=torch.float32), - "meta": [ - {"row_off": 2, "col_off": 3, "height": 2, "width": 2, "index": 0} - ], + "meta": [{"row_off": 2, "col_off": 3, "height": 2, "width": 2, "index": 0}], }, 0, ) @@ -228,3 +225,213 @@ def test_preprocess_model_preserves_lightning_module_instance(tmp_path): assert prepared is model assert prepared.training is False assert hasattr(prepared, "predict_step") + + +def prediction_batch(images, *, row=2, col=3, metadata="lists"): + batch_size, _, height, width = images.shape + records = [ + dict(row_off=row, col_off=col + i * width, height=height, width=width, index=i) + for i in range(batch_size) + ] + if metadata == "records": + meta = records + else: + meta = {key: [record[key] for record in records] for key in records[0]} + if metadata == "tensors": + meta = {key: torch.tensor(values) for key, values in meta.items()} + return {"image": images, "meta": meta} + + +@pytest.mark.parametrize("metadata", ["lists", "records", "tensors"]) +@pytest.mark.parametrize("compressed", [False, True]) +def test_prediction_manifest_round_trips_values_coordinates_and_format( + tmp_path, metadata, compressed +): + model = prepare_model.preprocess_model( + parent(tmp_path), None, str(tmp_path), [], factor=2 + ) + model._save_compressed = compressed + model.on_predict_start() + images = torch.stack([torch.full((2, 2, 3), 0.25), torch.full((2, 2, 3), 0.75)]) + assert model.predict_step(prediction_batch(images, metadata=metadata), 0) is None + model.on_predict_end() + manifest = json.loads((tmp_path / "index.json").read_text()) + assert manifest["factor"] == 2 + assert manifest["saved_dtype"] == "uint16" + assert manifest["saved_scale"] == 10000 + assert manifest["saved_container"] == ("npz" if compressed else "npy") + assert manifest["output_bands"] == 2 + assert len(manifest["entries"]) == 2 + for i, entry in enumerate(manifest["entries"]): + assert (entry["row_off_lr"], entry["col_off_lr"]) == (2, 3 + i * 3) + assert (entry["row_off_hr"], entry["col_off_hr"]) == (4, 6 + i * 6) + assert (entry["height_lr"], entry["width_lr"]) == (2, 3) + assert (entry["height_hr"], entry["width_hr"], entry["bands"]) == (4, 6, 2) + if compressed: + with np.load(entry["path"]) as archive: + data = archive[manifest["saved_key"]] + else: + data = np.load(entry["path"]) + np.testing.assert_array_equal( + data, np.full((2, 4, 6), [2500, 7500][i], dtype=np.uint16) + ) + assert not list(tmp_path.glob("*.png")), "Previews are opt-in" + + +@pytest.mark.parametrize( + "values,expected", + [ + ([-0.25, 0, 0.125, 1.25], [0, 0, 1250, 10000]), + ([100, 1000, 5000, 12000], [100, 1000, 5000, 10000]), + ], +) +def test_saved_predictions_support_normalized_and_reflectance_outputs( + tmp_path, values, expected +): + model = prepare_model.preprocess_model( + parent(tmp_path, 1), None, str(tmp_path), [], factor=1 + ) + model.on_predict_start() + model.predict_step( + prediction_batch(torch.tensor(values).reshape(1, 1, 2, 2).float()), 0 + ) + model.on_predict_end() + manifest = json.loads((tmp_path / "index.json").read_text()) + patch = np.load(manifest["entries"][0]["path"]) + assert patch.dtype == np.uint16 + np.testing.assert_array_equal(patch.ravel(), expected) + + +def test_model_band_count_must_remain_constant_across_batches(tmp_path): + model = prepare_model.preprocess_model( + parent(tmp_path), None, str(tmp_path), [], factor=1 + ) + model.on_predict_start() + model.predict_step(prediction_batch(torch.ones((1, 2, 2, 2))), 0) + with pytest.raises(ValueError, match="band count changed"): + model.predict_step(prediction_batch(torch.ones((1, 3, 2, 2)), row=4), 1) + assert len(list(tmp_path.glob("*.npy"))) == 1 + + +def test_wrapped_torch_model_is_in_eval_mode_and_weights_are_preserved(tmp_path): + original = torch.nn.Sequential( + torch.nn.Conv2d(1, 1, 1, bias=False), torch.nn.Dropout(0.9) + ) + original.train() + weights = original[0].weight.detach().clone() + model = prepare_model.preprocess_model( + parent(tmp_path), original, str(tmp_path), [], factor=1 + ) + image = torch.ones((1, 1, 2, 2)) + assert not original.training + assert not model.training + torch.testing.assert_close(original[0].weight, weights) + torch.testing.assert_close(model.predict(image), original(image)) + torch.testing.assert_close(model.predict(image), model.predict(image)) + + +@pytest.mark.parametrize("factor", [0, -1, 1.5, "2", None, True, False]) +def test_model_preparation_rejects_invalid_scale_before_writing(tmp_path, factor): + with pytest.raises(ValueError, match="positive integer"): + prepare_model.preprocess_model( + parent(tmp_path), None, str(tmp_path), [], factor=factor + ) + assert not list(tmp_path.iterdir()) + + +@pytest.mark.known_bug +@pytest.mark.xfail( + reason="Non-finite predictions are cast to uint16 rather than rejected", + raises=pytest.fail.Exception, +) +@pytest.mark.parametrize("value", [float("nan"), float("inf"), -float("inf")]) +def test_nonfinite_model_output_is_rejected_before_saving(tmp_path, value): + model = prepare_model.preprocess_model( + parent(tmp_path), None, str(tmp_path), [], factor=1 + ) + model.on_predict_start() + with pytest.raises(ValueError, match="(?i)finite|nan|inf"): + model.predict_step(prediction_batch(torch.full((1, 1, 2, 2), value)), 0) + assert not list(tmp_path.glob("*.npy")) + + +@pytest.mark.known_bug +@pytest.mark.xfail( + reason="A model can silently drop batch samples without validation", + raises=pytest.fail.Exception, +) +def test_output_batch_size_must_match_input_batch_size(tmp_path): + class DropsSample(torch.nn.Module): + def forward(self, x): + return x[:1] + + model = prepare_model.preprocess_model( + parent(tmp_path), DropsSample(), str(tmp_path), [], factor=1 + ) + model.on_predict_start() + with pytest.raises(ValueError, match="(?i)batch"): + model.predict_step(prediction_batch(torch.ones((2, 1, 2, 2))), 0) + + +def distributed_context(monkeypatch): + """Simulate rank metadata; these tests do not claim GPU/process coverage.""" + dist = prepare_model.torch.distributed + monkeypatch.setattr(dist, "is_available", lambda: True) + monkeypatch.setattr(dist, "is_initialized", lambda: True) + monkeypatch.setattr(dist, "get_rank", lambda: 0) + monkeypatch.setattr(dist, "get_world_size", lambda: 2) + monkeypatch.setattr(dist, "barrier", lambda: None) + monkeypatch.setattr(prepare_model.time, "sleep", lambda _: None) + + +def test_distributed_manifest_merge_sorts_deduplicates_and_accepts_empty_ranks( + tmp_path, monkeypatch +): + distributed_context(monkeypatch) + model = prepare_model.preprocess_model( + parent(tmp_path), None, str(tmp_path), [], factor=1 + ) + model.on_predict_start() + model.predict_step(prediction_batch(torch.ones((1, 1, 2, 2)), row=4), 0) + model.predict_step(prediction_batch(torch.ones((1, 1, 2, 2)), row=0), 1) + # Duplicate an actual entry in another rank's persisted manifest. + (tmp_path / "index_rank1.json").write_text( + json.dumps({"output_bands": 1, "entries": model._entries[:1]}) + ) + model.on_predict_end() + index = json.loads((tmp_path / "index.json").read_text()) + assert [(e["row_off_lr"], e["col_off_lr"]) for e in index["entries"]] == [ + (0, 3), + (4, 3), + ] + assert not list(tmp_path.glob("index_rank*.json")) + + +@pytest.mark.parametrize("other_bands", [0, 2, None]) +def test_distributed_manifest_merge_handles_empty_mismatched_and_missing_shards( + tmp_path, monkeypatch, other_bands +): + distributed_context(monkeypatch) + model = prepare_model.preprocess_model( + parent(tmp_path), None, str(tmp_path), [], factor=1 + ) + model.on_predict_start() + model.predict_step(prediction_batch(torch.ones((1, 1, 2, 2))), 0) + if other_bands is not None: + (tmp_path / "index_rank1.json").write_text( + json.dumps({"output_bands": other_bands, "entries": []}) + ) + if other_bands == 0: + model.on_predict_end() + index = json.loads((tmp_path / "index.json").read_text()) + assert index["output_bands"] == 1 + assert len(index["entries"]) == 1 + else: + exception, message = ( + (RuntimeError, "Missing prediction shard") + if other_bands is None + else (ValueError, "disagree on output band count") + ) + with pytest.raises(exception, match=message): + model.on_predict_end() + assert not (tmp_path / "index.json").exists() diff --git a/tests/test_reading_utils.py b/tests/test_reading_utils.py index f50556b..245d0b4 100644 --- a/tests/test_reading_utils.py +++ b/tests/test_reading_utils.py @@ -5,7 +5,6 @@ import pytest -pytest.importorskip("rasterio") from opensr_utils.data_utils import reading_utils @@ -134,3 +133,106 @@ def test_create_dirs_uses_s2gm_folder_as_base(dummy_runner, s2gm_folder): assert dummy_runner.placeholder_path == str(s2gm_folder) assert Path(dummy_runner.log_dir).parent == s2gm_folder + + +@pytest.mark.parametrize( + "filename", ["scene.tif", "scene.TIF", "scene.tiff", "scene.TIFF"] +) +def test_input_detection_accepts_readable_rasters_regardless_of_extension_case( + write_raster, dummy_runner, tmp_path, filename +): + path = write_raster(tmp_path / filename) + reading_utils.verify_input_file_type(dummy_runner, path) + assert dummy_runner.input_type == "file" + assert dummy_runner.root == str(path) + + +@pytest.mark.parametrize("delete", [False, True]) +def test_corrupt_zip_is_preserved_on_extraction_failure(dummy_runner, tmp_path, delete): + archive = tmp_path / "broken.zip" + archive.write_bytes(b"not a zip") + dummy_runner.delete_input_zip = delete + with pytest.raises(zipfile.BadZipFile): + reading_utils.verify_input_file_type(dummy_runner, archive) + assert archive.read_bytes() == b"not a zip" + + +@pytest.mark.parametrize( + "member", + ["../escaped.SAFE/manifest.safe", "nested/../../escaped.SAFE/manifest.safe"], +) +def test_all_zip_members_are_validated_before_any_extraction( + dummy_runner, tmp_path, member +): + archive = tmp_path / "download.zip" + with zipfile.ZipFile(archive, "w") as zf: + zf.writestr("scene.SAFE/manifest.safe", "valid member comes first") + zf.writestr(member, "unsafe member") + with pytest.raises(RuntimeError, match="Unsafe path"): + reading_utils.verify_input_file_type(dummy_runner, archive) + assert not (tmp_path / "download" / "scene.SAFE").exists() + assert not (tmp_path / "escaped.SAFE").exists() + assert archive.exists() + + +def test_zip_can_be_reused_after_opt_in_source_deletion(dummy_runner, tmp_path): + archive = tmp_path / "scene.zip" + with zipfile.ZipFile(archive, "w") as zf: + zf.writestr("scene.SAFE/manifest.safe", "preserve extracted content") + dummy_runner.delete_input_zip = True + reading_utils.verify_input_file_type(dummy_runner, archive) + first_root = dummy_runner.root + assert not archive.exists() + reading_utils.verify_input_file_type(dummy_runner, archive) + assert dummy_runner.root == first_root + assert ( + Path(first_root) / "manifest.safe" + ).read_text() == "preserve extracted content" + + +def test_worker_uses_preextracted_safe_without_deleting_source( + monkeypatch, dummy_runner, tmp_path +): + archive = tmp_path / "scene.zip" + archive.write_bytes(b"worker must not open this archive") + extracted = tmp_path / "scene" / "scene.SAFE" + extracted.mkdir(parents=True) + monkeypatch.setenv("WORLD_SIZE", "2") + monkeypatch.setenv("RANK", "1") + monkeypatch.setenv("LOCAL_RANK", "1") + dummy_runner.delete_input_zip = True + reading_utils.verify_input_file_type(dummy_runner, archive) + assert dummy_runner.input_type == "SAFE" + assert dummy_runner.root == str(extracted) + assert archive.exists() + + +@pytest.mark.known_bug +@pytest.mark.xfail( + reason="delete_input_zip deletes the archive before checking for a SAFE folder", + raises=AssertionError, +) +def test_zip_without_safe_is_retained_even_when_deletion_was_requested( + dummy_runner, tmp_path +): + archive = tmp_path / "wrong_download.zip" + with zipfile.ZipFile(archive, "w") as zf: + zf.writestr("readme.txt", "not a satellite product") + dummy_runner.delete_input_zip = True + with pytest.raises(NotImplementedError, match="does not contain"): + reading_utils.verify_input_file_type(dummy_runner, archive) + assert archive.exists() + + +def test_create_dirs_is_idempotent_and_keeps_existing_logs(dummy_runner, tmp_path): + dummy_runner.root = str(tmp_path / "scene.tif") + dummy_runner.input_type = "file" + dummy_runner.run_id = "test" + dummy_runner.image_meta = {} + reading_utils.create_dirs(dummy_runner) + log = Path(dummy_runner.log_file) + log.write_text("previous diagnostics\n") + reading_utils.create_dirs(dummy_runner) + assert log.read_text() == "previous diagnostics\n" + assert Path(dummy_runner.temp_folder).is_dir() + assert Path(dummy_runner.output_dir) == tmp_path diff --git a/tests/test_result_analysis.py b/tests/test_result_analysis.py index 62bf5e6..96a44d7 100644 --- a/tests/test_result_analysis.py +++ b/tests/test_result_analysis.py @@ -2,10 +2,9 @@ import pytest -np = pytest.importorskip("numpy") -pytest.importorskip("rasterio") -pytest.importorskip("skimage") -matplotlib = pytest.importorskip("matplotlib") +import numpy as np +import matplotlib + matplotlib.use("Agg", force=True) from opensr_utils.data_utils import result_analysis # noqa: E402 @@ -94,3 +93,50 @@ def test_generate_side_by_side_previews_writes_png( assert (out_dir / "example_000.png").exists() assert any("Image too small" in msg for msg in dummy_runner.messages) assert any("Saved preview PNG" in msg for msg in dummy_runner.messages) + + +@pytest.mark.parametrize("bands", [1, 2, 3, 5]) +def test_stretch_has_explicit_rgb_mapping_and_does_not_mutate_input(bands): + data = np.stack( + [np.full((2, 4), value) for value in [0.1, 0.2, 0.3, 0.4, 0.5][:bands]] + ) + before = data.copy() + result = result_analysis.stretch(data) + expected = { + 1: [0.35, 0.35, 0.35], + 2: [0.35, 0.7, 0.35], + 3: [0.35, 0.7, 1], + 5: [0.35, 0.7, 1], + }[bands] + assert result.shape == (2, 4, 3) + np.testing.assert_allclose(result, np.broadcast_to(expected, (2, 4, 3))) + np.testing.assert_array_equal(data, before) + + +def test_excerpt_pixels_and_georeferencing_match_the_source_window( + write_raster, dummy_runner, tmp_path, monkeypatch +): + import rasterio + from rasterio.transform import from_origin + from rasterio.windows import Window + + values = np.arange(2 * 6 * 8, dtype=np.uint16).reshape(2, 6, 8) + path = write_raster( + tmp_path / "source.tif", + data=values, + transform=from_origin(600000, 5100000, 10, 10), + crs="EPSG:32632", + ) + offsets = iter([2, 1, 0, 0]) + monkeypatch.setattr(np.random, "randint", lambda *args, **kwargs: next(offsets)) + output = tmp_path / "excerpt.tif" + returned = result_analysis.crop_and_save_georeferenced_excerpt( + dummy_runner, str(path), str(output), random_crop_size=(3, 2) + ) + np.testing.assert_array_equal(returned, values[:, 1:3, 2:5]) + with rasterio.open(path) as source, rasterio.open(output) as excerpt: + np.testing.assert_array_equal(excerpt.read(), returned) + assert excerpt.crs == source.crs + assert excerpt.transform == source.window_transform(Window(2, 1, 3, 2)) + assert excerpt.nodata == source.nodata + assert excerpt.dtypes == source.dtypes diff --git a/tests/test_tiling_contract.py b/tests/test_tiling_contract.py new file mode 100644 index 0000000..2f350ed --- /dev/null +++ b/tests/test_tiling_contract.py @@ -0,0 +1,55 @@ +"""Geometric invariants rather than an implementation of the tiling algorithm.""" + +import numpy as np +import pytest + +from opensr_utils.pipeline import large_file_processing + + +@pytest.mark.parametrize( + "width,height,window_size,overlap", + [ + (w, h, window, overlap) + for w, h in [(1, 1), (1, 19), (23, 1), (8, 8), (17, 23), (32, 32), (33, 31)] + for window, overlap in [((8, 8), 0), ((8, 8), 4), ((12, 8), 4), ((8, 12), 6)] + ], +) +def test_windows_are_unique_bounded_and_cover_every_pixel( + width, height, window_size, overlap +): + runner = object.__new__(large_file_processing) + runner.image_meta = {"width": width, "height": height} + runner.window_size = window_size + runner.overlap = overlap + windows = runner.create_image_windows() + coordinates = [ + (int(w.col_off), int(w.row_off), int(w.width), int(w.height)) for w in windows + ] + assert len(coordinates) == len(set(coordinates)) + assert windows == runner.create_image_windows(), "Ordering must be reproducible" + coverage = np.zeros((height, width), dtype=int) + for x, y, w, h in coordinates: + assert (w, h) == (min(width, window_size[0]), min(height, window_size[1])) + assert 0 <= x < x + w <= width + assert 0 <= y < y + h <= height + coverage[y : y + h, x : x + w] += 1 + assert np.all(coverage > 0) + # Neighboring tiles must retain at least the requested overlap on each axis. + for axis, length, size in [(0, width, window_size[0]), (1, height, window_size[1])]: + offsets = sorted({c[axis] for c in coordinates}) + assert offsets[0] == 0 + assert offsets[-1] + min(length, size) == length + assert all( + right - left <= max(1, size - overlap) + for left, right in zip(offsets, offsets[1:]) + ) + + +@pytest.mark.parametrize("width,height", [(0, 1), (1, 0), (-1, 3), (3, -1)]) +def test_empty_or_negative_image_dimensions_are_rejected(width, height): + runner = object.__new__(large_file_processing) + runner.window_size = (8, 8) + runner.overlap = 0 + runner.image_meta = {"width": width, "height": height} + with pytest.raises(ValueError, match="dimensions must be positive"): + runner.create_image_windows() diff --git a/tests/test_transform_to_cog.py b/tests/test_transform_to_cog.py index 86f8162..16c35eb 100644 --- a/tests/test_transform_to_cog.py +++ b/tests/test_transform_to_cog.py @@ -69,7 +69,7 @@ def test_make_cog_falls_back_to_rio_cogeo(monkeypatch, tmp_path): def test_readable_with_checksums_opens_valid_raster(write_raster, tmp_path): - pytest.importorskip("rasterio") + __import__("rasterio") tif = write_raster(tmp_path / "sr.tif", data=[[[1, 2], [3, 4]]]) assert transform_to_cog.readable_with_checksums(tif) is True @@ -118,3 +118,68 @@ def test_process_tree_counts_validation_failures(monkeypatch, tmp_path): assert transform_to_cog.process_tree(tmp_path, remove_original=True) == (0, 1) assert sr.exists() + + +@pytest.mark.integration +def test_real_cog_conversion_preserves_pixels_and_spatial_metadata( + write_raster, tmp_path +): + import numpy as np + import rasterio + from rio_cogeo.cogeo import cog_validate + + data = np.arange(3 * 16 * 20, dtype=np.uint16).reshape(3, 16, 20) + source = write_raster(tmp_path / "source.tif", data=data, crs="EPSG:32632") + output = tmp_path / "cog.tif" + transform_to_cog.make_cog(source, output) + assert cog_validate(output)[0] + assert transform_to_cog.readable_with_checksums(output) + with rasterio.open(source) as original, rasterio.open(output) as cog: + np.testing.assert_array_equal(cog.read(), data) + assert cog.crs == original.crs + assert cog.transform == original.transform + assert cog.nodata == original.nodata + assert cog.dtypes == original.dtypes + assert source.exists() + + +@pytest.mark.parametrize("failure", ["conversion", "validation", "readability"]) +def test_cog_failure_preserves_original_and_continues_to_next_file( + monkeypatch, tmp_path, failure +): + install_fake_cog_validate(monkeypatch) + sources = [tmp_path / name / "sr.tif" for name in ["bad", "good"]] + for source in sources: + source.parent.mkdir() + source.write_bytes(b"original") + + def convert(source, output): + if source.parent.name == "bad" and failure == "conversion": + raise OSError("conversion failed") + output.write_bytes(b"cog") + + def validate(path): + return (not (path.parent.name == "bad" and failure == "validation"), [], []) + + monkeypatch.setattr(transform_to_cog, "make_cog", convert) + monkeypatch.setattr(sys.modules["rio_cogeo.cogeo"], "cog_validate", validate) + monkeypatch.setattr( + transform_to_cog, + "readable_with_checksums", + lambda path: not (path.parent.name == "bad" and failure == "readability"), + ) + assert transform_to_cog.process_tree(tmp_path, remove_original=True) == (1, 1) + assert sources[0].read_bytes() == b"original" + assert not sources[1].exists() + + +def test_cog_dry_run_does_not_modify_existing_files(monkeypatch, tmp_path): + install_fake_cog_validate(monkeypatch) + source, output = tmp_path / "sr.tif", tmp_path / "sr_cog.tif" + source.write_bytes(b"source") + output.write_bytes(b"existing cog") + before = {p.name: p.read_bytes() for p in tmp_path.iterdir()} + assert transform_to_cog.process_tree( + tmp_path, dry_run=True, remove_original=True + ) == (0, 0) + assert {p.name: p.read_bytes() for p in tmp_path.iterdir()} == before diff --git a/tests/test_writing_utils.py b/tests/test_writing_utils.py index 24dd241..2d6e32b 100644 --- a/tests/test_writing_utils.py +++ b/tests/test_writing_utils.py @@ -1,12 +1,13 @@ from __future__ import annotations import json +from pathlib import Path from types import SimpleNamespace import pytest -np = pytest.importorskip("numpy") -rasterio = pytest.importorskip("rasterio") +import numpy as np +import rasterio from rasterio.transform import from_origin # noqa: E402 from rasterio.windows import Window # noqa: E402 @@ -467,3 +468,227 @@ def fake_stitch(self, **kwargs): assert writing_utils.ddp_safe_stitch(runner, limit=3) == ("done.tif", 0) assert not final.exists() assert calls[0]["limit"] == 3 + + +@pytest.mark.parametrize("profile", ["linear", "sigmoid", "cosine"]) +def test_four_way_overlap_has_an_analytic_weighted_mean_and_no_black_frame( + tmp_path, dummy_runner, profile +): + path = make_placeholder(tmp_path / "four_way.tif", width=7, height=7, count=2) + windows = [ + Window(0, 0, 5, 5), + Window(2, 0, 5, 5), + Window(0, 2, 5, 5), + Window(2, 2, 5, 5), + ] + meta = {"placeholder_path": str(path), "window_coordinates": windows} + # At (3,3), all four tiles have equal weights for all symmetric curves. + for index, value in enumerate([0, 100, 200, 300]): + data = np.stack([np.full((5, 5), value), np.full((5, 5), value + 1000)]) + writing_utils.write_to_placeholder( + dummy_runner, data, index, meta, factor=1, overlap=3, profile=profile + ) + with rasterio.open(path) as src: + result = src.read() + np.testing.assert_allclose(result[:, 3, 3], [150, 1150], atol=1, rtol=0) + np.testing.assert_array_equal(result[:, 0, 0], [0, 1000]) + np.testing.assert_array_equal(result[:, -1, -1], [300, 1300]) + assert np.all(result[1] >= 1000) + + +@pytest.mark.parametrize("profile", ["linear", "sigmoid", "cosine"]) +@pytest.mark.parametrize("reverse", [False, True]) +def test_vertical_and_horizontal_blending_agree_under_transposition( + tmp_path, dummy_runner, profile, reverse +): + def run(transposed): + path = make_placeholder( + tmp_path / f"{transposed}.tif", + width=4 if transposed else 12, + height=12 if transposed else 4, + ) + windows = ( + [Window(0, 0, 4, 8), Window(0, 4, 4, 8)] + if transposed + else [Window(0, 0, 8, 4), Window(4, 0, 8, 4)] + ) + meta = {"placeholder_path": str(path), "window_coordinates": windows} + for i in [1, 0] if reverse else [0, 1]: + patch = np.full( + (1, 8, 4) if transposed else (1, 4, 8), 100 * i, dtype=np.uint16 + ) + writing_utils.write_to_placeholder( + dummy_runner, + patch, + i, + meta, + factor=1, + overlap=4, + eliminate_border_px=1, + profile=profile, + ) + with rasterio.open(path) as src: + return src.read(1) + + np.testing.assert_array_equal(run(False), run(True).T) + + +@pytest.mark.parametrize( + "layout", ["2d", "chw", "hwc", "list", "tensor", "pil", "xarray"] +) +def test_writer_accepts_documented_patch_representations( + tmp_path, dummy_runner, layout +): + data = np.arange(20, dtype=np.uint16).reshape(4, 5) + if layout == "2d": + patch = data + elif layout == "chw": + patch = data[None] + elif layout == "hwc": + patch = data[..., None] + elif layout == "list": + patch = [data] + elif layout == "tensor": + import torch + + patch = torch.tensor(data[None].astype(np.float32), requires_grad=True) + elif layout == "pil": + from PIL import Image + + patch = Image.fromarray(data) + else: + import xarray as xr + + patch = xr.DataArray(data[None], dims=("band", "y", "x")) + path = make_placeholder(tmp_path / "output.tif", width=5, height=4) + meta = {"placeholder_path": str(path), "window_coordinates": [Window(0, 0, 5, 4)]} + writing_utils.write_to_placeholder( + dummy_runner, patch, 0, meta, factor=1, overlap=0 + ) + with rasterio.open(path) as src: + np.testing.assert_array_equal(src.read(1), data) + + +@pytest.mark.parametrize( + "window", + [Window(-1, 0, 2, 2), Window(0, -1, 2, 2), Window(1, 0, 2, 2), Window(0, 1, 2, 2)], +) +def test_out_of_bounds_patches_fail_without_modifying_output( + tmp_path, dummy_runner, window +): + path = make_placeholder(tmp_path / "output.tif", width=2, height=2) + meta = {"placeholder_path": str(path), "window_coordinates": [window]} + with pytest.raises(ValueError, match="exceeds placeholder bounds"): + writing_utils.write_to_placeholder( + dummy_runner, np.ones((1, 2, 2)), 0, meta, factor=1, overlap=0 + ) + with rasterio.open(path) as src: + assert not src.read().any() + assert not list(tmp_path.glob("*.sum.tif")) + + +@pytest.mark.parametrize("patch", [np.zeros((1, 1, 2, 2)), np.zeros(3), "invalid"]) +def test_writer_rejects_unsupported_shapes_and_types(tmp_path, dummy_runner, patch): + path = make_placeholder(tmp_path / "output.tif", width=2, height=2) + meta = {"placeholder_path": str(path), "window_coordinates": [Window(0, 0, 2, 2)]} + with pytest.raises(TypeError): + writing_utils.write_to_placeholder( + dummy_runner, patch, 0, meta, factor=1, overlap=0 + ) + + +def saved_patch_run(tmp_path, *, container="npy", coverage="complete", factor=1): + """A hand-written prediction manifest: no model or manifest writer involved.""" + placeholder = make_placeholder( + tmp_path / "placeholder.tif", width=4 * factor, height=2 * factor + ) + entries = [] + for x, value in [(0, 100), (2, 200)]: + path = tmp_path / f"patch_{x}.{container}" + data = np.full((1, 2 * factor, 2 * factor), value, dtype=np.uint16) + if container == "npz": + np.savez_compressed(path, prediction=data) + else: + np.save(path, data) + entries.append( + dict( + path=str(path), + row_off_lr=0, + col_off_lr=x, + width_lr=2, + height_lr=2, + bands=1, + ) + ) + if coverage == "gap": + entries.pop() + elif coverage == "missing": + Path(entries[-1]["path"]).unlink() + elif coverage == "corrupt": + Path(entries[-1]["path"]).write_bytes(b"invalid numpy payload") + (tmp_path / "index.json").write_text( + json.dumps( + dict( + entries=entries[::-1], + factor=factor, + saved_container=container, + saved_key="prediction", + output_bands=1, + ) + ) + ) + return SimpleNamespace( + temp_folder=str(tmp_path), + placeholder_filepath=str(placeholder), + final_sr_path=str(tmp_path / "sr.tif"), + factor=1, + overlap=0, + eliminate_border_px=0, + image_meta={"dtype": "uint16"}, + _log=lambda message: None, + ) + + +@pytest.mark.parametrize("container", ["npy", "npz"]) +@pytest.mark.parametrize("factor", [1, 3]) +def test_stitcher_obeys_manifest_scale_container_and_custom_key( + tmp_path, container, factor +): + runner = saved_patch_run(tmp_path, container=container, factor=factor) + output, missing = writing_utils.stitch_sr_patches(runner) + assert missing == 0 + with rasterio.open(output) as src: + expected = np.repeat(np.array([[100, 100, 200, 200]]), 2 * factor, axis=0) + np.testing.assert_array_equal(src.read(1), np.repeat(expected, factor, axis=1)) + + +@pytest.mark.parametrize( + "coverage,exception", + [("gap", RuntimeError), ("missing", RuntimeError), ("corrupt", ValueError)], +) +def test_failed_stitch_does_not_publish_incomplete_output_and_removes_accumulators( + tmp_path, coverage, exception +): + runner = saved_patch_run(tmp_path, coverage=coverage) + with pytest.raises(exception): + writing_utils.stitch_sr_patches(runner) + assert not Path(runner.final_sr_path).exists() + assert Path(runner.placeholder_filepath).exists() + assert not list(tmp_path.glob("*.sum.tif")) + assert not list(tmp_path.glob("*.weights.tif")) + + +@pytest.mark.known_bug +@pytest.mark.xfail( + reason="Overwrite deletes existing final output before validating replacement patches", + raises=AssertionError, +) +def test_failed_overwrite_keeps_last_successful_output(tmp_path): + runner = saved_patch_run(tmp_path, coverage="missing") + runner.overwrite = True + final = Path(runner.final_sr_path) + final.write_bytes(b"last successful output") + with pytest.raises(RuntimeError): + writing_utils.ddp_safe_stitch(runner) + assert final.exists() + assert final.read_bytes() == b"last successful output" From 027fdefc09efe6c07c8f3f27bc7a4a0e73861296 Mon Sep 17 00:00:00 2001 From: Simon Donike Date: Thu, 22 Oct 2026 15:51:46 +0200 Subject: [PATCH 3/7] Complete pipeline maintenance and add SEN2SR and ESA SRGAN workflows --- .github/constraints-oldest.txt | 8 + .github/workflows/ci.yml | 74 ++- .gitignore | 3 + MANIFEST.in | 5 + README.md | 319 ++++++++----- demo.py | 310 ++++++++++-- demo_local.py | 221 --------- examples/README.md | 64 +++ examples/run_esasrgan.py | 88 ++++ examples/run_sen2sr.py | 77 +++ opensr_utils/__init__.py | 29 +- opensr_utils/cli.py | 224 ++++++--- opensr_utils/data_utils/datamodule.py | 55 ++- opensr_utils/data_utils/masking.py | 145 ++++++ opensr_utils/data_utils/reading_utils.py | 114 ++++- opensr_utils/data_utils/writing_utils.py | 255 ++++++---- opensr_utils/model_utils/__init__.py | 8 + opensr_utils/model_utils/esasrgan.py | 270 +++++++++++ opensr_utils/model_utils/get_models.py | 188 +++++++- opensr_utils/model_utils/prepare_model.py | 518 +++++++++++--------- opensr_utils/model_utils/sen2sr.py | 222 +++++++++ opensr_utils/pipeline.py | 549 +++++++++++++++------- pyproject.toml | 12 + setup.py | 28 +- tests/README.md | 115 +++-- tests/test_band_selection.py | 53 ++- tests/test_cli.py | 139 +++++- tests/test_distributed.py | 251 ++++++++++ tests/test_distributed_trainer.py | 94 ++++ tests/test_esasrgan.py | 126 +++++ tests/test_examples.py | 171 +++++++ tests/test_imports.py | 1 + tests/test_masks.py | 135 ++++++ tests/test_model_band_indexes.py | 90 ++++ tests/test_model_registry.py | 84 ++++ tests/test_named_models.py | 161 +++++++ tests/test_pipeline_helpers.py | 23 - tests/test_pipeline_integration.py | 10 - tests/test_prepare_model.py | 77 ++- tests/test_public_api.py | 129 +++++ tests/test_reading_utils.py | 45 +- tests/test_sen2sr.py | 106 +++++ tests/test_writing_utils.py | 95 +++- 43 files changed, 4566 insertions(+), 1125 deletions(-) create mode 100644 .github/constraints-oldest.txt create mode 100644 MANIFEST.in delete mode 100755 demo_local.py create mode 100644 examples/README.md create mode 100755 examples/run_esasrgan.py create mode 100755 examples/run_sen2sr.py create mode 100644 opensr_utils/data_utils/masking.py create mode 100644 opensr_utils/model_utils/esasrgan.py create mode 100644 opensr_utils/model_utils/sen2sr.py create mode 100644 tests/test_distributed.py create mode 100644 tests/test_distributed_trainer.py create mode 100644 tests/test_esasrgan.py create mode 100644 tests/test_examples.py create mode 100644 tests/test_masks.py create mode 100644 tests/test_model_band_indexes.py create mode 100644 tests/test_model_registry.py create mode 100644 tests/test_named_models.py create mode 100644 tests/test_public_api.py create mode 100644 tests/test_sen2sr.py diff --git a/.github/constraints-oldest.txt b/.github/constraints-oldest.txt new file mode 100644 index 0000000..4e8b20f --- /dev/null +++ b/.github/constraints-oldest.txt @@ -0,0 +1,8 @@ +# Dependency floor exercised by the Python 3.9 CI job. Keep these pins +# together: Torch 2.0 predates NumPy 2's ABI and its Lightning stack has a +# narrower compatibility range than current releases. +numpy<2 +torch==2.0.0 +torchvision==0.15.1 +pytorch-lightning==2.0.9 +torchmetrics==1.2.1 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 980695f..3ed1b06 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -7,20 +7,82 @@ on: jobs: checks: runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + # Retain the package's established 3.9/3.10 compatibility while + # checking current wheels on every maintained interpreter through 3.14. + include: + - python-version: "3.9" + torch-version: "2.0.0" + torchvision-version: "0.15.1" + constraints: oldest + - python-version: "3.10" + torch-version: "2.6.0" + torchvision-version: "0.21.0" + constraints: none + - python-version: "3.11" + torch-version: "latest" + torchvision-version: "latest" + constraints: none + - python-version: "3.12" + torch-version: "latest" + torchvision-version: "latest" + constraints: none + - python-version: "3.13" + torch-version: "latest" + torchvision-version: "latest" + constraints: none + - python-version: "3.14" + torch-version: "latest" + torchvision-version: "latest" + constraints: none steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: - python-version: "3.12" + python-version: ${{ matrix.python-version }} - name: Install CPU PyTorch - run: python -m pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu + run: | + python -m pip install --upgrade pip + if [ "${{ matrix.torch-version }}" = "latest" ]; then + python -m pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu + else + # Torch 2.0 predates NumPy 2's ABI; install the complete oldest + # stack before the editable package. The constraints file is also + # passed to that package install below, preventing resolver-driven + # upgrades of Torch or Lightning. + python -m pip install \ + "torch==${{ matrix.torch-version }}" \ + "torchvision==${{ matrix.torchvision-version }}" \ + --index-url https://download.pytorch.org/whl/cpu + fi - name: Install package - run: python -m pip install -e '.[dev,cog]' + run: | + if [ "${{ matrix.constraints }}" = "oldest" ]; then + python -m pip install -c .github/constraints-oldest.txt -e '.[dev,cog]' + else + python -m pip install -e '.[dev,cog]' + fi - name: Syntax check - run: python -m compileall opensr_utils setup.py demo.py tests + run: python -m compileall opensr_utils setup.py demo.py tests examples - name: Shell syntax check run: bash -n run_batch.sh - name: Behavior and CPU integration tests - run: python -m pytest -q + run: >- + python -m pytest -q + --cov=opensr_utils + --cov-branch + --cov-report=term-missing + --cov-report=xml:coverage-${{ matrix.python-version }}.xml + - name: Upload coverage report + if: always() + uses: actions/upload-artifact@v4 + with: + name: coverage-${{ matrix.python-version }} + path: coverage-${{ matrix.python-version }}.xml + if-no-files-found: ignore - name: Check test quality - run: python -m ruff check tests && python -m ruff format --check tests + run: >- + python -m ruff check opensr_utils tests examples setup.py demo.py + && python -m ruff format --check opensr_utils tests examples setup.py demo.py diff --git a/.gitignore b/.gitignore index 7f1dfa2..902edeb 100644 --- a/.gitignore +++ b/.gitignore @@ -7,6 +7,8 @@ inference.py inf_1.py inf_2.py TODO.md +demo_local.py +.ruff_cache/ # images *.tif @@ -78,6 +80,7 @@ htmlcov/ .cache nosetests.xml coverage.xml +coverage-*.xml *.cover .hypothesis/ .pytest_cache/ diff --git a/MANIFEST.in b/MANIFEST.in new file mode 100644 index 0000000..3802ef0 --- /dev/null +++ b/MANIFEST.in @@ -0,0 +1,5 @@ +include demo.py +include run_batch.sh +recursive-include examples *.py *.md +recursive-include tests *.py *.md +include .github/constraints-oldest.txt diff --git a/README.md b/README.md index c7c107e..8f38e1f 100644 --- a/README.md +++ b/README.md @@ -1,145 +1,250 @@ -#### 🚀 Fast multi-GPU super-resolution for Sentinel-2 imagery 🌍 — seamless weighted blending ✨ removes patch artifacts, while flexible input support (.SAFE 📂, S2GM 🛰️, GeoTIFF 🗺️) makes generating high-quality SR products effortless. +# OpenSR Utils + +Super-resolution for large geospatial rasters with PyTorch or PyTorch Lightning +models. OpenSR Utils discovers input bands, batches overlapping windows, streams +predictions to disk, and blends them into a georeferenced GeoTIFF. Plain PyTorch +modules and Lightning modules both support batched CPU, CUDA and multi-GPU inference. [![DOI](https://zenodo.org/badge/716535395.svg)](https://doi.org/10.5281/zenodo.17599309) -![img1](resources/utils_poster.png) +![OpenSR workflow](resources/utils_poster.png) - -# Description -This package performs super-resolution with any PyTorch or PyTorch lighning model for the Sentinel-2 10m bands (R-G-B-NIR). +Install the package, or include the optional pretrained model loader: -### Functionalities: -- The Input can be either: - - a **".SAFE"** - - a **".SAFE.ZIP"** zipped .SAFE folder, as they come for batched downloads from the OA-Hub - - a **"S2GM"** folder as available from the S2 Global Mosaic Hub - WARNING: opensr-model does not work w/ mosiacs - - any **".tif"** file or similar that can be loaded by rasterio (4-band RGB-NIR) -- The following is performed automatically: - - Patching of input images by selectable size (eg 128x128) - - Super-Resolution of individual patches with provided model - - writing of georeferenced output raster - - overlapping and sigmoid weightning of patches by selectable pixel amount to reduce patching artifacts - See image - - CPU, GPU and multi-GPU inference is supported via PL-Lightning - - logging including example patches and a georef .tif excerpt example form the full SR -- Supported Models: - - 'LightningModule': Any PL Lightning model with a .predict() or .forward() function. If this model type is passed, multi-GPU and multi-batch processing is activated, which leads to a significant inference speed increase. - - 'torch.nn.Module': Any SR model with a .forward() function can be passed. The drawback is that for this model type, multi-GPU and multi-batch processing is not supported. This is therefore considerably slower. +```bash +pip install opensr-utils +pip install 'opensr-utils[model]' +``` +The CI matrix covers Python **3.9–3.14**, with pinned older PyTorch/Lightning +stacks and current compatible dependencies. The full suite is also exercised +locally on Python 3.12 and 3.14. Use `opensr-utils[cog]` for COG conversion and +`opensr-utils[dev,cog]` for development. For current model installations, Python +**3.12–3.14** supports both SEN2SR and ESA SRGAN. Python 3.15 is not in the tested +matrix because [released PyTorch wheels](https://pypi.org/project/torch/#files) +currently cover interpreters only through 3.14. +## Python usage -## 🚀 Command-Line Usage +Provide an input, model and output. The device, batching, tiling, temporary +storage, stitching and cleanup have defaults: -Once installed (`pip install opensr-utils`), you can run the large-file super-resolution pipeline directly from the command line. +```python +from opensr_utils import super_resolve -### Basic Example -```bash -opensr-run /data/sentinel2_tile.SAFE LDSRS2 +output = super_resolve('scene.SAFE.zip', model='LDSRS2', output='results/scene_sr.tif') ``` -This command will: +Pass your own `torch.nn.Module` or `LightningModule` instead of a model name. +`model=None` performs bilinear interpolation and requires no pretrained weights. +The scale is taken from the model's declared `factor`, falling back to 4. +Use `factor=1` for inference without upscaling; an explicit factor must match a +named model's actual scale. -- Take the Sentinel-2 `.SAFE` folder as input -- Run the **LDSR-S2** model for 4× super-resolution -- Save outputs in the same directory (with a placeholder `.tif` and temp folder for patches) +```python +output = super_resolve( + 'scene.tif', model=my_model, output='results/sr.tif', + factor=2, batch_size=8, device='cpu', cleanup=False, +) +``` ---- +For preparation, inspection and explicit execution, the existing class remains +available. Construction prepares the run without invoking the model: -### Full Example with Options -```bash -opensr-run /data/flood_scene.tif LDSRS2 --window_size 128 128 --factor 4 --overlap 12 --eliminate_border_px 2 --device cuda --gpus 0 1 --save_preview -``` +```python +from opensr_utils import large_file_processing -**Arguments explained:** -- `root` → Path to the input file or folder (`.tif`, `.SAFE`, or S2GM). -- `model` → `LDSRS2` or `None` for the interpolation placeholder. -- `--window_size` → Patch size in LR pixels (default: `128 128`). -- `--factor` → Positive integer output scale (default: `4`; use `1` for tiled inference without upscaling). -- `--overlap` → Overlap in pixels to avoid patch seams (default: `8`). -- `--eliminate_border_px` → Pixels cut at patch edges to reduce artifacts. -- `--device` → `cpu` or `cuda` (GPU). -- `--gpus` → List of GPU IDs (e.g. `0 1`). -- `--save_preview` → Saves LR/SR preview images every 10% of progress. -- `--debug` → Process only ~100 windows for testing. -- `--overwrite` → Replace an existing `sr.tif`; otherwise existing outputs are preserved. -- `--keep_temp` → Keep temporary patch files after stitching. - ---- - -### Run as Python Module -You can also execute via Python’s `-m` flag: -```bash -python -m opensr_utils /data/flood_scene.tif LDSRS2 --device cpu +with large_file_processing( + root='scene.tif', model=my_model, output_path='results/sr.tif', factor=2, +) as job: + print(len(job.image_meta['image_windows'])) + output = job.run() ``` +The one-call API always executes once and closes raster handles. The class also +has `close()` for callers who do not use a context manager. -## 🚀 Code usage -First, download a .SAFE tile from the Copernicus Browser, a Mosaic folder from S2G, or get your RGB-NIR .tif file ready. +## SEN2SR and ESA SRGAN -#### 1. install libraries -```sql -pip install "opensr-utils[model]" -``` -#### 2. Create Model - in this case our LDSR-S2 Model -```python -from opensr_utils.model_utils.get_models import get_ldsrs2 +The named loaders return adapters for the models' actual inference contracts: + +| Name | Supported pretrained model | Python | Input/output | +| --- | --- | --- | --- | +| `SEN2SR` | SEN2SRLite `NonReference_RGBN_x4` | 3.10–3.14 | Four RGB/NIR bands, 4× scale. | +| `ESASRGAN` or `SRGAN` | ESA OpenSR SRGAN `RGB-NIR` preset | 3.12–3.14 | Four RGB/NIR bands, 4× scale. | +| `LDSRS2` | ESA LDSR-S2 | Upstream package compatibility | Four RGB/NIR bands, 4× scale. | -device = "cuda" -model = get_ldsrs2(device="cpu") +```bash +python -m pip install 'opensr-utils[sen2sr]' +python -m pip install 'opensr-utils[srgan]' ``` -#### 3. Run large-scale Inference ```python +from opensr_utils import super_resolve -# -import opensr_utils -sr_object = opensr_utils.large_file_processing( - root=path, # File or Folder path - model=model, # your SR model - window_size=(128, 128), # LR window size for model input - factor=4, # SR factor; use 1 for non-SR tiled inference - overlap=12, # overlapping pixels for mosaic stitching - eliminate_border_px=2, # No of discarded border pixels per prediction - device=device, # "cuda" for GPU-accelerated inference - gpus=[1,2,3], # pass GPU ID (int) or list of GPUs - save_preview=True, # save a low-res preview of the output, and a tif georef - debug=False, - ) - -sr_object.run() +super_resolve('scene.SAFE', 'SEN2SR', 'results/sen2sr.tif', batch_size=1) +super_resolve('scene.SAFE', 'ESASRGAN', 'results/srgan.tif', batch_size=4) ``` +SEN2SRLite expects fixed 128×128 tiles. The adapter replicate-pads smaller edge +windows and crops predictions back to their true footprint. Larger windows are +rejected clearly. The four-band adapter does not load the ten-band/full Mamba +variants. The ESA SRGAN adapter preserves the official `predict_step` path, +including histogram matching and EMA behavior; pass the adapter rather than an +unwrapped upstream Lightning module to retain those semantics. All adapters use +normalized values, explicit scales and named output bands. + +SAFE/S2GM model inputs select and order the required **B04, B03, B02, B08** bands, +ignoring other spectral channels. GeoTIFF band descriptions can identify those +bands automatically; otherwise provide four native RGB/NIR channels or explicit +1-based indexes, for example `band_indexes=[4, 5, 2, 1]` (`--bands 4 5 2 1` on CLI). +Output GeoTIFFs retain the adapter's spectral band names. + +See **[model demos and download instructions](examples/README.md)** for automatic +and offline use of official weights. The instruction script has complete help: + +```bash +python demo.py --help +python demo.py scene.tif --model none --factor 1 --output results/check.tif +python examples/run_sen2sr.py scene.SAFE.zip --batch-size 1 --output results/sen2sr.tif +python examples/run_esasrgan.py scene.tif --batch-size 4 --output results/srgan.tif +``` +`demo.py` performs no inference on import and accepts device/GPU selection, +checkpoints, configs, download/cache controls, band indexes, tiling, batching, +overwrite, retention and previews. `--device cuda:1` is a convenience for selecting +a single GPU; `--device cuda --gpus 0 1` selects multiple GPUs. +## Command line -## Overlapping Strategy -In order to avoid patching artifacts that are present in many SR products, we perform a weighting based on the distance to the edge of the patches. It can be a linear weighting, but what works best is a sigmoid weight curve which puts leads to a more even edge. Additionally, in order to eliminate edge-artifacts that are present in many SR models, it is also possible to discard a fixed number of pixels along the edges of all patches. -![img3](resources/overlay_weights.png) -![img4](resources/overlay_matrix.png) +```bash +# Pretrained LDSR-S2; model installation/download access is required. +opensr-run scene.SAFE.zip LDSRS2 -o results/scene_sr.tif -Example of Patching Artifacts in other SR models: -![img5](resources/artifact_example.png) +# Four-band pretrained models, with optional model extras installed. +opensr-run scene.SAFE SEN2SR -o results/sen2sr.tif --batch-size 1 +opensr-run scene.tif SRGAN -o results/srgan.tif --batch-size 4 -### Local Demo -Run `python demo_local.py` to generate a local overlap demo. It simulates an SR image with per-patch spectral shifts, so the edge alignment can be seen in `playground/bilinear_cross_overlap_demo/comparison_input_and_srs.png`. -![Local overlap demo](resources/local_overlap_demo.png) +# Interpolation, using the automatic device and default 4× scale. +opensr-run scene.tif -o results/interpolated.tif +# Advanced throughput and blending settings. +opensr-run scene.tif LDSRS2 -o results/sr.tif \ + --device cuda --gpus 0 1 --batch-size 8 \ + --window-size 128 128 --overlap 12 --eliminate-border-px 2 --save-preview +``` -# Citation -If you use this code in your research, please cite: +`python -m opensr_utils` provides the same interface. Existing underscore options +such as `--window_size` and `--keep_temp` remain aliases. Model-loading and +processing failures report a diagnostic and return a nonzero exit status. + +| Setting | Default | Meaning | +| --- | --- | --- | +| `output` / `-o` | `sr.tif` beside resolved input | Python class uses `output_path`; S2GM defaults inside its folder. | +| `window_size` / `--window-size` | `(128, 128)` | LR window width and height, clipped for small inputs. | +| `factor` / `--factor` | Model scale, otherwise `4` | Positive integer model scale; declared model scales are validated. | +| `overlap` / `--overlap` | `8` | Even overlap in LR pixels, smaller than both window dimensions. | +| `eliminate_border_px` / `--eliminate-border-px` | `0` | Even interior border discard in LR pixels; overlap minus discard must be at least 4 when overlap is nonzero. | +| `device` / `--device` | `auto` | CUDA when available, otherwise CPU; explicit `cpu` and `cuda` are supported. | +| `gpus` / `--gpus` | GPU 0 for CUDA | GPU index or list of indices in Python; list of IDs on CLI. | +| `batch_size` / `--batch-size` | `16` | Tune for model memory use; incomplete final batches are preserved. | +| `num_workers` / `--num-workers` | `0` | Increase for parallel raster reads when I/O limits throughput. | +| `prefetch_factor` / `--prefetch-factor` | `2` | Positive batches per worker; ignored with zero workers. | +| `output_units` / `--output-units` | Model units, otherwise `normalized` | Explicit prediction units, described below. | +| `band_indexes` / `--bands` | Model descriptions or native order | Select 1-based channels from a file in model input order. | +| `checkpoint` / `--checkpoint` | Download official preset | Local SEN2SR MLSTAC directory/export or ESA SRGAN weights. | +| `model_config` / `--config` | Preset config | ESA SRGAN YAML accompanying local weights. | +| `cache_dir` / `--cache-dir` | Loader cache | Directory for downloaded artifacts. | +| `download=False` / `--no-download` | Download permitted | Require local model artifacts. | +| `compressed_patches` / `--compressed-patches` | `False` | Smaller NPZ intermediates; NPY avoids compression overhead. | +| `cleanup=False` / `--keep-temp` | Cleanup enabled | Keep every prediction and its manifest after a successful run. | +| `overwrite` / `--overwrite` | `False` | Allow atomic replacement of a previous successful output. | +| `delete_input_zip` / `--delete-input-zip` | `False` | Delete the source ZIP only after usable input validation. | +| `save_preview` / `--save-preview` | `False` | Save inference previews, a georeferenced crop and LR/SR comparisons. | +| `debug` / `--debug` | `False` | Predict at most 100 windows, keep diagnostics, and create no final product. | + +## Input and output contracts + +Supported inputs are Rasterio-readable files, Sentinel-2 `.SAFE` directories, +ZIP archives containing a SAFE product, and S2GM band folders. SAFE/S2GM common +channels are ordered **R, G, B, NIR** (B04, B03, B02, B08), followed by additional +spectral channels on the selected grid. Auxiliary bands such as AOT, WVP and TCI +are excluded. Generic PyTorch models retain native file band order and channel count; adapters +with declared spectral inputs select named or explicitly indexed bands. +SAFE discovery prefers 10 m common bands. Bands on other-sized grids are omitted; +same-sized bands with different transforms or CRSs are rejected. No implicit +reprojection occurs. Models must accept the discovered channels; model output +channel counts may differ from input counts. LDSR-S2 expects Sentinel-2 RGB/NIR +inputs; use a model suited to mosaics for S2GM data. + +Inputs are float32 values divided by 10000 and clipped to [0,1]. Masked or +nonfinite input pixels are filled with zero for the model. Predictions must be +finite tensors shaped `(batch, channels, height * factor, width * factor)` with +matching batch and metadata sizes. They are rounded and saved as uint16: + +- `output_units='normalized'`: clip to [0,1] and multiply by 10000. +- `output_units='reflectance'`: clip existing digital-number values to [0,10000]. + +The former brightness-based units heuristic has been removed. A dark model +output of `5` means 5 DN only with `output_units='reflectance'`; the normalized +contract clips it to 1 and saves 10000 DN. Input normalization is unchanged. + +The output preserves CRS and the complete affine footprint, including rotation +and shear. Source validity is the intersection of every input band's Rasterio +mask and finite values. That validity is upscaled by nearest-neighbor mapping +into an **internal GeoTIFF mask**, independently of prediction values. Valid +zero predictions remain valid. A common source nodata value is retained if +representable as uint16; otherwise nodata metadata is cleared. The internal +mask is authoritative; values under masked pixels are unspecified. Applications +should read masks, for example with `rasterio.open(output).read(masked=True)`. + +## Output safety and diagnostics + +Source rasters are protected against output-path, symlink and hardlink +collisions. A successful run atomically publishes a staging file beside the +final destination, after every patch and full raster coverage have validated. +An overwrite failure leaves the previous output intact. Publishing without +overwrite also protects against another job creating the destination during +stitching. Successful overwrites remove stale external mask/overview sidecars. Failed runs keep +patches and diagnostics for inspection. Retention keeps the manifest and every +patch it references; use that manifest to inspect coordinates, channels and units. +Logs and temporary files have separate run-specific directories beside the output. + +Debug runs return the retained `index.json` path, even if fewer than 100 windows +exist. They never publish or replace a final raster. Run again with `debug=False` +for a complete product; normal full-coverage checks still apply. + +For multiple GPUs, pass `gpus=[0, 1]` and let Lightning launch processes. Distributed +sampling never pads or duplicates windows and permits empty ranks. Externally +launched jobs must share an output filesystem and a unique `OPENSR_RUN_ID` across +ranks before construction (an already initialized process group can share it +automatically). `LOCAL_WORLD_SIZE` describes devices per node; global rank owns +publication. Distributed tests exercise real CPU/Gloo communication, with optional +GPU coverage where hardware is available; they do not establish multi-node +filesystem or GPU-driver compatibility for every deployment. + +## Blending and development + +Overlaps use weighted accumulation so four-way intersections and valid zeros +are handled consistently. Interior border discard does not remove the outer +image boundary. The lower-level stitcher supports linear, sigmoid and cosine +profiles; the pipeline uses sigmoid weighting. + +![Overlap weighting](resources/overlay_weights.png) + +See [tests/README.md](tests/README.md) for behavior tests, branch coverage, +real JP2 fixtures, distributed checks and model-adapter contracts. The runnable +[examples](examples/README.md) explain pretrained downloads and SR product creation. + +## Citation ```bibtex -@software{Donike_OpenSR-Utils_2025, -author = {Donike, Simon and Gomez-Chova, Luis}, -license = {MIT}, -month = nov, -title = {{OpenSR-Utils}}, -url = {https://github.com/ESAOpenSR/opensr-utils}, -version = {1.2.0}, -year = {2025}, -doi = {10.5281/zenodo.17599310} +@software{Donike_OpenSR_Utils_2025, + author = {Donike, Simon and Gomez-Chova, Luis}, + title = {OpenSR-Utils}, + license = {MIT}, + url = {https://github.com/ESAOpenSR/opensr-utils}, + year = {2025}, + doi = {10.5281/zenodo.17599310} } ``` - - -#### Stats -[![Downloads](https://static.pepy.tech/badge/opensr-utils)](https://pepy.tech/project/opensr-utils) diff --git a/demo.py b/demo.py index b316754..40dd1f5 100644 --- a/demo.py +++ b/demo.py @@ -1,31 +1,287 @@ #!/usr/bin/env python3 -""" -demo.py — Minimal usage example for OpenSR +"""Instructional command-line demo for OpenSR-Utils. + +Examples:: + + python demo.py scene.tif --model none --factor 1 --output scene_sr.tif + python demo.py scene.SAFE.zip --model sen2sr --checkpoint weights.ckpt + python demo.py scene.tif --model esasrgan --device cuda --batch-size 8 -This script shows: - 1. How to instantiate an SR model from opensr-model - 2. How to run large-scale inference with opensr-utils +``--help`` does not import torch, rasterio, or optional model packages. +Model-specific dependencies and weights are described in ``examples/README.md``. """ -# --- 1) Create Model ------------------------------------------------- -device = "cuda" # or "cpu" - Dont use the automated detection, it messes up the lightning trainer multi-GPU setup -from opensr_utils.model_utils.get_models import get_ldsrs2 - -model = get_ldsrs2(device="cpu") - -# --- 2) Run large-scale Inference ------------------------------------ -import opensr_utils - -# Path can be a single .tif, a Sentinel-2 .SAFE folder, or S2GM folder -path = "/path/to/your/input_data" -sr_object = opensr_utils.large_file_processing( - root=path, # File or Folder path - model=model, # your SR model - window_size=(128, 128), # LR window size for patching - factor=4, # SR factor; use 1 for non-SR tiled inference - overlap=12, # overlapping pixels to avoid artifacts - eliminate_border_px=2, # discard border pixels - device=device, # "cuda" for GPU-accelerated inference - gpus=0, # pass GPU ID or list of GPUs -) -sr_object.run() +from __future__ import annotations + +import argparse +from pathlib import Path +from typing import Sequence + + +# Explicit per-model defaults avoid inheriting the pipeline's generic scale. +MODEL_DEFAULTS = { + "none": {"factor": 1, "window_size": (128, 128), "overlap": 0}, + "ldsrs2": { + "factor": 4, + "window_size": (128, 128), + "overlap": 12, + "eliminate_border_px": 2, + }, + "sen2sr": { + "factor": 4, + "window_size": (128, 128), + "overlap": 12, + "eliminate_border_px": 2, + }, + "srgan": { + "factor": 4, + "window_size": (128, 128), + "overlap": 12, + "eliminate_border_px": 2, + }, + "esasrgan": { + "factor": 4, + "window_size": (128, 128), + "overlap": 12, + "eliminate_border_px": 2, + }, +} + + +def build_parser() -> argparse.ArgumentParser: + """Build the parser without importing heavy or optional dependencies.""" + parser = argparse.ArgumentParser( + description="Generate a tiled super-resolution GeoTIFF from a raster or SAFE product.", + epilog="Weights are downloaded only when a model is selected; use --model none for a smoke test.", + ) + parser.add_argument( + "input", type=Path, help="GeoTIFF, SAFE directory/archive, or S2GM folder" + ) + parser.add_argument( + "--model", + default="none", + type=str.lower, + choices=sorted(MODEL_DEFAULTS), + help="Model loader (default: none; srgan and esasrgan are aliases)", + ) + parser.add_argument( + "-o", "--output", type=Path, help="Output GeoTIFF (default: beside input)" + ) + parser.add_argument( + "--checkpoint", type=Path, help="Local model checkpoint/configuration" + ) + parser.add_argument( + "--config", type=Path, help="Model configuration (used by SRGAN/ESASRGAN)" + ) + parser.add_argument( + "--variant", + choices=("lite", "NonReference_RGBN_x4"), + help="SEN2SR variant (default: lite)", + ) + parser.add_argument( + "--cache-dir", type=Path, help="Directory for downloaded model weights" + ) + parser.add_argument( + "--download", + dest="download", + action=argparse.BooleanOptionalAction, + default=True, + help="Allow model loaders to download missing weights (default: yes)", + ) + parser.add_argument( + "--device", + default="auto", + help="auto, cpu, or cuda (default: auto); cuda:N selects one GPU", + ) + parser.add_argument( + "--gpus", + type=int, + nargs="+", + metavar="ID", + help="CUDA GPU IDs when using --device cuda", + ) + parser.add_argument( + "--factor", type=int, help="Output scale (default: selected model's scale)" + ) + parser.add_argument( + "--window-size", + "--window_size", + type=int, + nargs=2, + metavar=("WIDTH", "HEIGHT"), + help="Low-resolution tile size (default: model-specific)", + ) + parser.add_argument( + "--overlap", type=int, help="Tile overlap in low-resolution pixels" + ) + parser.add_argument( + "--eliminate-border-px", + "--eliminate_border_px", + type=int, + help="Discard this many pixels from each tile border", + ) + parser.add_argument( + "--bands", + type=int, + nargs="+", + metavar="INDEX", + help="1-based GeoTIFF band indexes in model input order (for example: --bands 4 3 2 8)", + ) + parser.add_argument( + "--batch-size", + "--batch_size", + type=int, + default=16, + help="Inference batch size (default: 16)", + ) + parser.add_argument( + "--num-workers", + "--num_workers", + type=int, + default=0, + help="Data loader workers (default: 0)", + ) + parser.add_argument( + "--output-units", + "--output_units", + choices=("normalized", "reflectance"), + default="normalized", + help="Model output units (default: normalized)", + ) + parser.add_argument( + "--overwrite", + action="store_true", + help="Replace an existing output after validation", + ) + parser.add_argument( + "--keep-temp", + "--keep_temp", + action="store_true", + help="Retain prediction patches and manifest", + ) + parser.add_argument( + "--debug", + action="store_true", + help="Infer at most 100 tiles and write only a manifest", + ) + parser.add_argument( + "--save-preview", + "--save_preview", + action="store_true", + help="Write LR/SR preview images", + ) + parser.add_argument( + "--delete-input-zip", + "--delete_input_zip", + action="store_true", + help="Delete a ZIP only after successful input validation", + ) + return parser + + +def _resolved_options(args: argparse.Namespace, model=None) -> dict: + defaults = MODEL_DEFAULTS[args.model] + factor = ( + args.factor + if args.factor is not None + else getattr(model, "factor", defaults["factor"]) + ) + return { + "factor": factor, + "window_size": tuple(args.window_size) + if args.window_size + else defaults["window_size"], + "overlap": args.overlap if args.overlap is not None else defaults["overlap"], + "eliminate_border_px": ( + args.eliminate_border_px + if args.eliminate_border_px is not None + else defaults.get("eliminate_border_px", 0) + ), + } + + +def main(argv: Sequence[str] | None = None) -> int: + """Parse arguments, load the selected model, and produce one product.""" + parser = build_parser() + args = parser.parse_args(argv) + if args.model == "none" and args.checkpoint: + parser.error( + "--checkpoint requires --model; use --model none without a checkpoint" + ) + if args.variant and args.model != "sen2sr": + parser.error("--variant is only supported with --model sen2sr") + if args.config and args.model not in ("srgan", "esasrgan"): + parser.error( + "--config is only supported with --model srgan or --model esasrgan" + ) + if args.factor is not None and args.factor <= 0: + parser.error("--factor must be a positive integer") + if args.overlap is not None and args.overlap < 0: + parser.error("--overlap must be non-negative") + + model = None + if args.model != "none": + try: + from opensr_utils.model_utils.get_models import get_model + + model_options = { + "checkpoint": args.checkpoint, + "cache_dir": args.cache_dir, + "download": args.download, + } + if args.config is not None: + model_options["config"] = args.config + if args.variant is not None: + model_options["variant"] = args.variant + model = get_model(args.model, device="cpu", **model_options) + except Exception as exc: + parser.error( + f"could not load {args.model}: {exc}. Install its optional model extra or pass --checkpoint." + ) + + options = _resolved_options(args, model) + gpus = args.gpus + device = args.device + if device.startswith("cuda:"): + try: + selected = int(device.split(":", 1)[1]) + except (ValueError, IndexError): + parser.error("--device cuda:N requires a non-negative integer N") + if selected < 0: + parser.error("--device cuda:N requires a non-negative integer N") + device = "cuda" + if gpus is None: + gpus = [selected] + elif device not in ("auto", "cpu", "cuda"): + parser.error("--device must be auto, cpu, cuda, or cuda:N") + if device != "cuda" and gpus is not None: + parser.error("--gpus requires --device cuda or cuda:N") + + try: + from opensr_utils import super_resolve + + result = super_resolve( + args.input, + model=model, + output=args.output, + device=device, + gpus=gpus, + batch_size=args.batch_size, + num_workers=args.num_workers, + output_units=args.output_units, + band_indexes=args.bands, + overwrite=args.overwrite, + cleanup=not args.keep_temp, + debug=args.debug, + save_preview=args.save_preview, + delete_input_zip=args.delete_input_zip, + **options, + ) + except (OSError, RuntimeError, TypeError, ValueError) as exc: + parser.error(f"processing failed: {exc}") + print(result) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/demo_local.py b/demo_local.py deleted file mode 100755 index fc3efd9..0000000 --- a/demo_local.py +++ /dev/null @@ -1,221 +0,0 @@ -#!/usr/bin/env python3 -"""Minimal bilinear overlap demo for opensr-utils. - -The demo converts resources/example_sat_img.png into a 640x640 LR GeoTIFF, -runs the real tiled pipeline with a 4x bilinear model for three overlap -settings, and adds a small random RGB color shift to each predicted SR patch. -The comparison PNG shows how overlap blending removes those patch-edge seams. -""" - -from pathlib import Path - -import numpy as np -import rasterio -import torch -from PIL import Image, ImageDraw -from rasterio.transform import from_origin - -import opensr_utils - - -OUT_DIR = Path("playground/bilinear_cross_overlap_demo") -INPUT_PNG = Path("resources/example_sat_img.png") - -NATIVE_SIZE = 640 -TILE_SIZE = 128 -FACTOR = 4 -WINDOW_SIZE = (TILE_SIZE, TILE_SIZE) -CASES = ( - ("overlap_0", 0, 0), - ("overlap_10", 10, 0), - ("overlap_30_edge_10", 30, 10), -) - -LABEL_HEIGHT = 44 -PANEL_GUTTER = 48 -COMPARISON_PNG = OUT_DIR / "comparison_input_and_srs.png" -PATCH_COLOR_SHIFT = 0.16 -PATCH_COLOR_SEED = 20240508 - - -class TintedBilinearSRModel(torch.nn.Module): - """4x bilinear super-resolution baseline with per-patch RGB shifts.""" - - def __init__(self, factor, color_shift=PATCH_COLOR_SHIFT, seed=PATCH_COLOR_SEED): - super().__init__() - self.factor = int(factor) - self.color_shift = float(color_shift) - self.generator = torch.Generator() - self.generator.manual_seed(int(seed)) - - def forward(self, x): - sr = torch.nn.functional.interpolate( - x, - scale_factor=self.factor, - mode="bilinear", - align_corners=False, - ) - if sr.shape[1] == 1: - sr = sr.repeat(1, 3, 1, 1) - elif sr.shape[1] > 3: - sr = sr[:, :3] - - shifts = torch.empty( - (sr.shape[0], sr.shape[1], 1, 1), - dtype=sr.dtype, - device="cpu", - ) - shifts.uniform_(-self.color_shift, self.color_shift, generator=self.generator) - shifts = shifts.to(sr.device) - return torch.clamp(sr + shifts, 0.0, 1.0) - - -def load_input_image(): - image = Image.open(INPUT_PNG).convert("RGB") - if image.size != (NATIVE_SIZE, NATIVE_SIZE): - image = image.resize((NATIVE_SIZE, NATIVE_SIZE), Image.Resampling.BICUBIC) - return np.asarray(image, dtype=np.float32) / 255.0 - - -def write_input_tif(path, image): - path.parent.mkdir(parents=True, exist_ok=True) - if image.ndim == 2: - data = image[None, ...] - else: - data = np.moveaxis(image[:, :, :3], -1, 0) - data = np.round(data * 10000).astype(np.uint16) - profile = { - "driver": "GTiff", - "height": image.shape[0], - "width": image.shape[1], - "count": data.shape[0], - "dtype": "uint16", - "crs": "EPSG:3857", - "transform": from_origin(0, image.shape[0], 1, 1), - } - with rasterio.open(path, "w", **profile) as dst: - dst.write(data) - - -def read_tif_unit(path): - with rasterio.open(path) as src: - data = np.clip(src.read().astype(np.float32) / 10000.0, 0.0, 1.0) - if data.shape[0] == 1: - return data[0] - return np.moveaxis(data[:3], 0, -1) - - -def unit_image_to_pil(image): - arr = (np.clip(image, 0.0, 1.0) * 255).astype(np.uint8) - if arr.ndim == 2: - return Image.fromarray(arr, mode="L") - return Image.fromarray(arr[:, :, :3], mode="RGB") - - -def run_case(name, overlap, eliminate_border_px, image): - case_dir = OUT_DIR / name - input_tif = case_dir / "input_lr_example_sat.tif" - - write_input_tif(input_tif, image) - - runner = opensr_utils.large_file_processing( - root=str(input_tif), - model=TintedBilinearSRModel(factor=FACTOR), - window_size=WINDOW_SIZE, - factor=FACTOR, - overlap=overlap, - eliminate_border_px=eliminate_border_px, - device="cpu", - gpus=None, - batch_size=8, - num_workers=0, - cleanup=True, - overwrite=True, - ) - - sr_tif = runner.run() - sr = read_tif_unit(sr_tif) - - return { - "name": name, - "overlap": overlap, - "eliminate_border_px": eliminate_border_px, - "window_count": len(runner.image_meta["image_windows"]), - "sr_tif": Path(sr_tif), - "panel": labeled_panel( - sr, - f"Tinted 4x bilinear SR, overlap={overlap} px, edge removal={eliminate_border_px} px", - ), - } - - -def labeled_panel(image, label): - panel = Image.new("RGB", (NATIVE_SIZE, NATIVE_SIZE + LABEL_HEIGHT), "white") - draw = ImageDraw.Draw(panel) - draw.text((12, 14), label, fill=(0, 0, 0)) - preview = unit_image_to_pil(image) - if preview.size != (NATIVE_SIZE, NATIVE_SIZE): - preview = preview.resize((NATIVE_SIZE, NATIVE_SIZE), Image.Resampling.BOX) - panel.paste(preview.convert("RGB"), (0, LABEL_HEIGHT)) - return panel - - -def remove_stale_pngs(): - if not OUT_DIR.exists(): - return - for path in OUT_DIR.rglob("*.png"): - path.unlink() - - -def save_comparison(input_image, rows): - panels = [ - labeled_panel(input_image, f"Input LR native ({NATIVE_SIZE}x{NATIVE_SIZE})") - ] - for row in rows: - panels.append(row["panel"]) - - comparison = Image.new( - "RGB", - ( - NATIVE_SIZE * len(panels) + PANEL_GUTTER * (len(panels) - 1), - NATIVE_SIZE + LABEL_HEIGHT, - ), - "white", - ) - x = 0 - for idx, panel in enumerate(panels): - comparison.paste(panel, (x, 0)) - x += NATIVE_SIZE + PANEL_GUTTER - if idx < len(panels) - 1: - draw = ImageDraw.Draw(comparison) - draw.line( - [(x - PANEL_GUTTER // 2, 0), (x - PANEL_GUTTER // 2, comparison.height)], - fill=(220, 220, 220), - width=1, - ) - comparison.save(COMPARISON_PNG) - - -def main(): - remove_stale_pngs() - image = load_input_image() - - rows = [] - for name, overlap, eliminate_border_px in CASES: - row = run_case(name, overlap, eliminate_border_px, image) - rows.append(row) - print(f"{name}") - print(f" overlap: {overlap}px") - print(f" edge removal: {eliminate_border_px}px") - print(f" LR input: {NATIVE_SIZE}x{NATIVE_SIZE}px") - print(f" SR output: {NATIVE_SIZE * FACTOR}x{NATIVE_SIZE * FACTOR}px") - print(f" LR tile size: {TILE_SIZE}x{TILE_SIZE}px") - print(f" windows: {row['window_count']}") - print(f" Export: {row['sr_tif']}") - - save_comparison(image, rows) - print(f"Comparison PNG: {COMPARISON_PNG}") - - -if __name__ == "__main__": - main() diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..5372519 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,64 @@ +# Model examples + +These scripts use the same tiled, georeferenced pipeline as the public API. +They support CPU and CUDA inference. Model downloads happen only when a model +is selected and `--no-download` is absent. + +## SEN2SR RGB-NIR + +The supported adapter is SEN2SRLite `NonReference_RGBN_x4`: a 4x model trained +on fixed 128x128 low-resolution tiles. Smaller edge tiles are padded and +cropped by the adapter. It expects channels in `B04, B03, B02, B08` order. +For an unlabeled BGRN GeoTIFF, select that order explicitly with the root demo: + +```bash +python -m pip install 'opensr-utils[sen2sr]' huggingface_hub + +# Automatic model-artifact download and CPU inference. +python examples/run_sen2sr.py input.SAFE.zip --output sen2sr.tif +python examples/run_sen2sr.py input.tif --device cuda --output sen2sr.tif + +# Optional offline cache. The directory contains the downloaded mlm.json. +hf download tacofoundation/SEN2SR \ + --include 'SEN2SRLite/NonReference_RGBN_x4/**' \ + --local-dir models/SEN2SRLite_RGBN +python examples/run_sen2sr.py input.SAFE.zip \ + --checkpoint models/SEN2SRLite_RGBN/SEN2SRLite/NonReference_RGBN_x4 \ + --no-download --output sen2sr.tif + +# If a standalone raster is stored as B, G, R, N, reorder it to R, G, B, N. +python demo.py input_bgrn.tif --model sen2sr --bands 3 2 1 4 \ + --output sen2sr.tif +``` + +SEN2SR documentation: . + +## SRGAN / ESASRGAN RGB-NIR + +The supported preset is the 4-band RGB-NIR generator. Install the published +extra (Python 3.12 through 3.14), then choose either automatic or local +artifacts: + +```bash +python -m pip install 'opensr-utils[srgan]>=0.5.1' + +# Automatic preset download and CPU/GPU inference. +python examples/run_esasrgan.py input.tif --output esasrgan.tif +python examples/run_esasrgan.py input.tif --device cuda --output esasrgan.tif + +# Offline local checkpoint and matching configuration. +hf download simon-donike/SR-GAN config_RGB-NIR.yaml RGB-NIR_4band_inference.ckpt \ + --local-dir models/SR-GAN +python examples/run_esasrgan.py input.tif \ + --checkpoint models/SR-GAN/RGB-NIR_4band_inference.ckpt \ + --config models/SR-GAN/config_RGB-NIR.yaml --no-download \ + --output esasrgan.tif +``` + +SRGAN documentation: . +Source: . + +Both examples accept `--device`, `--batch-size`, `--window-size`, `--overlap`, +`--eliminate-border-px`, and `--overwrite`. The model scale is 4x by default; +use `--factor` for a compatible checkpoint with another scale. OpenSR-Utils +normalizes model inputs to [0, 1] and writes uint16 GeoTIFF products. diff --git a/examples/run_esasrgan.py b/examples/run_esasrgan.py new file mode 100755 index 0000000..52294e1 --- /dev/null +++ b/examples/run_esasrgan.py @@ -0,0 +1,88 @@ +#!/usr/bin/env python3 +"""Run an ESA OpenSR SRGAN/ESASRGAN generator through OpenSR-Utils.""" + +from __future__ import annotations + +import argparse +from pathlib import Path +import sys + + +def _source_checkout_import(): + """Allow ``python /checkout/examples/run_esasrgan.py`` from any working directory.""" + try: + import opensr_utils # noqa: F401 + except ModuleNotFoundError: + sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + + +def main(argv=None) -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument( + "input", type=Path, help="GeoTIFF, SAFE directory/archive, or S2GM folder" + ) + parser.add_argument("-o", "--output", type=Path) + parser.add_argument( + "--checkpoint", + type=Path, + help="Local checkpoint; omit for the official RGB-NIR preset", + ) + parser.add_argument( + "--config", type=Path, help="Matching local model configuration" + ) + parser.add_argument("--cache-dir", type=Path, help="Model artifact cache directory") + parser.add_argument( + "--download", + action=argparse.BooleanOptionalAction, + default=True, + help="Allow downloading the official preset when no local checkpoint is supplied", + ) + parser.add_argument("--device", default="auto") + parser.add_argument("--factor", type=int, default=4) + parser.add_argument( + "--window-size", + type=int, + nargs=2, + default=(128, 128), + metavar=("WIDTH", "HEIGHT"), + ) + parser.add_argument("--overlap", type=int, default=12) + parser.add_argument("--eliminate-border-px", type=int, default=2) + parser.add_argument("--batch-size", type=int, default=16) + parser.add_argument("--overwrite", action="store_true") + args = parser.parse_args(argv) + if args.config is not None and args.checkpoint is None: + parser.error("--config requires --checkpoint") + if not args.download and args.checkpoint is None: + parser.error("--no-download requires --checkpoint") + + _source_checkout_import() + from opensr_utils import super_resolve + from opensr_utils.model_utils.get_models import get_model + + model = get_model( + "esasrgan", + device="cpu", + checkpoint=args.checkpoint, + config=args.config, + cache_dir=args.cache_dir, + download=args.download, + ) + result = super_resolve( + args.input, + model=model, + output=args.output, + device=args.device, + factor=args.factor, + window_size=tuple(args.window_size), + overlap=args.overlap, + eliminate_border_px=args.eliminate_border_px, + batch_size=args.batch_size, + overwrite=args.overwrite, + ) + print(result) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/examples/run_sen2sr.py b/examples/run_sen2sr.py new file mode 100755 index 0000000..a0e135a --- /dev/null +++ b/examples/run_sen2sr.py @@ -0,0 +1,77 @@ +#!/usr/bin/env python3 +"""Run a SEN2SR model through OpenSR-Utils' tiled geospatial pipeline.""" + +from __future__ import annotations + +import argparse +from pathlib import Path +import sys + + +def _source_checkout_import(): + """Allow ``python /checkout/examples/run_sen2sr.py`` from any working directory.""" + try: + import opensr_utils # noqa: F401 + except ModuleNotFoundError: + sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + + +def main() -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument( + "input", type=Path, help="GeoTIFF, SAFE directory/archive, or S2GM folder" + ) + parser.add_argument("-o", "--output", type=Path) + parser.add_argument("--checkpoint", type=Path) + parser.add_argument("--cache-dir", type=Path) + parser.add_argument( + "--download", action=argparse.BooleanOptionalAction, default=True + ) + parser.add_argument( + "--variant", choices=("lite", "NonReference_RGBN_x4"), default="lite" + ) + parser.add_argument("--device", default="auto") + parser.add_argument("--factor", type=int, default=4) + parser.add_argument( + "--window-size", + type=int, + nargs=2, + default=(128, 128), + metavar=("WIDTH", "HEIGHT"), + ) + parser.add_argument("--overlap", type=int, default=12) + parser.add_argument("--eliminate-border-px", type=int, default=2) + parser.add_argument("--batch-size", type=int, default=16) + parser.add_argument("--overwrite", action="store_true") + args = parser.parse_args() + + _source_checkout_import() + from opensr_utils import super_resolve + from opensr_utils.model_utils.get_models import get_model + + model = get_model( + "sen2sr", + device="cpu", + checkpoint=args.checkpoint, + cache_dir=args.cache_dir, + variant=args.variant, + download=args.download, + ) + result = super_resolve( + args.input, + model=model, + output=args.output, + device=args.device, + factor=args.factor, + window_size=tuple(args.window_size), + overlap=args.overlap, + eliminate_border_px=args.eliminate_border_px, + batch_size=args.batch_size, + overwrite=args.overwrite, + ) + print(result) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/opensr_utils/__init__.py b/opensr_utils/__init__.py index b73cea9..ddf37c7 100644 --- a/opensr_utils/__init__.py +++ b/opensr_utils/__init__.py @@ -8,7 +8,34 @@ except Exception: __version__ = "unknown" -__all__ = ["large_file_processing", "__version__"] +__all__ = ["super_resolve", "large_file_processing", "__version__"] + + +def super_resolve(input_path, model=None, output=None, **options): + """Run tiled inference and return the output GeoTIFF path. + + ``input_path`` accepts a raster, SAFE directory/archive, or S2GM directory. + ``model`` accepts a PyTorch/Lightning module, ``"LDSRS2"``, ``"SEN2SR"``, + ``"ESASRGAN"``/``"SRGAN"``, or ``None`` for bilinear interpolation. + Named models need their optional extra. Device selection, + tiling, batching, blending, temporary storage and cleanup are automatic. + + Pass advanced options supported by :class:`large_file_processing`, such as + ``factor``, ``batch_size``, ``cleanup=False`` or ``overwrite=True``. Named + model downloads accept ``checkpoint``, ``model_config`` and ``cache_dir``. + Declared model scale and units are used automatically. Model + outputs default to normalized [0, 1]; choose ``output_units="reflectance"`` + for values already in [0, 10000]. Debug runs return their manifest path and + preserve predictions without creating a final raster. + """ + if "auto_run" in options: + raise TypeError("super_resolve always runs inference; omit auto_run.") + from .pipeline import large_file_processing + + with large_file_processing( + root=input_path, model=model, output_path=output, **options + ) as runner: + return runner.run() def __getattr__(name): diff --git a/opensr_utils/cli.py b/opensr_utils/cli.py index ed2f029..19d0298 100644 --- a/opensr_utils/cli.py +++ b/opensr_utils/cli.py @@ -1,139 +1,221 @@ -def main(): +"""Command-line interface; importing this module does not load ML dependencies.""" + +from opensr_utils.model_utils.get_models import MODEL_NAMES, normalize_model_name + + +def main(argv=None): import argparse - from opensr_utils.pipeline import large_file_processing parser = argparse.ArgumentParser( - description="🚀 Patch-based super-resolution for large geospatial rasters" + description="Tiled super-resolution for rasters, SAFE archives and S2GM folders." + ) + parser.add_argument( + "root", help="Input raster, SAFE directory/archive or S2GM folder" ) - parser.add_argument("root", type=str, help="📂 Path to input file/folder") - parser.add_argument( "model", - type=str, - choices=["LDSRS2", "None"], - help="🤖 Model to run: 'LDSRS2' or 'None'", + nargs="?", + default="None", + type=normalize_model_name, + choices=MODEL_NAMES, + help="Pretrained model (SRGAN aliases ESASRGAN), or None for interpolation", + ) + parser.add_argument( + "-o", "--output", help="Output GeoTIFF (default: sr.tif beside input)" ) - parser.add_argument( + "--window-size", "--window_size", type=int, nargs=2, default=(128, 128), - help="🔲 LR window size (default: 128 128)", + help="LR window width and height (default: 128 128)", ) parser.add_argument( "--factor", type=int, - default=4, - help="⬆️ Positive integer output scale (default: 4; use 1 for no upscaling)", + default=None, + help="Positive integer output scale (default: selected model's scale, otherwise 4)", ) parser.add_argument( - "--overlap", type=int, default=8, help="🤝 Overlap in LR pixels (default: 8)" + "--overlap", type=int, default=8, help="Overlap in LR pixels (default: 8)" ) parser.add_argument( + "--eliminate-border-px", "--eliminate_border_px", type=int, default=0, - help="✂️ Pixels to eliminate at patch borders (default: 0)", + help="Discard interior patch borders in LR pixels (default: 0)", ) parser.add_argument( "--device", - type=str, - default="cpu", - choices=["cpu", "cuda"], - help="⚡ Device for inference (default: cpu)", + default="auto", + choices=["auto", "cpu", "cuda"], + help="Inference device (default: auto)", ) + parser.add_argument("--gpus", type=int, nargs="+", help="CUDA GPU IDs (default: 0)") parser.add_argument( - "--gpus", - type=int, - nargs="+", - default=[0], - help="💻 GPU IDs to use (default: 0)", + "--output-units", + "--output_units", + choices=["normalized", "reflectance"], + default=None, + help="Model output units (default: model's declared units, otherwise normalized)", ) parser.add_argument( + "--save-preview", "--save_preview", action="store_true", - help="🖼️ Also save one georeferenced crop and 10 LR/SR previews", + help="Save a georeferenced crop and LR/SR previews", ) parser.add_argument( - "--debug", action="store_true", help="🐞 Debug mode: process only ~100 windows" + "--debug", + action="store_true", + help="Infer at most 100 windows, keep predictions, and create no final raster", ) parser.add_argument( - "--overwrite", action="store_true", help="Replace an existing sr.tif output" + "--overwrite", + action="store_true", + help="Replace existing output after successful validation", ) parser.add_argument( + "--keep-temp", "--keep_temp", action="store_true", - help="Keep temporary patch files after stitching", + help="Keep every prediction and the manifest", ) parser.add_argument( + "--delete-input-zip", "--delete_input_zip", action="store_true", - help="Delete the source .zip after successful extraction", + help="Delete source ZIP only after usable input validation", ) parser.add_argument( - "--batch_size", type=int, default=16, help="Prediction batch size (default: 16)" + "--batch-size", + "--batch_size", + type=int, + default=16, + help="Prediction batch size (default: 16)", ) parser.add_argument( + "--num-workers", "--num_workers", type=int, - default=4, - help="DataLoader worker count (default: 4)", + default=0, + help="Data loading workers (default: 0)", ) parser.add_argument( + "--prefetch-factor", "--prefetch_factor", type=int, default=2, - help="DataLoader prefetch factor when workers > 0 (default: 2)", + help="Prefetch batches per worker (default: 2)", ) parser.add_argument( + "--compressed-patches", "--compressed_patches", action="store_true", - help="Store temporary patches as compressed .npz files", + help="Store predictions as compressed NPZ instead of NPY", ) + parser.add_argument( + "--checkpoint", + help="Local SEN2SR MLSTAC directory/export, or ESA SRGAN checkpoint", + ) + parser.add_argument( + "--config", + "--model-config", + help="ESA SRGAN YAML for an official local checkpoint", + ) + parser.add_argument("--cache-dir", help="Model download/cache directory") + parser.add_argument( + "--variant", "--model-variant", help="SEN2SR RGBN variant (lite)" + ) + parser.add_argument( + "--no-download", + action="store_true", + help="Use local model artifacts without network downloads", + ) + parser.add_argument( + "--bands", + type=int, + nargs="+", + help="1-based GeoTIFF input band indexes in the model's expected order", + ) + args = parser.parse_args(argv) - args = parser.parse_args() - - # --- Resolve model selection --- - if args.model == "LDSRS2": - # Lazy import to avoid CUDA init unless needed + # Load on CPU so Lightning can select and initialize CUDA processes itself. + model = None + if args.model != "None" or any((args.checkpoint, args.config, args.variant)): try: - from opensr_utils.model_utils.get_models import get_ldsrs2 + if args.model == "LDSRS2" and not any( + ( + args.checkpoint, + args.config, + args.cache_dir, + args.variant, + args.no_download, + ) + ): + from opensr_utils.model_utils.get_models import get_ldsrs2 - device = "cpu" # "cuda" or "cpu" - Dont use the torch automated detection here, it messes up the lightning trainer multi-GPU setup - model = get_ldsrs2(device=device) + model = get_ldsrs2(device="cpu") + else: + from opensr_utils.model_utils.get_models import get_model - except Exception as e: - print("❌ Could not load LDSR-S2 model from 'opensr_model'.") - print(f" Error: {e}") - return - else: - print( - "ℹ️ From CL, you can only run the LDSR-S2 model. Using interpolation placeholder instead" - ) - model = None # placeholder/no-model mode (still stitches pipeline outputs if provided) + model = get_model( + args.model, + device="cpu", + checkpoint=args.checkpoint, + config=args.config, + cache_dir=args.cache_dir, + variant=args.variant, + download=not args.no_download, + ) + except Exception as exc: + label = "LDSR-S2" if args.model == "LDSRS2" else args.model + parser.exit( + 1, + f"Could not load {label} model. Check its optional dependencies and model artifacts.\nError: {exc}\n", + ) + factor = args.factor if args.factor is not None else getattr(model, "factor", 4) + output_units = args.output_units or getattr(model, "output_units", "normalized") + input_options = {"band_indexes": args.bands} if args.bands is not None else {} - # --- Run the pipeline --- - runner = large_file_processing( - root=args.root, - model=model, - window_size=tuple(args.window_size), - factor=args.factor, - overlap=args.overlap, - eliminate_border_px=args.eliminate_border_px, - device=args.device, - gpus=args.gpus if args.device == "cuda" else None, - save_preview=args.save_preview, - debug=args.debug, - cleanup=not args.keep_temp, - overwrite=args.overwrite, - delete_input_zip=args.delete_input_zip, - batch_size=args.batch_size, - num_workers=args.num_workers, - prefetch_factor=args.prefetch_factor, - compressed_patches=args.compressed_patches, - ) - runner.run() + from opensr_utils.pipeline import large_file_processing + + runner = None + try: + runner = large_file_processing( + root=args.root, + model=model, + output_path=args.output, + output_units=output_units, + window_size=tuple(args.window_size), + factor=factor, + overlap=args.overlap, + eliminate_border_px=args.eliminate_border_px, + device=args.device, + gpus=args.gpus if args.device != "cpu" else None, + save_preview=args.save_preview, + debug=args.debug, + cleanup=not args.keep_temp, + overwrite=args.overwrite, + delete_input_zip=args.delete_input_zip, + batch_size=args.batch_size, + num_workers=args.num_workers, + prefetch_factor=args.prefetch_factor, + compressed_patches=args.compressed_patches, + **input_options, + ) + result = runner.run() + print(result) + except (OSError, ValueError, TypeError, RuntimeError) as exc: + diagnostic = ( + f"\nDiagnostics: {runner.temp_folder}" if runner is not None else "" + ) + parser.exit(1, f"Processing failed: {exc}{diagnostic}\n") + finally: + if runner is not None: + runner.close() if __name__ == "__main__": diff --git a/opensr_utils/data_utils/datamodule.py b/opensr_utils/data_utils/datamodule.py index 0d9c1ab..a0c47d2 100644 --- a/opensr_utils/data_utils/datamodule.py +++ b/opensr_utils/data_utils/datamodule.py @@ -6,7 +6,6 @@ import os import rasterio import numpy as np -from rasterio.windows import Window from torch.utils.data import Sampler @@ -43,7 +42,9 @@ def _infer_rank_world(): if torch.distributed.is_available() and torch.distributed.is_initialized(): return torch.distributed.get_rank(), torch.distributed.get_world_size() # Fallback to env if called a bit early; OK because we only use it in predict_dataloader - rank = int(os.environ.get("LOCAL_RANK", os.environ.get("RANK", "0"))) + # RANK is the global process id. LOCAL_RANK is only a device index and + # must not be used for sharding when a launcher has supplied both. + rank = int(os.environ.get("RANK", os.environ.get("LOCAL_RANK", "0"))) world = int(os.environ.get("WORLD_SIZE", "1")) return rank, world @@ -71,6 +72,9 @@ class PredictionDataset(Dataset): Path to the raster file or folder. windows : list of rasterio.windows.Window Sliding windows defining LR patches to read. + band_indexes : sequence of int, optional + For file inputs, the 1-based Rasterio channel indexes to read, in model + order. ``None`` preserves the native all-channel behavior. Returns ------- @@ -84,15 +88,28 @@ class PredictionDataset(Dataset): ----- - Input values are divided by 10000.0 and clamped to [0,1]. - File inputs preserve the raster's native band order and band count. + - Selected file channels preserve the order supplied in ``band_indexes``. - Dictionary inputs can contain any number of bands. """ - def __init__(self, input_type, root, windows, lr_file_dict): + def __init__(self, input_type, root, windows, lr_file_dict, band_indexes=None): # Set properties self.input_type = input_type self.root = root self.windows = windows self.lr_file_dict = lr_file_dict + if band_indexes is None: + self.band_indexes = None + else: + self.band_indexes = tuple(int(index) for index in band_indexes) + if ( + not self.band_indexes + or any(index < 1 for index in self.band_indexes) + or len(set(self.band_indexes)) != len(self.band_indexes) + ): + raise ValueError( + "band_indexes must contain unique positive Rasterio band indexes." + ) self._src_cache = {} # 1. If file @@ -183,8 +200,15 @@ def get_from_file(self, idx): """ window = self.windows[idx] src = self._open_cached(self.root) - data = src.read(window=window) # np.ndarray + indexes = self.band_indexes + data = src.read(indexes=indexes, window=window) # np.ndarray data = data.astype(np.float32) + # Masking is deliberately separate from clipping: a real zero is a + # valid observation and must remain distinguishable from nodata. + valid = (src.read_masks(indexes=indexes, window=window) != 0) & np.isfinite( + data + ) + data[~valid] = 0.0 return torch.from_numpy(data) def get_from_dict(self, idx): @@ -203,13 +227,18 @@ def get_from_dict(self, idx): """ window = self.windows[idx] tiles = [] + valid = None for b in self.band_order: src = self._open_cached(self.lr_file_dict[b]) tile = src.read(1, window=window) tiles.append(tile) + band_valid = src.read_masks(1, window=window) != 0 + band_valid &= np.isfinite(tile) + valid = band_valid if valid is None else (valid & band_valid) if not tiles: raise ValueError("No input bands were configured for dictionary input.") arr = np.stack(tiles, axis=0).astype(np.float32) + arr[:, ~valid] = 0.0 return torch.from_numpy(arr) @@ -232,6 +261,9 @@ class PredictionDataModule(LightningDataModule): Number of batches to prefetch per worker. batch_size : int, default=16 Number of patches per batch. + band_indexes : sequence of int, optional + 1-based Rasterio channel indexes forwarded to ``PredictionDataset`` for + file inputs. num_workers : int, default=4 Number of worker processes for data loading. @@ -250,6 +282,7 @@ def __init__( prefetch_factor=2, batch_size=16, num_workers=4, + band_indexes=None, ): super().__init__() self.input_type = input_type @@ -259,6 +292,7 @@ def __init__( self.num_workers = num_workers self.batch_size = batch_size self.prefetch_factor = prefetch_factor + self.band_indexes = band_indexes def setup(self, stage=None): """ @@ -274,6 +308,7 @@ def setup(self, stage=None): root=self.root, windows=self.windows, lr_file_dict=self.lr_file_dict, + band_indexes=self.band_indexes, ) def predict_dataloader(self): @@ -290,6 +325,18 @@ def predict_dataloader(self): world_size=world, ) + if len(sampler) == 0: + # Lightning skips prediction hooks entirely for a zero-length + # local loader. A control-only batch keeps on_predict_start + # and on_predict_end symmetric across ranks while carrying no + # image, metadata, or fabricated inference window. + return DataLoader( + [{"_opensr_empty_rank": True}], + batch_size=1, + shuffle=False, + num_workers=0, + ) + # Pin memory only if running on CUDA pin_memory = torch.cuda.is_available() diff --git a/opensr_utils/data_utils/masking.py b/opensr_utils/data_utils/masking.py new file mode 100644 index 0000000..3ae9fca --- /dev/null +++ b/opensr_utils/data_utils/masking.py @@ -0,0 +1,145 @@ +"""Blockwise input validity and output mask handling. + +Rasterio's per-band masks are intersected, so a pixel is valid only when all +input bands consider it valid and all of their values are finite. This is +kept independent of pixel values: zero is a valid value whenever the source +mask says it is valid. +""" + +from __future__ import annotations + +import math +from contextlib import ExitStack +import numpy as np +import rasterio +from rasterio.windows import Window + + +def _source_paths(runner) -> list[str]: + meta = getattr(runner, "image_meta", {}) + paths = meta.get("lr_file_dict") or {} + if isinstance(paths, dict): + # Preserve the dataset's established band order for deterministic + # intersections, while avoiding duplicate paths. + values = paths.values() + else: + values = paths + result = [] + for path in values: + path = str(path) + if path not in result: + result.append(path) + if not result: + raise ValueError("Cannot build an input mask without source rasters") + return result + + +def _common_nodata(sources, indexes=None) -> float | int | None: + """Return a common representable nodata value, if one exists.""" + values = [] + for src in sources: + # A file may have distinct nodata values per band. They all have to + # agree for a single output nodata value to be meaningful. + nodatavals = src.nodatavals + if indexes is not None: + nodatavals = [nodatavals[index - 1] for index in indexes] + values.extend(nodatavals) + if not values or any(value is None for value in values): + return None + first = values[0] + if any(value != first for value in values[1:]): + return None + try: + value = float(first) + except (TypeError, ValueError): + return None + if not math.isfinite(value) or value < 0 or value > np.iinfo(np.uint16).max: + return None + if not value.is_integer(): + return None + return int(value) + + +def _valid_window(sources, window: Window, indexes=None) -> np.ndarray: + valid = None + for src in sources: + masks = src.read_masks(indexes=indexes, window=window) + values = src.read(indexes=indexes, window=window) + band_valid = np.all(masks != 0, axis=0) + band_valid &= np.all(np.isfinite(values), axis=0) + valid = band_valid if valid is None else (valid & band_valid) + return valid + + +def apply_input_mask(runner, dst): + """Apply the source validity mask to an upscaled output dataset. + + ``dst`` must be an open rasterio dataset in update mode. The source is + read a small LR window for each destination block and enlarged with + nearest-neighbour indexing. Rasterio writes the resulting validity as an + internal TIFF mask, so no full-resolution boolean array is retained. + + The common source nodata value is copied when it is representable by + ``uint16``; otherwise the output nodata value is cleared. The internal + mask remains authoritative, which means valid zero predictions stay + valid even when the nodata value is zero. + """ + meta = getattr(runner, "image_meta", {}) + factor = int( + meta.get("output_factor") or meta.get("factor") or getattr(runner, "factor", 1) + ) + if factor <= 0: + raise ValueError(f"Upscaling factor must be positive, got {factor}") + + paths = _source_paths(runner) + with ExitStack() as stack: + sources = [stack.enter_context(rasterio.open(path)) for path in paths] + indexes = None + if getattr(runner, "input_type", None) == "file": + indexes = meta.get("band_indexes") + if indexes is not None: + indexes = tuple(int(index) for index in indexes) + if ( + not indexes + or any(index < 1 for index in indexes) + or len(set(indexes)) != len(indexes) + or any(index > src.count for src in sources for index in indexes) + ): + raise ValueError( + "band_indexes must refer to unique positive source bands." + ) + source_width = sources[0].width + source_height = sources[0].height + if any( + src.width != source_width or src.height != source_height for src in sources + ): + raise ValueError( + "Input rasters must have matching dimensions to build a mask" + ) + + nodata = _common_nodata(sources, indexes=indexes) + # Rasterio exposes nodata as a profile value. Updating the writer's + # nodata values also ensures the value survives the atomic rename. + dst.nodata = nodata + + for _, out_win in dst.block_windows(1): + row0 = int(out_win.row_off) + col0 = int(out_win.col_off) + row1 = row0 + int(out_win.height) + col1 = col0 + int(out_win.width) + lr_row0 = row0 // factor + lr_col0 = col0 // factor + lr_row1 = min(source_height, (row1 + factor - 1) // factor) + lr_col1 = min(source_width, (col1 + factor - 1) // factor) + lr_window = Window(lr_col0, lr_row0, lr_col1 - lr_col0, lr_row1 - lr_row0) + lr_valid = _valid_window(sources, lr_window, indexes=indexes) + # Indexing avoids allocating a potentially large repeated source + # window and handles edge blocks whose dimensions are partial. + rows = (np.arange(row0, row1) // factor) - lr_row0 + cols = (np.arange(col0, col1) // factor) - lr_col0 + out_valid = lr_valid[np.ix_(rows, cols)] + dst.write_mask(np.where(out_valid, 255, 0).astype(np.uint8), window=out_win) + return dst + + +__all__ = ["apply_input_mask"] diff --git a/opensr_utils/data_utils/reading_utils.py b/opensr_utils/data_utils/reading_utils.py index 4202345..574545b 100644 --- a/opensr_utils/data_utils/reading_utils.py +++ b/opensr_utils/data_utils/reading_utils.py @@ -1,7 +1,7 @@ import rasterio -import os, shutil, zipfile +import os +import zipfile from pathlib import Path -from datetime import datetime import time @@ -71,7 +71,7 @@ def can_read_directly_with_rasterio(self, filename): if ext.lower() in supported_extensions: try: # Attempt to open the file with Rasterio to ensure it's not just a matching extension - with rasterio.open(filename) as src: + with rasterio.open(filename): return True except rasterio.errors.RasterioIOError: self._log(f"Rasterio can't open {filename}.") @@ -124,14 +124,14 @@ def create_dirs(self): """ def _is_rank0_env() -> bool: - # Works before torch.distributed init: rely on launcher env vars if present + # Global rank is authoritative when both launcher variables are present. lr = os.environ.get("LOCAL_RANK", "") r = os.environ.get("RANK", "") - ws = os.environ.get("WORLD_SIZE", "1") - if ws not in ("", "1"): # multi-process likely - # treat rank0 when both LOCAL_RANK and RANK are 0 or empty - return (lr in ("", "0")) and (r in ("", "0")) - return True # single process → rank0 + if r != "": + return r == "0" + if lr != "": + return lr == "0" + return True def _wait_until(predicate, timeout_s=600.0, sleep_s=0.1, what="dirs"): t0 = time.time() @@ -145,7 +145,27 @@ def _wait_until(predicate, timeout_s=600.0, sleep_s=0.1, what="dirs"): raise TimeoutError(f"Timed out waiting for {what} prepared by rank0.") p = Path(self.root) - if self.input_type == "SAFE": + requested_output = getattr(self, "output_path", None) + output_path = ( + Path(requested_output).expanduser() + if requested_output + else (p.parent / "sr.tif" if self.input_type == "file" else None) + ) + if output_path and self.input_type == "file": + # Resolve the default and explicit destinations before creating any dirs. + # samefile additionally catches an existing hardlink to the source. + try: + same_file = os.path.samefile(output_path, p) + except (FileNotFoundError, OSError): + same_file = False + if output_path.resolve() == p.resolve() or same_file: + raise ValueError( + "Output path must differ from the input raster; " + "writing in place is not supported." + ) + if requested_output: + base = output_path.parent + elif self.input_type == "SAFE": base = p.parent elif self.input_type == "file": base = p.parent @@ -239,9 +259,14 @@ def _dirs_ready(): # Common paths for all ranks self.placeholder_path = str(base) self.output_dir = str(base) - self.placeholder_filepath = str(base / f"sr_placeholder_{run_id}.tif") + placeholder_name = ( + f".sr_placeholder_{run_id}.tif" + if requested_output + else f"sr_placeholder_{run_id}.tif" + ) + self.placeholder_filepath = str(base / placeholder_name) self.output_file_path = self.placeholder_filepath - self.final_sr_path = str(base / "sr.tif") + self.final_sr_path = str(output_path if requested_output else base / "sr.tif") # Metadata self.image_meta["placeholder_dir"] = self.placeholder_path @@ -261,16 +286,18 @@ def verify_input_file_type(self, root): self.root → final usable path (file or folder) self.input_type → "file" | "SAFE" | "S2GM" """ - import os, time, zipfile + import os + import time from pathlib import Path def _is_rank0_env() -> bool: lr = os.environ.get("LOCAL_RANK", "") r = os.environ.get("RANK", "") - ws = os.environ.get("WORLD_SIZE", "1") - if ws not in ("", "1"): - return (lr in ("", "0")) and (r in ("", "0")) - return True # CPU/1-GPU → rank0 behavior + if r != "": + return r == "0" + if lr != "": + return lr == "0" + return True def _can_read_with_rasterio(self, path: str) -> bool: try: @@ -316,16 +343,52 @@ def _find_safe(): with zipfile.ZipFile(p, "r") as zf: _safe_extract(zf, extract_dir) - # Mark ready for other ranks + # Validate the extracted result before publishing readiness or deleting + # the source. In particular, a valid zip containing no SAFE product + # must remain available for inspection/retry. + safe_candidates = _find_safe() + if not safe_candidates: + raise NotImplementedError("🚫 Archive does not contain a .SAFE folder.") + + # Mark ready for other ranks only after extraction and validation. try: sentinel.write_text("ok") except Exception: pass - # Optionally delete zip (rank0 only). Keep the source archive by default. + # A real pipeline validates the product in get_image_meta. Defer + # deletion until that method has opened usable spectral rasters; + # Standalone callers validate readable spectral data here instead. if getattr(self, "delete_input_zip", False) and p.exists(): - p.unlink() - self._log(f"🗑️ Deleted archive: {p.name}") + if callable(getattr(self, "get_image_meta", None)): + self._pending_input_zip_delete = str(p) + else: + # Standalone callers do not run get_image_meta, so perform + # the same minimal validation here before deleting the + # source archive. + spectral_files = [ + path + for safe in safe_candidates + for path in safe.rglob("*.jp2") + if any( + token.startswith("B") and token[1:].isalnum() + for token in path.stem.split("_") + ) + ] + usable = False + for spectral_path in spectral_files: + try: + with rasterio.open(spectral_path): + usable = True + break + except Exception: + continue + if not usable: + raise FileNotFoundError( + f"No readable spectral bands found in {safe_candidates[0]}" + ) + p.unlink() + self._log(f"🗑️ Deleted archive: {p.name}") else: # Non-rank0: wait until .SAFE appears (or sentinel says ok) timeout_s = 600.0 @@ -364,7 +427,14 @@ def _find_safe(): return # ---------------- S2GM folder ---------------- - if p.is_dir() and "S2GM" in str(p): + if p.is_dir() and ( + "S2GM" in str(p) + or any( + band.stem.upper().startswith("B") and band.stem[1:].isdigit() + for band in p.rglob("*") + if band.suffix.lower() in (".tif", ".tiff") + ) + ): self.input_type = "S2GM" self._log("📁 Input is Sentinel-2 S2GM folder — processing possible! 🚀") return diff --git a/opensr_utils/data_utils/writing_utils.py b/opensr_utils/data_utils/writing_utils.py index 7367cf1..8c63f84 100644 --- a/opensr_utils/data_utils/writing_utils.py +++ b/opensr_utils/data_utils/writing_utils.py @@ -138,9 +138,10 @@ def _create_accumulator_files( profile.pop("blockxsize", None) profile.pop("blockysize", None) - with rasterio.open(sum_path, "w", **sum_profile) as sum_dst, rasterio.open( - weight_path, "w", **weight_profile - ) as weight_dst: + with ( + rasterio.open(sum_path, "w", **sum_profile) as sum_dst, + rasterio.open(weight_path, "w", **weight_profile) as weight_dst, + ): if not initialize_from_dst: return nodata = dst.nodata @@ -368,6 +369,8 @@ def coerce_to_chw_float32(x, expected_C=None): C, H, W = sr.shape if C != expected_C: raise ValueError(f"Band mismatch: dst has {expected_C} bands, SR has {C}") + if not np.isfinite(sr).all(): + raise ValueError("SR patch contains NaN or infinite values") hr_win = Window(col_off=col_off, row_off=row_off, width=W, height=H) if ( @@ -458,24 +461,17 @@ def stitch_sr_patches( limit=None, *, cleanup_every=50, + cleanup=True, profile="linear", profile_alpha=6.0, gdal_cache_mb=256, ): """ - Distributed-safe wrapper for stitching SR patches into a placeholder GeoTIFF. - - This function ensures that the expensive write phase is performed only once - (on global rank 0), while all other ranks in a distributed run return - immediately. A synchronization barrier is inserted to prevent race - conditions, using Lightning's strategy barrier when available. + Stitch staged SR patches into the placeholder GeoTIFF. - Behavior by environment - ----------------------- - - **CPU / single process**: Stitches normally. - - **Single GPU**: Stitches normally (rank 0 is the only rank). - - **Multi-GPU (DDP)**: Only rank 0 executes the stitch. Other ranks skip - and wait at a safe barrier to ensure consistent teardown. + This is the single-process write primitive. Distributed rank selection and + rank selection belongs to :func:`ddp_safe_stitch`. Publication respects + ``self.overwrite`` here as well, including concurrent destination creation. Parameters ---------- @@ -486,11 +482,16 @@ def stitch_sr_patches( Path to the ``index.json`` describing patches. Defaults to ``/index.json``. limit : int, optional - If provided, only the first ``limit`` patches are stitched (useful - for debugging). + If provided, only the first ``limit`` patches are considered. The + selected patches must still cover the complete output before it can + be published; callers needing an incomplete preview should avoid the + stitching step entirely. cleanup_every : int, default=50 - Frequency (in tiles) at which staged temporary files are deleted. - Set lower to reduce RAM usage. + Retained for API compatibility. Patch files are removed only after a + complete successful stitch, so failures leave inputs for diagnosis. + cleanup : bool, default=True + Remove consumed patch files after the output is validated and + published. Set to ``False`` to retain every patch and the manifest. profile : {"linear", "sigmoid", "cosine"}, default="linear" Feathering profile used when blending overlaps (see :func:`write_to_placeholder`). @@ -501,16 +502,11 @@ def stitch_sr_patches( Returns ------- - out : tuple or None - If run on rank 0, returns ``(sr_path, missing_count)`` from - :func:`stitch_sr_patches`. For other ranks, returns ``None``. + out : tuple + Returns ``(sr_path, missing_count)`` after successful publication. Notes ----- - - This function should always be called instead of - :func:`stitch_sr_patches` directly in distributed runs. - - Uses Lightning's barrier if available; otherwise falls back to - ``torch.distributed.barrier()`` with proper safety checks. - Recommended environment settings for stability: ``GDAL_CACHEMAX=256`` and ``GDAL_NUM_THREADS=1``. """ @@ -521,6 +517,24 @@ def stitch_sr_patches( idx = json.load(f) entries = idx["entries"] + if not isinstance(entries, list): + raise ValueError("Patch manifest 'entries' must be a list") + required = ("row_off_lr", "col_off_lr", "width_lr", "height_lr", "path") + for entry in entries: + if any(key not in entry for key in required): + raise ValueError(f"Patch manifest entry is missing one of {required}") + try: + values = [float(entry[key]) for key in required[0:4]] + except (TypeError, ValueError) as exc: + raise ValueError("Patch manifest window values must be numeric") from exc + if not np.isfinite(values).all() or any(v != int(v) for v in values): + raise ValueError("Patch manifest window values must be finite integers") + if values[0] < 0 or values[1] < 0 or values[2] <= 0 or values[3] <= 0: + raise ValueError( + "Patch manifest windows must have non-negative offsets and positive dimensions" + ) + if not isinstance(entry["path"], str) or not entry["path"]: + raise ValueError("Patch manifest entry path must be a non-empty string") entries.sort(key=lambda e: (e["row_off_lr"], e["col_off_lr"])) if limit is not None: entries = entries[: int(limit)] @@ -535,6 +549,8 @@ def stitch_sr_patches( ], } factor = int(idx.get("factor", self.factor)) + if factor <= 0: + raise ValueError("Patch manifest factor must be a positive integer") # Public overlap/eliminate_border_px are specified in LR pixels. Blending # happens on SR patches, so convert both to HR pixels. overlap = int(self.overlap) * factor @@ -552,7 +568,11 @@ def stitch_sr_patches( missing_count = 0 # 3) GDAL environment + single open - with rasterio.Env(GDAL_CACHEMAX=gdal_cache_mb, NUM_THREADS="1"): + with rasterio.Env( + GDAL_CACHEMAX=gdal_cache_mb, + NUM_THREADS="1", + GDAL_TIFF_INTERNAL_MASK=True, + ): with rasterio.open(image_meta["placeholder_path"], "r+") as dst: if expected_bands and dst.count != int(expected_bands): raise ValueError( @@ -561,85 +581,112 @@ def stitch_sr_patches( ) sum_path = _accumulator_path(image_meta["placeholder_path"], "sum") weight_path = _accumulator_path(image_meta["placeholder_path"], "weights") - try: - _create_accumulator_files( - dst, - sum_path=sum_path, - weight_path=weight_path, - initialize_from_dst=False, - ) - with rasterio.open(sum_path, "r+") as sum_dst, rasterio.open( - weight_path, "r+" - ) as weight_dst: - for i, e in enumerate( - tqdm(entries, desc="Stitching → placeholder", unit="tile"), - start=1, - ): - p = e["path"] - try: - if container == "npz" and p.endswith(".npz"): - with np.load(p) as z: - sr = z[key] - else: - sr = np.load(p) - - write_to_placeholder( - self, - sr, - i - 1, - image_meta, - factor=factor, - overlap=overlap, - eliminate_border_px=eliminate_border_px, - profile=profile, - profile_alpha=profile_alpha, - dst=dst, - sum_dst=sum_dst, - weight_dst=weight_dst, - ) - to_delete.append(p) - except FileNotFoundError: - missing_count += 1 - - # periodic flush + cleanup - if cleanup_every and (i % cleanup_every == 0): - for fp in to_delete: - try: - os.remove(fp) - except FileNotFoundError: - pass - for leftover in glob.glob(fp + ".*"): - try: - os.remove(leftover) - except FileNotFoundError: - pass - to_delete.clear() - - if limit is None and missing_count == 0: - uncovered = _count_uncovered_pixels(weight_dst) - if uncovered: - raise RuntimeError( - f"{uncovered} output pixels were not covered by any tile." - ) - finally: - for aux_path in (sum_path, weight_path): + # Failed stitches keep their accumulators; cleanup follows publication. + _create_accumulator_files( + dst, + sum_path=sum_path, + weight_path=weight_path, + initialize_from_dst=False, + ) + with ( + rasterio.open(sum_path, "r+") as sum_dst, + rasterio.open(weight_path, "r+") as weight_dst, + ): + for i, e in enumerate( + tqdm(entries, desc="Stitching → placeholder", unit="tile"), + start=1, + ): + p = e["path"] try: - os.remove(aux_path) + if container == "npz" and p.endswith(".npz"): + with np.load(p) as z: + sr = z[key] + else: + sr = np.load(p) + + write_to_placeholder( + self, + sr, + i - 1, + image_meta, + factor=factor, + overlap=overlap, + eliminate_border_px=eliminate_border_px, + profile=profile, + profile_alpha=profile_alpha, + dst=dst, + sum_dst=sum_dst, + weight_dst=weight_dst, + ) + to_delete.append(p) except FileNotFoundError: - pass + missing_count += 1 + + if missing_count == 0: + uncovered = _count_uncovered_pixels(weight_dst) + if uncovered: + raise RuntimeError( + f"{uncovered} output pixels were not covered by any tile." + ) + # Apply source validity masks while the staging dataset is + # still open for discovered raster input. + if getattr(self, "input_type", None) and getattr( + self, "image_meta", {} + ).get("lr_file_dict"): + from .masking import apply_input_mask + + apply_input_mask(self, dst) if missing_count: raise RuntimeError( f"{missing_count} patch files were missing and could not be stitched." ) - # 4) rename placeholder -> final + # 4) Publish the staging raster atomically. An existing final remains + # untouched until every patch and the coverage check have succeeded. sr_path = getattr(self, "final_sr_path", None) or image_meta[ "placeholder_path" ].replace("sr_placeholder.tif", "sr.tif") - os.replace(image_meta["placeholder_path"], sr_path) + if getattr(self, "overwrite", False): + os.replace(image_meta["placeholder_path"], sr_path) + # These describe the previous raster and must not shadow the new + # product's internal mask, pixels or metadata. Leave them untouched + # until the replacement has been successfully published. + for suffix in (".msk", ".ovr", ".aux.xml"): + try: + os.remove(sr_path + suffix) + except FileNotFoundError: + pass + else: + # An existence check alone races with other jobs. Linking within the + # destination filesystem atomically creates the name only if absent. + try: + os.link(image_meta["placeholder_path"], sr_path) + except FileExistsError as exc: + raise FileExistsError( + f"Output already exists at {sr_path}. Pass overwrite=True to replace it." + ) from exc + os.unlink(image_meta["placeholder_path"]) self.final_sr_path = sr_path + for aux_path in (sum_path, weight_path): + try: + os.remove(aux_path) + except FileNotFoundError: + pass + + if cleanup: + for fp in to_delete: + try: + os.remove(fp) + except FileNotFoundError: + pass + for leftover in glob.glob(fp + ".*"): + try: + os.remove(leftover) + except FileNotFoundError: + pass + self._log(f"🧩 Stitched {len(entries)} tiles into: {sr_path}") return sr_path, missing_count @@ -654,6 +701,7 @@ def ddp_safe_stitch( limit=None, *, cleanup_every=50, + cleanup=True, profile="linear", profile_alpha=6.0, gdal_cache_mb=256, @@ -663,8 +711,8 @@ def ddp_safe_stitch( This function ensures that the stitching phase runs only once on the global rank 0 process when using multi-GPU training with PyTorch Lightning - (DDP). All other ranks return immediately. Unlike the idempotent version, - this implementation will overwrite an existing ``sr.tif`` if found. + (DDP). All other ranks return immediately. Existing output is replaced + atomically only after a complete, validated stitch succeeds. Behavior by environment ----------------------- @@ -676,9 +724,8 @@ def ddp_safe_stitch( Overwrite policy ---------------- - If a final output file ``sr.tif`` already exists in the target folder, - it is **deleted and replaced** by a fresh stitched output. - - A warning message is printed to notify that the file will be - overwritten. + it is replaced after validation; failures leave it untouched. + - A warning message is printed to notify that the file will be replaced. - If a placeholder file ``sr_placeholder.tif`` exists, it will be used as the stitching target as normal. @@ -691,10 +738,14 @@ def ddp_safe_stitch( Path to the ``index.json`` file describing all patches. Defaults to ``/index.json``. limit : int, optional - If given, only the first ``limit`` patches are stitched (useful - for debugging). + If given, only the first ``limit`` patches are considered. They must + still cover the complete output before publication. cleanup_every : int, default=50 - Frequency (in tiles) at which staged temporary files are deleted. + Retained for API compatibility; cleanup occurs after successful + publication rather than periodically. + cleanup : bool, default=True + Remove consumed patches after successful publication. ``False`` keeps + every patch and the manifest. profile : {"linear", "sigmoid", "cosine"}, default="linear" Feathering profile used when blending overlaps (see :func:`write_to_placeholder`). @@ -748,13 +799,13 @@ def _is_rank0_local(): f"Output already exists at {sr_path}. Pass overwrite=True to replace it." ) self._log(f"⚠️ Existing output found at {sr_path} — will be overwritten.") - os.remove(sr_path) out = stitch_sr_patches( self, index_path=index_path, limit=limit, cleanup_every=cleanup_every, + cleanup=cleanup, profile=profile, profile_alpha=profile_alpha, gdal_cache_mb=gdal_cache_mb, diff --git a/opensr_utils/model_utils/__init__.py b/opensr_utils/model_utils/__init__.py index 5d673fb..7908d02 100644 --- a/opensr_utils/model_utils/__init__.py +++ b/opensr_utils/model_utils/__init__.py @@ -3,10 +3,18 @@ __all__ = [ "preprocess_model", + "get_model", + "get_ldsrs2", + "get_sen2sr", + "get_esasrgan", ] def __getattr__(name): + if name in {"get_model", "get_ldsrs2", "get_sen2sr", "get_esasrgan"}: + from . import get_models + + return getattr(get_models, name) if name == "preprocess_model": from .prepare_model import preprocess_model diff --git a/opensr_utils/model_utils/esasrgan.py b/opensr_utils/model_utils/esasrgan.py new file mode 100644 index 0000000..0d73a12 --- /dev/null +++ b/opensr_utils/model_utils/esasrgan.py @@ -0,0 +1,270 @@ +"""Adapters for the ESA OpenSR SRGAN/ESRGAN inference package. + +The ESA implementation is an optional dependency. Keeping its import inside +the loader means that installing ``opensr-utils`` does not pull in the GAN +training stack, while ``ESASRGAN`` remains an ordinary ``torch.nn.Module`` +that can be handed to :class:`opensr_utils.large_file_processing`. + +The official package currently exposes ``load_inference_model`` presets. The +adapter uses its ``predict_step`` when available, preserving the published +histogram matching and EMA inference behavior. +""" + +from __future__ import annotations + +from pathlib import Path +from typing import Any + +import torch + + +class ESASRGAN(torch.nn.Module): + """Wrap an ESA OpenSR-SRGAN model for tiled OpenSR inference. + + Parameters + ---------- + model: + An already constructed ESA SRGAN/ESRGAN model. It must implement + ``forward`` or expose a callable ``generator``. + scale_factor: + Spatial scale produced by the checkpoint. ESA's published RGB-NIR + preset is 4x; use 2 for a 20 m preset. + input_units: + ``"normalized"`` (the opensr-utils default) or ``"reflectance"`` for + Sentinel-2 DN values in [0, 10000]. + output_units: + The units returned by this adapter. The pipeline's normalized mode + expects [0, 1]; reflectance mode returns [0, 10000]. + """ + + def __init__( + self, + model: torch.nn.Module, + *, + scale_factor: int = 4, + input_units: str = "normalized", + output_units: str = "normalized", + bands: int = 4, + input_bands: tuple[str, ...] | None = None, + ) -> None: + super().__init__() + if not isinstance(model, torch.nn.Module) and not callable(model): + raise TypeError("model must be a torch.nn.Module or callable") + if ( + isinstance(scale_factor, bool) + or not isinstance(scale_factor, int) + or scale_factor <= 0 + ): + raise ValueError("scale_factor must be a positive integer") + if bands <= 0 or isinstance(bands, bool) or not isinstance(bands, int): + raise ValueError("bands must be a positive integer") + if input_units not in {"normalized", "reflectance"}: + raise ValueError("input_units must be normalized or reflectance") + if output_units not in {"normalized", "reflectance"}: + raise ValueError("output_units must be normalized or reflectance") + self.model = model + self.scale_factor = scale_factor + # ``factor`` is the name used by opensr-utils' pipeline and by other + # model adapters; retain scale_factor as the descriptive alias. + self.factor = scale_factor + self.input_units = input_units + self.output_units = output_units + self.bands = bands + self.input_bands = tuple(input_bands or ("B04", "B03", "B02", "B08")) + if len(self.input_bands) != bands: + raise ValueError("input_bands length must equal bands") + # Consumers can use this stable metadata when writing named SR bands. + self.output_bands = self.input_bands + self.output_band_names = self.input_bands + + def forward(self, x: torch.Tensor) -> torch.Tensor: + if not isinstance(x, torch.Tensor) or x.ndim != 4: + raise ValueError("ESASRGAN input must be a 4-D BCHW tensor") + if x.shape[1] != self.bands: + raise ValueError( + f"ESASRGAN expects {self.bands} channels, got {x.shape[1]}" + ) + if not torch.isfinite(x).all().item(): + raise ValueError("ESASRGAN input contains NaN or infinite values") + if self.input_units == "reflectance": + x = x / 10000.0 + with torch.inference_mode(): + # ESA's predict_step performs histogram matching and EMA-aware + # inference. Because x is explicitly normalized first, its + # normalise_10k implementation deterministically returns [0, 1]. + predict_step = getattr(self.model, "predict_step", None) + if callable(predict_step): + normalizer = getattr(self.model, "normalizer", None) + method = getattr(normalizer, "method", None) + if normalizer is not None and method != "normalise_10k": + raise ValueError( + "ESA SRGAN predict_step requires normalizer.method=" + "'normalise_10k'; use a plain generator for other units." + ) + result = predict_step(x) + else: + try: + result = self.model(x) + except (AttributeError, NotImplementedError): + generator = getattr(self.model, "generator", None) + if generator is None or not callable(generator): + raise + result = generator(x) + result = _unwrap_prediction(result) + if result.ndim != 4 or result.shape[0] != x.shape[0]: + raise ValueError("ESASRGAN model must return a BCHW tensor") + expected = (x.shape[-2] * self.scale_factor, x.shape[-1] * self.scale_factor) + if tuple(result.shape[-2:]) != expected: + raise ValueError( + f"ESASRGAN output shape {tuple(result.shape[-2:])} does not match " + f"scale_factor={self.scale_factor} (expected {expected})" + ) + if result.shape[1] != self.bands: + raise ValueError( + f"ESASRGAN returned {result.shape[1]} channels, expected {self.bands}" + ) + if not torch.isfinite(result).all().item(): + raise ValueError("ESASRGAN output contains NaN or infinite values") + result = result.clamp(0, 1) + return result * 10000.0 if self.output_units == "reflectance" else result + + +def _unwrap_prediction(value: Any) -> torch.Tensor: + """Extract a tensor from common Lightning/inference return containers.""" + if isinstance(value, torch.Tensor): + return value + if isinstance(value, dict): + for key in ("sr", "output", "prediction", "pred", "image"): + if key in value: + return _unwrap_prediction(value[key]) + if isinstance(value, (tuple, list)) and value: + return _unwrap_prediction(value[0]) + raise TypeError("ESA SRGAN model returned no tensor prediction") + + +def _load_checkpoint(path: str | Path, *, map_location: str = "cpu") -> Any: + """Load a trusted local Torch module export or serialized module checkpoint.""" + checkpoint = torch.load(Path(path), map_location=map_location, weights_only=False) + if isinstance(checkpoint, torch.nn.Module): + return checkpoint + if isinstance(checkpoint, dict) and isinstance( + checkpoint.get("model"), torch.nn.Module + ): + return checkpoint["model"] + raise ValueError( + "A local ESA SRGAN checkpoint must contain a serialized torch.nn.Module; " + "use load_inference_model for official presets." + ) + + +def load_esasrgan( + preset: str = "RGB-NIR", + *, + checkpoint: str | Path | None = None, + config_path: str | Path | None = None, + cache_dir: str | Path | None = None, + device: str | torch.device = "cpu", + scale_factor: int | None = None, + input_units: str = "normalized", + output_units: str = "normalized", + bands: int = 4, + input_bands: tuple[str, ...] | None = None, +) -> ESASRGAN: + """Load an ESA SRGAN preset or local Torch module checkpoint. + + The official ``opensr-srgan`` package is imported only when this function + is called. Loading always starts on CPU, then moves the adapter to the + requested device, avoiding accidental GPU allocation during construction. + """ + if config_path is not None: + if checkpoint is None: + raise ValueError( + "config_path requires checkpoint; refusing to construct an " + "untrained ESA SRGAN model for inference." + ) + try: + from opensr_srgan import load_from_config + except ImportError as exc: + raise ImportError( + "ESA SRGAN support requires the optional 'opensr-srgan' package; " + "install it with `python -m pip install opensr-srgan`." + ) from exc + model = load_from_config( + config_path, + checkpoint, + map_location="cpu", + mode="eval", + ) + elif checkpoint is not None: + model = _load_checkpoint(checkpoint, map_location="cpu") + else: + if preset.strip().replace("_", "-").upper() == "SWIR": + raise ValueError( + "The SWIR ESA SRGAN preset has six bands and 8x scaling; " + "use an explicit six-band adapter configuration." + ) + try: + from opensr_srgan import load_inference_model + except ImportError as exc: + raise ImportError( + "ESA SRGAN support requires the optional 'opensr-srgan' package; " + "install it with `python -m pip install opensr-srgan`." + ) from exc + model = load_inference_model( + preset, + cache_dir=cache_dir, + map_location="cpu", + ) + # Prefer architecture metadata from official configs. The public + # pipeline currently defaults to RGB-NIR; requiring explicit band labels + # for other configurations prevents silently feeding SWIR channels in the + # wrong order. + model_config = getattr(model, "config", None) + configured_bands = getattr(getattr(model_config, "Model", None), "in_bands", None) + configured_factor = getattr( + getattr(model_config, "Generator", None), "scaling_factor", None + ) + if configured_bands is not None: + configured_bands = int(configured_bands) + if configured_bands != bands and input_bands is None: + raise ValueError( + f"Loaded ESA SRGAN config expects {configured_bands} bands; " + "provide matching input_bands explicitly." + ) + bands = configured_bands + if configured_factor is not None: + configured_factor = int(configured_factor) + if scale_factor is not None and int(scale_factor) != configured_factor: + raise ValueError( + f"scale_factor={scale_factor} conflicts with loaded ESA config " + f"scaling_factor={configured_factor}." + ) + scale_factor = configured_factor + if scale_factor is None: + scale_factor = 4 + adapter = ESASRGAN( + model, + scale_factor=scale_factor, + input_units=input_units, + output_units=output_units, + bands=bands, + input_bands=input_bands, + ) + adapter.eval() + return adapter.to(torch.device(device)) + + +# Friendly aliases used by model registries and older examples. +load_srgan = load_esasrgan +load_esar = load_esasrgan +get_esasrgan = load_esasrgan +SRGAN = ESASRGAN + +__all__ = [ + "ESASRGAN", + "SRGAN", + "load_esasrgan", + "get_esasrgan", + "load_srgan", + "load_esar", +] diff --git a/opensr_utils/model_utils/get_models.py b/opensr_utils/model_utils/get_models.py index 1676f35..d91465d 100644 --- a/opensr_utils/model_utils/get_models.py +++ b/opensr_utils/model_utils/get_models.py @@ -1,32 +1,178 @@ -import requests -from omegaconf import OmegaConf -from io import StringIO -import opensr_model # your model package +"""Lazy pretrained model loaders with a shared, explicit inference interface. + +Importing this module never imports Torch or any optional model package. Models +are loaded on CPU by default; the pipeline lets Lightning place them later. +""" + +from __future__ import annotations + +from pathlib import Path + + +MODEL_NAMES = ("None", "LDSRS2", "SEN2SR", "ESASRGAN", "SRGAN") + + +def normalize_model_name(name) -> str: + """Resolve documented aliases without importing model dependencies.""" + key = ( + "NONE" + if name is None + else str(name).strip().upper().replace("-", "").replace("_", "") + ) + aliases = { + "NONE": "None", + "BILINEAR": "None", + "INTERPOLATION": "None", + "LDSRS2": "LDSRS2", + "SEN2SR": "SEN2SR", + "SEN2SRLITE": "SEN2SR", + "ESASRGAN": "ESASRGAN", + "SRGAN": "ESASRGAN", + } + try: + return aliases[key] + except KeyError as exc: + raise ValueError( + f"Unknown model {name!r}. Choose one of {', '.join(MODEL_NAMES)}." + ) from exc def get_ldsrs2(device: str = "cpu"): + """Load ESA's pretrained four-band LDSR-S2 diffusion model. + + Install ``opensr-utils[model]`` first. The model's own loader manages its + pretrained checkpoint; model construction starts on the requested device. """ - Load the LDSR-S2 model on a specified device. - - Parameters - ---------- - device : str, optional - Device to load the model on. - Options: "cpu", "cuda", "cuda:0", etc. - Default is "cpu". - - Returns - ------- - opensr_model.SRLatentDiffusion - The initialized and pretrained LDSR-S2 model. - """ - # config + from io import StringIO + + import requests + from omegaconf import OmegaConf + + try: + import opensr_model + except ImportError as exc: + raise ImportError( + "LDSR-S2 requires: python -m pip install 'opensr-utils[model]'" + ) from exc + config_url = "https://raw.githubusercontent.com/ESAOpenSR/opensr-model/refs/heads/main/opensr_model/configs/config_10m.yaml" response = requests.get(config_url, timeout=30) response.raise_for_status() config = OmegaConf.load(StringIO(response.text)) - - # model model = opensr_model.SRLatentDiffusion(config, device=device) model.load_pretrained(config.ckpt_version) return model + + +def get_sen2sr(*args, **kwargs): + """Load the supported SEN2SRLite RGBN adapter; see ``sen2sr.load_sen2sr``.""" + from .sen2sr import load_sen2sr + + return load_sen2sr(*args, **kwargs) + + +def get_esasrgan(*args, **kwargs): + """Load ESA's RGB-NIR SRGAN adapter; see ``esasrgan.load_esasrgan``.""" + from .esasrgan import load_esasrgan + + return load_esasrgan(*args, **kwargs) + + +def get_model( + name, + *, + device="cpu", + checkpoint=None, + config=None, + cache_dir=None, + variant=None, + download=True, + **model_options, +): + """Load a named model, with downloads and local artifacts kept explicit. + + ``SEN2SR`` uses the four-band SEN2SRLite RGBN model. A local ``checkpoint`` + can name its MLSTAC directory/manifest, or a supported exported model file. + ``ESASRGAN`` and ``SRGAN`` are aliases for ESA's RGB-NIR preset; official + local state dictionaries require both ``config`` and ``checkpoint``. + ``None`` selects interpolation and returns ``None`` for the pipeline. + + ``download=False`` requires local artifacts and never falls back to a + remote preset. Advanced adapter options may be passed as keyword arguments. + """ + name = normalize_model_name(name) + if name == "None": + if ( + checkpoint is not None + or config is not None + or variant is not None + or model_options + ): + raise ValueError( + "Interpolation does not use model checkpoints, configuration or variants." + ) + return None + if name == "LDSRS2": + if ( + checkpoint is not None + or config is not None + or cache_dir is not None + or variant is not None + or not download + or model_options + ): + raise ValueError( + "LDSRS2 uses its upstream pretrained loader; checkpoint/config/cache/variant overrides and offline loading are not supported here." + ) + return get_ldsrs2(device=device) + if name == "SEN2SR": + if config is not None: + raise ValueError( + "SEN2SR uses an MLSTAC manifest; pass its directory with checkpoint= instead of config=." + ) + if not download and checkpoint is None: + raise ValueError( + "Offline SEN2SR loading requires local checkpoint artifacts." + ) + options = dict( + device=device, cache_dir=cache_dir, download=download, **model_options + ) + if variant is not None: + options["variant"] = variant + if checkpoint is not None: + path = Path(checkpoint).expanduser() + if path.is_dir() or path.name == "mlm.json": + options["model_dir"] = path if path.is_dir() else path.parent + else: + options["checkpoint"] = path + return get_sen2sr(**options) + if variant is not None: + raise ValueError( + "variant is a SEN2SR option; ESA SRGAN uses the RGB-NIR preset." + ) + if not download: + if checkpoint is None: + raise ValueError( + "Offline ESA SRGAN loading requires a local checkpoint (and config for official state dictionaries)." + ) + if not Path(checkpoint).expanduser().is_file(): + raise FileNotFoundError( + f"Local ESA SRGAN checkpoint does not exist: {checkpoint}" + ) + return get_esasrgan( + device=device, + checkpoint=checkpoint, + config_path=config, + cache_dir=cache_dir, + **model_options, + ) + + +__all__ = [ + "MODEL_NAMES", + "normalize_model_name", + "get_model", + "get_ldsrs2", + "get_sen2sr", + "get_esasrgan", +] diff --git a/opensr_utils/model_utils/prepare_model.py b/opensr_utils/model_utils/prepare_model.py index 53ccc40..31d8a58 100644 --- a/opensr_utils/model_utils/prepare_model.py +++ b/opensr_utils/model_utils/prepare_model.py @@ -1,90 +1,21 @@ +"""Wrap SR models for streamed inference and collective manifest finalization. + +Each rank persists patches and a shard index. All ranks exchange write status; +rank zero validates and atomically publishes the merged index. Hooks are bound +on preparation so plain PyTorch and Lightning models share the same workflow. +""" + import os import json import torch import numpy as np from pytorch_lightning import LightningModule import time -import glob import math +from numbers import Integral +from datetime import timedelta from PIL import Image -""" -Multi-GPU SR Inference Workflow -================================ - - ┌─────────────┐ - │ Trainer.run │ - └──────┬──────┘ - │ - ▼ - ┌─────────────────────────┐ - │ Each GPU rank executes: │ - └──────────┬──────────────┘ - │ - ▼ - [on_predict_start] - │ Initialize: - │ - rank/world_size - │ - temp folder - │ - local entries[] - ▼ - [predict_step] - │ For each batch: - │ - Run model (SR patch) - │ - Save patch → temp/sr_rXXXX_cXXXX.npz - │ - Append offsets + path to entries[] - ▼ - [on_predict_end] - │ Write shard index_rank{r}.json - │ - │───► DDP barrier ───(all ranks wait)───┐ - │ │ - ▼ │ - Rank >0: │ Rank 0: - - Finished │ - Collect all shard JSONs - - Optionally delete shards │ - Merge entries[] - │ - Deduplicate + sort - │ - Write global index.json - │ - Clean up shard files - ▼ - ┌───────────────┐ - │ index.json │ - │ (global list) │ - └───────────────┘ -""" - - -""" -Module: preprocess_model - -Provides utilities to wrap a PyTorch or Lightning model for distributed -super-resolution (SR) inference. The core workflow integrates with PyTorch -Lightning’s `.predict()` loop: - -1. **Model wrapping** - - Accepts a plain `torch.nn.Module`, `LightningModule`, or `None`. - - If `None`, a placeholder bilinear upsampling model is used. - - If plain torch model, it is wrapped into a minimal LightningModule. - -2. **Hook injection** - - Adds `on_predict_start`, `predict_step`, and `on_predict_end` hooks. - - These hooks handle patch inference, saving results to disk, and writing - per-rank index files. - -3. **Distributed execution (DDP)** - - Each GPU rank saves its own shard (`index_rank{r}.json`). - - Synchronization barrier ensures all ranks finish writing. - - Rank 0 merges shards into a global `index.json` in deterministic order. - -4. **Temporary storage** - - SR patches are saved to `.npz` files in `temp/`. - - Index JSON stores file paths, LR/HR offsets, and dimensions. - -This design allows inference on arbitrarily large raster datasets across -multiple GPUs without memory bottlenecks. Patches are streamed to disk and -stitched later. -""" - # ------------------------------------------------------------------------- # Placeholder interpolation model @@ -125,28 +56,40 @@ def predict(self, x): def get_world_info(): - """ - Return (world_size, rank) in a robust way: - - CPU or single-GPU: world_size = 1 - - Multi-GPU DDP: world_size = number of GPUs (world size) - """ + """Return process world size and global rank, regardless of visible GPUs.""" ddp = torch.distributed.is_available() and torch.distributed.is_initialized() if ddp: world_size = torch.distributed.get_world_size() rank = torch.distributed.get_rank() else: - # if CUDA is available, check how many GPUs are visible - gpu_count = torch.cuda.device_count() if torch.cuda.is_available() else 0 - world_size = gpu_count if gpu_count > 1 else 1 - rank = 0 + world_size = int(os.environ.get("WORLD_SIZE", "1")) + rank = int(os.environ.get("RANK", os.environ.get("LOCAL_RANK", "0"))) return world_size, rank +def _distributed_barrier(timeout_seconds=30): + """Synchronize ranks while turning gloo failures into regular exceptions.""" + dist = torch.distributed + backend = None + try: + backend = dist.get_backend() + except (AttributeError, RuntimeError, ValueError): + pass + if backend == "gloo" and hasattr(dist, "monitored_barrier"): + try: + return dist.monitored_barrier(timeout=timedelta(seconds=timeout_seconds)) + except TypeError: # older torch versions have no timeout parameter + return dist.monitored_barrier() + return dist.barrier() + + # ------------------------------------------------------------------------- # Preprocessor that also attaches predict_step + hooks that save predictions to disk -def preprocess_model(self, model, temp_folder, windows, factor): +def preprocess_model( + self, model, temp_folder, windows, factor, output_units="normalized" +): """ Prepare a model for distributed patch-based super-resolution inference. @@ -164,6 +107,10 @@ def preprocess_model(self, model, temp_folder, windows, factor): List of LR windows corresponding to input patches. factor : int Positive integer output scale. Use 1 for models that preserve resolution. + output_units : {"normalized", "reflectance"}, default="normalized" + Interpretation of model predictions before persistence. Normalized values + are clipped to [0, 1] and scaled to uint16 [0, 10000]; reflectance/DN + values are clipped directly to [0, 10000]. Returns ------- @@ -203,6 +150,15 @@ def preprocess_model(self, model, temp_folder, windows, factor): if not isinstance(factor, int) or isinstance(factor, bool) or factor <= 0: raise ValueError("factor must be a positive integer.") factor = int(factor) + unit_aliases = { + "normalized": "normalized", + "normalised": "normalized", + "reflectance": "reflectance", + "dn": "reflectance", + } + units = unit_aliases.get(str(output_units).strip().lower()) + if units is None: + raise ValueError("output_units must be 'normalized' or 'reflectance'.") # --- define hooks here so they stay out of the global namespace --- def _rank_world(self): @@ -260,13 +216,34 @@ def predict_step(self, batch, batch_idx, dataloader_idx=0): - Handles both dict-of-lists (PL default) and list-of-dict meta formats. - Saves filenames as `sr_r{row_off_hr}_c{col_off_hr}.npz`. """ + # An empty rank needs hooks to run, but has no image to infer. + if "_opensr_empty_rank" in batch: + return None x = batch["image"] # (B,C,H,W) tensor meta = batch["meta"] # list[dict] or dict of lists + if not isinstance(x, torch.Tensor) or x.ndim != 4: + raise ValueError("Input batch image must be a 4-D tensor (B,C,H,W).") + input_batch = int(x.shape[0]) sr = self.predict(x) if hasattr(self, "predict") else self.forward(x) + if not isinstance(sr, torch.Tensor) or sr.ndim != 4: + raise ValueError("Model output must be a 4-D tensor (B,C,H,W).") + if int(sr.shape[0]) != input_batch: + raise ValueError( + "Model output batch size does not match input batch size: " + f"got {int(sr.shape[0])}, expected {input_batch}." + ) + if not torch.isfinite(sr).all().item(): + raise ValueError( + "Model output contains NaN or infinite values; predictions must be finite." + ) sr = sr.detach().cpu() # (B,C,Hh,Ww) scale = int(self._save_factor) B, C, Hh, Ww = sr.shape + if C <= 0 or Hh <= 0 or Ww <= 0: + raise ValueError( + "Model output must have positive channel and spatial dimensions." + ) if self._output_bands is None: self._output_bands = int(C) elif int(C) != int(self._output_bands): @@ -275,10 +252,74 @@ def predict_step(self, batch, batch_idx, dataloader_idx=0): ) # meta may be a dict of lists (PL default); normalize to per-sample dicts - if isinstance(meta, dict) and isinstance(meta["row_off"], torch.Tensor): - meta = [{k: int(v[i].item()) for k, v in meta.items()} for i in range(B)] - elif isinstance(meta, dict): - meta = [{k: int(v[i]) for k, v in meta.items()} for i in range(B)] + if isinstance(meta, dict): + required = ("row_off", "col_off", "height", "width") + missing = [key for key in required if key not in meta] + if missing: + raise ValueError( + f"Prediction metadata is missing required fields: {', '.join(missing)}." + ) + try: + lengths = {len(value) for value in meta.values()} + except TypeError as exc: + raise ValueError( + "Prediction metadata values must be batched sequences." + ) from exc + if lengths != {B}: + raise ValueError( + f"Prediction metadata batch size does not match input batch size ({B})." + ) + meta = [ + { + k: v[i].item() if isinstance(v, torch.Tensor) else v[i] + for k, v in meta.items() + } + for i in range(B) + ] + elif isinstance(meta, (list, tuple)): + if len(meta) != B: + raise ValueError( + f"Prediction metadata batch size does not match input batch size ({B})." + ) + meta = list(meta) + else: + raise ValueError( + "Prediction metadata must be a dict of batches or a list of records." + ) + for i, record in enumerate(meta): + missing = [ + key + for key in ("row_off", "col_off", "height", "width") + if key not in record + ] + if missing: + raise ValueError( + f"Prediction metadata record {i} is missing: {', '.join(missing)}." + ) + for key in ("row_off", "col_off", "height", "width"): + value = record[key] + if isinstance(value, torch.Tensor) and value.numel() == 1: + value = value.item() + if isinstance(value, bool) or not isinstance(value, Integral): + raise ValueError( + f"Prediction metadata record {i} requires an integer {key}." + ) + record[key] = int(value) + if record[key] < 0 and key in ("row_off", "col_off"): + raise ValueError( + f"Prediction metadata record {i} has a negative {key}." + ) + if record[key] <= 0 and key in ("height", "width"): + raise ValueError( + f"Prediction metadata record {i} has non-positive {key}." + ) + expected_h = record["height"] * scale + expected_w = record["width"] * scale + if Hh != expected_h or Ww != expected_w: + raise ValueError( + f"Model output shape {Hh}x{Ww} does not match expected " + f"{expected_h}x{expected_w} for factor {scale} (record {i})." + ) for i in range(B): mi = meta[i] @@ -286,18 +327,8 @@ def predict_step(self, batch, batch_idx, dataloader_idx=0): col_off_lr = mi["col_off"] row_off_hr = row_off_lr * scale col_off_hr = col_off_lr * scale - expected_h = mi["height"] * scale - expected_w = mi["width"] * scale - if Hh != expected_h or Ww != expected_w: - raise ValueError( - f"Model output shape {Hh}x{Ww} does not match expected " - f"{expected_h}x{expected_w} for factor {scale}." - ) - s = sr[i] # (C,Hh,Ww) float - mean_val = float(torch.mean(s)) - # simple range heuristic: [0,1] vs already ~[0,10000] - if mean_val < 10: + if units == "normalized": s = torch.clamp(s, 0.0, 1.0) * 10000.0 else: s = torch.clamp(s, 0.0, 10000.0) @@ -364,8 +395,9 @@ def predict_step(self, batch, batch_idx, dataloader_idx=0): lr_rgb = (((lr_rgb) * gain) * 255.0).astype(np.uint8).clip(0, 255) # CHW -> HWC for PIL - rgb, lr_rgb = np.transpose(rgb, (1, 2, 0)), np.transpose( - lr_rgb, (1, 2, 0) + rgb, lr_rgb = ( + np.transpose(rgb, (1, 2, 0)), + np.transpose(lr_rgb, (1, 2, 0)), ) # save @@ -384,146 +416,163 @@ def predict_step(self, batch, batch_idx, dataloader_idx=0): return None - def on_predict_end(self): - """ - Hook executed once prediction finishes. - - Workflow - -------- - 1. Write per-rank shard JSON: - - Contains rank, world_size, factor, saved dtype/scale, and patch entries. - 2. Synchronize ranks via `torch.distributed.barrier()` (if DDP). - 3. Rank 0 collects shard JSONs: - - Waits for all shards to exist. - - Reads entries, merges, deduplicates, sorts by LR offsets. - - Writes merged global `index.json`. - 4. Cleanup: - - Deletes shard JSONs (optional). - - Deletes leftover partial files (optional). - - Multi-GPU Details - ----------------- - - Each GPU saves only the patches it predicted. - - Index merging ensures a single consistent record of all patches. - - Sorting by (row_off_lr, col_off_lr) guarantees deterministic order. - - Prints - ------ - - Per-rank: number of entries written. - - Rank 0: total merged entries and output path of `index.json`. - """ - shard = { - "rank": self._rank, - "world_size": self._world, + def manifest_metadata(self): + return { "factor": int(self._save_factor), "output_bands": int(self._output_bands or 0), - "entries": self._entries, "saved_dtype": "uint16", "saved_scale": 10000, + "output_units": units, "saved_container": "npz" if self._save_compressed else "npy", "saved_key": "arr", } - shard_path = os.path.join( - self._save_temp_folder, f"index_rank{self._rank}.json" + + def write_manifest(path, data): + # Readers see complete JSON, even on a slow shared filesystem. + part = path + ".part" + with open(part, "w", encoding="utf-8") as stream: + json.dump(data, stream, separators=(",", ":")) + stream.flush() + os.fsync(stream.fileno()) + os.replace(part, path) + + def merge_shards(self, world): + """Validate and publish a deterministic index; retain shards on failure.""" + paths = [ + os.path.join(self._save_temp_folder, f"index_rank{rank}.json") + for rank in range(world) + ] + # Permit a short metadata-visibility delay on shared filesystems. + for _ in range(50): + if all(os.path.exists(path) for path in paths): + break + time.sleep(0.05) + + metadata = manifest_metadata(self) + output_bands = None + entries = [] + for path in paths: + if not os.path.exists(path): + raise RuntimeError(f"Missing prediction shard index: {path}") + with open(path, encoding="utf-8") as stream: + shard = json.load(stream) + for field in ( + "factor", + "saved_dtype", + "saved_scale", + "output_units", + "saved_container", + ): + if field in shard and shard[field] != metadata[field]: + raise ValueError(f"Prediction shards disagree on {field}.") + bands = shard.get("output_bands") + if bands: + if output_bands is not None and int(bands) != output_bands: + raise ValueError( + "Prediction shards disagree on output band count: " + f"{output_bands} vs {bands}." + ) + output_bands = int(bands) + entries.extend(shard.get("entries", [])) + + # Duplicate records from the same patch are harmless. Distinct windows + # must remain in deterministic row/column order for reproducibility. + unique = {} + for entry in entries: + key = (entry["row_off_lr"], entry["col_off_lr"], entry["path"]) + unique.setdefault(key, entry) + entries = sorted( + unique.values(), + key=lambda entry: (entry["row_off_lr"], entry["col_off_lr"]), + ) + entry_bands = {int(entry["bands"]) for entry in entries if entry.get("bands")} + if len(entry_bands) > 1 or ( + entry_bands and output_bands is not None and entry_bands != {output_bands} + ): + raise ValueError("Prediction entries disagree on output band count.") + metadata["output_bands"] = output_bands or next(iter(entry_bands), 0) + write_manifest( + os.path.join(self._save_temp_folder, "index.json"), + {**metadata, "entries": entries}, ) - with open(shard_path, "w") as f: - json.dump(shard, f, separators=(",", ":")) # compact - f.flush() - os.fsync(f.fileno()) - # print(f"[rank {self._rank}] wrote {len(self._entries)} entries → {shard_path}") - - # ---- DDP sync ---- - ddp = torch.distributed.is_available() and torch.distributed.is_initialized() + for path in paths: + os.remove(path) + + def on_predict_end(self): + """Persist every shard and exchange errors at matching collective phases. + + Every live rank reaches the barrier even if its local write failed. + After synchronization, all ranks exchange write status before rank zero + merges. Merge errors are broadcast so workers cannot report success. + A failed barrier exits directly: another collective on a broken group + could hang. The launcher's process-group timeout bounds other collectives. + """ + dist = torch.distributed + ddp = dist.is_available() and dist.is_initialized() + backend = None if ddp: - torch.distributed.barrier() - - # ---- Merge on rank 0 (or single-process) ---- - if (not ddp) or (torch.distributed.get_rank() == 0): - world = self._world if ddp else 1 - shard_paths = [ - os.path.join(self._save_temp_folder, f"index_rank{r}.json") - for r in range(world) - ] + try: + backend = dist.get_backend() + except (AttributeError, RuntimeError, ValueError): + pass # Lightweight tests may supply only rank/barrier metadata. - # (Optional) wait briefly if FS is slow - for _ in range(50): - if all(os.path.exists(p) for p in shard_paths): - break - time.sleep(0.05) - - merged_entries = [] - meta = { - "factor": int(self._save_factor), - "output_bands": None, - "saved_dtype": "uint16", - "saved_scale": 10000, - "saved_container": "npz" if self._save_compressed else "npy", - "saved_key": "arr", - } - for p in shard_paths: - if not os.path.exists(p): - raise RuntimeError(f"Missing prediction shard index: {p}") - with open(p) as f: - data = json.load(f) - shard_bands = data.get("output_bands") - if shard_bands: - if meta["output_bands"] is None: - meta["output_bands"] = int(shard_bands) - elif int(shard_bands) != int(meta["output_bands"]): - raise ValueError( - "Prediction shards disagree on output band count: " - f"{meta['output_bands']} vs {shard_bands}." - ) - merged_entries.extend(data.get("entries", [])) - - # dedupe & deterministic order - # key by LR offsets + path (handles accidental dupes) - seen = set() - uniq = [] - for e in merged_entries: - k = (e["row_off_lr"], e["col_off_lr"], e["path"]) - if k not in seen: - seen.add(k) - uniq.append(e) - uniq.sort(key=lambda e: (e["row_off_lr"], e["col_off_lr"])) - entry_bands = {int(e["bands"]) for e in uniq if e.get("bands")} - if len(entry_bands) > 1: - raise ValueError( - f"Prediction entries disagree on output band count: {sorted(entry_bands)}." - ) - if meta["output_bands"] is None and entry_bands: - meta["output_bands"] = entry_bands.pop() - if meta["output_bands"] is None: - meta["output_bands"] = 0 - - merged = {**meta, "entries": uniq} - merged_path = os.path.join(self._save_temp_folder, "index.json") - with open(merged_path, "w") as f: - json.dump(merged, f, separators=(",", ":")) - f.flush() - os.fsync(f.fileno()) - # print(f"[rank 0] merged {len(uniq)} entries → {merged_path}") - - # CleanUp + original_error = None + error = None try: - KEEP_SHARDS = False # toggle for debugging - KEEP_PARTS = False # toggle for debugging - if not KEEP_SHARDS: - for p in shard_paths: - try: - os.remove(p) - except FileNotFoundError: - pass - - # optional: nuke partials - if KEEP_PARTS == False: - for p in glob.glob(os.path.join(self._save_temp_folder, "*.part")): - try: - os.remove(p) - except FileNotFoundError: - pass - except UnboundLocalError: - pass # If we're in single GPU, or in CPU, these variables dont exist + write_manifest( + os.path.join(self._save_temp_folder, f"index_rank{self._rank}.json"), + { + **manifest_metadata(self), + "rank": self._rank, + "world_size": self._world, + "entries": self._entries, + }, + ) + except Exception as exc: + original_error = exc + error = f"{type(exc).__name__}: {exc}" + + if ddp: + try: + _distributed_barrier(getattr(self, "_save_sync_timeout", 30)) + except Exception as exc: + raise RuntimeError( + f"Distributed prediction finalization failed: synchronization barrier: {exc}" + ) from exc + + if backend is not None: + statuses = [None] * self._world + try: + dist.all_gather_object(statuses, error) + except Exception as exc: + raise RuntimeError( + f"Distributed prediction finalization failed: write-status exchange: {exc}" + ) from exc + error = next((status for status in statuses if status is not None), None) + if error is not None: + if backend is None: + raise original_error + raise RuntimeError(f"Distributed prediction finalization failed: {error}") + + if not ddp or self._rank == 0: + try: + merge_shards(self, self._world if ddp else 1) + except Exception as exc: + original_error = exc + error = f"{type(exc).__name__}: {exc}" + if backend is not None: + status = [error] + try: + dist.broadcast_object_list(status, src=0) + except Exception as exc: + raise RuntimeError( + f"Distributed prediction finalization failed: merge-status exchange: {exc}" + ) from exc + error = status[0] + if error is not None: + if backend is None: + raise original_error + raise RuntimeError(f"Distributed prediction finalization failed: {error}") # --------------------------------------------------------------------- # Attach hooks to model @@ -589,4 +638,5 @@ def predict(self, x): model._save_temp_folder = temp_folder model._save_windows = windows model._save_factor = factor + model._save_output_units = units return model diff --git a/opensr_utils/model_utils/sen2sr.py b/opensr_utils/model_utils/sen2sr.py new file mode 100644 index 0000000..7dce1b9 --- /dev/null +++ b/opensr_utils/model_utils/sen2sr.py @@ -0,0 +1,222 @@ +"""Adapters and loaders for the ESAOpenSR SEN2SR models. + +The upstream ``sen2sr`` package uses MLSTAC manifests rather than exposing a +stable PyTorch constructor. This module keeps that detail at the boundary so +the rest of OpenSR Utils can consume an ordinary ``torch.nn.Module``. The +default is the small, CPU-capable ``SEN2SRLite`` RGBN model. +""" + +from __future__ import annotations + +from pathlib import Path +import tempfile + +import torch +from torch import Tensor, nn + + +DEFAULT_VARIANT = "NonReference_RGBN_x4" +MODEL_REPOSITORY = "https://huggingface.co/tacofoundation/sen2sr/resolve/main" +VARIANT_MANIFESTS = { + "nonreference_rgbn_x4": "SEN2SRLite/NonReference_RGBN_x4/mlm.json", + "sen2srlite_nonreference_rgbn_x4": "SEN2SRLite/NonReference_RGBN_x4/mlm.json", + "lite": "SEN2SRLite/NonReference_RGBN_x4/mlm.json", +} + + +def _device(value: str | torch.device) -> torch.device: + target = torch.device(value) + if target.type == "cuda" and not torch.cuda.is_available(): + raise RuntimeError("SEN2SR requested CUDA, but CUDA is not available") + return target + + +class SEN2SRAdapter(nn.Module): + """Validate and adapt a loaded SEN2SR model for OpenSR Utils. + + The RGBN model expects channels in ``B04, B03, B02, B08`` order and input + values normalized to reflectance ``[0, 1]``. A batch of shape + ``(batch, 4, height, width)`` is returned as ``(batch, 4, height*4, + width*4)``. Validation here gives the pipeline an actionable error before + a less clear convolution or manifest error occurs. + """ + + input_bands = ("B04", "B03", "B02", "B08") + output_bands = input_bands + output_band_names = input_bands + input_units = "normalized" + input_size = (128, 128) + max_window_size = input_size + factor = 4 + output_units = "normalized" + + def __init__(self, model: nn.Module, *, device: str | torch.device = "cpu"): + super().__init__() + if not isinstance(model, nn.Module) and not callable(model): + raise TypeError("model must be a torch.nn.Module or callable") + self.model = model + # ``.to(...)`` may be called later by Lightning/DDP. Do not cache the + # initial device: forward() discovers the module's current placement. + self.requested_device = _device(device) + self._register_hard_constraint_masks() + self.to(self.requested_device) + self.eval() + + def _register_hard_constraint_masks(self) -> None: + """Make SEN2SR's plain Fourier mask tensor follow device placement. + + The upstream ``HardConstraint`` stores ``low_pass_mask`` as a regular + tensor rather than a registered buffer. Registering the known tensor + as nonpersistent preserves the upstream checkpoint format while making + ``.to(cuda)`` and Lightning/DDP placement correct. + """ + for module in self.modules(): + mask = getattr(module, "low_pass_mask", None) + if isinstance(mask, Tensor) and "low_pass_mask" not in module._buffers: + delattr(module, "low_pass_mask") + module.register_buffer("low_pass_mask", mask, persistent=False) + + def forward(self, x: Tensor) -> Tensor: + if not isinstance(x, Tensor): + raise TypeError("SEN2SR input must be a torch.Tensor") + if x.ndim != 4: + raise ValueError("SEN2SR input must have shape (batch, 4, height, width)") + if x.shape[1] != 4: + raise ValueError( + "SEN2SR RGBN expects four channels in B04,B03,B02,B08 order; " + f"received {x.shape[1]}" + ) + height, width = (int(x.shape[2]), int(x.shape[3])) + if height > self.input_size[0] or width > self.input_size[1]: + raise ValueError( + "SEN2SR RGBN accepts input tiles no larger than 128x128 " + f"(the upstream hard constraint is fixed at 512x512); received {(height, width)}" + ) + if min(x.shape[0], x.shape[2], x.shape[3]) <= 0: + raise ValueError("SEN2SR input dimensions must be positive") + if not torch.is_floating_point(x): + x = x.float() + if not torch.isfinite(x).all().item(): + raise ValueError("SEN2SR input contains NaN or infinite values") + model_device = x.device + if isinstance(self.model, nn.Module): + try: + model_device = next(self.model.parameters()).device + except StopIteration: + model_device = x.device + x = x.to(model_device) + padded = torch.nn.functional.pad( + x, + (0, self.input_size[1] - width, 0, self.input_size[0] - height), + mode="replicate", + ) + with torch.inference_mode(): + output = self.model(padded) + if isinstance(output, (tuple, list)): + output = output[0] + if not isinstance(output, Tensor) or output.ndim != 4: + raise ValueError("SEN2SR model must return a 4-D tensor") + expected = ( + padded.shape[0], + 4, + self.input_size[0] * self.factor, + self.input_size[1] * self.factor, + ) + if tuple(output.shape) != expected: + raise ValueError( + "SEN2SR RGBN output has unexpected shape: " + f"received {tuple(output.shape)}, expected {expected}" + ) + if not torch.isfinite(output).all().item(): + raise ValueError("SEN2SR output contains NaN or infinite values") + return output[..., : height * self.factor, : width * self.factor] + + +def _manifest_url(variant: str) -> str: + key = variant.strip().lower().replace("-", "_").replace(" ", "_") + try: + path = VARIANT_MANIFESTS[key] + except KeyError as exc: + choices = ", ".join(sorted(VARIANT_MANIFESTS)) + raise ValueError( + f"Unknown SEN2SR variant {variant!r}; choose one of {choices}" + ) from exc + return f"{MODEL_REPOSITORY}/{path}" + + +def _load_checkpoint(path: Path, target: torch.device) -> nn.Module: + """Load a local TorchScript or serialized module checkpoint.""" + try: + model = torch.jit.load(str(path), map_location=target) + except RuntimeError: + payload = torch.load(str(path), map_location="cpu", weights_only=False) + if not isinstance(payload, nn.Module): + raise ValueError( + "A local SEN2SR checkpoint must be TorchScript or a serialized " + "torch.nn.Module; a state_dict needs the upstream MLSTAC manifest." + ) + model = payload + return model.to(target).eval() + + +def load_sen2sr( + model_dir: str | Path | None = None, + *, + variant: str = DEFAULT_VARIANT, + device: str | torch.device = "cpu", + download: bool = True, + cache_dir: str | Path | None = None, + checkpoint: str | Path | None = None, +) -> SEN2SRAdapter: + """Load a SEN2SR RGBN model from MLSTAC or a local checkpoint. + + ``model_dir`` points to a directory containing the upstream ``mlm.json`` + manifest. ``checkpoint`` may point to a TorchScript file or a serialized + ``torch.nn.Module``. When neither is supplied, the official manifest is + downloaded lazily through ``mlstac``. Weights are constructed on CPU and + moved only after loading, avoiding accidental GPU allocation during setup. + """ + target = _device(device) + if model_dir is not None and checkpoint is not None: + raise ValueError("Provide model_dir or checkpoint, not both") + + if checkpoint is not None: + path = Path(checkpoint).expanduser() + if not path.is_file(): + raise FileNotFoundError(f"SEN2SR checkpoint does not exist: {path}") + return SEN2SRAdapter(_load_checkpoint(path, target), device=target) + + try: + import mlstac + except ImportError as exc: + raise ImportError( + "Loading SEN2SR requires the optional 'mlstac' package. " + "Install it with: pip install sen2sr mlstac" + ) from exc + + if model_dir is None: + if not download: + raise ValueError("download=False requires model_dir or checkpoint") + root = ( + Path(cache_dir).expanduser() + if cache_dir + else Path(tempfile.gettempdir()) / "opensr-utils" / "sen2sr" + ) + root.mkdir(parents=True, exist_ok=True) + model_dir = root / variant + manifest = _manifest_url(variant) + mlstac.download(file=manifest, output_dir=str(model_dir)) + path = Path(model_dir).expanduser() + if not path.exists(): + raise FileNotFoundError(f"SEN2SR model directory does not exist: {path}") + loaded = mlstac.load(str(path)) + # MLSTAC's documented compiled_model API accepts a torch device. + model = loaded.compiled_model(device=torch.device("cpu")) + if not isinstance(model, nn.Module) and not callable(model): + raise TypeError("MLSTAC compiled_model() did not return a callable model") + return SEN2SRAdapter(model, device=target) + + +get_sen2sr = load_sen2sr + +__all__ = ["DEFAULT_VARIANT", "SEN2SRAdapter", "get_sen2sr", "load_sen2sr"] diff --git a/opensr_utils/pipeline.py b/opensr_utils/pipeline.py index 03a8f6f..04799ee 100644 --- a/opensr_utils/pipeline.py +++ b/opensr_utils/pipeline.py @@ -1,17 +1,17 @@ # -*- coding: utf-8 -*- -# torch stuff +"""Windowed inference with disk-backed blending and atomic output publication.""" + import torch from pytorch_lightning import LightningModule -torch.set_float32_matmul_precision("medium") - # general imports import os import shutil import json from datetime import datetime +from pathlib import Path # Geo import rasterio @@ -23,92 +23,41 @@ class large_file_processing: - """ - Large-scale super-resolution pipeline for Sentinel-2 and other geospatial inputs. - - This class orchestrates the full workflow for processing large raster datasets - (e.g. Sentinel-2 SAFE archives, S2GM folders, or standalone GeoTIFFs) with a - super-resolution (SR) model. It handles input validation, directory setup, - patch-based inference, distributed (DDP) support, and final stitched outputs. - - Workflow - -------- - 1. **Validate input and arguments** - - Checks existence of `root`, model type, overlap/border settings, SR factor. - 2. **Detect input type** - - Supports raster file, `.SAFE` folder, `S2GM` folder, or zipped SAFE archive. - - If zipped, unzips and updates `self.root`. - 3. **Create directories** - - Sets up `logs/`, `temp/` next to the input for intermediate files. - 4. **Extract image metadata** - - Reads size, CRS, transforms, and computes sliding-window coordinates. - 5. **Prepare dynamic output metadata** - - Defers placeholder creation until prediction metadata is available. - 6. **Initialize datamodule** - - Builds a PyTorch Lightning DataModule for batched inference windows. - 7. **Preprocess model** - - Places model on correct device, switches to eval mode, prepares for inference. - 8. **Run super-resolution** - - If not in debug mode, runs patch-based inference and saves results in `temp/`. - 9. **Create placeholder and stitch patches into final output** - - On rank 0 only: creates a placeholder matching the actual prediction - factor/band count, then stitches patches into `final_sr_path`. - 10. **Cleanup and previews** - - Deletes temporary LR patches. - - Optionally saves example crops and preview images in `logs/`. - - Parameters - ---------- - root : str - Path to input (SAFE folder, S2GM folder, single raster, or Copernicus zip). - model : torch.nn.Module | LightningModule | None, default=None - Super-resolution model to use. If `None`, runs in a placeholder/no-model mode. - window_size : tuple[int, int], default=(128, 128) - Spatial size of low-resolution windows (before SR). - factor : int, default=4 - Super-resolution upscaling factor. Any positive integer is accepted; - use ``1`` for tiled inference with models that preserve resolution. - overlap : int, default=8 - Overlap (in LR pixels) between adjacent windows. Must be even. - eliminate_border_px : int, default=0 - Number of border pixels to discard per window in the SR output. - Must be even; if overlap is non-zero, must be smaller than `overlap`. - device : {"cpu","cuda"}, default="cpu" - Device on which to run the model. - gpus : int | list[int] | None, default=1 - GPU index or list of GPU indices. If `device="cpu"`, ignored. - save_preview : bool, default=False - If True, saves 1 cropped SR excerpt and 10 side-by-side LR/SR previews. - debug : bool, default=False - If True, processes only 100 windows globally (DDP-safe). - - Attributes (after init) - ----------------------- - root : str - Final resolved input path (after unzip if necessary). - input_type : str - One of {"file","SAFE","S2GM"}. - placeholder_path : str - Base folder containing logs/temp/sr. - log_dir : str - Path to the logs directory. - temp_folder : str - Path to temporary patch storage. - output_dir : str - Path to SR output directory. - image_meta : dict - Metadata such as CRS, transforms, dimensions, and window layout. - model : torch.nn.Module | LightningModule - Preprocessed model in eval mode. - final_sr_path : str - Path to the stitched super-resolved GeoTIFF (set after stitching). - - Notes - ----- - - Designed for multi-GPU environments with PyTorch Lightning (DDP). - - Uses weighted overlap blending to avoid patch seams. - - On rank 0, the stitched result is written to disk and previews are saved. - - Non-rank0 processes perform inference only, without logging or stitching. + """Prepare and execute memory-bounded super-resolution of geospatial inputs. + + Accept a raster, SAFE directory/ZIP or S2GM folder and a PyTorch/Lightning + model (or ``None`` for bilinear interpolation). Construction discovers input, + validates grids and prepares inference; call :meth:`run` to create a product, + or use :func:`opensr_utils.super_resolve` for the one-call workflow. + + Windows are ``(width, height)`` in LR pixels. ``factor`` is a positive integer; + overlap and discarded borders are also in LR pixels. Batches stream to disk + and overlapping predictions blend through disk-backed float32 accumulators. + Plain PyTorch modules and Lightning modules both support batching and DDP. + + ``device="auto"`` chooses CUDA when available, otherwise CPU. ``gpus`` selects + CUDA IDs; ``batch_size``, ``num_workers``, ``prefetch_factor`` and + ``compressed_patches`` allow throughput/storage tuning. Models load on CPU + before Lightning places them on their execution devices. + + Model inputs are normalized to [0,1]. ``output_units="normalized"`` scales + predictions by 10000; ``"reflectance"`` accepts existing [0,10000] values. + Nonfinite outputs are errors; finite outputs are clipped, rounded and saved + as uint16. The output's internal validity mask preserves input masks and + nodata independently of predicted values, including valid zeros. + + ``output_path`` names a destination GeoTIFF; the default is ``sr.tif`` beside + the input (inside S2GM folders). Source rasters cannot be destinations. + Existing outputs require ``overwrite=True`` and are atomically replaced only + after full coverage and mask validation. ``cleanup=False`` keeps every patch + and the manifest. Failed runs retain diagnostics. Source ZIP deletion always + requires ``delete_input_zip=True`` and successful input validation. + + ``debug=True`` infers at most 100 windows, retains patches and returns the + manifest path without publishing a final raster. ``save_preview=True`` adds + preview images/crops. Use this object as a context manager or call ``close`` + to release cached raster handles. ``auto_run`` exists for legacy callers; + explicit ``run`` is the default. """ def __init__( @@ -116,10 +65,10 @@ def __init__( root: str, model=None, window_size: tuple = (128, 128), - factor: int = 4, + factor=None, overlap: int = 8, eliminate_border_px=0, - device: str = "cpu", + device: str = "auto", gpus=None, save_preview: bool = False, debug=False, @@ -128,34 +77,53 @@ def __init__( overwrite: bool = False, delete_input_zip: bool = False, batch_size: int = 16, - num_workers: int = 4, + num_workers: int = 0, prefetch_factor: int = 2, compressed_patches: bool = False, + output_path=None, + output_units=None, + checkpoint=None, + model_config=None, + cache_dir=None, + model_variant=None, + download: bool = True, + band_indexes=None, ): # 1) Validate public inputs. Do not use assert: optimized Python removes it. + if isinstance(model, str): + from opensr_utils.model_utils.get_models import normalize_model_name + + model = normalize_model_name(model) if model is not None and not isinstance( - model, (LightningModule, torch.nn.Module) + model, (str, LightningModule, torch.nn.Module) ): raise TypeError("Model must be a PyTorch module, LightningModule, or None.") if not isinstance(window_size, (tuple, list)) or len(window_size) != 2: raise TypeError( "window_size must be a tuple/list of two positive integers." ) - if not all(isinstance(v, int) and v > 0 for v in window_size): + if not all( + isinstance(v, int) and not isinstance(v, bool) and v > 0 + for v in window_size + ): raise ValueError("window_size must contain two positive integers.") - if not isinstance(overlap, int) or overlap < 0 or overlap % 2 != 0: + if ( + isinstance(overlap, bool) + or not isinstance(overlap, int) + or overlap < 0 + or overlap % 2 != 0 + ): raise ValueError("overlap must be a non-negative even integer.") if ( not isinstance(eliminate_border_px, int) + or isinstance(eliminate_border_px, bool) or eliminate_border_px < 0 or eliminate_border_px % 2 != 0 ): raise ValueError("eliminate_border_px must be a non-negative even integer.") if overlap == 0: if eliminate_border_px != 0: - raise ValueError( - "eliminate_border_px must be 0 when overlap is 0." - ) + raise ValueError("eliminate_border_px must be 0 when overlap is 0.") elif eliminate_border_px >= overlap: raise ValueError("eliminate_border_px must be smaller than overlap.") if overlap > 0 and (overlap - eliminate_border_px) < 4: @@ -164,30 +132,77 @@ def __init__( ) if overlap >= min(window_size): raise ValueError("overlap must be smaller than both window dimensions.") + explicit_factor = factor is not None + if factor is None: + factor = getattr(model, "factor", 4) if not isinstance(factor, int) or isinstance(factor, bool) or factor <= 0: raise ValueError("factor must be a positive integer.") - if device not in ("cpu", "cuda"): - raise ValueError("device must be 'cpu' or 'cuda'.") + if device not in ("auto", "cpu", "cuda"): + raise ValueError("device must be 'auto', 'cpu' or 'cuda'.") + if output_units not in (None, "normalized", "reflectance"): + raise ValueError("output_units must be 'normalized' or 'reflectance'.") for name, value in { "batch_size": batch_size, "num_workers": num_workers, "prefetch_factor": prefetch_factor, }.items(): - if not isinstance(value, int) or value < 0: + if isinstance(value, bool) or not isinstance(value, int) or value < 0: raise ValueError(f"{name} must be a non-negative integer.") if batch_size == 0: raise ValueError("batch_size must be greater than zero.") + if num_workers and prefetch_factor == 0: + raise ValueError( + "prefetch_factor must be greater than zero when num_workers > 0." + ) + + self.output_path = ( + str(Path(output_path).expanduser().resolve()) + if output_path is not None + else None + ) + if self.output_path and Path(self.output_path).suffix.lower() not in ( + ".tif", + ".tiff", + ): + raise ValueError("output_path must name a .tif or .tiff file.") + self.output_units = output_units + if band_indexes is not None: + if ( + not isinstance(band_indexes, (list, tuple)) + or not band_indexes + or any( + isinstance(index, bool) or not isinstance(index, int) or index <= 0 + for index in band_indexes + ) + or len(set(band_indexes)) != len(band_indexes) + ): + raise ValueError( + "band_indexes must be unique positive 1-based raster band indexes." + ) + band_indexes = list(band_indexes) + self._requested_band_indexes = band_indexes + if not isinstance(model, str) and any( + value is not None + for value in (checkpoint, model_config, cache_dir, model_variant) + ): + raise ValueError( + "Checkpoint/config/cache/variant options require a named model; pass an already loaded module without loader options." + ) # General Settings self.debug = bool( debug ) # if True, only process 100 windows globally (DDP-safe) - self.root = root # path to folder containing S2 SAFE data format + self.root = str(Path(root).expanduser()) self.window_size = tuple(window_size) # window size of the LR image self.factor = int(factor) # sr factor of the model self.overlap = overlap # overlap in px of the LR image windows self.eliminate_border_px = eliminate_border_px # border pixels to eliminate in px on each side of the SR image - self.device = device # device to run model on + self.device = ( + ("cuda" if torch.cuda.is_available() else "cpu") + if device == "auto" + else device + ) self.save_preview = bool(save_preview) self.cleanup = bool(cleanup) self.overwrite = bool(overwrite) @@ -197,6 +212,13 @@ def __init__( self.prefetch_factor = int(prefetch_factor) self.compressed_patches = bool(compressed_patches) existing_run_id = os.environ.get("OPENSR_RUN_ID") + distributed = torch.distributed + active_group = distributed.is_available() and distributed.is_initialized() + self._external_world = ( + distributed.get_world_size() + if active_group + else int(os.environ.get("WORLD_SIZE", "1")) + ) launcher_env = ( os.environ.get("WORLD_SIZE", "1") not in ("", "1") or os.environ.get("LOCAL_RANK") is not None @@ -206,6 +228,15 @@ def __init__( self.run_id = existing_run_id else: self.run_id = f"{datetime.now().strftime('%Y%m%d_%H%M%S_%f')}_{os.getpid()}" + if active_group: + shared_id = [self.run_id if distributed.get_rank() == 0 else None] + distributed.broadcast_object_list(shared_id, src=0) + self.run_id = shared_id[0] + elif self._external_world > 1: + raise ValueError( + "External distributed launches require a unique OPENSR_RUN_ID shared by all ranks. " + "Alternatively, let the pipeline launch workers with gpus=[0, 1]." + ) os.environ["OPENSR_RUN_ID"] = self.run_id if isinstance(gpus, int): # pass GPU/s to Trainer as list self.gpus = [gpus] # number of gpus or list of gpu ids to use @@ -215,14 +246,20 @@ def __init__( self.gpus = list(gpus) else: raise TypeError("gpus must be None, an int, or a list/tuple of ints.") - if self.gpus is not None and not all( - isinstance(g, int) and g >= 0 for g in self.gpus + if self.gpus is not None and ( + not self.gpus + or not all( + isinstance(g, int) and not isinstance(g, bool) and g >= 0 + for g in self.gpus + ) + or len(set(self.gpus)) != len(self.gpus) ): - raise ValueError("gpus must contain non-negative integer GPU ids.") + raise ValueError("gpus must contain unique non-negative integer GPU ids.") if self.device == "cpu": self.gpus = None elif self.gpus is None: - self.gpus = [0] + local_world = int(os.environ.get("LOCAL_WORLD_SIZE", "1")) + self.gpus = list(range(local_world)) if self._external_world > 1 else [0] # 3) Locals/init-only (no paths derived yet!) - leave empty self.image_meta = {} @@ -246,8 +283,34 @@ def __init__( # Get Image information based on input, including image coordinate windows self.get_image_meta(self.root) # multi-GPU safe - # Create Datamodule based on input files and Windows - self.create_datamodule() # Runs on all Ranks + # Load on CPU; Lightning moves the model after selecting its execution strategy. + if isinstance(model, str): + from opensr_utils.model_utils.get_models import get_model + + model = get_model( + model, + device="cpu", + checkpoint=checkpoint, + config=model_config, + cache_dir=cache_dir, + variant=model_variant, + download=download, + ) + model_factor = getattr(model, "factor", None) + if model_factor is not None: + if explicit_factor and model_factor != self.factor: + raise ValueError( + f"The selected model produces factor {model_factor}; requested factor={self.factor}." + ) + self.factor = model_factor + model_units = getattr(model, "output_units", None) + if model_units and output_units is not None and output_units != model_units: + raise ValueError( + f"The model returns {model_units} output; use output_units={model_units!r}." + ) + self.output_units = output_units or model_units or "normalized" + self._configure_model_input(model) + self.create_datamodule() # Make sure model is useable and in eval mode self.model = preprocess_model( @@ -256,14 +319,117 @@ def __init__( temp_folder=self.temp_folder, windows=self.image_meta["image_windows"], factor=self.factor, + output_units=self.output_units, ) + # Deletion is opt-in and happens only after source, channel, model and + # window contracts have all validated successfully. + pending_zip = getattr(self, "_pending_input_zip_delete", None) + if pending_zip and self._is_rank0(): + pending_path = Path(pending_zip) + if pending_path.exists(): + pending_path.unlink() + self._log(f"Deleted validated archive: {pending_path.name}") + self._pending_input_zip_delete = None + # Print Status self._log("📊 Status: Model and Data ready for inference ✅") if auto_run: self.run() + def _configure_model_input(self, model): + """Select declared model bands without changing generic module inputs.""" + if getattr(model, "input_units", "normalized") != "normalized": + raise ValueError( + "The pipeline supplies normalized [0,1] inputs. Construct the adapter with input_units='normalized'." + ) + declared_output_bands = getattr(model, "output_band_names", None) + if declared_output_bands is not None: + if ( + not isinstance(declared_output_bands, (tuple, list)) + or not declared_output_bands + or any( + not isinstance(name, str) or not name + for name in declared_output_bands + ) + ): + raise ValueError( + "Model output_band_names must be a sequence of nonempty band names." + ) + self.image_meta["output_band_names"] = tuple(declared_output_bands) + required = tuple(getattr(model, "input_bands", ())) + maximum = getattr(model, "max_window_size", None) + if maximum is not None: + actual = ( + min(self.window_size[0], self.image_meta["width"]), + min(self.window_size[1], self.image_meta["height"]), + ) + if any(size > limit for size, limit in zip(actual, maximum)): + raise ValueError( + f"This model accepts windows up to {tuple(maximum)}; requested {actual}. Use window_size={tuple(maximum)}." + ) + aliases = { + "R": "B04", + "RED": "B04", + "G": "B03", + "GREEN": "B03", + "B": "B02", + "BLUE": "B02", + "NIR": "B08", + } + if self.input_type == "file": + with rasterio.open(self.root) as source: + indexes = self._requested_band_indexes + if indexes is not None and max(indexes) > source.count: + raise ValueError( + f"band_indexes requests a channel beyond the raster's {source.count} bands." + ) + if required and indexes is None: + names = [ + aliases.get( + (name or "").strip().upper(), (name or "").strip().upper() + ) + for name in source.descriptions + ] + if all(name in names for name in required): + if any(names.count(name) != 1 for name in required): + raise ValueError( + f"Raster band descriptions must uniquely identify {required}." + ) + indexes = [names.index(name) + 1 for name in required] + elif source.count != len(required) or any( + name in required for name in names + ): + raise ValueError( + f"Model requires bands {required}. Set GeoTIFF band descriptions or pass band_indexes in that order; unlabeled inputs must contain exactly {len(required)} bands." + ) + selected_count = len(indexes) if indexes is not None else source.count + if required and selected_count != len(required): + raise ValueError( + f"Model requires {len(required)} bands in {required} order; selected {selected_count}." + ) + self.image_meta["band_indexes"] = indexes + self.image_meta["bands"] = selected_count + return + if self._requested_band_indexes is not None: + raise ValueError( + "band_indexes is for single raster files; SAFE/S2GM model bands are selected by name." + ) + if required: + paths = self.image_meta["lr_file_dict"] + by_band = { + aliases.get(label.upper(), label.upper()): (label, path) + for label, path in paths.items() + } + missing = [band for band in required if band not in by_band] + if missing: + raise FileNotFoundError( + f"Model requires missing spectral bands {missing}; available bands: {sorted(by_band)}." + ) + self.image_meta["lr_file_dict"] = dict(by_band[band] for band in required) + self.image_meta["bands"] = len(required) + def create_datamodule(self, windows=None): """ Create a PredictionDataModule for patch-based inference. @@ -271,11 +437,15 @@ def create_datamodule(self, windows=None): The datamodule wraps the input type, root path, and sliding windows, and handles batching for PyTorch Lightning’s predict loop. """ + previous = getattr(self, "datamodule", None) + if previous is not None: + previous.dataset.close() dm = PredictionDataModule( input_type=self.input_type, root=self.root, - windows=windows or self.image_meta["image_windows"], + windows=self.image_meta["image_windows"] if windows is None else windows, lr_file_dict=self.image_meta["lr_file_dict"], + band_indexes=self.image_meta.get("band_indexes"), prefetch_factor=self.prefetch_factor, batch_size=self.batch_size, num_workers=self.num_workers, @@ -376,6 +546,14 @@ def safe_band_name(path): src.width == self.image_meta["width"] and src.height == self.image_meta["height"] ): + if ( + src.transform != self.image_meta["transform"] + or src.crs != self.image_meta["crs"] + ): + raise ValueError( + "SAFE bands have matching dimensions but are on " + "different grids (transform or CRS mismatch)." + ) same_grid[label] = path self.image_meta["lr_file_dict"] = same_grid self.image_meta["bands"] = len(self.image_meta["lr_file_dict"]) @@ -387,7 +565,7 @@ def safe_band_name(path): tifs = [] for root, _, files in os.walk(self.root): for f in files: - if f.lower().endswith(".tif"): + if f.lower().endswith((".tif", ".tiff")): tifs.append(os.path.join(root, f)) if not tifs: @@ -396,7 +574,8 @@ def safe_band_name(path): ) by_name = { - os.path.splitext(os.path.basename(p))[0]: p for p in sorted(tifs) + os.path.splitext(os.path.basename(p))[0].upper(): p + for p in sorted(tifs) } lr_file_dict = {} for label, band_name in ( @@ -417,6 +596,12 @@ def safe_band_name(path): lr_file_dict[band_name] = path self.image_meta["lr_file_dict"] = lr_file_dict + if not lr_file_dict: + raise FileNotFoundError( + f"No usable S2GM bands found in {self.root}; " + "auxiliary rasters such as AOT/WVP are not spectral bands." + ) + # Get image properties with rasterio.open( next(iter(self.image_meta["lr_file_dict"].values())) @@ -433,12 +618,41 @@ def safe_band_name(path): src.width == self.image_meta["width"] and src.height == self.image_meta["height"] ): + if ( + src.transform != self.image_meta["transform"] + or src.crs != self.image_meta["crs"] + ): + raise ValueError( + "S2GM bands have matching dimensions but are on " + "different grids (transform or CRS mismatch)." + ) same_grid[label] = path self.image_meta["lr_file_dict"] = same_grid self.image_meta["bands"] = len(self.image_meta["lr_file_dict"]) if self.image_meta["bands"] <= 0: raise FileNotFoundError("No S2GM bands matched the selected grid size.") + # Protect every selected source band, including directory inputs. The + # samefile check catches an existing hardlink even when its pathname is + # different from the source pathname. + requested_output = getattr(self, "output_path", None) + if requested_output and self.input_type in {"SAFE", "S2GM"}: + output_path = os.path.abspath(os.path.expanduser(str(requested_output))) + for source_path in self.image_meta["lr_file_dict"].values(): + source_path = os.path.abspath(str(source_path)) + try: + same_file = os.path.samefile(output_path, source_path) + except (FileNotFoundError, OSError): + same_file = False + if ( + os.path.realpath(output_path) == os.path.realpath(source_path) + or same_file + ): + raise ValueError( + "Output path must differ from every selected input band; " + "writing in place is not supported." + ) + # finally, add image windows to metadata self.image_meta["image_windows"] = self.create_image_windows() if not self.image_meta["image_windows"]: @@ -458,22 +672,19 @@ def create_placeholder_file( """ Create an empty HR GeoTIFF placeholder for stitched SR results. - - Output path: `/sr_placeholder.tif`. + - Uses a run-specific staging path beside the final destination. - Only rank 0 creates/writes the file and ensures `temp/` exists. - Other ranks wait until the placeholder is readable, then return. - Safe on CPU and single-GPU (treated as rank 0). """ - import os, time - import rasterio - from rasterio.transform import Affine + import time def _is_rank0_env() -> bool: # Works before torch.distributed is initialized - lr = os.environ.get("LOCAL_RANK", "") r = os.environ.get("RANK", "") ws = os.environ.get("WORLD_SIZE", "1") if ws not in ("", "1"): - return (lr in ("", "0")) and (r in ("", "0")) + return int(r or os.environ.get("LOCAL_RANK", "0")) == 0 return True # single process → rank0 def _placeholder_readable() -> bool: @@ -515,9 +726,7 @@ def _placeholder_readable() -> bool: W = int(self.image_meta["width"] * scale) H = int(self.image_meta["height"] * scale) tr = self.image_meta["transform"] - save_transform = Affine( - tr.a / scale, tr.b, tr.c, tr.d, tr.e / scale, tr.f - ) + save_transform = tr * Affine.scale(1 / scale) profile = { "driver": "GTiff", @@ -536,9 +745,15 @@ def _placeholder_readable() -> bool: "nodata": 0, } - # Open with "w" to (re)create atomically from the POV of other ranks - with rasterio.open(self.output_file_path, "w", **profile): - pass + # The private staging path is never a published final product. + with rasterio.open(self.output_file_path, "w", **profile) as destination: + names = self.image_meta.get("output_band_names") + if names is not None: + if len(names) != nb: + raise ValueError( + "Declared output band names do not match the predicted channel count." + ) + destination.descriptions = names self._log( f"💾 Saved empty placeholder SR image at: {self.output_file_path}" @@ -558,7 +773,7 @@ def _placeholder_readable() -> bool: time.sleep(wait_sleep_s) # No logging here (avoid concurrent writes); rank 0 logs already. - def create_image_windows(self): # Works + def create_image_windows(self): """ Generate overlapping rasterio Windows covering the input image. @@ -627,7 +842,7 @@ def run(self, debug=None, save_preview=None, cleanup=None, overwrite=None): cleanup = self.cleanup if cleanup is None else bool(cleanup) overwrite = self.overwrite if overwrite is None else bool(overwrite) - if os.path.exists(self.final_sr_path) and not overwrite: + if not debug and os.path.exists(self.final_sr_path) and not overwrite: raise FileExistsError( f"Output already exists at {self.final_sr_path}. " "Pass overwrite=True to replace it." @@ -635,10 +850,18 @@ def run(self, debug=None, save_preview=None, cleanup=None, overwrite=None): self.start_super_resolution(debug=debug, save_preview=save_preview) + if debug: + # A truncated run is diagnostic data, never a complete SR product. + index_path = os.path.join(self.temp_folder, "index.json") + self._log( + f"Debug predictions retained in {index_path}; no final raster created." + ) + return index_path + trainer = getattr(self, "trainer", None) if self._is_rank0(trainer): self._log("🪡 Stitching results into final sr.tif...") - self.write_to_file(overwrite=overwrite) + self.write_to_file(overwrite=overwrite, cleanup=cleanup) if cleanup: self.delete_LR_temp() @@ -670,6 +893,7 @@ def run(self, debug=None, save_preview=None, cleanup=None, overwrite=None): f"✅ Saved {num_examples} side-by-side preview images to logs folder." ) + self.close() self._log("🎉 Processing done! SR process exited.") return self.final_sr_path @@ -701,7 +925,8 @@ def start_super_resolution(self, debug: bool = False, save_preview: bool = False self.model._save_progress_preview = bool(save_preview) # Devices: list[int] or 1 for CPU/single-GPU - devices = self.gpus if self.gpus is not None else 1 + local_world = int(os.environ.get("LOCAL_WORLD_SIZE", str(self._external_world))) + devices = self.gpus if self.gpus is not None else local_world # Build Trainer kwargs robustly across PL versions trainer_kwargs = dict( @@ -715,12 +940,15 @@ def start_super_resolution(self, debug: bool = False, save_preview: bool = False ) # Use DDP only when we truly have >1 CUDA devices - if ( + if self._external_world > 1 or ( isinstance(devices, (list, tuple)) and len(devices) > 1 and self.device == "cuda" ): trainer_kwargs["strategy"] = "ddp" + trainer_kwargs["num_nodes"] = max( + 1, self._external_world // max(1, local_world) + ) # Make sure PL doesn't override our custom sampler sig = inspect.signature(Trainer) @@ -765,7 +993,9 @@ def start_super_resolution(self, debug: bool = False, save_preview: bool = False f"✅ Prediction complete! SR patches saved in 📂: {self.temp_folder}" ) if debug: - self._log("Debug mode was ON → processed only 100 windows.") + self._log( + f"Debug mode processed {len(windows_run)} of {len(windows_all)} windows." + ) def _prepare_placeholder_from_prediction_index(self, index_path=None): """ @@ -816,40 +1046,11 @@ def _prepare_placeholder_from_prediction_index(self, index_path=None): factor=output_factor, ) - def write_to_file(self, index_path=None, limit=None, overwrite=None): - """ - Multi-GPU safe entry point for stitching super-resolved patches. - - This method wraps around ``writing_utils.ddp_safe_stitch`` to ensure that - the expensive GeoTIFF write phase is performed only once (on global rank 0), - while all other ranks in a distributed run wait at a synchronization barrier. - This prevents file corruption and crashes when using PyTorch DDP. - - Behavior by environment: - ------------------------ - - **CPU / single process**: stitches normally. - - **Single GPU**: stitches normally (rank 0 is the only rank). - - **Multi-GPU (DDP)**: only rank 0 writes to the GeoTIFF, all other ranks - return immediately after the barrier. - - Parameters - ---------- - index_path : str, optional - Path to ``index.json`` describing all patches. Defaults to - ``/index.json``. - limit : int, optional - If given, only the first ``limit`` patches are stitched - (useful for debugging). + def write_to_file(self, index_path=None, limit=None, overwrite=None, cleanup=None): + """Stitch on global rank zero and atomically publish a validated raster. - Notes - ----- - - Actual stitching and file I/O are handled by - :func:`opensr_utils.data_utils.writing_utils.ddp_safe_stitch`. - - Ensure that the placeholder GeoTIFF has already been created before - calling this function. - - Environment variables such as ``GDAL_CACHEMAX=256`` and - ``GDAL_NUM_THREADS=1`` are recommended for stability when running with - multiple processes. + Other ranks return immediately. Failed writes retain the previous output, + patches and diagnostics; ``cleanup=False`` also retains successful patches. """ from opensr_utils.data_utils.writing_utils import ddp_safe_stitch @@ -861,16 +1062,28 @@ def write_to_file(self, index_path=None, limit=None, overwrite=None): self, index_path=index_path, limit=limit, - cleanup_every=50, # tune if RAM pressure + cleanup=getattr(self, "cleanup", True) + if cleanup is None + else bool(cleanup), profile="sigmoid", # "linear"|"sigmoid"|"cosine" profile_alpha=6.0, gdal_cache_mb=256, ) + def close(self): + """Release cached raster handles; retained patches and logs stay on disk.""" + datamodule = getattr(self, "datamodule", None) + if datamodule is not None: + datamodule.dataset.close() + + def __enter__(self): + return self + + def __exit__(self, exc_type, exc_value, traceback): + self.close() + def _is_rank0(self, trainer=None): """Return True only for the process that should print (rank 0).""" - import os, torch - # When Trainer exists, trust it if trainer is not None and hasattr(trainer, "is_global_zero"): return bool(trainer.is_global_zero) @@ -887,7 +1100,7 @@ def _is_rank0(self, trainer=None): lr = os.environ.get("LOCAL_RANK", "") ws = os.environ.get("WORLD_SIZE", "") if ws not in ("", "1"): # multi-process expected - return (r in ("", "0")) and (lr in ("", "0")) + return int(r or lr or "0") == 0 # Single process return True @@ -937,6 +1150,6 @@ def _log(self, message: str): f.write(bl_line + "\n") self._log_backlog.clear() f.write(line + "\n") - except Exception as e: + except OSError: # in case file is not writable, keep line in backlog self._log_backlog.append(line) diff --git a/pyproject.toml b/pyproject.toml index 4f5decf..755e905 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -11,3 +11,15 @@ markers = [ "integration: exercises the real CPU inference or COG pipeline on local rasters", "known_bug: desired behavior blocked by a documented defect (strict xfail)", ] + +[tool.coverage.run] +branch = true +source = ["opensr_utils"] + +[tool.coverage.report] +show_missing = true +skip_covered = true +exclude_also = [ + "if TYPE_CHECKING:", + "if __name__ == .__main__.:", +] diff --git a/setup.py b/setup.py index 802807c..6177e23 100644 --- a/setup.py +++ b/setup.py @@ -16,7 +16,20 @@ packages=find_packages(include=["opensr_utils", "opensr_utils.*"]), long_description=long_description, long_description_content_type="text/markdown", + # Keep the public API usable on the long-lived Python 3.9/3.10 + # environments used by existing ESA processing workflows. Newer CI jobs + # exercise the current PyTorch wheels through Python 3.14. python_requires=">=3.9", + classifiers=[ + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3 :: Only", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13", + "Programming Language :: Python :: 3.14", + ], install_requires=[ "numpy", "einops", @@ -34,8 +47,21 @@ ], extras_require={ "model": ["opensr-model>=1.0.0"], + # SEN2SR and MLSTAC currently require Python >=3.10. Keeping these + # integrations optional preserves the core package's Python 3.9 floor. + "sen2sr": ["sen2sr>=0.8.5", "mlstac>=0.4.9"], + # opensr-srgan supports Python >=3.12,<3.15 upstream. + "srgan": ["opensr-srgan>=0.5.1"], + "all-models": [ + "opensr-model>=1.0.0", + "sen2sr>=0.8.5", + "mlstac>=0.4.9", + "opensr-srgan>=0.5.1", + ], "cog": ["rio-cogeo"], - "dev": ["pytest", "ruff"], + # Keep coverage tooling in the development extra so local and CI + # measurements exercise the same dependency set as the test suite. + "dev": ["pytest", "pytest-cov", "ruff"], }, entry_points={ "console_scripts": [ diff --git a/tests/README.md b/tests/README.md index cc189e2..2ac0e10 100644 --- a/tests/README.md +++ b/tests/README.md @@ -1,75 +1,86 @@ # Behavior tests -These tests define observable contracts for future refactors. They use small -local rasters, known pixel values and deterministic models rather than pretrained -weights. HTTP requests through `requests` are blocked by an autouse fixture; -model-loading tests mock the download/checkpoint boundary. No GPU is required. +Tests use local rasters, known pixel values and deterministic models. Pretrained +weights and HTTP access are unnecessary: an autouse fixture blocks `requests` +network calls, and model-loader tests mock the download/checkpoint boundary. +Runtime dependencies are required during collection. Fixed maintenance regressions +run as normal tests, with no expected-failure markers. ## Run locally -Use a virtual environment with Python and the package's runtime dependencies: - ```bash python -m pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu python -m pip install -e '.[dev,cog]' python -m pytest -q +python -m ruff check opensr_utils tests examples setup.py demo.py +python -m ruff format --check opensr_utils tests examples setup.py demo.py ``` -In the current workspace the prepared environment is `/work/envs/opensr`: - -```bash -/work/envs/opensr/bin/python -m pytest -q -``` - -Runtime dependencies are required: collection should fail if they are missing, -rather than allowing CI to pass by skipping most tests. CI runs the full suite -on CPU. To select cases: +The prepared workspace environment is `/work/envs/opensr/bin/python`. The real +process tests need permission to open local loopback sockets; restricted sandboxes +must enable local networking for those tests. They do not contact external services. +CPU/Gloo workers use bounded process-group and process-join timeouts. The Lightning +check runs in a bounded subprocess with a dynamically selected port. ```bash python -m pytest -m integration -q -python -m pytest -m 'not integration and not known_bug' -q -python -m pytest -m known_bug --runxfail -q -python -m ruff check tests -python -m ruff format --check tests +python -m pytest tests/test_distributed.py tests/test_distributed_trainer.py -q +python -m pytest --cov=opensr_utils --cov-branch --cov-report=term-missing --cov-report=html ``` -`known_bug` tests define desired behavior that production code does not yet -provide. They use strict `xfail`: fixing the behavior causes CI to fail until the -marker is removed. Failure types are constrained to the reproduced defect. -`--runxfail` disables those markers to expose the actual failures. The defect -backlog and remaining design decisions are in [TODO.md](../TODO.md). +CI covers Python 3.9–3.14. Its oldest interpreter uses the constrained versions in +[constraints-oldest.txt](../.github/constraints-oldest.txt); other jobs use current +compatible dependencies. CPU PyTorch and real COG dependencies are installed. +Branch-aware XML coverage reports are uploaded per interpreter. Coverage is used +to identify missing behavior cases; no arbitrary percentage gate masks the +importance of individual branches. Child-process execution is validated through +observable files and process outcomes; its lines may not appear in the parent +coverage report. + +The model tests keep official downloads outside the normal test suite. Adapter +tests exercise tensor values, batch shapes, tile padding/cropping, normalization, +ESA histogram-inference delegation, band selection and labeled GeoTIFF output. +Pretrained smoke runs use the published SEN2SRLite RGBN and ESA RGB-NIR artifacts +following [the model examples](../examples/README.md). Optional model dependencies +can be installed with `.[sen2sr]` (Python 3.10+) and `.[srgan]` (Python 3.12–3.14). ## Contracts and scope -| Area | Contract | +| Area | Observable contract | | --- | --- | -| Construction | Validate arguments before creating files; inference is explicit by default. | -| Band selection | Common channels are R/G/B/NIR; preserve additional spectral channels on the selected grid; ignore auxiliary files. | -| Input values | Read as float32, divide by 10000 and clamp to [0,1]; retain file channel order. | -| Tiling | Deterministic, unique, bounded windows cover every pixel, including narrow images and final edges. | -| Sampling/batching | Every index appears exactly once across ranks; never pad distributed inference or drop a final partial batch. | -| Model execution | Evaluation/inference mode; output channels may differ from input channels; dimensions obey the scale factor. | -| Patch persistence | NPY and compressed NPZ carry uint16 predictions and manifests with consistent LR/HR coordinates and channel metadata. | -| Blending | All three profiles handle valid zero values, preserve outer borders and support symmetric horizontal/vertical overlaps. | -| Output | Preserve CRS and spatial footprint; compare real tiled output against independently calculated expected pixels. | -| File safety | Protect source data and existing outputs; reject incomplete products; retain diagnostics after failures. | -| CLI/model loader | Forward options, reject malformed arguments, validate HTTP responses and stop after failed loading stages. | -| Auxiliary tools | Cold imports avoid loading ML dependencies or writing files; COGs and excerpts retain pixels and spatial metadata. | +| API and CLI | One-call execution, explicit output destinations, automatic device defaults, nonzero failure status, and handle cleanup. | +| Construction | Validate arguments before inference; protect source/output collisions and preserve existing outputs. | +| Discovery | R/G/B/NIR order, auxiliary exclusion, preferred resolution, selected-grid channels, and rejection of spatial mismatches. | +| Input values | Float32 normalized/clipped values, native file channel order, and zero-filled masked/nonfinite inputs. | +| Tiling | Unique deterministic windows cover image edges, rectangular/tiny/narrow rasters and every pixel. | +| Sampling | Every index appears once across ranks; no padded inference samples or dropped partial batches. | +| Model execution | Evaluation/inference mode, dynamic output channels, explicit units, finite values and complete batch validation. | +| Persistence | NPY/NPZ uint16 values and manifests with consistent LR/HR offsets, channels and units. | +| Blending | Linear/sigmoid/cosine weighting, four-way intersections, valid zeros, outer borders and symmetric overlaps. | +| Spatial output | Correct CRS, full affine footprint including rotation/shear, dimensions and independently calculated pixels. | +| Masks | Intersect input validity, nearest-neighbor upscaling, internal masks, source nodata metadata and valid zero predictions. | +| Safety | Atomic publication, failed overwrite preservation, full coverage, retained diagnostics, complete retention and ZIP validation. | +| Debug | At most 100 retained windows, no final product, and a subsequent exhaustive full run. | +| Distributed | Real Gloo communication, empty ranks, rank identities, shard/write/merge errors, lost peers and recovery. | +| Auxiliary tools | Lightweight cold imports, crop georeferencing and real COG conversion/validation. | + +Full CPU inference tests compare nearest-neighbor models with independent NumPy +repeats. A one-DN tolerance accounts for weighted float32 accumulation followed by +integer casting. Other tests use exact values or explicit numerical tolerances. +Mask tests include partial output blocks larger than 512 pixels, factor-three +upscaling, differing source masks and nonfinite values. -The full CPU inference tests use nearest-neighbor models so expected output is -computed independently with NumPy repeats. A one-DN absolute tolerance accounts -for float32 weighted accumulation followed by integer casting. Array/layout and -manifest tests otherwise check exact values or explicit numerical tolerances. +Most SAFE discovery fixtures store GeoTIFF payloads under SAFE filenames for +speed. A separate fixture creates and reads actual JP2OpenJPEG bands, verifies +the driver and tolerates lossy-codec quantization. It skips only when that driver +is unavailable; other discovery tests still run. The small generated products +cannot represent every vendor/product-generation variant. -SAFE discovery fixtures use GeoTIFF payloads with `.jp2` filenames; Rasterio -detects the actual format. They exercise naming, resolution preference and band -selection, not JP2 codec support. COG conversion uses the real converter and -validator. Distributed manifest tests simulate rank state and on-disk shards; -they do not replace multi-process/GPU testing. +Real Gloo workers and a two-rank CPU Lightning run complement the simulated shard +unit tests. The optional two-GPU NCCL test skips without suitable hardware. These +checks do not establish all CUDA-driver or multi-node shared-filesystem behavior. -Prefer new tests at public boundaries, using hand-calculated expectations and -failure-preservation checks. Mock external services and rank/process context; -keep the raster I/O, models, persistence and stitching real where inexpensive. -Use `pipeline_factory` / `dataset_factory` for automatic raster-handle cleanup. -Keep unresolved units, nodata and debug-output choices in the backlog until -their intended behavior is decided. +Prefer tests at public boundaries with hand-calculated expectations and failure +preservation checks. `pipeline_factory` and `dataset_factory` close raster handles +automatically. Keep mocks at external boundaries and use real raster I/O, model +execution, persistence and stitching when inexpensive. diff --git a/tests/test_band_selection.py b/tests/test_band_selection.py index 356ad2b..38de817 100644 --- a/tests/test_band_selection.py +++ b/tests/test_band_selection.py @@ -5,6 +5,7 @@ import numpy as np import pytest +import rasterio from rasterio.transform import from_origin @@ -40,7 +41,47 @@ def test_common_bands_have_rgb_nir_labels_and_values(spectral_scene, pipeline_fa assert runner.image_meta["bands"] == 4 assert set(runner.image_meta["lr_file_dict"]) == {"R", "G", "B", "NIR"} np.testing.assert_allclose( - runner.datamodule.dataset[0]["image"][:, 0, 0], [0.4, 0.3, 0.2, 0.8] + runner.datamodule.dataset[0]["image"][:, 0, 0], + [0.4, 0.3, 0.2, 0.8], + atol=0.01, + ) + + +def test_safe_discovery_reads_real_jpeg2000_bands(tmp_path, pipeline_factory): + """Exercise the JP2OpenJPEG decoder, rather than a GeoTIFF with a .jp2 name.""" + with rasterio.Env() as env: + if "JP2OpenJPEG" not in env.drivers(): + pytest.skip("Rasterio was built without JP2OpenJPEG support") + + root = tmp_path / "real.SAFE" + img_data = root / "GRANULE" / "L2A_TEST" / "IMG_DATA" / "R10m" + img_data.mkdir(parents=True) + transform = from_origin(0, 16, 1, 1) + values = {"B02": 2000, "B03": 3000, "B04": 4000, "B08": 8000} + for band, value in values.items(): + path = img_data / f"T_TEST_{band}_10m.jp2" + with rasterio.open( + path, + "w", + driver="JP2OpenJPEG", + width=16, + height=16, + count=1, + dtype="uint16", + crs="EPSG:4326", + transform=transform, + ) as dst: + dst.write(np.full((1, 16, 16), value, dtype=np.uint16)) + + runner = pipeline_factory(root) + assert runner.image_meta["bands"] == 4 + for path in runner.image_meta["lr_file_dict"].values(): + with rasterio.open(path) as src: + assert src.driver == "JP2OpenJPEG" + np.testing.assert_allclose( + runner.datamodule.dataset[0]["image"][:, 0, 0], + [0.4, 0.3, 0.2, 0.8], + atol=0.01, ) @@ -103,11 +144,6 @@ def test_safe_without_usable_bands_has_a_clear_error(tmp_path, pipeline_factory) pipeline_factory(root) -@pytest.mark.known_bug -@pytest.mark.xfail( - reason="S2GM auxiliary-only input leaks StopIteration instead of a useful error", - raises=StopIteration, -) def test_s2gm_without_usable_bands_has_a_clear_error( tmp_path, write_raster, pipeline_factory ): @@ -117,11 +153,6 @@ def test_s2gm_without_usable_bands_has_a_clear_error( pipeline_factory(root) -@pytest.mark.known_bug -@pytest.mark.xfail( - reason="Band grid validation currently checks dimensions only", - raises=pytest.fail.Exception, -) @pytest.mark.parametrize("mismatch", ["transform", "crs"]) def test_same_size_bands_on_different_grids_are_rejected( spectral_scene, mismatch, write_raster, pipeline_factory diff --git a/tests/test_cli.py b/tests/test_cli.py index 7010987..53efc5a 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -15,6 +15,9 @@ class FakeRunner: def __init__(self, **kwargs): calls.append(("init", kwargs)) + def close(self): + pass + def run(self): calls.append(("run", None)) return "sr.tif" @@ -60,7 +63,7 @@ def test_cli_runs_placeholder_model_with_cpu_defaults(monkeypatch, capsys): assert kwargs["cleanup"] is False assert kwargs["compressed_patches"] is True assert calls[-1] == ("run", None) - assert "Using interpolation placeholder" in capsys.readouterr().out + assert "sr.tif" in capsys.readouterr().out def test_cli_loads_ldsrs2_model_and_passes_cuda_gpus(monkeypatch): @@ -96,6 +99,56 @@ def test_cli_loads_ldsrs2_model_and_passes_cuda_gpus(monkeypatch): assert kwargs["delete_input_zip"] is True +@pytest.mark.parametrize( + "name,canonical", [("sen2sr", "SEN2SR"), ("SRGAN", "ESASRGAN")] +) +def test_cli_named_models_use_local_artifacts_and_declared_contract( + monkeypatch, name, canonical +): + calls = [] + install_fake_pipeline(monkeypatch, calls) + registry = types.ModuleType("opensr_utils.model_utils.get_models") + model = types.SimpleNamespace(factor=4, output_units="normalized") + loads = [] + registry.get_model = lambda *args, **kwargs: loads.append((args, kwargs)) or model + monkeypatch.setitem(sys.modules, "opensr_utils.model_utils.get_models", registry) + cli.main( + [ + "input.tif", + name, + "--checkpoint", + "local-weights", + "--no-download", + "--bands", + "3", + "2", + "1", + "4", + "--device", + "cpu", + ] + ) + assert loads == [ + ( + (canonical,), + dict( + device="cpu", + checkpoint="local-weights", + config=None, + cache_dir=None, + variant=None, + download=False, + ), + ) + ] + options = calls[0][1] + assert options["model"] is model + assert options["factor"] == 4 + assert options["output_units"] == "normalized" + assert options["band_indexes"] == [3, 2, 1, 4] + assert calls[-1] == ("run", None) + + def test_cli_returns_when_ldsrs2_model_load_fails(monkeypatch, capsys): calls = [] install_fake_pipeline(monkeypatch, calls) @@ -108,10 +161,11 @@ def fail(device="cpu"): monkeypatch.setitem(sys.modules, "opensr_utils.model_utils.get_models", get_models) monkeypatch.setattr(sys, "argv", ["opensr-run", "/data/input.tif", "LDSRS2"]) - cli.main() - + with pytest.raises(SystemExit) as exc: + cli.main() + assert exc.value.code == 1 assert calls == [] - output = capsys.readouterr().out + output = capsys.readouterr().err assert "Could not load LDSR-S2 model" in output assert "download failed" in output @@ -120,7 +174,6 @@ def fail(device="cpu"): "argv", [ [], - ["input.tif"], ["input.tif", "unknown"], ["input.tif", "None", "--device", "tpu"], ["input.tif", "None", "--window_size", "8"], @@ -195,7 +248,9 @@ def test_cli_passes_all_explicit_processing_options_and_runs_once(monkeypatch): window_size=(16, 24), overlap=6, eliminate_border_px=2, - device="cpu", + device="auto", + output_path=None, + output_units="normalized", gpus=None, batch_size=7, num_workers=3, @@ -219,14 +274,11 @@ def fail(**kwargs): monkeypatch.setattr(module, "large_file_processing", fail) monkeypatch.setattr(sys, "argv", ["opensr-run", "input.tif", "None"]) - with pytest.raises(FileExistsError): + with pytest.raises(SystemExit) as exc: cli.main() + assert exc.value.code == 1 -@pytest.mark.known_bug -@pytest.mark.xfail( - reason="CLI returns success when model loading fails", raises=pytest.fail.Exception -) def test_model_loading_failure_returns_nonzero_exit_status(monkeypatch): install_fake_pipeline(monkeypatch, []) get_models = types.ModuleType("opensr_utils.model_utils.get_models") @@ -240,3 +292,68 @@ def fail(device): with pytest.raises(SystemExit) as exc: cli.main() assert exc.value.code != 0 + + +def test_cli_minimal_call_and_output_destination(monkeypatch, capsys): + calls = [] + install_fake_pipeline(monkeypatch, calls) + monkeypatch.setattr( + sys, "argv", ["opensr-run", "input.tif", "-o", "results/output.tif"] + ) + cli.main() + options = calls[0][1] + assert options["model"] is None + assert options["device"] == "auto" + assert options["output_path"] == "results/output.tif" + assert "sr.tif" in capsys.readouterr().out + + +@pytest.mark.integration +def test_cli_real_inference_retains_all_patches_and_writes_explicit_destination( + write_raster, tmp_path +): + import json + import os + from pathlib import Path + import subprocess + + import numpy as np + import rasterio + + data = np.arange(256, dtype=np.uint16).reshape(1, 16, 16) + source = write_raster(tmp_path / "input.tif", data=data, nodata=None) + output = tmp_path / "results" / "output.tif" + completed = subprocess.run( + [ + sys.executable, + "-m", + "opensr_utils", + str(source), + "-o", + str(output), + "--device", + "cpu", + "--factor", + "1", + "--window-size", + "2", + "2", + "--overlap", + "0", + "--batch-size", + "7", + "--keep-temp", + ], + capture_output=True, + text=True, + timeout=45, + env={**os.environ, "CUDA_VISIBLE_DEVICES": ""}, + ) + assert completed.returncode == 0, completed.stderr + assert completed.stdout.strip().splitlines()[-1] == str(output) + with rasterio.open(output) as result: + np.testing.assert_allclose(result.read(), data, atol=1, rtol=0) + (manifest,) = output.parent.glob("temp_*/index.json") + entries = json.loads(manifest.read_text())["entries"] + assert len(entries) == 64 + assert all(Path(entry["path"]).is_file() for entry in entries) diff --git a/tests/test_distributed.py b/tests/test_distributed.py new file mode 100644 index 0000000..08ef10d --- /dev/null +++ b/tests/test_distributed.py @@ -0,0 +1,251 @@ +"""Small real CPU/Gloo checks for prediction finalization.""" + +from types import SimpleNamespace +import os +from datetime import timedelta +import queue as queue_module +import time + +import pytest +import torch +import torch.multiprocessing as mp + +from opensr_utils.model_utils import prepare_model as prepare_module +from opensr_utils.model_utils.prepare_model import get_world_info, preprocess_model + + +def _worker(rank, world, init_file, output_dir, mode, queue, backend="gloo"): + os.environ["RANK"] = str(rank) + os.environ["LOCAL_RANK"] = "0" + if backend == "gloo" and os.name == "posix": + os.environ.setdefault("GLOO_SOCKET_IFNAME", "lo") + if backend == "nccl": + torch.cuda.set_device(rank) + torch.distributed.init_process_group( + backend, + init_method=f"file://{init_file}", + rank=rank, + world_size=world, + timeout=timedelta(seconds=10), + ) + try: + parent = SimpleNamespace( + log_dir=output_dir, + datamodule=SimpleNamespace(dataset=[None] * world), + _log=lambda _message: None, + ) + model = preprocess_model(parent, None, output_dir, [], factor=1) + model._save_sync_timeout = 3 + model.on_predict_start() + if mode in ("rankcheck", "missing_shard", "missing_shard_recover"): + observed_world, observed_rank = get_world_info() + assert (observed_world, observed_rank) == (world, rank) + if mode != "empty" or rank == 0: + batch = { + "image": torch.ones( + (1, 1, 2, 2), device=f"cuda:{rank}" if backend == "nccl" else "cpu" + ), + "meta": [{"row_off": rank, "col_off": 0, "height": 2, "width": 2}], + } + model.predict_step(batch, 0) + if mode in ("band_error", "recover") and rank == 1: + model._output_bands = 2 + if mode == "missing" and rank == 1: + queue.put((rank, "lost-peer")) + return + try: + original_replace = os.replace + replace_state = {"failed": False} + + def replace_with_failure(source, destination): + if ( + mode in ("write_failure", "write_failure_recover") + and rank == 1 + and not replace_state["failed"] + and destination.endswith("index_rank1.json") + ): + replace_state["failed"] = True + raise OSError("injected shard write failure") + return original_replace(source, destination) + + if mode in ("write_failure", "write_failure_recover"): + os.replace = replace_with_failure + original_barrier = prepare_module._distributed_barrier + state = {"first": True} + + def barrier_with_missing_shard(timeout_seconds=30): + result = original_barrier(timeout_seconds) + if ( + rank == 0 + and mode in ("missing_shard", "missing_shard_recover") + and state["first"] + ): + shard = os.path.join(output_dir, "index_rank1.json") + if os.path.exists(shard): + os.unlink(shard) + state["first"] = False + return result + + if mode in ("missing_shard", "missing_shard_recover"): + prepare_module._distributed_barrier = barrier_with_missing_shard + if mode == "recover": + try: + model.on_predict_end() + except Exception: + pass + model._output_bands = 1 + model.on_predict_end() + elif mode == "missing_shard_recover": + try: + model.on_predict_end() + except Exception: + pass + model.on_predict_end() + elif mode == "write_failure_recover": + try: + model.on_predict_end() + except Exception: + pass + os.replace = original_replace + model.on_predict_end() + else: + model.on_predict_end() + queue.put((rank, "ok")) + except Exception as exc: + queue.put((rank, str(exc))) + finally: + if torch.distributed.is_initialized(): + torch.distributed.destroy_process_group() + + +def _run(tmp_path, mode, backend="gloo"): + init_file = str(tmp_path / "gloo-init") + queue = mp.get_context("spawn").Queue() + context = mp.spawn( + _worker, + args=(2, init_file, str(tmp_path), mode, queue, backend), + nprocs=2, + join=False, + ) + deadline = time.monotonic() + 45 + try: + while not context.join(timeout=1): + if time.monotonic() >= deadline: + pytest.fail("Distributed workers exceeded the 45-second deadline") + finally: + for process in context.processes: + if process.is_alive(): + process.terminate() + process.join(timeout=5) + if process.is_alive(): + process.kill() + process.join(timeout=5) + results = [] + for _ in range(2): + try: + results.append(queue.get(timeout=2)) + except (queue_module.Empty, TypeError): + results.append((-1, "worker produced no result")) + queue.close() + queue.join_thread() + return results + + +@pytest.mark.skipif( + not torch.distributed.is_available(), reason="PyTorch distributed unavailable" +) +def test_real_gloo_handles_empty_rank_and_global_rank_metadata(tmp_path): + results = _run(tmp_path, "empty") + assert sorted(results) == [(0, "ok"), (1, "ok")] + + +@pytest.mark.skipif( + not torch.distributed.is_available(), reason="PyTorch distributed unavailable" +) +def test_real_gloo_propagates_manifest_merge_failure_to_all_ranks(tmp_path): + results = _run(tmp_path, "band_error") + assert all( + status.startswith("Distributed prediction finalization failed:") + for _, status in results + ) + assert all("output band count" in status for _, status in results) + + +@pytest.mark.skipif( + not torch.distributed.is_available(), reason="PyTorch distributed unavailable" +) +def test_real_gloo_missing_peer_is_bounded(tmp_path): + results = _run(tmp_path, "missing") + assert any(status == "lost-peer" for _, status in results) + assert any( + "barrier" in status.lower() or "distributed prediction" in status.lower() + for _, status in results + ) + + +@pytest.mark.skipif( + not torch.distributed.is_available(), reason="PyTorch distributed unavailable" +) +def test_real_gloo_merge_failure_can_recover_in_same_group(tmp_path): + results = _run(tmp_path, "recover") + assert sorted(results) == [(0, "ok"), (1, "ok")] + + +@pytest.mark.skipif( + not torch.distributed.is_available(), reason="PyTorch distributed unavailable" +) +def test_real_gloo_missing_shard_is_reported_to_all_ranks(tmp_path): + results = _run(tmp_path, "missing_shard") + assert all( + "Distributed prediction finalization failed" in status for _, status in results + ) + assert all("Missing prediction shard" in status for _, status in results) + + +@pytest.mark.skipif( + not torch.distributed.is_available(), reason="PyTorch distributed unavailable" +) +def test_real_gloo_missing_shard_recovers_in_same_group(tmp_path): + results = _run(tmp_path, "missing_shard_recover") + assert sorted(results) == [(0, "ok"), (1, "ok")] + + +@pytest.mark.skipif( + not torch.distributed.is_available(), reason="PyTorch distributed unavailable" +) +def test_real_gloo_rank1_shard_write_failure_propagates(tmp_path): + results = _run(tmp_path, "write_failure") + assert all("injected shard write failure" in status for _, status in results) + + +@pytest.mark.skipif( + not torch.distributed.is_available(), reason="PyTorch distributed unavailable" +) +def test_real_gloo_rank1_shard_write_failure_recovers(tmp_path): + results = _run(tmp_path, "write_failure_recover") + assert sorted(results) == [(0, "ok"), (1, "ok")] + + +@pytest.mark.skipif( + not torch.distributed.is_available(), reason="PyTorch distributed unavailable" +) +def test_real_gloo_uses_global_rank_when_local_rank_differs(tmp_path): + results = _run(tmp_path, "rankcheck") + assert sorted(results) == [(0, "ok"), (1, "ok")] + + +@pytest.mark.skipif( + torch.cuda.device_count() < 2 or not torch.distributed.is_nccl_available(), + reason="requires two CUDA devices and NCCL", +) +def test_real_nccl_prediction_and_empty_rank_when_two_gpus_are_available(tmp_path): + results = _run(tmp_path, "empty", backend="nccl") + assert sorted(results) == [(0, "ok"), (1, "ok")] + import json + import numpy as np + + manifest = json.loads((tmp_path / "index.json").read_text()) + assert len(manifest["entries"]) == 1 + np.testing.assert_array_equal( + np.load(manifest["entries"][0]["path"]), np.full((1, 2, 2), 10000) + ) diff --git a/tests/test_distributed_trainer.py b/tests/test_distributed_trainer.py new file mode 100644 index 0000000..27b3477 --- /dev/null +++ b/tests/test_distributed_trainer.py @@ -0,0 +1,94 @@ +"""A real Lightning CPU/DDP prediction check with an empty rank.""" + +import json +import os +import subprocess +import sys +import socket + +import numpy as np +import pytest + + +@pytest.mark.skipif(os.name == "nt", reason="ddp_fork is Unix-only") +def test_lightning_ddp_fork_persists_one_window_with_empty_rank(tmp_path): + """Two CPU ranks must finish when the global sampler has one item.""" + raster = tmp_path / "input.tif" + temp = tmp_path / "temp" + script = r""" +import os +import sys +from datetime import timedelta +from types import SimpleNamespace + +import numpy as np +import rasterio +from rasterio.transform import from_origin +from rasterio.windows import Window +from pytorch_lightning import Trainer +from pytorch_lightning.strategies import DDPStrategy + +from opensr_utils.data_utils.datamodule import PredictionDataModule +from opensr_utils.model_utils.prepare_model import preprocess_model + +raster_path, temp_path = sys.argv[1:] +with rasterio.open( + raster_path, "w", driver="GTiff", width=2, height=2, count=1, + dtype="uint16", transform=from_origin(0, 2, 1, 1), nodata=None, +) as dst: + dst.write(np.array([[[1000, 2000], [3000, 4000]]], dtype=np.uint16)) + +windows = [Window(0, 0, 2, 2)] +dm = PredictionDataModule( + "file", raster_path, windows, {"file": raster_path}, + batch_size=1, num_workers=0, +) +dm.setup() +parent = SimpleNamespace(log_dir=temp_path, datamodule=dm, _log=lambda message: None) +model = preprocess_model(parent, None, temp_path, windows, factor=1) +model.model_dm_length = len(dm.dataset) +model._save_temp_folder = temp_path +model._save_windows = windows +model._save_factor = 1 +model._save_compressed = False +model._save_progress_preview = False +model._save_sync_timeout = 20 + +trainer = Trainer( + accelerator="cpu", devices=2, + strategy=DDPStrategy(start_method="fork", timeout=timedelta(seconds=10)), + logger=False, + enable_checkpointing=False, enable_model_summary=False, + enable_progress_bar=False, inference_mode=True, + use_distributed_sampler=False, +) +trainer.predict(model, datamodule=dm, return_predictions=False) +""" + env = os.environ.copy() + env.setdefault("MASTER_ADDR", "127.0.0.1") + # Keep concurrent pytest workers from sharing a process-group endpoint. + with socket.socket() as listener: + listener.bind(("127.0.0.1", 0)) + env["MASTER_PORT"] = str(listener.getsockname()[1]) + if sys.platform.startswith("linux"): + env.setdefault("GLOO_SOCKET_IFNAME", "lo") + env.setdefault("MPLCONFIGDIR", str(tmp_path / "mpl")) + completed = subprocess.run( + [sys.executable, "-c", script, str(raster), str(temp)], + cwd=os.getcwd(), + env=env, + capture_output=True, + text=True, + timeout=60, + ) + assert completed.returncode == 0, completed.stdout + "\n" + completed.stderr + + index_path = temp / "index.json" + assert index_path.exists() + index = json.loads(index_path.read_text()) + assert len(index["entries"]) == 1 + patch_path = temp / "sr_r000000000_c000000000.npy" + assert patch_path.exists() + patch = np.load(patch_path) + assert patch.shape == (1, 2, 2) + np.testing.assert_array_equal(patch[0], [[1000, 2000], [3000, 4000]]) diff --git a/tests/test_esasrgan.py b/tests/test_esasrgan.py new file mode 100644 index 0000000..02466ea --- /dev/null +++ b/tests/test_esasrgan.py @@ -0,0 +1,126 @@ +from pathlib import Path +import sys +import types + +import pytest +import torch + +from opensr_utils.model_utils.esasrgan import ESASRGAN, load_esasrgan + + +class _TinySR(torch.nn.Module): + def forward(self, x): + return torch.nn.functional.interpolate(x, scale_factor=2, mode="nearest") + + +class _PredictSR(_TinySR): + def forward(self, x): + return super().forward(x) * 0.25 + + def predict_step(self, x): + return super().forward(x) * 0.5 + + +class _BrokenPredict(_TinySR): + def predict_step(self, x): + raise TypeError("upstream failure") + + +class _ConfiguredSR(_TinySR): + config = types.SimpleNamespace( + Model=types.SimpleNamespace(in_bands=4), + Generator=types.SimpleNamespace(scaling_factor=2), + ) + + +def test_adapter_normalizes_dn_and_returns_expected_shape(): + model = ESASRGAN(_TinySR(), scale_factor=2, input_units="reflectance") + out = model(torch.full((2, 4, 3, 5), 5000.0)) + assert out.shape == (2, 4, 6, 10) + assert torch.allclose(out, torch.full_like(out, 0.5)) + + +def test_adapter_can_return_reflectance_units(): + model = ESASRGAN(_TinySR(), scale_factor=2, output_units="reflectance") + out = model(torch.full((1, 4, 2, 2), 0.25)) + assert torch.allclose(out, torch.full_like(out, 2500.0)) + + +def test_adapter_prefers_predict_step_without_brightness_heuristic(): + out = ESASRGAN(_PredictSR(), scale_factor=2)(torch.ones(1, 4, 2, 2)) + assert torch.allclose(out, torch.full_like(out, 0.5)) + + +def test_predict_step_errors_are_not_silently_replaced_by_forward(): + with pytest.raises(TypeError, match="upstream failure"): + ESASRGAN(_BrokenPredict(), scale_factor=2)(torch.ones(1, 4, 2, 2)) + + +def test_predict_step_rejects_non_10k_normalizer(): + model = _PredictSR() + model.normalizer = types.SimpleNamespace(method="zero_one") + with pytest.raises(ValueError, match="normalise_10k"): + ESASRGAN(model, scale_factor=2)(torch.ones(1, 4, 2, 2)) + + +@pytest.mark.parametrize("bad", [torch.zeros(1, 3, 2, 2), torch.zeros(1, 4, 2, 2, 1)]) +def test_adapter_rejects_wrong_input_shape(bad): + with pytest.raises(ValueError, match="expects|4-D"): + ESASRGAN(_TinySR(), scale_factor=2)(bad) + + +def test_adapter_rejects_wrong_model_scale(): + with pytest.raises(ValueError, match="does not match"): + ESASRGAN(_TinySR(), scale_factor=4)(torch.zeros(1, 4, 2, 2)) + + +def test_loader_uses_official_optional_api_on_cpu(monkeypatch): + seen = {} + + def load(preset, **kwargs): + seen.update(preset=preset, **kwargs) + return _TinySR() + + monkeypatch.setitem( + sys.modules, "opensr_srgan", types.SimpleNamespace(load_inference_model=load) + ) + adapter = load_esasrgan("RGB-NIR", device="cpu", scale_factor=2) + assert isinstance(adapter, ESASRGAN) + assert seen == {"preset": "RGB-NIR", "map_location": "cpu", "cache_dir": None} + + +def test_loader_local_module_checkpoint(tmp_path): + path = Path(tmp_path) / "model.pt" + torch.save(_TinySR(), path) + adapter = load_esasrgan(checkpoint=path, scale_factor=2) + assert torch.allclose(adapter(torch.ones(1, 4, 1, 1)), torch.ones(1, 4, 2, 2)) + + +def test_loader_explains_missing_optional_package(monkeypatch): + monkeypatch.setitem(sys.modules, "opensr_srgan", None) + with pytest.raises(ImportError, match="opensr-srgan"): + load_esasrgan() + + +def test_loader_infers_config_scale_and_rejects_explicit_mismatch(monkeypatch): + def load_from_config(*args, **kwargs): + return _ConfiguredSR() + + fake = types.SimpleNamespace(load_from_config=load_from_config) + monkeypatch.setitem(sys.modules, "opensr_srgan", fake) + model = load_esasrgan(config_path="config.yaml", checkpoint="weights.ckpt") + assert model.factor == 2 + with pytest.raises(ValueError, match="conflicts"): + load_esasrgan( + config_path="config.yaml", checkpoint="weights.ckpt", scale_factor=4 + ) + + +def test_loader_rejects_config_without_checkpoint(): + with pytest.raises(ValueError, match="requires checkpoint"): + load_esasrgan(config_path="config.yaml") + + +def test_loader_rejects_swir_preset_until_six_band_pipeline_is_explicit(): + with pytest.raises(ValueError, match="SWIR"): + load_esasrgan("SWIR") diff --git a/tests/test_examples.py b/tests/test_examples.py new file mode 100644 index 0000000..dfb7122 --- /dev/null +++ b/tests/test_examples.py @@ -0,0 +1,171 @@ +"""Smoke tests for the import-light instructional scripts.""" + +from __future__ import annotations + +import subprocess +import sys +import types +from pathlib import Path + +import pytest + + +ROOT = Path(__file__).resolve().parents[1] + + +def test_demo_help_is_available_without_model_imports(): + result = subprocess.run( + [sys.executable, str(ROOT / "demo.py"), "--help"], + cwd=ROOT, + check=False, + capture_output=True, + text=True, + ) + assert result.returncode == 0 + assert "--checkpoint" in result.stdout + assert "--model" in result.stdout + + +def test_model_examples_expose_help_without_downloading_weights(): + for script in ("run_sen2sr.py", "run_esasrgan.py"): + result = subprocess.run( + [sys.executable, str(ROOT / "examples" / script), "--help"], + cwd=ROOT, + check=False, + capture_output=True, + text=True, + ) + assert result.returncode == 0, result.stderr + assert "usage:" in result.stdout + + +def test_demo_runs_tiny_model_none_workflow(tmp_path): + rasterio = pytest.importorskip("rasterio") + import numpy as np + + source = tmp_path / "input.tif" + output = tmp_path / "output.tif" + with rasterio.open( + source, + "w", + driver="GTiff", + width=4, + height=4, + count=1, + dtype="uint16", + crs="EPSG:4326", + transform=rasterio.transform.from_origin(0, 4, 1, 1), + ) as dst: + dst.write(np.arange(16, dtype="uint16").reshape(1, 4, 4)) + result = subprocess.run( + [ + sys.executable, + str(ROOT / "demo.py"), + str(source), + "--model", + "none", + "--factor", + "1", + "--output", + str(output), + ], + cwd=ROOT, + check=False, + capture_output=True, + text=True, + ) + assert result.returncode == 0, result.stderr + assert output.exists() + + +def test_demo_passes_checkpoint_options_to_model_registry(monkeypatch, tmp_path): + import demo + import opensr_utils + + calls = [] + fake_loader = types.ModuleType("opensr_utils.model_utils.get_models") + + def get_model(name, **kwargs): + calls.append((name, kwargs)) + return "fake-model" + + fake_loader.get_model = get_model + monkeypatch.setitem(sys.modules, "opensr_utils.model_utils.get_models", fake_loader) + forwarded = {} + monkeypatch.setattr( + opensr_utils, "super_resolve", lambda *a, **kw: forwarded.update(kw) or "result" + ) + checkpoint = tmp_path / "model.ckpt" + config = tmp_path / "model.yaml" + assert ( + demo.main( + [ + "input.tif", + "--model", + "ESASRGAN", + "--checkpoint", + str(checkpoint), + "--config", + str(config), + "--no-download", + ] + ) + == 0 + ) + assert calls == [ + ( + "esasrgan", + { + "device": "cpu", + "checkpoint": checkpoint, + "cache_dir": None, + "download": False, + "config": config, + }, + ) + ] + + +def test_demo_translates_cuda_device_selector_to_pipeline_gpu(monkeypatch): + import demo + import opensr_utils + + forwarded = {} + monkeypatch.setattr( + opensr_utils, "super_resolve", lambda *a, **kw: forwarded.update(kw) or "result" + ) + assert demo.main(["input.tif", "--model", "none", "--device", "cuda:3"]) == 0 + assert forwarded["device"] == "cuda" + assert forwarded["gpus"] == [3] + + +def test_esasrgan_example_forwards_auto_download_and_cache_options( + monkeypatch, tmp_path +): + import opensr_utils + from examples import run_esasrgan + + calls = [] + fake_loader = types.ModuleType("opensr_utils.model_utils.get_models") + + def get_model(name, **kwargs): + calls.append((name, kwargs)) + return "fake-model" + + fake_loader.get_model = get_model + monkeypatch.setitem(sys.modules, "opensr_utils.model_utils.get_models", fake_loader) + monkeypatch.setattr(opensr_utils, "super_resolve", lambda *a, **kw: "result") + cache_dir = tmp_path / "cache" + assert run_esasrgan.main(["input.tif", "--cache-dir", str(cache_dir)]) == 0 + assert calls == [ + ( + "esasrgan", + { + "device": "cpu", + "checkpoint": None, + "config": None, + "cache_dir": cache_dir, + "download": True, + }, + ) + ] diff --git a/tests/test_imports.py b/tests/test_imports.py index 020b2d8..10c4a74 100644 --- a/tests/test_imports.py +++ b/tests/test_imports.py @@ -15,6 +15,7 @@ "opensr_utils", "opensr_utils.data_utils", "opensr_utils.model_utils", + "opensr_utils.model_utils.get_models", "opensr_utils.cli", "opensr_utils.data_utils.transform_to_cog", ], diff --git a/tests/test_masks.py b/tests/test_masks.py new file mode 100644 index 0000000..5833283 --- /dev/null +++ b/tests/test_masks.py @@ -0,0 +1,135 @@ +import numpy as np +import rasterio +from rasterio.transform import from_origin + +from opensr_utils.data_utils.datamodule import PredictionDataset +from opensr_utils.data_utils.masking import apply_input_mask + + +def _write(path, values, *, nodata=None, mask=None): + values = np.asarray(values) + with rasterio.open( + path, + "w", + driver="GTiff", + width=values.shape[-1], + height=values.shape[-2], + count=1, + dtype=values.dtype, + transform=from_origin(0, values.shape[-2], 1, 1), + nodata=nodata, + ) as dst: + dst.write(values[None]) + if mask is not None: + dst.write_mask(np.asarray(mask, dtype=np.uint8) * 255) + + +def test_dataset_masks_nonfinite_and_intersects_dictionary_inputs(tmp_path): + first = tmp_path / "first.tif" + second = tmp_path / "second.tif" + _write(first, np.array([[0, 10000], [20000, 30000]], dtype=np.float32)) + _write( + second, np.array([[1, np.nan], [1, 1]], dtype=np.float32), mask=[[1, 1], [0, 1]] + ) + + dataset = PredictionDataset( + "S2GM", + str(tmp_path), + [rasterio.windows.Window(0, 0, 2, 2)], + {"R": str(first), "G": str(second)}, + ) + image = dataset[0]["image"].numpy() + assert image[0, 0, 0] == 0 # valid zero remains data + assert image[0, 0, 1] == 0 # invalid through the other source + assert image[1, 1, 0] == 0 # source mask is intersected + assert image[1, 0, 1] == 0 # NaN is filled before normalization + + +def test_apply_input_mask_upscales_nearest_and_keeps_valid_zero(tmp_path): + source = tmp_path / "source.tif" + _write( + source, np.ones((2, 2), dtype=np.uint16), nodata=65535, mask=[[1, 0], [1, 1]] + ) + output = tmp_path / "output.tif" + with rasterio.open( + output, + "w", + driver="GTiff", + width=4, + height=4, + count=1, + dtype="uint16", + transform=from_origin(0, 2, 0.5, 0.5), + nodata=0, + tiled=True, + blockxsize=16, + blockysize=16, + ) as dst: + runner = type( + "Runner", + (), + {"image_meta": {"lr_file_dict": {"R": str(source)}, "output_factor": 2}}, + )() + apply_input_mask(runner, dst) + dst.write(np.zeros((1, 4, 4), dtype=np.uint16)) + + with rasterio.open(output) as src: + mask = src.read_masks(1) + assert np.all(mask[:2, :2] == 255) + assert np.all(mask[:2, 2:] == 0) + assert src.nodata == 65535 + + +def test_apply_input_mask_is_exact_across_partial_blocks_and_factor_three(tmp_path): + """The last 1-pixel output rows/columns must map to the right LR pixels.""" + height, width, factor = 173, 171, 3 + transform = rasterio.Affine(1.2, 0.17, 42.0, -0.11, -1.3, 9.0) + first = tmp_path / "first-large.tif" + second = tmp_path / "second-large.tif" + first_values = np.ones((height, width), dtype=np.float32) + second_values = np.full((height, width), 2.0, dtype=np.float32) + # A finite source value is still invalid when its source mask is zero. + second_values[169, 170] = np.nan + first_mask = np.ones((height, width), dtype=np.uint8) + second_mask = np.ones((height, width), dtype=np.uint8) + first_mask[2, 4] = 0 + second_mask[100, 80] = 0 + _write(first, first_values, mask=first_mask) + _write(second, second_values, mask=second_mask) + + output = tmp_path / "large-output.tif" + out_height, out_width = height * factor, width * factor + with rasterio.open( + output, + "w", + driver="GTiff", + width=out_width, + height=out_height, + count=5, # output channels need not match input channels + dtype="uint16", + transform=transform * rasterio.Affine.scale(1 / factor), + tiled=True, + blockxsize=256, + blockysize=256, + ) as dst: + runner = type( + "Runner", + (), + { + "image_meta": { + "lr_file_dict": {"R": str(first), "G": str(second)}, + "output_factor": factor, + } + }, + )() + apply_input_mask(runner, dst) + + with rasterio.open(output) as src: + actual = src.read_masks(1) == 255 + expected_lr = first_mask.astype(bool) & second_mask.astype(bool) + expected_lr[169, 170] = False # nonfinite source value + expected = expected_lr[ + np.floor_divide(np.arange(out_height), factor)[:, None], + np.floor_divide(np.arange(out_width), factor)[None, :], + ] + np.testing.assert_array_equal(actual, expected) diff --git a/tests/test_model_band_indexes.py b/tests/test_model_band_indexes.py new file mode 100644 index 0000000..d6fbfff --- /dev/null +++ b/tests/test_model_band_indexes.py @@ -0,0 +1,90 @@ +"""Public band index behavior for ordinary multi-band model inputs.""" + +import numpy as np +import rasterio +from rasterio.transform import from_origin + +from opensr_utils.data_utils.datamodule import PredictionDataset +from opensr_utils.data_utils.masking import apply_input_mask + + +def _write_five_band(path, data): + with rasterio.open( + path, + "w", + driver="GTiff", + width=2, + height=2, + count=5, + dtype="float32", + transform=from_origin(0, 2, 1, 1), + ) as dst: + dst.write(np.asarray(data, dtype=np.float32)) + + +def test_file_dataset_reads_reordered_selected_band_indexes(tmp_path): + source = tmp_path / "five-band.tif" + values = np.stack( + [ + np.full((2, 2), 1000), # extra + np.full((2, 2), 2000), # G + np.full((2, 2), 3000), # B + np.full((2, 2), 4000), # R + np.full((2, 2), 8000), # NIR + ] + ) + _write_five_band(source, values) + dataset = PredictionDataset( + "file", + str(source), + [rasterio.windows.Window(0, 0, 2, 2)], + {}, + band_indexes=[4, 2, 3, 5], + ) + + np.testing.assert_allclose(dataset[0]["image"][:, 0, 0], [0.4, 0.2, 0.3, 0.8]) + + +def test_file_mask_ignores_invalid_unselected_band(tmp_path): + source = tmp_path / "five-band-invalid-extra.tif" + values = np.stack( + [ + np.full((2, 2), np.nan), # invalid, unselected extra + np.full((2, 2), 2000), + np.full((2, 2), 3000), + np.full((2, 2), 4000), + np.full((2, 2), 8000), + ] + ) + _write_five_band(source, values) + output = tmp_path / "output.tif" + with rasterio.open( + output, + "w", + driver="GTiff", + width=4, + height=4, + count=1, + dtype="uint16", + transform=from_origin(0, 2, 0.5, 0.5), + tiled=True, + blockxsize=16, + blockysize=16, + ) as dst: + runner = type( + "Runner", + (), + { + "input_type": "file", + "factor": 2, + "image_meta": { + "lr_file_dict": {"file": str(source)}, + "band_indexes": [4, 2, 3, 5], + "output_factor": 2, + }, + }, + )() + apply_input_mask(runner, dst) + + with rasterio.open(output) as src: + assert np.all(src.read_masks(1) == 255) diff --git a/tests/test_model_registry.py b/tests/test_model_registry.py new file mode 100644 index 0000000..1fa02c5 --- /dev/null +++ b/tests/test_model_registry.py @@ -0,0 +1,84 @@ +"""Named dispatch stays lazy and makes local/offline artifact choices explicit.""" + +from pathlib import Path + +import pytest + +from opensr_utils.model_utils import get_models + + +@pytest.mark.parametrize( + "name,expected", + [ + (None, "None"), + ("bilinear", "None"), + ("LDSR-S2", "LDSRS2"), + ("sen2sr", "SEN2SR"), + ("SEN2SRLite", "SEN2SR"), + ("srgan", "ESASRGAN"), + ("ESASRGAN", "ESASRGAN"), + ], +) +def test_model_aliases_have_one_canonical_dispatch(name, expected): + assert get_models.normalize_model_name(name) == expected + + +def test_unknown_model_reports_available_choices(): + with pytest.raises(ValueError, match="Unknown model.*SEN2SR"): + get_models.get_model("unavailable") + + +def test_sen2sr_local_manifest_uses_offline_directory(monkeypatch, tmp_path): + manifest = tmp_path / "mlm.json" + manifest.write_text("{}") + calls = [] + sentinel = object() + monkeypatch.setattr( + get_models, "get_sen2sr", lambda **kwargs: calls.append(kwargs) or sentinel + ) + assert ( + get_models.get_model( + "SEN2SR", checkpoint=manifest, download=False, variant="lite" + ) + is sentinel + ) + assert calls == [ + dict( + device="cpu", + cache_dir=None, + download=False, + variant="lite", + model_dir=tmp_path, + ) + ] + + +def test_srgan_local_artifacts_are_forwarded_to_official_loader(monkeypatch, tmp_path): + checkpoint = tmp_path / "generator.ckpt" + checkpoint.write_bytes(b"mock checkpoint boundary") + config = tmp_path / "config.yaml" + config.write_text("Model: {}") + calls = [] + monkeypatch.setattr( + get_models, "get_esasrgan", lambda **kwargs: calls.append(kwargs) or "adapter" + ) + assert ( + get_models.get_model( + "SRGAN", config=config, checkpoint=checkpoint, download=False + ) + == "adapter" + ) + assert calls == [ + dict(device="cpu", checkpoint=checkpoint, config_path=config, cache_dir=None) + ] + + +@pytest.mark.parametrize("model", ["SEN2SR", "SRGAN"]) +def test_offline_loading_requires_explicit_local_artifacts(model): + with pytest.raises(ValueError, match="requires"): + get_models.get_model(model, download=False) + + +def test_interpolation_does_not_accept_a_checkpoint(tmp_path): + with pytest.raises(ValueError, match="Interpolation"): + get_models.get_model(None, checkpoint=Path(tmp_path / "model.pt")) diff --git a/tests/test_named_models.py b/tests/test_named_models.py new file mode 100644 index 0000000..782a59d --- /dev/null +++ b/tests/test_named_models.py @@ -0,0 +1,161 @@ +"""Adapter-backed public workflows with real raster I/O and independent pixels.""" + +import zipfile +from types import SimpleNamespace + +import numpy as np +import pytest +import rasterio +import torch + +from opensr_utils import super_resolve +from opensr_utils.model_utils.esasrgan import ESASRGAN +from opensr_utils.model_utils.sen2sr import SEN2SRAdapter + + +RGBN = ("B04", "B03", "B02", "B08") + + +class FixedSENTile(torch.nn.Module): + def forward(self, x): + assert x.shape[-2:] == (128, 128) + return x.repeat_interleave(4, -2).repeat_interleave(4, -1) + + +class OfficialGAN(torch.nn.Module): + normalizer = SimpleNamespace(method="normalise_10k") + + def forward(self, x): + pytest.fail("Official ESA inference must use predict_step") + + def predict_step(self, x): + return x.repeat_interleave(4, -2).repeat_interleave(4, -1) + + +def adapter(name): + if name == "SEN2SR": + return SEN2SRAdapter(FixedSENTile()) + return ESASRGAN(OfficialGAN()) + + +@pytest.mark.integration +@pytest.mark.parametrize("name", ["SEN2SR", "ESASRGAN"]) +def test_declared_model_bands_reorder_files_and_preserve_validity_and_labels( + name, write_raster, tmp_path +): + values = np.array([8000, 2000, np.nan, 4000, 3000], dtype=np.float32) + data = np.broadcast_to(values[:, None, None], (5, 3, 5)).copy() + data[3, 1, 2] = np.nan + source = write_raster( + tmp_path / "input.tif", data=data, dtype="float32", nodata=None + ) + with rasterio.open(source, "r+") as raster: + raster.descriptions = ("B08", "B02", "unused", "B04", "B03") + output = super_resolve( + source, adapter(name), device="cpu", window_size=(8, 8), overlap=4 + ) + expected = data[[3, 4, 1, 0]].copy() + valid = np.isfinite(expected).all(axis=0) + expected[:, ~valid] = 0 + expected = np.repeat(np.repeat(expected, 4, 1), 4, 2) + expected_mask = np.repeat(np.repeat(valid, 4, 0), 4, 1) + with rasterio.open(output) as result: + assert result.descriptions == RGBN + assert result.shape == (12, 20) + # Data beneath the invalid output mask is deliberately unspecified. + np.testing.assert_allclose( + result.read()[:, expected_mask], expected[:, expected_mask], atol=1, rtol=0 + ) + np.testing.assert_array_equal(result.read_masks(1) != 0, expected_mask) + + +@pytest.mark.integration +@pytest.mark.parametrize("name", ["SEN2SR", "ESASRGAN"]) +def test_model_selection_ignores_unused_dictionary_spectral_bands( + name, write_raster, tmp_path +): + source = tmp_path / "spectral_bands" + for band, value in ( + ("B04", 4000), + ("B03", 3000), + ("B02", 2000), + ("B08", 8000), + ("B11", 65535), + ): + write_raster( + source / f"{band}.tif", data=np.full((1, 3, 5), value), nodata=65535 + ) + output = super_resolve(source, adapter(name), device="cpu") + with rasterio.open(output) as result: + np.testing.assert_array_equal(result.read()[:, 0, 0], [4000, 3000, 2000, 8000]) + assert np.all(result.read_masks() == 255) + assert result.descriptions == RGBN + + +def test_named_public_api_loads_on_cpu_and_infers_factor( + monkeypatch, write_raster, tmp_path +): + from opensr_utils.model_utils import get_models + + calls = [] + source = write_raster( + tmp_path / "input.tif", data=np.full((4, 2, 3), 2000), nodata=None + ) + + def load(name, **options): + calls.append((name, options)) + return adapter("SEN2SR") + + monkeypatch.setattr(get_models, "get_model", load) + output = super_resolve( + source, "sen2sr", device="cpu", checkpoint=tmp_path / "weights", download=False + ) + assert calls[0][0] == "SEN2SR" + assert calls[0][1]["device"] == "cpu" + assert calls[0][1]["download"] is False + with rasterio.open(output) as result: + assert result.shape == (8, 12) + np.testing.assert_array_equal(result.read(), np.full((4, 8, 12), 2000)) + + +def test_invalid_model_contract_keeps_source_archive(write_raster, tmp_path): + product = tmp_path / "source" / "tile.SAFE" + bands = product / "GRANULE" / "tile" / "IMG_DATA" + for band in RGBN: + write_raster(bands / f"TEST_{band}_10m.jp2", data=np.full((1, 2, 3), 2000)) + archive = tmp_path / "input.zip" + with zipfile.ZipFile(archive, "w") as container: + for path in product.rglob("*"): + if path.is_file(): + container.write(path, path.relative_to(product.parent)) + with pytest.raises(ValueError, match="produces factor 4"): + super_resolve(archive, adapter("SEN2SR"), factor=2, delete_input_zip=True) + assert archive.is_file() + assert not (tmp_path / "sr.tif").exists() + + +def test_pipeline_rejects_adapter_that_would_normalize_twice(write_raster, tmp_path): + source = write_raster(tmp_path / "input.tif", count=4) + model = ESASRGAN(OfficialGAN(), input_units="reflectance") + with pytest.raises(ValueError, match="supplies normalized"): + super_resolve(source, model) + + +def test_sen2sr_rejects_oversize_windows_before_inference(write_raster, tmp_path): + source = write_raster(tmp_path / "input.tif", count=4, width=129, height=129) + with pytest.raises(ValueError, match="accepts windows up to"): + super_resolve(source, adapter("SEN2SR"), window_size=(256, 256)) + + +def test_unlabeled_multiband_input_can_select_explicit_rgbn_indexes( + write_raster, tmp_path +): + data = np.broadcast_to( + np.array([8000, 2000, 9999, 4000, 3000])[:, None, None], (5, 2, 3) + ) + source = write_raster(tmp_path / "input.tif", data=data, nodata=None) + output = super_resolve( + source, adapter("ESASRGAN"), band_indexes=[4, 5, 2, 1], device="cpu" + ) + with rasterio.open(output) as result: + np.testing.assert_array_equal(result.read()[:, 0, 0], [4000, 3000, 2000, 8000]) diff --git a/tests/test_pipeline_helpers.py b/tests/test_pipeline_helpers.py index 95ee1b3..40abee7 100644 --- a/tests/test_pipeline_helpers.py +++ b/tests/test_pipeline_helpers.py @@ -380,29 +380,6 @@ def test_run_refuses_to_overwrite_existing_output(tmp_path): runner.run() -def test_write_to_file_delegates_to_ddp_safe_stitch(monkeypatch, tmp_path): - from opensr_utils.data_utils import writing_utils - - runner = blank_runner() - runner.overwrite = False - calls = [] - - def fake_ddp_safe_stitch(self, **kwargs): - calls.append((self, kwargs)) - return ("out.tif", 0) - - monkeypatch.setattr(writing_utils, "ddp_safe_stitch", fake_ddp_safe_stitch) - - assert runner.write_to_file( - index_path=str(tmp_path / "index.json"), limit=2, overwrite=True - ) == ("out.tif", 0) - assert runner.overwrite is True - assert calls[0][0] is runner - assert calls[0][1]["index_path"].endswith("index.json") - assert calls[0][1]["limit"] == 2 - assert calls[0][1]["profile"] == "sigmoid" - - def test_write_to_file_creates_placeholder_from_prediction_index(monkeypatch, tmp_path): from opensr_utils.data_utils import writing_utils diff --git a/tests/test_pipeline_integration.py b/tests/test_pipeline_integration.py index 6d4f397..85d24f9 100644 --- a/tests/test_pipeline_integration.py +++ b/tests/test_pipeline_integration.py @@ -82,11 +82,6 @@ def test_tiled_inference_matches_whole_image_and_preserves_georeferencing( assert not Path(runner.placeholder_filepath).exists() -@pytest.mark.known_bug -@pytest.mark.xfail( - reason="Upscaling divides affine a/e but leaves rotation/shear b/d unchanged", - raises=AssertionError, -) def test_upscaling_rotated_raster_preserves_its_spatial_footprint( write_raster, pipeline_factory, tmp_path ): @@ -178,11 +173,6 @@ def test_explicit_overwrite_replaces_old_output_with_readable_result( np.testing.assert_array_equal(result.read(), np.full((1, 16, 16), 2000)) -@pytest.mark.known_bug -@pytest.mark.xfail( - reason="Stitcher deletes patches every 50 tiles even with cleanup=False", - raises=AssertionError, -) def test_keep_temp_preserves_every_prediction_for_reproducibility( write_raster, pipeline_factory, tmp_path ): diff --git a/tests/test_prepare_model.py b/tests/test_prepare_model.py index 3a8893b..143cc3b 100644 --- a/tests/test_prepare_model.py +++ b/tests/test_prepare_model.py @@ -47,7 +47,7 @@ def test_get_world_info_prefers_initialized_distributed(monkeypatch): assert prepare_model.get_world_info() == (4, 2) -def test_get_world_info_uses_cuda_count_without_distributed(monkeypatch): +def test_visible_gpus_do_not_create_distributed_processes(monkeypatch): monkeypatch.setattr(prepare_model.torch.distributed, "is_available", lambda: True) monkeypatch.setattr( prepare_model.torch.distributed, "is_initialized", lambda: False @@ -55,7 +55,7 @@ def test_get_world_info_uses_cuda_count_without_distributed(monkeypatch): monkeypatch.setattr(prepare_model.torch.cuda, "is_available", lambda: True) monkeypatch.setattr(prepare_model.torch.cuda, "device_count", lambda: 3) - assert prepare_model.get_world_info() == (3, 0) + assert prepare_model.get_world_info() == (1, 0) def test_preprocess_model_uses_placeholder_and_writes_prediction_index(tmp_path): @@ -279,17 +279,17 @@ def test_prediction_manifest_round_trips_values_coordinates_and_format( @pytest.mark.parametrize( - "values,expected", + "values,expected,units", [ - ([-0.25, 0, 0.125, 1.25], [0, 0, 1250, 10000]), - ([100, 1000, 5000, 12000], [100, 1000, 5000, 10000]), + ([-0.25, 0, 0.125, 1.25], [0, 0, 1250, 10000], "normalized"), + ([100, 1000, 5000, 12000], [100, 1000, 5000, 10000], "reflectance"), ], ) def test_saved_predictions_support_normalized_and_reflectance_outputs( - tmp_path, values, expected + tmp_path, values, expected, units ): model = prepare_model.preprocess_model( - parent(tmp_path, 1), None, str(tmp_path), [], factor=1 + parent(tmp_path, 1), None, str(tmp_path), [], factor=1, output_units=units ) model.on_predict_start() model.predict_step( @@ -339,11 +339,6 @@ def test_model_preparation_rejects_invalid_scale_before_writing(tmp_path, factor assert not list(tmp_path.iterdir()) -@pytest.mark.known_bug -@pytest.mark.xfail( - reason="Non-finite predictions are cast to uint16 rather than rejected", - raises=pytest.fail.Exception, -) @pytest.mark.parametrize("value", [float("nan"), float("inf"), -float("inf")]) def test_nonfinite_model_output_is_rejected_before_saving(tmp_path, value): model = prepare_model.preprocess_model( @@ -355,11 +350,6 @@ def test_nonfinite_model_output_is_rejected_before_saving(tmp_path, value): assert not list(tmp_path.glob("*.npy")) -@pytest.mark.known_bug -@pytest.mark.xfail( - reason="A model can silently drop batch samples without validation", - raises=pytest.fail.Exception, -) def test_output_batch_size_must_match_input_batch_size(tmp_path): class DropsSample(torch.nn.Module): def forward(self, x): @@ -373,6 +363,18 @@ def forward(self, x): model.predict_step(prediction_batch(torch.ones((2, 1, 2, 2))), 0) +def test_invalid_later_metadata_record_writes_no_batch_patches(tmp_path): + model = prepare_model.preprocess_model( + parent(tmp_path), None, str(tmp_path), [], factor=1 + ) + model.on_predict_start() + batch = prediction_batch(torch.ones((2, 1, 2, 2))) + batch["meta"]["height"][1] = 0 + with pytest.raises(ValueError, match="non-positive height"): + model.predict_step(batch, 0) + assert not list(tmp_path.glob("*.npy")) + + def distributed_context(monkeypatch): """Simulate rank metadata; these tests do not claim GPU/process coverage.""" dist = prepare_model.torch.distributed @@ -435,3 +437,44 @@ def test_distributed_manifest_merge_handles_empty_mismatched_and_missing_shards( with pytest.raises(exception, match=message): model.on_predict_end() assert not (tmp_path / "index.json").exists() + + +@pytest.mark.parametrize( + "units,expected", + [ + ("normalized", [0, 1, 9999, 10000, 10000, 10000, 10000, 10000]), + ("reflectance", [0, 0, 1, 1, 1, 10, 10, 10]), + ], +) +def test_explicit_output_units_have_no_brightness_threshold(tmp_path, units, expected): + values = torch.tensor([0, 0.0001, 0.9999, 1, 1.0001, 9.999, 10, 10.001]) + model = prepare_model.preprocess_model( + parent(tmp_path, 1), None, str(tmp_path), [], factor=1, output_units=units + ) + model.on_predict_start() + model.predict_step(prediction_batch(values.reshape(1, 1, 2, 4)), 0) + model.on_predict_end() + manifest = json.loads((tmp_path / "index.json").read_text()) + assert manifest["output_units"] == units + np.testing.assert_array_equal( + np.load(manifest["entries"][0]["path"]).ravel(), expected + ) + + +@pytest.mark.parametrize("metadata", ["lists", "records"]) +@pytest.mark.parametrize("invalid", [0.5, float("nan"), True]) +def test_noninteger_later_offsets_cannot_partially_persist_batch( + tmp_path, metadata, invalid +): + model = prepare_model.preprocess_model( + parent(tmp_path), None, str(tmp_path), [], factor=1 + ) + model.on_predict_start() + batch = prediction_batch(torch.ones((2, 1, 2, 2)), metadata=metadata) + if metadata == "lists": + batch["meta"]["row_off"][1] = invalid + else: + batch["meta"][1]["row_off"] = invalid + with pytest.raises(ValueError, match="integer row_off"): + model.predict_step(batch, 0) + assert not list(tmp_path.glob("*.npy")) diff --git a/tests/test_public_api.py b/tests/test_public_api.py new file mode 100644 index 0000000..624dbb1 --- /dev/null +++ b/tests/test_public_api.py @@ -0,0 +1,129 @@ +"""Public workflows: one call, explicit destination and diagnostic-only debug runs.""" + +import json +import os +from pathlib import Path + +import numpy as np +import pytest +import rasterio +import torch + +from opensr_utils import super_resolve + + +class Identity(torch.nn.Module): + def forward(self, x): + return x + + +@pytest.mark.integration +def test_one_call_api_writes_requested_output_and_releases_sources( + write_raster, tmp_path +): + data = np.arange(20, dtype=np.uint16).reshape(1, 4, 5) * 100 + source = write_raster(tmp_path / "source.tif", data=data, nodata=None) + destination = tmp_path / "results" / "enhanced.tif" + result = super_resolve(source, Identity(), destination, factor=1, device="cpu") + assert result == str(destination) + with rasterio.open(result) as src: + np.testing.assert_array_equal(src.read(), data) + np.testing.assert_array_equal(src.dataset_mask(), np.full((4, 5), 255)) + assert source.exists() + assert not list(destination.parent.glob("temp_*")) + assert len(list(destination.parent.glob("logs_*"))) == 1 + with pytest.raises(FileExistsError): + super_resolve(source, Identity(), destination, factor=1, device="cpu") + + +@pytest.mark.integration +def test_debug_retains_first_100_windows_and_never_publishes_partial_output( + write_raster, pipeline_factory, tmp_path +): + source = write_raster(tmp_path / "input.tif", width=22, height=22, nodata=None) + runner = pipeline_factory( + source, model=Identity(), factor=1, window_size=(2, 2), overlap=0, cleanup=True + ) + output = Path(runner.final_sr_path) + output.write_bytes(b"previous complete output") + manifest = Path(runner.run(debug=True)) + index = json.loads(manifest.read_text()) + assert len(index["entries"]) == 100 + assert len(runner.image_meta["image_windows"]) == 121 + assert all(Path(entry["path"]).is_file() for entry in index["entries"]) + assert output.read_bytes() == b"previous complete output" + assert not Path(runner.placeholder_filepath).exists() + + # A subsequent full run must cover the whole raster and may clean diagnostics. + runner.run(debug=False, overwrite=True) + with rasterio.open(output) as result, rasterio.open(source) as original: + np.testing.assert_allclose(result.read(), original.read(), atol=1) + assert not manifest.parent.exists() + + +@pytest.mark.parametrize("alias", ["same", "symlink", "hardlink"]) +def test_output_cannot_replace_input_even_with_overwrite(alias, write_raster, tmp_path): + source = write_raster(tmp_path / "input.tif") + destination = source if alias == "same" else tmp_path / "alias.tif" + if alias == "symlink": + destination.symlink_to(source) + elif alias == "hardlink": + os.link(source, destination) + before = source.read_bytes() + with pytest.raises(ValueError, match="[Oo]utput.*input|[Oo]utput.*source"): + super_resolve(source, Identity(), destination, factor=1, overwrite=True) + assert source.read_bytes() == before + + +def test_default_output_cannot_replace_input_named_sr(write_raster, tmp_path): + source = write_raster(tmp_path / "sr.tif") + before = source.read_bytes() + with pytest.raises(ValueError, match="[Oo]utput.*input|[Oo]utput.*source"): + super_resolve(source, Identity(), factor=1, overwrite=True) + assert source.read_bytes() == before + + +@pytest.mark.integration +def test_final_raster_preserves_source_mask_when_valid_predictions_are_zero( + write_raster, tmp_path +): + class Zeros(torch.nn.Module): + def forward(self, x): + return ( + torch.zeros_like(x[:, :1]) + .repeat_interleave(2, -2) + .repeat_interleave(2, -1) + ) + + values = np.array([[[0, 100], [200, 300]]], dtype=np.uint16) + source = write_raster(tmp_path / "input.tif", data=values, nodata=0) + output = super_resolve(source, Zeros(), factor=2, device="cpu") + with rasterio.open(output) as result: + np.testing.assert_array_equal( + result.read(), np.zeros((1, 4, 4), dtype=np.uint16) + ) + expected_valid = np.repeat(np.repeat(values[0] != 0, 2, 0), 2, 1) + np.testing.assert_array_equal(result.read_masks(1) != 0, expected_valid) + assert result.nodata == 0 + assert not Path(output + ".msk").exists() + + +def test_one_call_api_rejects_auto_run_before_side_effects(tmp_path): + with pytest.raises(TypeError, match="omit auto_run"): + super_resolve(tmp_path / "input.tif", auto_run=True) + assert not list(tmp_path.iterdir()) + + +@pytest.mark.integration +def test_band_folder_discovery_does_not_require_a_special_directory_name( + write_raster, tmp_path +): + folder = tmp_path / "bands" + values = {"b04": 4000, "b03": 3000, "b02": 2000, "b08": 8000} + for band, value in values.items(): + write_raster( + folder / f"{band}.tiff", data=np.full((1, 2, 3), value), nodata=None + ) + output = super_resolve(folder, Identity(), factor=1, device="cpu") + with rasterio.open(output) as result: + np.testing.assert_array_equal(result.read()[:, 0, 0], list(values.values())) diff --git a/tests/test_reading_utils.py b/tests/test_reading_utils.py index 245d0b4..9c0b7ea 100644 --- a/tests/test_reading_utils.py +++ b/tests/test_reading_utils.py @@ -4,6 +4,7 @@ from pathlib import Path import pytest +import rasterio from opensr_utils.data_utils import reading_utils @@ -77,10 +78,14 @@ def test_verify_input_file_type_extracts_safe_zip(dummy_runner, tmp_path): assert archive.exists() -def test_verify_input_file_type_can_delete_zip_after_extract(dummy_runner, tmp_path): +def test_verify_input_file_type_can_delete_zip_after_extract( + dummy_runner, write_raster, tmp_path +): + band = write_raster(tmp_path / "B04.tif") archive = tmp_path / "download.zip" with zipfile.ZipFile(archive, "w") as zf: zf.writestr("S2A_TEST.SAFE/manifest.safe", "") + zf.write(band, "S2A_TEST.SAFE/GRANULE/L2A/IMG_DATA/T_TEST_B04_10m.jp2") dummy_runner.delete_input_zip = True reading_utils.verify_input_file_type(dummy_runner, str(archive)) @@ -175,10 +180,14 @@ def test_all_zip_members_are_validated_before_any_extraction( assert archive.exists() -def test_zip_can_be_reused_after_opt_in_source_deletion(dummy_runner, tmp_path): +def test_zip_can_be_reused_after_opt_in_source_deletion( + dummy_runner, write_raster, tmp_path +): + band = write_raster(tmp_path / "B04.tif") archive = tmp_path / "scene.zip" with zipfile.ZipFile(archive, "w") as zf: zf.writestr("scene.SAFE/manifest.safe", "preserve extracted content") + zf.write(band, "scene.SAFE/GRANULE/L2A/IMG_DATA/T_TEST_B04_10m.jp2") dummy_runner.delete_input_zip = True reading_utils.verify_input_file_type(dummy_runner, archive) first_root = dummy_runner.root @@ -207,11 +216,6 @@ def test_worker_uses_preextracted_safe_without_deleting_source( assert archive.exists() -@pytest.mark.known_bug -@pytest.mark.xfail( - reason="delete_input_zip deletes the archive before checking for a SAFE folder", - raises=AssertionError, -) def test_zip_without_safe_is_retained_even_when_deletion_was_requested( dummy_runner, tmp_path ): @@ -224,6 +228,33 @@ def test_zip_without_safe_is_retained_even_when_deletion_was_requested( assert archive.exists() +def test_zip_with_empty_safe_is_retained_after_pipeline_validation( + tmp_path, pipeline_factory +): + archive = tmp_path / "empty_product.zip" + with zipfile.ZipFile(archive, "w") as zf: + zf.writestr("empty.SAFE/manifest.safe", "metadata only") + + with pytest.raises(FileNotFoundError, match="No JP2 bands|usable SAFE bands"): + pipeline_factory(archive, delete_input_zip=True) + assert archive.exists() + + +def test_zip_with_corrupt_safe_band_is_retained_after_pipeline_validation( + tmp_path, pipeline_factory +): + archive = tmp_path / "corrupt_product.zip" + with zipfile.ZipFile(archive, "w") as zf: + zf.writestr( + "corrupt.SAFE/GRANULE/L2A/IMG_DATA/T_TEST_B04_10m.jp2", + "not a JPEG2000 raster", + ) + + with pytest.raises(rasterio.errors.RasterioIOError): + pipeline_factory(archive, delete_input_zip=True) + assert archive.exists() + + def test_create_dirs_is_idempotent_and_keeps_existing_logs(dummy_runner, tmp_path): dummy_runner.root = str(tmp_path / "scene.tif") dummy_runner.input_type = "file" diff --git a/tests/test_sen2sr.py b/tests/test_sen2sr.py new file mode 100644 index 0000000..1bcbaf3 --- /dev/null +++ b/tests/test_sen2sr.py @@ -0,0 +1,106 @@ +from __future__ import annotations + +import sys +import types + +import pytest +import torch +from torch import nn + +from opensr_utils.model_utils.sen2sr import SEN2SRAdapter, load_sen2sr + + +class UpsampleRGBN(nn.Module): + def forward(self, x): + return torch.nn.functional.interpolate(x, scale_factor=4, mode="nearest") + + +def test_adapter_registers_upstream_plain_hard_constraint_mask(): + class HardConstraintLike(nn.Module): + def __init__(self): + super().__init__() + self.low_pass_mask = torch.ones(1) + + def forward(self, x): + return x + + model = HardConstraintLike() + adapter = SEN2SRAdapter(model) + assert "low_pass_mask" in dict(model.named_buffers()) + assert "low_pass_mask" not in model.state_dict() + adapter.to("meta") + assert model.low_pass_mask.device.type == "meta" + + +def test_adapter_preserves_batch_and_rgbn_shape_on_cpu(): + model = SEN2SRAdapter(UpsampleRGBN()) + output = model(torch.rand(2, 4, 128, 128)) + assert output.shape == (2, 4, 512, 512) + assert output.device.type == "cpu" + assert not model.training + + +@pytest.mark.parametrize("height,width", [(1, 1), (1, 127), (63, 91), (128, 64)]) +def test_adapter_pads_edge_tiles_and_crops_output(height, width): + output = SEN2SRAdapter(UpsampleRGBN())(torch.rand(2, 4, height, width)) + assert output.shape == (2, 4, height * 4, width * 4) + + +@pytest.mark.parametrize( + "shape", [(4, 128, 128), (2, 3, 128, 128), (2, 5, 128, 128), (2, 4, 129, 128)] +) +def test_adapter_rejects_wrong_band_or_rank(shape): + with pytest.raises( + (ValueError, TypeError), match="(four channels|shape|128x128|no larger)" + ): + SEN2SRAdapter(UpsampleRGBN())(torch.ones(shape)) + + +def test_adapter_rejects_bad_output_contract(): + class Wrong(nn.Module): + def forward(self, x): + return x + + with pytest.raises(ValueError, match="unexpected shape"): + SEN2SRAdapter(Wrong())(torch.ones(1, 4, 128, 128)) + + +def test_loader_uses_official_manifest_and_compiles_on_cpu(monkeypatch, tmp_path): + calls = {} + + class Loaded: + def compiled_model(self, *, device): + calls["device"] = device + return UpsampleRGBN() + + def download(*, file, output_dir): + calls["file"] = file + calls["output_dir"] = output_dir + (tmp_path / "NonReference_RGBN_x4").mkdir() + + def load(path): + calls["path"] = path + return Loaded() + + monkeypatch.setitem( + sys.modules, "mlstac", types.SimpleNamespace(download=download, load=load) + ) + model = load_sen2sr(cache_dir=tmp_path, device="cpu") + result = model(torch.ones(1, 4, 128, 128)) + assert result.shape == (1, 4, 512, 512) + assert calls["file"].endswith("SEN2SRLite/NonReference_RGBN_x4/mlm.json") + assert calls["device"] == torch.device("cpu") + + +def test_loader_accepts_local_serialized_module(tmp_path): + path = tmp_path / "model.pt" + torch.save(UpsampleRGBN(), path) + model = load_sen2sr(checkpoint=path) + assert model(torch.ones(1, 4, 128, 128)).shape == (1, 4, 512, 512) + + +def test_loader_rejects_state_dict_checkpoint(tmp_path): + path = tmp_path / "state.pt" + torch.save(UpsampleRGBN().state_dict(), path) + with pytest.raises(ValueError, match="state_dict"): + load_sen2sr(checkpoint=path) diff --git a/tests/test_writing_utils.py b/tests/test_writing_utils.py index 2d6e32b..3518642 100644 --- a/tests/test_writing_utils.py +++ b/tests/test_writing_utils.py @@ -466,7 +466,7 @@ def fake_stitch(self, **kwargs): monkeypatch.setattr(writing_utils, "stitch_sr_patches", fake_stitch) assert writing_utils.ddp_safe_stitch(runner, limit=3) == ("done.tif", 0) - assert not final.exists() + assert final.read_bytes() == b"existing" assert calls[0]["limit"] == 3 @@ -666,7 +666,7 @@ def test_stitcher_obeys_manifest_scale_container_and_custom_key( "coverage,exception", [("gap", RuntimeError), ("missing", RuntimeError), ("corrupt", ValueError)], ) -def test_failed_stitch_does_not_publish_incomplete_output_and_removes_accumulators( +def test_failed_stitch_does_not_publish_incomplete_output_and_keeps_diagnostics( tmp_path, coverage, exception ): runner = saved_patch_run(tmp_path, coverage=coverage) @@ -674,15 +674,11 @@ def test_failed_stitch_does_not_publish_incomplete_output_and_removes_accumulato writing_utils.stitch_sr_patches(runner) assert not Path(runner.final_sr_path).exists() assert Path(runner.placeholder_filepath).exists() - assert not list(tmp_path.glob("*.sum.tif")) - assert not list(tmp_path.glob("*.weights.tif")) + # Failed stitches retain accumulators as diagnostics for inspection. + assert list(tmp_path.glob("*.sum.tif")) + assert list(tmp_path.glob("*.weights.tif")) -@pytest.mark.known_bug -@pytest.mark.xfail( - reason="Overwrite deletes existing final output before validating replacement patches", - raises=AssertionError, -) def test_failed_overwrite_keeps_last_successful_output(tmp_path): runner = saved_patch_run(tmp_path, coverage="missing") runner.overwrite = True @@ -692,3 +688,84 @@ def test_failed_overwrite_keeps_last_successful_output(tmp_path): writing_utils.ddp_safe_stitch(runner) assert final.exists() assert final.read_bytes() == b"last successful output" + + +def test_partial_limit_does_not_publish_or_replace_existing_output(tmp_path): + runner = saved_patch_run(tmp_path) + runner.overwrite = True + final = Path(runner.final_sr_path) + final.write_bytes(b"last successful output") + + with pytest.raises(RuntimeError, match="output pixels were not covered"): + writing_utils.ddp_safe_stitch(runner, limit=1) + + assert final.read_bytes() == b"last successful output" + assert Path(runner.placeholder_filepath).exists() + + +def test_cleanup_false_retains_manifest_and_every_prediction(tmp_path): + runner = saved_patch_run(tmp_path) + patch_paths = [ + Path(entry["path"]) + for entry in json.loads((tmp_path / "index.json").read_text())["entries"] + ] + + writing_utils.stitch_sr_patches(runner, cleanup=False) + + assert (tmp_path / "index.json").exists() + assert all(path.exists() for path in patch_paths) + + +def test_concurrent_destination_creation_cannot_bypass_no_overwrite( + monkeypatch, tmp_path +): + runner = saved_patch_run(tmp_path) + final = Path(runner.final_sr_path) + count_uncovered = writing_utils._count_uncovered_pixels + + def concurrent_publication(weights): + uncovered = count_uncovered(weights) + final.write_bytes(b"another successful run") + return uncovered + + monkeypatch.setattr( + writing_utils, "_count_uncovered_pixels", concurrent_publication + ) + with pytest.raises(FileExistsError, match="Output already exists"): + writing_utils.ddp_safe_stitch(runner) + assert final.read_bytes() == b"another successful run" + assert Path(runner.placeholder_filepath).exists() + assert len(list(tmp_path.glob("patch_*.npy"))) == 2 + + +def test_successful_overwrite_removes_stale_external_raster_sidecars(tmp_path): + runner = saved_patch_run(tmp_path) + runner.overwrite = True + final = Path(runner.final_sr_path) + make_placeholder(final, width=4, height=2) + with rasterio.Env(GDAL_TIFF_INTERNAL_MASK=False): + with rasterio.open(final, "r+") as old: + old.write_mask(np.zeros((2, 4), dtype=np.uint8)) + assert Path(str(final) + ".msk").exists() + for suffix in (".ovr", ".aux.xml"): + Path(str(final) + suffix).write_bytes(b"old raster sidecar") + + writing_utils.ddp_safe_stitch(runner) + for suffix in (".msk", ".ovr", ".aux.xml"): + assert not Path(str(final) + suffix).exists() + with rasterio.open(final) as result: + np.testing.assert_array_equal(result.read(1), [[100, 100, 200, 200]] * 2) + assert np.all(result.read_masks(1) == 255) + + +def test_failed_overwrite_preserves_previous_raster_sidecars(tmp_path): + runner = saved_patch_run(tmp_path, coverage="missing") + runner.overwrite = True + final = Path(runner.final_sr_path) + final.write_bytes(b"previous raster") + sidecar = Path(str(final) + ".msk") + sidecar.write_bytes(b"previous mask") + with pytest.raises(RuntimeError): + writing_utils.ddp_safe_stitch(runner) + assert final.read_bytes() == b"previous raster" + assert sidecar.read_bytes() == b"previous mask" From ecd3bef24ec7968a0d2fbbb46cd16548e5a26e91 Mon Sep 17 00:00:00 2001 From: Simon Donike Date: Thu, 22 Oct 2026 16:06:41 +0200 Subject: [PATCH 4/7] Add all-band SEN2SR with LDSR-S2 backbone and dedicated model examples --- .github/workflows/ci.yml | 6 +- .gitignore | 1 + MANIFEST.in | 2 +- README.md | 104 ++++++++++++-------- examples/README.md | 126 ++++++++++++++++--------- examples/run_ldsrs2.py | 76 +++++++++++++++ demo.py => examples/run_model.py | 8 +- examples/run_sen2sr.py | 40 ++++++-- opensr_utils/cli.py | 4 +- opensr_utils/data_utils/datamodule.py | 29 +++++- opensr_utils/data_utils/grids.py | 32 +++++++ opensr_utils/data_utils/masking.py | 7 +- opensr_utils/model_utils/get_models.py | 23 ++++- opensr_utils/model_utils/ldsrs2.py | 104 ++++++++++++++++++++ opensr_utils/model_utils/sen2sr.py | 118 +++++++++++++++++++---- opensr_utils/pipeline.py | 49 +++++++++- setup.py | 1 + tests/README.md | 10 +- tests/test_datamodule.py | 3 +- tests/test_examples.py | 75 ++++++++++++++- tests/test_grids.py | 53 +++++++++++ tests/test_ldsrs2.py | 53 +++++++++++ tests/test_named_models.py | 56 +++++++++++ tests/test_sen2sr.py | 58 +++++++++++- 24 files changed, 902 insertions(+), 136 deletions(-) create mode 100644 examples/run_ldsrs2.py rename demo.py => examples/run_model.py (96%) create mode 100644 opensr_utils/data_utils/grids.py create mode 100644 opensr_utils/model_utils/ldsrs2.py create mode 100644 tests/test_grids.py create mode 100644 tests/test_ldsrs2.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3ed1b06..70ae389 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -65,7 +65,7 @@ jobs: python -m pip install -e '.[dev,cog]' fi - name: Syntax check - run: python -m compileall opensr_utils setup.py demo.py tests examples + run: python -m compileall opensr_utils setup.py tests examples - name: Shell syntax check run: bash -n run_batch.sh - name: Behavior and CPU integration tests @@ -84,5 +84,5 @@ jobs: if-no-files-found: ignore - name: Check test quality run: >- - python -m ruff check opensr_utils tests examples setup.py demo.py - && python -m ruff format --check opensr_utils tests examples setup.py demo.py + python -m ruff check opensr_utils tests examples setup.py + && python -m ruff format --check opensr_utils tests examples setup.py diff --git a/.gitignore b/.gitignore index 902edeb..70e9ac8 100644 --- a/.gitignore +++ b/.gitignore @@ -8,6 +8,7 @@ inf_1.py inf_2.py TODO.md demo_local.py +demo.py .ruff_cache/ # images diff --git a/MANIFEST.in b/MANIFEST.in index 3802ef0..6ce7830 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,5 +1,5 @@ -include demo.py include run_batch.sh recursive-include examples *.py *.md recursive-include tests *.py *.md include .github/constraints-oldest.txt +exclude demo.py diff --git a/README.md b/README.md index 8f38e1f..71143f3 100644 --- a/README.md +++ b/README.md @@ -64,56 +64,78 @@ with large_file_processing( The one-call API always executes once and closes raster handles. The class also has `close()` for callers who do not use a context manager. -## SEN2SR and ESA SRGAN +## Model examples -The named loaders return adapters for the models' actual inference contracts: - -| Name | Supported pretrained model | Python | Input/output | -| --- | --- | --- | --- | -| `SEN2SR` | SEN2SRLite `NonReference_RGBN_x4` | 3.10–3.14 | Four RGB/NIR bands, 4× scale. | -| `ESASRGAN` or `SRGAN` | ESA OpenSR SRGAN `RGB-NIR` preset | 3.12–3.14 | Four RGB/NIR bands, 4× scale. | -| `LDSRS2` | ESA LDSR-S2 | Upstream package compatibility | Four RGB/NIR bands, 4× scale. | +Runnable examples live in **[examples/](examples/README.md)**. Each script has +`--help`, device selection, batching, tiling and output options. Start with +Python 3.12–3.14 and install the extra for your chosen model: ```bash -python -m pip install 'opensr-utils[sen2sr]' -python -m pip install 'opensr-utils[srgan]' -``` +python -m pip install 'opensr-utils[sen2sr-ldsr]' # SEN2SR + LDSR-S2 backbone +python -m pip install 'opensr-utils[model]' # LDSR-S2 RGB-NIR alone +python -m pip install 'opensr-utils[srgan]' # ESA SRGAN RGB-NIR -```python -from opensr_utils import super_resolve +# All ten supported Sentinel-2 bands, with LDSR-S2 as the RGB-NIR backbone. +python examples/run_sen2sr.py scene.SAFE.zip --device cuda --output results/all_bands.tif + +# Separate four-band RGB-NIR diffusion example. +python examples/run_ldsrs2.py scene.SAFE.zip --device cuda --output results/rgbn.tif -super_resolve('scene.SAFE', 'SEN2SR', 'results/sen2sr.tif', batch_size=1) -super_resolve('scene.SAFE', 'ESASRGAN', 'results/srgan.tif', batch_size=4) +# Four-band ESA SRGAN example. +python examples/run_esasrgan.py scene.tif --device cuda --output results/srgan.tif + +# Interpolation and advanced generic options. +python examples/run_model.py --help +python examples/run_model.py scene.tif --model none --factor 1 --output results/check.tif ``` -SEN2SRLite expects fixed 128×128 tiles. The adapter replicate-pads smaller edge -windows and crops predictions back to their true footprint. Larger windows are -rejected clearly. The four-band adapter does not load the ten-band/full Mamba -variants. The ESA SRGAN adapter preserves the official `predict_step` path, -including histogram matching and EMA behavior; pass the adapter rather than an -unwrapped upstream Lightning module to retain those semantics. All adapters use -normalized values, explicit scales and named output bands. +| Example | Model and bands | Scale | +| --- | --- | --- | +| `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 | +| `run_ldsrs2.py` | LDSR-S2 alone. Input/output: **B04, B03, B02, B08** (RGB-NIR). | 4× | +| `run_esasrgan.py` | ESA SRGAN `RGB-NIR` preset. Input/output: **B04, B03, B02, B08**. | 4× | + +“All bands” means the ten bands supported by SEN2SR; B01, B09 and B10 are not +model inputs. The all-band example retains SEN2SR's learned red-edge/SWIR fusion +stages and replaces its RGB-NIR generator with LDSR-S2. For SAFE/S2GM folders, +it explicitly resamples native 20 m bands onto the RGB 10 m reference grid using +windowed nearest-neighbor reads, then applies the learned model. It writes ten +labeled bands at 2.5 m, preserving the georeferenced footprint and validity mask. +No full intermediate stack is needed. -SAFE/S2GM model inputs select and order the required **B04, B03, B02, B08** bands, -ignoring other spectral channels. GeoTIFF band descriptions can identify those -bands automatically; otherwise provide four native RGB/NIR channels or explicit -1-based indexes, for example `band_indexes=[4, 5, 2, 1]` (`--bands 4 5 2 1` on CLI). -Output GeoTIFFs retain the adapter's spectral band names. +The generic named `SEN2SR` loader still defaults to its four-band RGB-NIR +variant for compatibility. The all-band example explicitly selects +`variant="main", backbone="ldsrs2"`. -See **[model demos and download instructions](examples/README.md)** for automatic -and offline use of official weights. The instruction script has complete help: +The same composition is available in Python: -```bash -python demo.py --help -python demo.py scene.tif --model none --factor 1 --output results/check.tif -python examples/run_sen2sr.py scene.SAFE.zip --batch-size 1 --output results/sen2sr.tif -python examples/run_esasrgan.py scene.tif --batch-size 4 --output results/srgan.tif +```python +from opensr_utils import super_resolve +from opensr_utils.model_utils import get_model + +# Downloads SEN2SR fusion artifacts and the LDSR-S2 backbone on first use. +model = get_model("SEN2SR", variant="main", backbone="ldsrs2", device="cpu") +output = super_resolve( + "scene.SAFE.zip", model, "results/all_bands.tif", + device="auto", batch_size=1, resample_inputs=True, +) + +# LDSR-S2 alone produces only R, G, B and NIR. +from opensr_utils.model_utils.ldsrs2 import load_ldsrs2 + +rgbn_model = load_ldsrs2() +output_rgbn = super_resolve("scene.SAFE.zip", rgbn_model, "results/rgbn.tif") ``` -`demo.py` performs no inference on import and accepts device/GPU selection, -checkpoints, configs, download/cache controls, band indexes, tiling, batching, -overwrite, retention and previews. `--device cuda:1` is a convenience for selecting -a single GPU; `--device cuda --gpus 0 1` selects multiple GPUs. +Standalone GeoTIFFs must already share a grid. Band descriptions select and order +model channels automatically; unlabeled inputs must use the order in the table, +or supply `--bands` / `band_indexes` explicitly. Fixed 128×128 model tiles are +replicate-padded and cropped for smaller edge windows. The SRGAN adapter retains +the official histogram matching and EMA inference path. + +See [examples/README.md](examples/README.md) for local weights, offline inference +and diffusion sampling options. The root `demo.py` is a local, ignored scratch +script; published examples, tests and source distributions use `examples/`. ## Command line @@ -151,6 +173,7 @@ processing failures report a diagnostic and return a nonzero exit status. | `num_workers` / `--num-workers` | `0` | Increase for parallel raster reads when I/O limits throughput. | | `prefetch_factor` / `--prefetch-factor` | `2` | Positive batches per worker; ignored with zero workers. | | `output_units` / `--output-units` | Model units, otherwise `normalized` | Explicit prediction units, described below. | +| `resample_inputs` (Python) | `False` | Explicitly map folder bands to the selected reference grid; enabled by the all-band SEN2SR example. | | `band_indexes` / `--bands` | Model descriptions or native order | Select 1-based channels from a file in model input order. | | `checkpoint` / `--checkpoint` | Download official preset | Local SEN2SR MLSTAC directory/export or ESA SRGAN weights. | | `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 are excluded. Generic PyTorch models retain native file band order and channel count; adapters with declared spectral inputs select named or explicitly indexed bands. SAFE discovery prefers 10 m common bands. Bands on other-sized grids are omitted; -same-sized bands with different transforms or CRSs are rejected. No implicit -reprojection occurs. Models must accept the discovered channels; model output +same-sized bands with different transforms or CRSs are rejected. Set +`resample_inputs=True` explicitly to read folder bands on the selected reference +grid, as in the all-band example; default discovery performs no reprojection. Models must accept the discovered channels; model output channel counts may differ from input counts. LDSR-S2 expects Sentinel-2 RGB/NIR inputs; use a model suited to mosaics for S2GM data. diff --git a/examples/README.md b/examples/README.md index 5372519..19a4d4f 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,64 +1,104 @@ # Model examples -These scripts use the same tiled, georeferenced pipeline as the public API. -They support CPU and CUDA inference. Model downloads happen only when a model -is selected and `--no-download` is absent. +The examples run the public tiled pipeline and write labeled, georeferenced +uint16 GeoTIFFs. Run any script with `--help` before downloading weights. Use +Python 3.12–3.14 to install all model families in one environment. -## SEN2SR RGB-NIR +## All-band SEN2SR with an LDSR-S2 backbone -The supported adapter is SEN2SRLite `NonReference_RGBN_x4`: a 4x model trained -on fixed 128x128 low-resolution tiles. Smaller edge tiles are padded and -cropped by the adapter. It expects channels in `B04, B03, B02, B08` order. -For an unlabeled BGRN GeoTIFF, select that order explicitly with the root demo: +`run_sen2sr.py` combines SEN2SRLite's learned red-edge/SWIR fusion with **LDSR-S2 +as its RGB-NIR backbone**. It reads and writes ten bands in this exact order: + +```text +B02 B03 B04 B05 B06 B07 B08 B8A B11 B12 +``` + +B01, B09 and B10 are outside the upstream model's supported bands. Native +SAFE/S2GM folders can contain both 10 m and 20 m sources: windowed +nearest-neighbor reads map them to the RGB 10 m reference grid before SEN2SR's +learned 20 m → 10 m → 2.5 m stages. The output has ten bands at 2.5 m. Standalone +GeoTIFFs must already have a common grid; descriptions select bands by name, or +use `--bands` with ten 1-based indexes in the order above. + +```bash +python -m pip install 'opensr-utils[sen2sr-ldsr]' huggingface_hub + +# Automatic SEN2SR fusion and LDSR-S2 backbone downloads. +python examples/run_sen2sr.py scene.SAFE.zip --device cuda --output sen2sr_all.tif + +# Diffusion batch size defaults to 1. Sampling steps control inference cost; +# omit this option to use the backbone's configured quality/speed settings. +python examples/run_sen2sr.py aligned_10band.tif --sampling-steps 20 \ + --batch-size 1 --device cuda --output sen2sr_all.tif + +# Download every fusion artifact, including the 20m/10m fusion weights. +hf download tacofoundation/SEN2SR --include 'SEN2SRLite/main/**' \ + --local-dir models/SEN2SR +hf download simon-donike/RS-SR-LTDF opensr-ldsrs2_v1_0_0.ckpt \ + --local-dir models/LDSRS2 +``` + +The LDSR-S2 checkpoint also needs a matching configuration. Obtain +[config_10m.yaml from opensr-model](https://github.com/ESAOpenSR/opensr-model/blob/main/opensr_model/configs/config_10m.yaml) +and save it as `models/LDSRS2/config_10m.yaml`. Keep the checkpoint/config pair +from the same model release. Fully offline inference then uses: ```bash -python -m pip install 'opensr-utils[sen2sr]' huggingface_hub - -# Automatic model-artifact download and CPU inference. -python examples/run_sen2sr.py input.SAFE.zip --output sen2sr.tif -python examples/run_sen2sr.py input.tif --device cuda --output sen2sr.tif - -# Optional offline cache. The directory contains the downloaded mlm.json. -hf download tacofoundation/SEN2SR \ - --include 'SEN2SRLite/NonReference_RGBN_x4/**' \ - --local-dir models/SEN2SRLite_RGBN -python examples/run_sen2sr.py input.SAFE.zip \ - --checkpoint models/SEN2SRLite_RGBN/SEN2SRLite/NonReference_RGBN_x4 \ - --no-download --output sen2sr.tif - -# If a standalone raster is stored as B, G, R, N, reorder it to R, G, B, N. -python demo.py input_bgrn.tif --model sen2sr --bands 3 2 1 4 \ - --output sen2sr.tif +python examples/run_sen2sr.py scene.SAFE.zip --device cuda --no-download \ + --checkpoint models/SEN2SR/SEN2SRLite/main \ + --backbone-checkpoint models/LDSRS2/opensr-ldsrs2_v1_0_0.ckpt \ + --backbone-config models/LDSRS2/config_10m.yaml --output sen2sr_all.tif ``` -SEN2SR documentation: . +This composes the official [SEN2SR](https://github.com/ESAOpenSR/SEN2SR) fusion +model with [LDSR-S2](https://github.com/ESAOpenSR/opensr-model). Smaller windows +are replicate-padded to 128×128 and cropped after inference. All Fourier masks +and diffusion device state follow CPU/CUDA placement. -## SRGAN / ESASRGAN RGB-NIR +## LDSR-S2 RGB-NIR only -The supported preset is the 4-band RGB-NIR generator. Install the published -extra (Python 3.12 through 3.14), then choose either automatic or local -artifacts: +`run_ldsrs2.py` runs the diffusion model alone and writes four bands in +**B04, B03, B02, B08** (R, G, B, NIR) order at 4× scale. SAFE/S2GM inputs select +those bands automatically. For an unlabeled B, G, R, NIR GeoTIFF, use +`--bands 3 2 1 4`. ```bash -python -m pip install 'opensr-utils[srgan]>=0.5.1' +python -m pip install 'opensr-utils[model]' +python examples/run_ldsrs2.py scene.SAFE.zip --device cuda --output ldsrs2_rgbn.tif +python examples/run_ldsrs2.py input_bgrn.tif --bands 3 2 1 4 \ + --device cpu --output ldsrs2_rgbn.tif + +# Reuse the local checkpoint/config pair downloaded above. +python examples/run_ldsrs2.py scene.SAFE.zip --device cuda --no-download \ + --checkpoint models/LDSRS2/opensr-ldsrs2_v1_0_0.ckpt \ + --config models/LDSRS2/config_10m.yaml --output ldsrs2_rgbn.tif +``` -# Automatic preset download and CPU/GPU inference. -python examples/run_esasrgan.py input.tif --output esasrgan.tif +`--sampling-steps` overrides the backbone's configured diffusion steps. CPU is +supported but diffusion inference benefits substantially from CUDA. + +## ESA SRGAN RGB-NIR + +`run_esasrgan.py` uses the official four-band `RGB-NIR` preset, including its +histogram matching and EMA inference path. Its optional package supports Python +3.12–3.14. + +```bash +python -m pip install 'opensr-utils[srgan]' huggingface_hub python examples/run_esasrgan.py input.tif --device cuda --output esasrgan.tif -# Offline local checkpoint and matching configuration. hf download simon-donike/SR-GAN config_RGB-NIR.yaml RGB-NIR_4band_inference.ckpt \ --local-dir models/SR-GAN -python examples/run_esasrgan.py input.tif \ +python examples/run_esasrgan.py input.tif --no-download \ --checkpoint models/SR-GAN/RGB-NIR_4band_inference.ckpt \ - --config models/SR-GAN/config_RGB-NIR.yaml --no-download \ - --output esasrgan.tif + --config models/SR-GAN/config_RGB-NIR.yaml --output esasrgan.tif ``` -SRGAN documentation: . -Source: . +Upstream [inference documentation](https://srgan.opensr.eu/api-reference/inference/) +and [source](https://github.com/ESAOpenSR/SRGAN). -Both examples accept `--device`, `--batch-size`, `--window-size`, `--overlap`, -`--eliminate-border-px`, and `--overwrite`. The model scale is 4x by default; -use `--factor` for a compatible checkpoint with another scale. OpenSR-Utils -normalizes model inputs to [0, 1] and writes uint16 GeoTIFF products. +All dedicated examples accept `--device`, `--batch-size`, `--window-size`, +`--overlap`, `--eliminate-border-px`, and `--overwrite`. `run_model.py` exposes +additional generic controls for interpolation, multiple GPUs, previews, +diagnostic runs and retaining predictions. Examples are safe to import and +`--help` does not import Torch or download model artifacts. diff --git a/examples/run_ldsrs2.py b/examples/run_ldsrs2.py new file mode 100644 index 0000000..e95678f --- /dev/null +++ b/examples/run_ldsrs2.py @@ -0,0 +1,76 @@ +#!/usr/bin/env python3 +"""Super-resolve only Sentinel-2 RGB-NIR (B04, B03, B02, B08) with LDSR-S2.""" + +from __future__ import annotations + +import argparse +from pathlib import Path +import sys + + +def main(argv=None) -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument( + "input", type=Path, help="GeoTIFF, SAFE directory/archive, or S2GM folder" + ) + parser.add_argument("-o", "--output", type=Path) + parser.add_argument( + "--checkpoint", type=Path, help="Local LDSR-S2 checkpoint (requires --config)" + ) + parser.add_argument("--config", type=Path, help="Matching LDSR-S2 YAML") + parser.add_argument( + "--download", action=argparse.BooleanOptionalAction, default=True + ) + parser.add_argument( + "--sampling-steps", type=int, help="Override the model's diffusion steps" + ) + parser.add_argument( + "--bands", type=int, nargs=4, help="1-based GeoTIFF indexes in R,G,B,NIR order" + ) + parser.add_argument("--device", default="auto", choices=("auto", "cpu", "cuda")) + parser.add_argument("--batch-size", type=int, default=1) + parser.add_argument( + "--window-size", + type=int, + nargs=2, + default=(128, 128), + metavar=("WIDTH", "HEIGHT"), + ) + parser.add_argument("--overlap", type=int, default=12) + parser.add_argument("--eliminate-border-px", type=int, default=2) + parser.add_argument("--overwrite", action="store_true") + args = parser.parse_args(argv) + if (args.checkpoint is None) != (args.config is None): + parser.error("--checkpoint and --config must be supplied together") + if not args.download and args.checkpoint is None: + parser.error("--no-download requires --checkpoint and --config") + + # Keep --help independent of Torch and optional model installations. + sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + from opensr_utils import super_resolve + from opensr_utils.model_utils.ldsrs2 import load_ldsrs2 + + model = load_ldsrs2( + checkpoint=args.checkpoint, + config_path=args.config, + sampling_steps=args.sampling_steps, + download=args.download, + ) + output = super_resolve( + args.input, + model, + args.output, + device=args.device, + batch_size=args.batch_size, + window_size=tuple(args.window_size), + overlap=args.overlap, + eliminate_border_px=args.eliminate_border_px, + band_indexes=args.bands, + overwrite=args.overwrite, + ) + print(output) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/demo.py b/examples/run_model.py similarity index 96% rename from demo.py rename to examples/run_model.py index 40dd1f5..2e6675b 100644 --- a/demo.py +++ b/examples/run_model.py @@ -3,12 +3,12 @@ Examples:: - python demo.py scene.tif --model none --factor 1 --output scene_sr.tif - python demo.py scene.SAFE.zip --model sen2sr --checkpoint weights.ckpt - python demo.py scene.tif --model esasrgan --device cuda --batch-size 8 + python examples/run_model.py scene.tif --model none --factor 1 --output scene_sr.tif + python examples/run_model.py scene.SAFE.zip --model sen2sr --checkpoint weights.ckpt + python examples/run_model.py scene.tif --model esasrgan --device cuda --batch-size 8 ``--help`` does not import torch, rasterio, or optional model packages. -Model-specific dependencies and weights are described in ``examples/README.md``. +Model-specific dependencies and weights are described in ``README.md`` in this directory. """ from __future__ import annotations diff --git a/examples/run_sen2sr.py b/examples/run_sen2sr.py index a0e135a..59131c8 100755 --- a/examples/run_sen2sr.py +++ b/examples/run_sen2sr.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -"""Run a SEN2SR model through OpenSR-Utils' tiled geospatial pipeline.""" +"""Super-resolve all ten SEN2SR bands using an LDSR-S2 RGB-NIR backbone.""" from __future__ import annotations @@ -16,7 +16,7 @@ def _source_checkout_import(): sys.path.insert(0, str(Path(__file__).resolve().parents[1])) -def main() -> int: +def main(argv=None) -> int: parser = argparse.ArgumentParser(description=__doc__) parser.add_argument( "input", type=Path, help="GeoTIFF, SAFE directory/archive, or S2GM folder" @@ -28,7 +28,17 @@ def main() -> int: "--download", action=argparse.BooleanOptionalAction, default=True ) parser.add_argument( - "--variant", choices=("lite", "NonReference_RGBN_x4"), default="lite" + "--backbone-checkpoint", type=Path, help="Local LDSR-S2 weights" + ) + parser.add_argument("--backbone-config", type=Path, help="Matching LDSR-S2 YAML") + parser.add_argument( + "--sampling-steps", type=int, help="Override the backbone's diffusion steps" + ) + parser.add_argument( + "--bands", + type=int, + nargs=10, + help="Ten 1-based GeoTIFF indexes in B02,B03,B04,B05,B06,B07,B08,B8A,B11,B12 order", ) parser.add_argument("--device", default="auto") parser.add_argument("--factor", type=int, default=4) @@ -41,9 +51,19 @@ def main() -> int: ) parser.add_argument("--overlap", type=int, default=12) parser.add_argument("--eliminate-border-px", type=int, default=2) - parser.add_argument("--batch-size", type=int, default=16) + parser.add_argument("--batch-size", type=int, default=1) parser.add_argument("--overwrite", action="store_true") - args = parser.parse_args() + args = parser.parse_args(argv) + if (args.backbone_checkpoint is None) != (args.backbone_config is None): + parser.error( + "--backbone-checkpoint and --backbone-config must be supplied together" + ) + if not args.download and ( + args.checkpoint is None or args.backbone_checkpoint is None + ): + parser.error( + "--no-download requires local SEN2SR --checkpoint and both LDSR-S2 backbone artifacts" + ) _source_checkout_import() from opensr_utils import super_resolve @@ -54,7 +74,11 @@ def main() -> int: device="cpu", checkpoint=args.checkpoint, cache_dir=args.cache_dir, - variant=args.variant, + variant="main", + backbone="ldsrs2", + backbone_checkpoint=args.backbone_checkpoint, + backbone_config=args.backbone_config, + sampling_steps=args.sampling_steps, download=args.download, ) result = super_resolve( @@ -68,6 +92,10 @@ def main() -> int: eliminate_border_px=args.eliminate_border_px, batch_size=args.batch_size, overwrite=args.overwrite, + band_indexes=args.bands, + # Native 20m red-edge/SWIR sources must be mapped to the RGB 10m grid. + # WarpedVRT reads do this per window, without a full intermediate stack. + resample_inputs=True, ) print(result) return 0 diff --git a/opensr_utils/cli.py b/opensr_utils/cli.py index 19d0298..f1b4c56 100644 --- a/opensr_utils/cli.py +++ b/opensr_utils/cli.py @@ -127,7 +127,9 @@ def main(argv=None): ) parser.add_argument("--cache-dir", help="Model download/cache directory") parser.add_argument( - "--variant", "--model-variant", help="SEN2SR RGBN variant (lite)" + "--variant", + "--model-variant", + help="SEN2SR variant: lite (RGBN) or main (ten bands)", ) parser.add_argument( "--no-download", diff --git a/opensr_utils/data_utils/datamodule.py b/opensr_utils/data_utils/datamodule.py index a0c47d2..647cfbb 100644 --- a/opensr_utils/data_utils/datamodule.py +++ b/opensr_utils/data_utils/datamodule.py @@ -4,9 +4,10 @@ from torch.utils.data import Dataset, DataLoader from pytorch_lightning import LightningDataModule import os -import rasterio import numpy as np +from contextlib import ExitStack from torch.utils.data import Sampler +from .grids import open_input_raster class ShardedInferenceSampler(Sampler[int]): @@ -92,12 +93,22 @@ class PredictionDataset(Dataset): - Dictionary inputs can contain any number of bands. """ - def __init__(self, input_type, root, windows, lr_file_dict, band_indexes=None): + def __init__( + self, + input_type, + root, + windows, + lr_file_dict, + band_indexes=None, + resample_grid=None, + ): # Set properties self.input_type = input_type self.root = root self.windows = windows self.lr_file_dict = lr_file_dict + self.resample_grid = resample_grid + self._source_stack = ExitStack() if band_indexes is None: self.band_indexes = None else: @@ -135,16 +146,21 @@ def _resolve_band_order(self): def __getstate__(self): state = self.__dict__.copy() state["_src_cache"] = {} + state["_source_stack"] = None return state def _open_cached(self, path): if path not in self._src_cache: - self._src_cache[path] = rasterio.open(path) + if self._source_stack is None: + self._source_stack = ExitStack() + self._src_cache[path] = self._source_stack.enter_context( + open_input_raster(path, self.resample_grid) + ) return self._src_cache[path] def close(self): - for src in self._src_cache.values(): - src.close() + if self._source_stack is not None: + self._source_stack.close() self._src_cache.clear() def __del__(self): @@ -283,6 +299,7 @@ def __init__( batch_size=16, num_workers=4, band_indexes=None, + resample_grid=None, ): super().__init__() self.input_type = input_type @@ -293,6 +310,7 @@ def __init__( self.batch_size = batch_size self.prefetch_factor = prefetch_factor self.band_indexes = band_indexes + self.resample_grid = resample_grid def setup(self, stage=None): """ @@ -309,6 +327,7 @@ def setup(self, stage=None): windows=self.windows, lr_file_dict=self.lr_file_dict, band_indexes=self.band_indexes, + resample_grid=self.resample_grid, ) def predict_dataloader(self): diff --git a/opensr_utils/data_utils/grids.py b/opensr_utils/data_utils/grids.py new file mode 100644 index 0000000..6261af9 --- /dev/null +++ b/opensr_utils/data_utils/grids.py @@ -0,0 +1,32 @@ +"""Open explicitly resampled inputs without materializing a full raster stack.""" + +from contextlib import contextmanager + +import rasterio +from rasterio.enums import Resampling +from rasterio.vrt import WarpedVRT + + +@contextmanager +def open_input_raster(path, grid=None): + """Read a source on the requested reference grid, preserving source masks. + + Nearest-neighbor mapping preserves native 20 m samples for SEN2SR's learned + 20 m -> 10 m stage. Both data loading and final validity use this same view. + """ + with rasterio.open(path) as source: + if grid is None or all( + getattr(source, key) == value for key, value in grid.items() + ): + yield source + else: + if source.crs is None: + raise ValueError(f"Cannot resample a source without a CRS: {path}") + with WarpedVRT( + source, + **grid, + resampling=Resampling.nearest, + dtype="float32", + nodata=float("nan"), + ) as aligned: + yield aligned diff --git a/opensr_utils/data_utils/masking.py b/opensr_utils/data_utils/masking.py index 3ae9fca..e74b7c7 100644 --- a/opensr_utils/data_utils/masking.py +++ b/opensr_utils/data_utils/masking.py @@ -11,8 +11,8 @@ import math from contextlib import ExitStack import numpy as np -import rasterio from rasterio.windows import Window +from .grids import open_input_raster def _source_paths(runner) -> list[str]: @@ -93,7 +93,10 @@ def apply_input_mask(runner, dst): paths = _source_paths(runner) with ExitStack() as stack: - sources = [stack.enter_context(rasterio.open(path)) for path in paths] + sources = [ + stack.enter_context(open_input_raster(path, meta.get("resample_grid"))) + for path in paths + ] indexes = None if getattr(runner, "input_type", None) == "file": indexes = meta.get("band_indexes") diff --git a/opensr_utils/model_utils/get_models.py b/opensr_utils/model_utils/get_models.py index d91465d..6dbba32 100644 --- a/opensr_utils/model_utils/get_models.py +++ b/opensr_utils/model_utils/get_models.py @@ -65,7 +65,7 @@ def get_ldsrs2(device: str = "cpu"): def get_sen2sr(*args, **kwargs): - """Load the supported SEN2SRLite RGBN adapter; see ``sen2sr.load_sen2sr``.""" + """Load a four- or ten-band SEN2SR adapter; see ``sen2sr.load_sen2sr``.""" from .sen2sr import load_sen2sr return load_sen2sr(*args, **kwargs) @@ -91,7 +91,9 @@ def get_model( ): """Load a named model, with downloads and local artifacts kept explicit. - ``SEN2SR`` uses the four-band SEN2SRLite RGBN model. A local ``checkpoint`` + ``SEN2SR`` defaults to four-band SEN2SRLite RGBN. ``variant='main'`` selects + all ten bands; ``backbone='ldsrs2'`` replaces its RGB-NIR generator with + LDSR-S2, keeping SEN2SR's learned fusion stages. A local ``checkpoint`` can name its MLSTAC directory/manifest, or a supported exported model file. ``ESASRGAN`` and ``SRGAN`` are aliases for ESA's RGB-NIR preset; official local state dictionaries require both ``config`` and ``checkpoint``. @@ -113,6 +115,23 @@ def get_model( ) return None if name == "LDSRS2": + if ( + checkpoint is not None + or config is not None + or not download + or model_options + ): + from .ldsrs2 import load_ldsrs2 + + if cache_dir is not None or variant is not None: + raise ValueError("LDSR-S2 does not use cache_dir or variant overrides.") + return load_ldsrs2( + device=device, + checkpoint=checkpoint, + config_path=config, + download=download, + **model_options, + ) if ( checkpoint is not None or config is not None diff --git a/opensr_utils/model_utils/ldsrs2.py b/opensr_utils/model_utils/ldsrs2.py new file mode 100644 index 0000000..2e48374 --- /dev/null +++ b/opensr_utils/model_utils/ldsrs2.py @@ -0,0 +1,104 @@ +"""RGB-NIR LDSR-S2 inference, also usable as SEN2SR's four-band backbone.""" + +from __future__ import annotations + +from pathlib import Path +import inspect + +from torch import nn + +from .sen2sr import RGBN_BANDS, SEN2SRAdapter + + +class _DiffusionInference(nn.Module): + def __init__(self, model, sampling_steps=None): + super().__init__() + self.model = model + # Older opensr-model releases interpret a null step count literally, + # whereas recent releases choose a count for their configured sampler. + settings = getattr(getattr(model, "config", None), "denoiser_settings", None) + if ( + sampling_steps is None + and settings is not None + and getattr(settings, "sampling_steps", None) is None + and "sampler" not in inspect.signature(model.forward).parameters + ): + sampling_steps = 100 + self.sampling_steps = sampling_steps + + def forward(self, x): + # Upstream caches ordinary device attributes, which Module.to() does + # not update. Keep them consistent with Lightning's actual placement. + for module in self.model.modules(): + if "device" in vars(module): + module.device = x.device + options = ( + {} + if self.sampling_steps is None + else {"sampling_steps": self.sampling_steps} + ) + return self.model(x, **options) + + +class LDSRS2Adapter(SEN2SRAdapter): + """Apply the same fixed-tile, RGB-NIR contract as the published model. + + Padding to 128 square pixels also supports older opensr-model releases + whose encoder assumes square inputs. Output is cropped to the true extent. + """ + + input_bands = RGBN_BANDS + + def __init__(self, model, *, sampling_steps=None, device="cpu"): + if sampling_steps is not None and ( + isinstance(sampling_steps, bool) + or not isinstance(sampling_steps, int) + or sampling_steps <= 0 + ): + raise ValueError("sampling_steps must be a positive integer.") + super().__init__(_DiffusionInference(model, sampling_steps), device=device) + + +def load_ldsrs2( + *, + checkpoint=None, + config_path=None, + sampling_steps=None, + device="cpu", + download=True, +): + """Load the official preset or an explicit local config/checkpoint pair. + + Local artifacts make offline inference reproducible. A missing local + checkpoint never falls back to a downloaded preset. + """ + if (checkpoint is None) != (config_path is None): + raise ValueError( + "Local LDSR-S2 loading requires both checkpoint and config_path." + ) + if checkpoint is None: + if not download: + raise ValueError( + "Offline LDSR-S2 requires a local checkpoint and config_path." + ) + from .get_models import get_ldsrs2 + + model = get_ldsrs2(device="cpu") + else: + checkpoint = Path(checkpoint).expanduser() + config_path = Path(config_path).expanduser() + for path in (checkpoint, config_path): + if not path.is_file(): + raise FileNotFoundError(f"LDSR-S2 artifact does not exist: {path}") + try: + import opensr_model + from omegaconf import OmegaConf + except ImportError as exc: + raise ImportError( + "LDSR-S2 requires: python -m pip install 'opensr-utils[model]'" + ) from exc + model = opensr_model.SRLatentDiffusion( + OmegaConf.load(config_path), device="cpu" + ) + model.load_pretrained(str(checkpoint)) + return LDSRS2Adapter(model, sampling_steps=sampling_steps, device=device) diff --git a/opensr_utils/model_utils/sen2sr.py b/opensr_utils/model_utils/sen2sr.py index 7dce1b9..63567aa 100644 --- a/opensr_utils/model_utils/sen2sr.py +++ b/opensr_utils/model_utils/sen2sr.py @@ -3,7 +3,8 @@ The upstream ``sen2sr`` package uses MLSTAC manifests rather than exposing a stable PyTorch constructor. This module keeps that detail at the boundary so the rest of OpenSR Utils can consume an ordinary ``torch.nn.Module``. The -default is the small, CPU-capable ``SEN2SRLite`` RGBN model. +default is the small, CPU-capable ``SEN2SRLite`` RGBN model. The ten-band main +variant can retain its fusion stages and use LDSR-S2 as its RGB-NIR backbone. """ from __future__ import annotations @@ -16,8 +17,14 @@ DEFAULT_VARIANT = "NonReference_RGBN_x4" +RGBN_BANDS = ("B04", "B03", "B02", "B08") +# The composite model's Python loader uses Sentinel-2 wavelength order. Its +# manifest describes an internal fusion stage; it is not the public band order. +ALL_BANDS = ("B02", "B03", "B04", "B05", "B06", "B07", "B08", "B8A", "B11", "B12") MODEL_REPOSITORY = "https://huggingface.co/tacofoundation/sen2sr/resolve/main" VARIANT_MANIFESTS = { + "main": "SEN2SRLite/main/mlm.json", + "all": "SEN2SRLite/main/mlm.json", "nonreference_rgbn_x4": "SEN2SRLite/NonReference_RGBN_x4/mlm.json", "sen2srlite_nonreference_rgbn_x4": "SEN2SRLite/NonReference_RGBN_x4/mlm.json", "lite": "SEN2SRLite/NonReference_RGBN_x4/mlm.json", @@ -34,14 +41,12 @@ def _device(value: str | torch.device) -> torch.device: class SEN2SRAdapter(nn.Module): """Validate and adapt a loaded SEN2SR model for OpenSR Utils. - The RGBN model expects channels in ``B04, B03, B02, B08`` order and input - values normalized to reflectance ``[0, 1]``. A batch of shape - ``(batch, 4, height, width)`` is returned as ``(batch, 4, height*4, - width*4)``. Validation here gives the pipeline an actionable error before - a less clear convolution or manifest error occurs. + The default RGBN variant expects ``B04, B03, B02, B08``. ``variant='main'`` + expects the ten bands in ``ALL_BANDS`` order. Inputs use normalized [0,1] + reflectances; output preserves batch/bands and scales both spatial axes 4x. """ - input_bands = ("B04", "B03", "B02", "B08") + input_bands = RGBN_BANDS output_bands = input_bands output_band_names = input_bands input_units = "normalized" @@ -50,11 +55,23 @@ class SEN2SRAdapter(nn.Module): factor = 4 output_units = "normalized" - def __init__(self, model: nn.Module, *, device: str | torch.device = "cpu"): + def __init__( + self, + model: nn.Module, + *, + device: str | torch.device = "cpu", + variant: str = DEFAULT_VARIANT, + ): super().__init__() if not isinstance(model, nn.Module) and not callable(model): raise TypeError("model must be a torch.nn.Module or callable") self.model = model + _manifest_url(variant) + self.input_bands = ( + ALL_BANDS if variant.strip().lower() in ("main", "all") else RGBN_BANDS + ) + self.output_bands = self.input_bands + self.output_band_names = self.input_bands # ``.to(...)`` may be called later by Lightning/DDP. Do not cache the # initial device: forward() discovers the module's current placement. self.requested_device = _device(device) @@ -80,16 +97,18 @@ def forward(self, x: Tensor) -> Tensor: if not isinstance(x, Tensor): raise TypeError("SEN2SR input must be a torch.Tensor") if x.ndim != 4: - raise ValueError("SEN2SR input must have shape (batch, 4, height, width)") - if x.shape[1] != 4: raise ValueError( - "SEN2SR RGBN expects four channels in B04,B03,B02,B08 order; " + "SEN2SR input must have shape (batch, channels, height, width)" + ) + if x.shape[1] != len(self.input_bands): + raise ValueError( + f"SEN2SR expects {len(self.input_bands)} channels in {self.input_bands} order; " f"received {x.shape[1]}" ) height, width = (int(x.shape[2]), int(x.shape[3])) if height > self.input_size[0] or width > self.input_size[1]: raise ValueError( - "SEN2SR RGBN accepts input tiles no larger than 128x128 " + "SEN2SR accepts input tiles no larger than 128x128 " f"(the upstream hard constraint is fixed at 512x512); received {(height, width)}" ) if min(x.shape[0], x.shape[2], x.shape[3]) <= 0: @@ -118,7 +137,7 @@ def forward(self, x: Tensor) -> Tensor: raise ValueError("SEN2SR model must return a 4-D tensor") expected = ( padded.shape[0], - 4, + len(self.output_bands), self.input_size[0] * self.factor, self.input_size[1] * self.factor, ) @@ -167,16 +186,43 @@ def load_sen2sr( download: bool = True, cache_dir: str | Path | None = None, checkpoint: str | Path | None = None, + backbone: str | None = None, + backbone_checkpoint: str | Path | None = None, + backbone_config: str | Path | None = None, + sampling_steps: int | None = None, ) -> SEN2SRAdapter: - """Load a SEN2SR RGBN model from MLSTAC or a local checkpoint. + """Load a four- or ten-band SEN2SR model from MLSTAC or local artifacts. ``model_dir`` points to a directory containing the upstream ``mlm.json`` manifest. ``checkpoint`` may point to a TorchScript file or a serialized ``torch.nn.Module``. When neither is supplied, the official manifest is downloaded lazily through ``mlstac``. Weights are constructed on CPU and moved only after loading, avoiding accidental GPU allocation during setup. + For ten-band inference use ``variant='main', backbone='ldsrs2'``. The + optional ``backbone_checkpoint`` and ``backbone_config`` pair avoids network + access for the diffusion backbone; ``sampling_steps`` controls its cost. """ target = _device(device) + # Resolve the contract before touching artifacts or optional packages. + _manifest_url(variant) + if backbone not in (None, "ldsrs2"): + raise ValueError("The supported optional SEN2SR backbone is 'ldsrs2'.") + if backbone is not None and variant.strip().lower() not in ("main", "all"): + raise ValueError("The LDSR-S2 backbone requires the ten-band variant='main'.") + if backbone is None and any( + value is not None + for value in (backbone_checkpoint, backbone_config, sampling_steps) + ): + raise ValueError( + "Backbone artifacts and sampling_steps require backbone='ldsrs2'." + ) + if backbone == "ldsrs2": + if (backbone_checkpoint is None) != (backbone_config is None): + raise ValueError("Supply both backbone_checkpoint and backbone_config.") + if not download and backbone_checkpoint is None: + raise ValueError( + "Offline SEN2SR with LDSR-S2 requires local backbone_checkpoint and backbone_config." + ) if model_dir is not None and checkpoint is not None: raise ValueError("Provide model_dir or checkpoint, not both") @@ -184,7 +230,17 @@ def load_sen2sr( path = Path(checkpoint).expanduser() if not path.is_file(): raise FileNotFoundError(f"SEN2SR checkpoint does not exist: {path}") - return SEN2SRAdapter(_load_checkpoint(path, target), device=target) + model = _load_checkpoint(path, torch.device("cpu")) + return _adapt_model( + model, + target, + variant, + backbone, + backbone_checkpoint, + backbone_config, + sampling_steps, + download, + ) try: import mlstac @@ -214,7 +270,37 @@ def load_sen2sr( model = loaded.compiled_model(device=torch.device("cpu")) if not isinstance(model, nn.Module) and not callable(model): raise TypeError("MLSTAC compiled_model() did not return a callable model") - return SEN2SRAdapter(model, device=target) + return _adapt_model( + model, + target, + variant, + backbone, + backbone_checkpoint, + backbone_config, + sampling_steps, + download, + ) + + +def _adapt_model( + model, target, variant, backbone, checkpoint, config, sampling_steps, download +): + if backbone == "ldsrs2": + from .ldsrs2 import load_ldsrs2 + + if not hasattr(model, "sr_model"): + raise ValueError( + "The all-band SEN2SR export must expose its RGB-NIR sr_model backbone." + ) + # Keep SEN2SR's learned red-edge/SWIR fusion stages, replacing only its + # four-band 10m -> 2.5m generator with the requested latent diffusion model. + model.sr_model = load_ldsrs2( + checkpoint=checkpoint, + config_path=config, + sampling_steps=sampling_steps, + download=download, + ) + return SEN2SRAdapter(model, device=target, variant=variant) get_sen2sr = load_sen2sr diff --git a/opensr_utils/pipeline.py b/opensr_utils/pipeline.py index 04799ee..a50f137 100644 --- a/opensr_utils/pipeline.py +++ b/opensr_utils/pipeline.py @@ -40,6 +40,11 @@ class large_file_processing: ``compressed_patches`` allow throughput/storage tuning. Models load on CPU before Lightning places them on their execution devices. + ``resample_inputs=True`` explicitly maps folder bands onto the selected + reference grid with nearest-neighbor WarpedVRT reads. This retains native + 20 m inputs for SEN2SR's all-band fusion without a full intermediate stack. + Default discovery keeps its strict grid validation and excludes other sizes. + Model inputs are normalized to [0,1]. ``output_units="normalized"`` scales predictions by 10000; ``"reflectance"`` accepts existing [0,10000] values. Nonfinite outputs are errors; finite outputs are clipped, rounded and saved @@ -88,6 +93,7 @@ def __init__( model_variant=None, download: bool = True, band_indexes=None, + resample_inputs: bool = False, ): # 1) Validate public inputs. Do not use assert: optimized Python removes it. if isinstance(model, str): @@ -181,6 +187,7 @@ def __init__( ) band_indexes = list(band_indexes) self._requested_band_indexes = band_indexes + self.resample_inputs = bool(resample_inputs) if not isinstance(model, str) and any( value is not None for value in (checkpoint, model_config, cache_dir, model_variant) @@ -310,6 +317,14 @@ def __init__( ) self.output_units = output_units or model_units or "normalized" self._configure_model_input(model) + if self.image_meta.get("resample_grid"): + from opensr_utils.data_utils.grids import open_input_raster + + # Fail before optional ZIP deletion if any selected view cannot + # be georeferenced on the target grid. + for path in self.image_meta["lr_file_dict"].values(): + with open_input_raster(path, self.image_meta["resample_grid"]): + pass self.create_datamodule() # Make sure model is useable and in eval mode @@ -427,7 +442,11 @@ def _configure_model_input(self, model): raise FileNotFoundError( f"Model requires missing spectral bands {missing}; available bands: {sorted(by_band)}." ) - self.image_meta["lr_file_dict"] = dict(by_band[band] for band in required) + # Canonical keys preserve the model's requested order, including + # all-band wavelength order instead of the generic RGB-NIR prefix. + self.image_meta["lr_file_dict"] = { + band: by_band[band][1] for band in required + } self.image_meta["bands"] = len(required) def create_datamodule(self, windows=None): @@ -446,6 +465,7 @@ def create_datamodule(self, windows=None): windows=self.image_meta["image_windows"] if windows is None else windows, lr_file_dict=self.image_meta["lr_file_dict"], band_indexes=self.image_meta.get("band_indexes"), + resample_grid=self.image_meta.get("resample_grid"), prefetch_factor=self.prefetch_factor, batch_size=self.batch_size, num_workers=self.num_workers, @@ -521,11 +541,18 @@ def safe_band_name(path): except FileNotFoundError: pass used = set(lr_file_dict.values()) + seen_bands = {safe_band_name(path) for path in used} for path in jp2s: if path not in used: name = safe_band_name(path) - if name.startswith("B") and name[1:].isalnum(): - lr_file_dict[name] = path + if ( + name.startswith("B") + and name[1:].isalnum() + and name not in seen_bands + ): + # Prefer the native 20 m copy to a duplicate 60 m copy. + lr_file_dict[name] = pick_safe_band(name) + seen_bands.add(name) if not lr_file_dict: raise FileNotFoundError(f"No usable SAFE bands found in {self.root}.") @@ -542,6 +569,9 @@ def safe_band_name(path): same_grid = {} for label, path in lr_file_dict.items(): with rasterio.open(path) as src: + if self.resample_inputs: + same_grid[label] = path + continue if ( src.width == self.image_meta["width"] and src.height == self.image_meta["height"] @@ -614,6 +644,9 @@ def safe_band_name(path): same_grid = {} for label, path in self.image_meta["lr_file_dict"].items(): with rasterio.open(path) as src: + if self.resample_inputs: + same_grid[label] = path + continue if ( src.width == self.image_meta["width"] and src.height == self.image_meta["height"] @@ -632,6 +665,16 @@ def safe_band_name(path): if self.image_meta["bands"] <= 0: raise FileNotFoundError("No S2GM bands matched the selected grid size.") + if self.resample_inputs and self.input_type != "file": + if self.image_meta["crs"] is None: + raise ValueError( + "Input resampling requires georeferenced rasters with a CRS." + ) + self.image_meta["resample_grid"] = { + name: self.image_meta[name] + for name in ("width", "height", "transform", "crs") + } + # Protect every selected source band, including directory inputs. The # samefile check catches an existing hardlink even when its pathname is # different from the source pathname. diff --git a/setup.py b/setup.py index 6177e23..42b7522 100644 --- a/setup.py +++ b/setup.py @@ -50,6 +50,7 @@ # SEN2SR and MLSTAC currently require Python >=3.10. Keeping these # integrations optional preserves the core package's Python 3.9 floor. "sen2sr": ["sen2sr>=0.8.5", "mlstac>=0.4.9"], + "sen2sr-ldsr": ["sen2sr>=0.8.5", "mlstac>=0.4.9", "opensr-model>=1.0.0"], # opensr-srgan supports Python >=3.12,<3.15 upstream. "srgan": ["opensr-srgan>=0.5.1"], "all-models": [ diff --git a/tests/README.md b/tests/README.md index 2ac0e10..a4af513 100644 --- a/tests/README.md +++ b/tests/README.md @@ -12,8 +12,8 @@ run as normal tests, with no expected-failure markers. python -m pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu python -m pip install -e '.[dev,cog]' python -m pytest -q -python -m ruff check opensr_utils tests examples setup.py demo.py -python -m ruff format --check opensr_utils tests examples setup.py demo.py +python -m ruff check opensr_utils tests examples setup.py +python -m ruff format --check opensr_utils tests examples setup.py ``` The prepared workspace environment is `/work/envs/opensr/bin/python`. The real @@ -40,9 +40,13 @@ coverage report. The model tests keep official downloads outside the normal test suite. Adapter tests exercise tensor values, batch shapes, tile padding/cropping, normalization, ESA histogram-inference delegation, band selection and labeled GeoTIFF output. -Pretrained smoke runs use the published SEN2SRLite RGBN and ESA RGB-NIR artifacts +Pretrained smoke runs use SEN2SRLite RGBN, its ten-band fusion with an LDSR-S2 +backbone, standalone LDSR-S2 RGB-NIR, and ESA SRGAN RGB-NIR artifacts following [the model examples](../examples/README.md). Optional model dependencies can be installed with `.[sen2sr]` (Python 3.10+) and `.[srgan]` (Python 3.12–3.14). +Use `.[sen2sr-ldsr]` for the all-band diffusion example. Native-resolution +SAFE/S2GM tests check resampled values, band order and independent validity; +spawn-style dataset serialization reopens virtual grids instead of GDAL handles. ## Contracts and scope diff --git a/tests/test_datamodule.py b/tests/test_datamodule.py index a9bc2f7..fa53aba 100644 --- a/tests/test_datamodule.py +++ b/tests/test_datamodule.py @@ -3,6 +3,7 @@ import pickle import pytest +import rasterio import numpy as np import torch @@ -229,7 +230,7 @@ def test_dataset_clips_reflectance_and_preserves_spatial_values( image = dataset[0]["image"] np.testing.assert_allclose(image.numpy(), [[[0, 0, 0.1], [0.5, 1, 1]]]) assert image.dtype == torch.float32 - with datamodule.rasterio.open(path) as src: + with rasterio.open(path) as src: np.testing.assert_array_equal(src.read(1), values) diff --git a/tests/test_examples.py b/tests/test_examples.py index dfb7122..ada2dad 100644 --- a/tests/test_examples.py +++ b/tests/test_examples.py @@ -15,7 +15,7 @@ def test_demo_help_is_available_without_model_imports(): result = subprocess.run( - [sys.executable, str(ROOT / "demo.py"), "--help"], + [sys.executable, str(ROOT / "examples" / "run_model.py"), "--help"], cwd=ROOT, check=False, capture_output=True, @@ -27,7 +27,7 @@ def test_demo_help_is_available_without_model_imports(): def test_model_examples_expose_help_without_downloading_weights(): - for script in ("run_sen2sr.py", "run_esasrgan.py"): + for script in ("run_sen2sr.py", "run_esasrgan.py", "run_ldsrs2.py"): result = subprocess.run( [sys.executable, str(ROOT / "examples" / script), "--help"], cwd=ROOT, @@ -60,7 +60,7 @@ def test_demo_runs_tiny_model_none_workflow(tmp_path): result = subprocess.run( [ sys.executable, - str(ROOT / "demo.py"), + str(ROOT / "examples" / "run_model.py"), str(source), "--model", "none", @@ -79,7 +79,7 @@ def test_demo_runs_tiny_model_none_workflow(tmp_path): def test_demo_passes_checkpoint_options_to_model_registry(monkeypatch, tmp_path): - import demo + from examples import run_model as demo import opensr_utils calls = [] @@ -127,7 +127,7 @@ def get_model(name, **kwargs): def test_demo_translates_cuda_device_selector_to_pipeline_gpu(monkeypatch): - import demo + from examples import run_model as demo import opensr_utils forwarded = {} @@ -169,3 +169,68 @@ def get_model(name, **kwargs): }, ) ] + + +def test_sen2sr_example_selects_all_bands_and_ldsr_backbone(monkeypatch, tmp_path): + import opensr_utils + from examples import run_sen2sr + from opensr_utils.model_utils import get_models + + calls = [] + monkeypatch.setattr( + get_models, + "get_model", + lambda name, **kw: calls.append((name, kw)) or "composite", + ) + forwarded = {} + monkeypatch.setattr( + opensr_utils, "super_resolve", lambda *a, **kw: forwarded.update(kw) or "result" + ) + assert run_sen2sr.main(["scene.SAFE", "--sampling-steps", "20"]) == 0 + assert calls[0][1]["variant"] == "main" + assert calls[0][1]["backbone"] == "ldsrs2" + assert calls[0][1]["sampling_steps"] == 20 + assert forwarded["resample_inputs"] is True + assert forwarded["batch_size"] == 1 + + +def test_ldsrs2_example_selects_rgbn_and_forwards_sampling(monkeypatch): + import opensr_utils + from examples import run_ldsrs2 + from opensr_utils.model_utils import ldsrs2 + + calls = [] + monkeypatch.setattr( + ldsrs2, "load_ldsrs2", lambda **kw: calls.append(kw) or "rgbn-model" + ) + forwarded = {} + monkeypatch.setattr( + opensr_utils, "super_resolve", lambda *a, **kw: forwarded.update(kw) or "result" + ) + assert ( + run_ldsrs2.main( + ["input.tif", "--bands", "3", "2", "1", "4", "--sampling-steps", "10"] + ) + == 0 + ) + assert calls[0]["sampling_steps"] == 10 + assert forwarded["band_indexes"] == [3, 2, 1, 4] + + +@pytest.mark.parametrize( + "script,options", + [ + ("run_sen2sr.py", ["scene.SAFE", "--no-download"]), + ("run_sen2sr.py", ["scene.SAFE", "--backbone-config", "config.yaml"]), + ("run_ldsrs2.py", ["scene.SAFE", "--no-download"]), + ("run_ldsrs2.py", ["scene.SAFE", "--config", "config.yaml"]), + ], +) +def test_invalid_offline_examples_fail_before_model_loading(script, options): + result = subprocess.run( + [sys.executable, str(ROOT / "examples" / script), *options], + capture_output=True, + text=True, + ) + assert result.returncode == 2 + assert "requires" in result.stderr or "together" in result.stderr diff --git a/tests/test_grids.py b/tests/test_grids.py new file mode 100644 index 0000000..eefb4ce --- /dev/null +++ b/tests/test_grids.py @@ -0,0 +1,53 @@ +"""Resampling must preserve source validity independently of valid zero values.""" + +import pickle + +import numpy as np +import rasterio +from rasterio.transform import from_origin +from rasterio.windows import Window + +from opensr_utils.data_utils.datamodule import PredictionDataset +from opensr_utils.data_utils.grids import open_input_raster + + +def test_resampling_preserves_internal_mask_and_valid_zeros(write_raster, tmp_path): + path = write_raster( + tmp_path / "source.tif", + data=np.zeros((1, 2, 3)), + nodata=None, + transform=from_origin(0, 40, 20, 20), + crs="EPSG:32632", + ) + valid = np.ones((2, 3), dtype="uint8") * 255 + valid[0, 1] = 0 + with rasterio.open(path, "r+") as source: + source.write_mask(valid) + grid = dict( + width=6, + height=4, + transform=from_origin(0, 40, 10, 10), + crs=rasterio.crs.CRS.from_epsg(32632), + ) + with open_input_raster(path, grid) as source: + expected = valid.repeat(2, 0).repeat(2, 1) + np.testing.assert_array_equal(source.read_masks(1), expected) + np.testing.assert_array_equal(source.read(1)[expected != 0], 0) + + # Spawned workers reopen the same virtual grid instead of pickling GDAL handles. + dataset = PredictionDataset( + "S2GM", + str(tmp_path), + [Window(0, 0, 6, 4)], + {"B05": str(path)}, + resample_grid=grid, + ) + try: + expected_values = dataset[0]["image"] + restored = pickle.loads(pickle.dumps(dataset)) + try: + np.testing.assert_array_equal(restored[0]["image"], expected_values) + finally: + restored.close() + finally: + dataset.close() diff --git a/tests/test_ldsrs2.py b/tests/test_ldsrs2.py new file mode 100644 index 0000000..a93bead --- /dev/null +++ b/tests/test_ldsrs2.py @@ -0,0 +1,53 @@ +"""The four-band diffusion boundary is explicit and device placement is current.""" + +from types import SimpleNamespace + +import pytest +import torch + +from opensr_utils.model_utils.ldsrs2 import LDSRS2Adapter, load_ldsrs2 + + +class Diffusion(torch.nn.Module): + def __init__(self): + super().__init__() + self.device = "stale" + self.config = SimpleNamespace( + denoiser_settings=SimpleNamespace(sampling_steps=None) + ) + self.steps = None + + def forward(self, x, *, sampling_steps): + assert self.device == x.device + self.steps = sampling_steps + return x.repeat_interleave(4, -2).repeat_interleave(4, -1) + + +def test_rgbn_diffusion_pads_crops_and_supports_legacy_auto_steps(): + diffusion = Diffusion() + model = LDSRS2Adapter(diffusion) + values = torch.arange(4, dtype=torch.float32)[None, :, None, None] / 10 + result = model(values.expand(2, 4, 3, 5)) + assert model.output_band_names == ("B04", "B03", "B02", "B08") + assert result.shape == (2, 4, 12, 20) + torch.testing.assert_close(result, values.expand(2, 4, 12, 20)) + assert diffusion.steps == 100 + + +@pytest.mark.parametrize("steps", [0, -1, True, 1.5]) +def test_invalid_sampling_steps_are_rejected(steps): + with pytest.raises(ValueError, match="sampling_steps"): + LDSRS2Adapter(Diffusion(), sampling_steps=steps) + + +@pytest.mark.parametrize( + "options", + [ + {"download": False}, + {"checkpoint": "missing.ckpt"}, + {"config_path": "config.yaml"}, + ], +) +def test_offline_loading_requires_matching_local_artifacts(options): + with pytest.raises(ValueError, match="requires"): + load_ldsrs2(**options) diff --git a/tests/test_named_models.py b/tests/test_named_models.py index 782a59d..f29e0d3 100644 --- a/tests/test_named_models.py +++ b/tests/test_named_models.py @@ -159,3 +159,59 @@ def test_unlabeled_multiband_input_can_select_explicit_rgbn_indexes( ) with rasterio.open(output) as result: np.testing.assert_array_equal(result.read()[:, 0, 0], [4000, 3000, 2000, 8000]) + + +@pytest.mark.integration +@pytest.mark.parametrize("source_kind", ["SAFE", "S2GM"]) +def test_all_band_native_resolution_products_keep_order_values_and_masks( + source_kind, write_raster, tmp_path +): + from rasterio.transform import from_origin + from opensr_utils.model_utils.sen2sr import ALL_BANDS + + source = tmp_path / ("tile.SAFE" if source_kind == "SAFE" else "bands") + band_dir = ( + source / "GRANULE" / "tile" / "IMG_DATA" if source_kind == "SAFE" else source + ) + ten_meter = {"B02", "B03", "B04", "B08"} + for index, band in enumerate(ALL_BANDS): + is_native_10m = band in ten_meter + resolution = 10 if is_native_10m else 20 + shape = (4, 6) if is_native_10m else (2, 3) + data = np.full((1, *shape), index * 500, dtype="uint16") + if band == "B05": + data[0, 1, 1] = 65535 + filename = ( + f"TEST_{band}_{resolution}m.jp2" if source_kind == "SAFE" else f"{band}.tif" + ) + write_raster( + band_dir / filename, + data=data, + nodata=65535, + transform=from_origin(600000, 5100000, resolution, resolution), + crs="EPSG:32632", + ) + if source_kind == "SAFE": + # This duplicate must not displace the native 20 m source. + write_raster( + band_dir / "TEST_B05_60m.jp2", + data=np.full((1, 1, 1), 9999), + nodata=65535, + transform=from_origin(600000, 5100000, 60, 60), + crs="EPSG:32632", + ) + model = SEN2SRAdapter(FixedSENTile(), variant="main") + output = super_resolve(source, model, device="cpu", resample_inputs=True) + valid = np.ones((4, 6), dtype=bool) + valid[2:4, 2:4] = False + expected_mask = np.repeat(np.repeat(valid, 4, 0), 4, 1) + with rasterio.open(output) as result: + assert result.count == 10 + assert result.descriptions == ALL_BANDS + assert result.shape == (16, 24) + assert result.transform.almost_equals(from_origin(600000, 5100000, 2.5, 2.5)) + np.testing.assert_array_equal(result.dataset_mask() != 0, expected_mask) + for index in range(10): + np.testing.assert_array_equal( + result.read(index + 1)[expected_mask], index * 500 + ) diff --git a/tests/test_sen2sr.py b/tests/test_sen2sr.py index 1bcbaf3..10834ad 100644 --- a/tests/test_sen2sr.py +++ b/tests/test_sen2sr.py @@ -51,7 +51,7 @@ def test_adapter_pads_edge_tiles_and_crops_output(height, width): ) def test_adapter_rejects_wrong_band_or_rank(shape): with pytest.raises( - (ValueError, TypeError), match="(four channels|shape|128x128|no larger)" + (ValueError, TypeError), match="(4 channels|shape|128x128|no larger)" ): SEN2SRAdapter(UpsampleRGBN())(torch.ones(shape)) @@ -104,3 +104,59 @@ def test_loader_rejects_state_dict_checkpoint(tmp_path): torch.save(UpsampleRGBN().state_dict(), path) with pytest.raises(ValueError, match="state_dict"): load_sen2sr(checkpoint=path) + + +def test_all_band_model_uses_ldsrs2_backbone_and_keeps_fusion(monkeypatch, tmp_path): + from opensr_utils.model_utils import get_models + from opensr_utils.model_utils.sen2sr import ALL_BANDS + + class Diffusion(nn.Module): + device = "initial" + + def __init__(self): + super().__init__() + self.device = "initial" + self.received = None + + def forward(self, x, *, sampling_steps): + assert self.device == x.device + self.received = sampling_steps + return (x + 0.1).repeat_interleave(4, -2).repeat_interleave(4, -1) + + class Composite(nn.Module): + def __init__(self): + super().__init__() + self.sr_model = nn.Identity() + + def forward(self, x): + result = x.repeat_interleave(4, -2).repeat_interleave(4, -1) + result[:, [2, 1, 0, 6]] = self.sr_model(x[:, [2, 1, 0, 6]]) + return result + + diffusion = Diffusion() + composite = Composite() + monkeypatch.setattr(get_models, "get_ldsrs2", lambda **kw: diffusion) + monkeypatch.setitem( + sys.modules, + "mlstac", + types.SimpleNamespace( + load=lambda path: types.SimpleNamespace( + compiled_model=lambda **kw: composite + ) + ), + ) + model = load_sen2sr(tmp_path, variant="main", backbone="ldsrs2", sampling_steps=7) + values = torch.arange(10, dtype=torch.float32)[None, :, None, None] / 100 + result = model(values) + expected = values.clone() + expected[:, [2, 1, 0, 6]] += 0.1 + torch.testing.assert_close( + result, expected.repeat_interleave(4, -2).repeat_interleave(4, -1) + ) + assert model.input_bands == model.output_band_names == ALL_BANDS + assert diffusion.received == 7 + + +def test_ldsr_backbone_requires_all_band_variant(): + with pytest.raises(ValueError, match="ten-band"): + load_sen2sr(backbone="ldsrs2") From 1d08e52395a9a9edd1b32ca36e57f203cf39e388 Mon Sep 17 00:00:00 2001 From: Simon Donike Date: Thu, 22 Oct 2026 16:20:39 +0200 Subject: [PATCH 5/7] fix ruff, CI 1x --- .github/constraints-oldest.txt | 2 +- .github/workflows/ci.yml | 57 ++++------------------------------ README.md | 9 ++---- setup.py | 7 +++-- tests/README.md | 7 ++--- 5 files changed, 17 insertions(+), 65 deletions(-) diff --git a/.github/constraints-oldest.txt b/.github/constraints-oldest.txt index 4e8b20f..9a710f1 100644 --- a/.github/constraints-oldest.txt +++ b/.github/constraints-oldest.txt @@ -1,4 +1,4 @@ -# Dependency floor exercised by the Python 3.9 CI job. Keep these pins +# Dependency floor for local Python 3.9 compatibility checks. Keep these pins # together: Torch 2.0 predates NumPy 2's ABI and its Lightning stack has a # narrower compatibility range than current releases. numpy<2 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 70ae389..6509386 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -7,63 +7,18 @@ on: jobs: checks: runs-on: ubuntu-latest - strategy: - fail-fast: false - matrix: - # Retain the package's established 3.9/3.10 compatibility while - # checking current wheels on every maintained interpreter through 3.14. - include: - - python-version: "3.9" - torch-version: "2.0.0" - torchvision-version: "0.15.1" - constraints: oldest - - python-version: "3.10" - torch-version: "2.6.0" - torchvision-version: "0.21.0" - constraints: none - - python-version: "3.11" - torch-version: "latest" - torchvision-version: "latest" - constraints: none - - python-version: "3.12" - torch-version: "latest" - torchvision-version: "latest" - constraints: none - - python-version: "3.13" - torch-version: "latest" - torchvision-version: "latest" - constraints: none - - python-version: "3.14" - torch-version: "latest" - torchvision-version: "latest" - constraints: none steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: - python-version: ${{ matrix.python-version }} + python-version: "3.12" - name: Install CPU PyTorch run: | python -m pip install --upgrade pip - if [ "${{ matrix.torch-version }}" = "latest" ]; then - python -m pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu - else - # Torch 2.0 predates NumPy 2's ABI; install the complete oldest - # stack before the editable package. The constraints file is also - # passed to that package install below, preventing resolver-driven - # upgrades of Torch or Lightning. - python -m pip install \ - "torch==${{ matrix.torch-version }}" \ - "torchvision==${{ matrix.torchvision-version }}" \ - --index-url https://download.pytorch.org/whl/cpu - fi + python -m pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu - name: Install package run: | - if [ "${{ matrix.constraints }}" = "oldest" ]; then - python -m pip install -c .github/constraints-oldest.txt -e '.[dev,cog]' - else - python -m pip install -e '.[dev,cog]' - fi + python -m pip install -e '.[dev,cog]' - name: Syntax check run: python -m compileall opensr_utils setup.py tests examples - name: Shell syntax check @@ -74,13 +29,13 @@ jobs: --cov=opensr_utils --cov-branch --cov-report=term-missing - --cov-report=xml:coverage-${{ matrix.python-version }}.xml + --cov-report=xml:coverage-3.12.xml - name: Upload coverage report if: always() uses: actions/upload-artifact@v4 with: - name: coverage-${{ matrix.python-version }} - path: coverage-${{ matrix.python-version }}.xml + name: coverage-3.12 + path: coverage-3.12.xml if-no-files-found: ignore - name: Check test quality run: >- diff --git a/README.md b/README.md index 71143f3..363e582 100644 --- a/README.md +++ b/README.md @@ -16,13 +16,10 @@ pip install opensr-utils pip install 'opensr-utils[model]' ``` -The CI matrix covers Python **3.9–3.14**, with pinned older PyTorch/Lightning -stacks and current compatible dependencies. The full suite is also exercised -locally on Python 3.12 and 3.14. Use `opensr-utils[cog]` for COG conversion and +CI runs on Python **3.12** with current compatible dependencies. Use +`opensr-utils[cog]` for COG conversion and `opensr-utils[dev,cog]` for development. For current model installations, Python -**3.12–3.14** supports both SEN2SR and ESA SRGAN. Python 3.15 is not in the tested -matrix because [released PyTorch wheels](https://pypi.org/project/torch/#files) -currently cover interpreters only through 3.14. +**3.12–3.14** supports both SEN2SR and ESA SRGAN. ## Python usage diff --git a/setup.py b/setup.py index 42b7522..70e0b85 100644 --- a/setup.py +++ b/setup.py @@ -17,8 +17,8 @@ long_description=long_description, long_description_content_type="text/markdown", # Keep the public API usable on the long-lived Python 3.9/3.10 - # environments used by existing ESA processing workflows. Newer CI jobs - # exercise the current PyTorch wheels through Python 3.14. + # environments used by existing ESA processing workflows. CI exercises + # current PyTorch wheels on Python 3.12. python_requires=">=3.9", classifiers=[ "Programming Language :: Python :: 3", @@ -62,7 +62,8 @@ "cog": ["rio-cogeo"], # Keep coverage tooling in the development extra so local and CI # measurements exercise the same dependency set as the test suite. - "dev": ["pytest", "pytest-cov", "ruff"], + # Pin the reviewed lint/format version so CI and local checks agree. + "dev": ["pytest", "pytest-cov", "ruff==0.15.12"], }, entry_points={ "console_scripts": [ diff --git a/tests/README.md b/tests/README.md index a4af513..226ebf1 100644 --- a/tests/README.md +++ b/tests/README.md @@ -28,10 +28,9 @@ python -m pytest tests/test_distributed.py tests/test_distributed_trainer.py -q python -m pytest --cov=opensr_utils --cov-branch --cov-report=term-missing --cov-report=html ``` -CI covers Python 3.9–3.14. Its oldest interpreter uses the constrained versions in -[constraints-oldest.txt](../.github/constraints-oldest.txt); other jobs use current -compatible dependencies. CPU PyTorch and real COG dependencies are installed. -Branch-aware XML coverage reports are uploaded per interpreter. Coverage is used +CI runs on Python 3.12 with current compatible dependencies and a pinned Ruff +version shared with local development. CPU PyTorch and real COG dependencies are +installed. A branch-aware XML coverage report is uploaded. Coverage is used to identify missing behavior cases; no arbitrary percentage gate masks the importance of individual branches. Child-process execution is validated through observable files and process outcomes; its lines may not appear in the parent From 53b72ee05a85c75586c7c15356aa13b9b4883712 Mon Sep 17 00:00:00 2001 From: Simon Donike Date: Thu, 22 Oct 2026 16:26:49 +0200 Subject: [PATCH 6/7] Prepare v2.1.0 release and standard MIT license --- .github/workflows/publish-to-pypi.yml | 73 ++++++++++++++++++++------- CITATION.cff | 4 +- LICENSE.md | 22 ++++++-- setup.py | 2 +- 4 files changed, 77 insertions(+), 24 deletions(-) diff --git a/.github/workflows/publish-to-pypi.yml b/.github/workflows/publish-to-pypi.yml index d5fc9c6..80b18fa 100644 --- a/.github/workflows/publish-to-pypi.yml +++ b/.github/workflows/publish-to-pypi.yml @@ -2,25 +2,64 @@ name: Publish Python Package on: release: - types: [created] + types: [published] + +permissions: + contents: read + +concurrency: + group: pypi-${{ github.event.release.tag_name }} + cancel-in-progress: false jobs: build-and-publish: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 - - name: Set up Python - uses: actions/setup-python@v2 - with: - python-version: '3.x' - - name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install setuptools wheel twine - - name: Build and publish - env: - TWINE_USERNAME: __token__ - TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }} - run: | - python setup.py sdist bdist_wheel - twine upload dist/* + - uses: actions/checkout@v4 + with: + ref: ${{ github.event.release.tag_name }} + persist-credentials: false + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.12" + - name: Install build tools + run: | + python -m pip install --upgrade pip + python -m pip install build twine + - name: Build distributions + run: python -m build + - name: Validate distributions and release version + env: + RELEASE_TAG: ${{ github.event.release.tag_name }} + run: | + python -m twine check --strict dist/* + python - <<'PY' + import os + from email.parser import BytesParser + from pathlib import Path + from zipfile import ZipFile + + wheel, = Path("dist").glob("*.whl") + with ZipFile(wheel) as archive: + metadata_path, = ( + name for name in archive.namelist() + if name.endswith(".dist-info/METADATA") + ) + metadata = BytesParser().parsebytes(archive.read(metadata_path)) + expected_tag = f"v{metadata['Version']}" + if os.environ["RELEASE_TAG"] != expected_tag: + raise SystemExit(f"Release tag must match package version: {expected_tag}") + PY + - name: Upload distributions + uses: actions/upload-artifact@v4 + with: + name: python-package-${{ github.event.release.tag_name }} + path: dist/* + if-no-files-found: error + - name: Publish to PyPI + env: + TWINE_USERNAME: __token__ + TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }} + TWINE_NON_INTERACTIVE: "1" + run: python -m twine upload dist/* diff --git a/CITATION.cff b/CITATION.cff index 6b2453c..ca6ebdd 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -16,9 +16,9 @@ authors: repository-code: 'https://github.com/ESAOpenSR/opensr-utils' url: 'https://opensr.eu/' -version: 1.2.0 +version: 2.1.0 doi: '10.5281/zenodo.17599310' -date-released: 2025-11-12 +date-released: 2026-10-22 keywords: - super-resolution diff --git a/LICENSE.md b/LICENSE.md index d84c297..2fd9b09 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,7 +1,21 @@ -Copyright 2024 ESA OpenSR +MIT License -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: +Copyright (c) 2024 ESA OpenSR -The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. +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 SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/setup.py b/setup.py index 70e0b85..03807fc 100644 --- a/setup.py +++ b/setup.py @@ -6,7 +6,7 @@ setup( name="opensr-utils", - version="2.0.0", + version="2.1.0", author="Simon Donike, Cesar Aybar, Luis Gomez Chova, Freddie Kalaitzis", author_email="accounts@donike.net", description="Utilities supporting the ESA opensr-model package for Super-Resolution of Sentinel-2 Imagery", From 64156dfb9125e161697bb05a9a900b8571760a5a Mon Sep 17 00:00:00 2001 From: Simon Donike Date: Thu, 22 Oct 2026 16:28:55 +0200 Subject: [PATCH 7/7] Use the version-independent Zenodo DOI for citations --- CITATION.cff | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CITATION.cff b/CITATION.cff index ca6ebdd..662101e 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -17,7 +17,7 @@ authors: repository-code: 'https://github.com/ESAOpenSR/opensr-utils' url: 'https://opensr.eu/' version: 2.1.0 -doi: '10.5281/zenodo.17599310' +doi: '10.5281/zenodo.17599309' date-released: 2026-10-22 keywords: