Prepare 0.5.0 release

Author: wrignj08

.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0  # full history so setuptools-scm can read tags
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - uses: astral-sh/setup-uv@v8.0.0
+        with:
+          cache-suffix: ${{ matrix.python-version }}
+
+      - run: uv sync --all-extras --dev
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Type check
+        run: uv run mypy omniwatermask/
+
+      - name: Test
+        run: uv run pytest tests/ -x -q  # e2e/inference tests excluded via addopts

.github/workflows/publish.yml

@@ -0,0 +1,75 @@
+name: Publish to PyPI
+
+# Triggered by pushing a tag that looks like a version, e.g. `v0.4.4`.
+# The version comes from the git tag itself (via setuptools-scm) — no file to bump.
+# Publishing uses PyPI trusted publishing (OIDC) — no API tokens, no secrets.
+# To enable: at https://pypi.org/manage/project/omniwatermask/settings/publishing/
+# add a publisher with:
+#   Owner            DPIRD-DMA
+#   Repository name  OmniWaterMask
+#   Workflow name    publish.yml
+#   Environment      pypi
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+*"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0  # full history so setuptools-scm can read tags
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - uses: astral-sh/setup-uv@v8.0.0
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/omniwatermask
+    permissions:
+      id-token: write  # required for trusted publishing
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    needs: publish-to-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # required to create releases
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

.gitignore

@@ -1,4 +1,10 @@
 cache/*.json
+# coverage.py artifacts
+.coverage
+.coverage.*
+htmlcov/
+# setuptools-scm generated version file
+omniwatermask/_version.py
 omniwatermask/__pycache__/*
 omniwatermask/models/*.pth
 water_vectors_cache/*
@@ -15,4 +21,9 @@ examples/data/naip_water_test_OmniWaterMask_0.4.3.tif
 examples/data/naip_water_test.tif
 examples/OWM_cache/*
 examples/cache/*
-examples/data/*
+examples/data/*
+data/S2B_MSIL2A_20241219T013659_R031_T52LEH_20241219T030742_TL_RGBNIR.tif
+OWM_cache/*
+data/S2A_56HLH_20231011_0_L2A_RGBNIR.tif
+examples/water_vectors_cache/gdfs/*.parquet
+examples/water_vectors_cache/*.db

.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.8
+    hooks:
+      - id: ruff-check
+      - id: ruff-format
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: uv run mypy omniwatermask/
+        language: system
+        pass_filenames: false
+        always_run: true
+      - id: pytest
+        name: pytest
+        entry: uv run pytest tests/ -x -q -m "not e2e"
+        language: system
+        pass_filenames: false
+        always_run: true
+        stages: [pre-push]

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.5.0] - Jun 3, 2026
+
+### Changed
+- **Breaking:** No-data is now written as a GDAL dataset mask via `dst.write_mask()` instead of as a second data band, so GIS software (e.g. QGIS) treats no-data pixels as transparent. The mask is embedded inside the GeoTIFF (`GDAL_TIFF_INTERNAL_MASK`) rather than written as a `.tif.msk` sidecar. Standard output GeoTIFFs now have a single `Water predictions` band; read the mask with `src.read_masks(1)`. Debug output is unchanged.
+- Versioning now derives from git tags via `setuptools-scm` (generates `omniwatermask/_version.py` at build time); the hardcoded `omniwatermask/__version__.py` was removed.
+- End-to-end tests are now excluded from the default test run (`addopts = "-m 'not e2e'"`); run them explicitly with `pytest -m e2e`.
+
+### Added
+- `py.typed` marker and full type hints — the package now ships type information (PEP 561) and is checked with `mypy --strict`.
+- Pre-commit hooks (ruff lint/format, mypy, fast tests) and GitHub Actions CI.
+- PyPI trove classifiers and project URLs (Repository, Issues, Changelog) in `pyproject.toml`.
+- Cloudy Sentinel-2 example notebook demonstrating cloud masking with OmniCloudMask before inference, plus a "Cloudy imagery" guidance section in the README.
+
 ## [0.4.3] - Mar 5, 2026
 
 ### Fixed

README.md

@@ -1,14 +1,17 @@
-# OmniWaterMask
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/DPIRD-DMA/OmniWaterMask/main/assets/omniwatermask-title.svg" alt="OmniWaterMask" width="680">
 
 [![image](https://img.shields.io/pypi/v/omniwatermask.svg)](https://pypi.python.org/pypi/omniwatermask)
 [![image](https://static.pepy.tech/badge/omniwatermask)](https://pepy.tech/project/omniwatermask)
 [![image](https://img.shields.io/conda/vn/conda-forge/omniwatermask.svg)](https://anaconda.org/conda-forge/omniwatermask)
-[![Conda Downloads](https://img.shields.io/conda/dn/conda-forge/omniwatermask.svg)](https://anaconda.org/conda-forge/omniwatermask)
 [![Conda Recipe](https://img.shields.io/badge/recipe-omniwatermask-green.svg)](https://github.com/conda-forge/omniwatermask-feedstock)
 
+</div>
+
 OmniWaterMask is a Python library for high accuracy water segmentation in high to moderate resolution satellite imagery, supporting a wide range of resolutions, sensors, and processing levels.
 
-[The OmniWaterMask paper is now published 🎉](https://www.sciencedirect.com/science/article/pii/S0924271625002692)
+[Check out the paper here](https://www.sciencedirect.com/science/article/pii/S0924271625002692)
 
 
 ## Features
@@ -95,6 +98,17 @@ water_mask_path = make_water_mask(
 
 -   When working with scenes containing no-data regions, explicitly set the 'no_data_value' parameter to ensure proper handling of these areas.
 
+### Cloudy imagery
+
+If you are working with cloudy imagery, either:
+
+-   use a **temporal mosaic** that is already cloud and cloud-shadow free (e.g. via [s2mosaic](https://github.com/DPIRD-DMA/s2mosaic) for Sentinel-2), or
+-   apply a **high quality cloud and cloud shadow mask** and set those pixels to `0` (the `no_data_value`) before running OWM.
+
+This matters because OWM optimises its detection thresholds both **locally** (per region/patch) and **globally** (across the whole scene). Cloud and cloud-shadow pixels are out-of-distribution and can skew those optimisations, so bad data in one part of a scene can degrade the water prediction in other, otherwise-clean parts. Masking those pixels to no-data removes them from the optimisation entirely.
+
+[OmniCloudMask](https://github.com/DPIRD-DMA/OmniCloudMask) is a good choice for the masking step. See the [cloudy Sentinel-2 example](https://github.com/DPIRD-DMA/OmniWaterMask/blob/main/examples/Sentinel-2%20example.ipynb) for an end-to-end mask-then-infer workflow.
+
 
 ## Parameters
 
@@ -145,6 +159,7 @@ Example notebooks are available in the [examples/](https://github.com/DPIRD-DMA/
 
 -   [NAIP example](https://github.com/DPIRD-DMA/OmniWaterMask/blob/main/examples/NAIP%20example.ipynb) — Water segmentation on NAIP aerial imagery from HuggingFace
 -   [Sentinel-2 example](https://github.com/DPIRD-DMA/OmniWaterMask/blob/main/examples/Sentinel%202%20example.ipynb) — Water segmentation on a Sentinel-2 mosaic using [s2mosaic](https://github.com/DPIRD-DMA/s2mosaic)
+-   [Cloudy Sentinel-2 example](https://github.com/DPIRD-DMA/OmniWaterMask/blob/main/examples/Sentinel-2%20example.ipynb) — Masking clouds with [OmniCloudMask](https://github.com/DPIRD-DMA/OmniCloudMask) before running OWM on a cloudy AWS scene
 
 ## Changelog
 
@@ -154,6 +169,48 @@ See [CHANGELOG.md](https://github.com/DPIRD-DMA/OmniWaterMask/blob/main/CHANGELO
 
 Contributions are welcome! Please submit a pull request or open an issue to discuss any changes.
 
+### Development setup
+
+Clone the repository and install the dependencies (including the dev group) with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv sync --all-extras --dev
+```
+
+Optionally install the git hooks (ruff lint/format on commit, mypy + the fast tests on push):
+
+```bash
+uv run pre-commit install
+uv run pre-commit install --hook-type pre-push
+```
+
+### Running the tests
+
+Tests use `pytest`. The fast suite (unit tests + model-mocked pipeline tests) runs in a few seconds and is what CI runs by default:
+
+```bash
+uv run pytest                              # full fast suite
+uv run pytest tests/test_orchestration.py  # one file
+uv run pytest -k make_water_mask           # match by name
+```
+
+End-to-end tests that download the real model weights and run inference on real imagery are marked `e2e` and excluded by default (see `addopts` in `pyproject.toml`). To run them explicitly:
+
+```bash
+uv run pytest -m e2e                        # only the e2e/inference tests
+uv run pytest -m ""                         # everything, including e2e
+```
+
+Lint, format and type-check:
+
+```bash
+uv run ruff check .
+uv run ruff format .
+uv run mypy omniwatermask/
+```
+
+For maintainers: pushing a version tag (e.g. `git tag v0.4.4 && git push --tags`) builds the package and publishes it to PyPI via GitHub Actions trusted publishing — no tokens required.
+
 ## License
 
 This project is licensed under the MIT License