From 1acfdd832739e13eff4932bca351ea7cd7cb0a78 Mon Sep 17 00:00:00 2001 From: Brendan Collins Date: Mon, 25 May 2026 07:47:56 -0700 Subject: [PATCH 1/2] Audit GeoTIFF example notebooks for tier wording (#2382) Adds a tier callout near the top of each GeoTIFF-touching example notebook so a reader can tell which sections sit on the stable contract and which exercise advanced or experimental paths. Each callout names the relevant SUPPORTED_FEATURES key (for example codec.jpeg2000, reader.http_cog, reader.vrt) and points to docs/source/reference/geotiff.rst for the full tier matrix. Notebooks touched: 25_GLCM_Texture, 29_Preview, 39_GeoTIFF_IO, 40_JPEG2000_Compression, 46_GeoTIFF_Performance, 47_Streaming_GeoTIFF_Write, 52_COG_Overview_Generation. Markdown-only changes. No code cells, narrative ordering, or loaded data were modified. Closes #2382. Part of epic #2345. --- examples/user_guide/25_GLCM_Texture.ipynb | 13 +++++++++++- examples/user_guide/29_Preview.ipynb | 9 +++++++++ examples/user_guide/39_GeoTIFF_IO.ipynb | 11 ++++++++++ .../user_guide/40_JPEG2000_Compression.ipynb | 15 +++++++++++++- .../user_guide/46_GeoTIFF_Performance.ipynb | 13 +++++++++++- .../47_Streaming_GeoTIFF_Write.ipynb | 11 ++++++++++ .../52_COG_Overview_Generation.ipynb | 20 +++++++++++++++++-- 7 files changed, 87 insertions(+), 5 deletions(-) diff --git a/examples/user_guide/25_GLCM_Texture.ipynb b/examples/user_guide/25_GLCM_Texture.ipynb index 4d196bce0..fb8a38bcb 100644 --- a/examples/user_guide/25_GLCM_Texture.ipynb +++ b/examples/user_guide/25_GLCM_Texture.ipynb @@ -10,6 +10,17 @@ "Gray-Level Co-occurrence Matrix (GLCM) features capture spatial patterns that spectral bands alone cannot distinguish. They quantify how pixel intensities co-occur within a neighborhood, producing metrics like contrast, homogeneity, and entropy. This notebook covers the six Haralick features available in `glcm_texture`, parameter tuning, and a satellite-based water/land classification example." ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Tier note\n", + "\n", + "The classification section reads a Sentinel-2 Cloud-Optimized GeoTIFF over HTTPS with `open_geotiff`. The HTTP COG reader sits at the `advanced` tier in `xrspatial.geotiff.SUPPORTED_FEATURES` (`reader.http_cog`): range fetching, redirect handling, and cache behaviour are not contracted at the stable bar. Local COG reads (`reader.local_cog`) and the GLCM kernel itself are unrelated to that caveat -- swap the URL for a local path and the rest of the notebook stays inside the stable surface.\n", + "\n", + "**See also:** the GeoTIFF / COG reference page at `docs/source/reference/geotiff.rst` lists every feature in `xrspatial.geotiff.SUPPORTED_FEATURES` against its tier (`stable`, `advanced`, `experimental`, `internal_only`) and links the release gate that locks each promise.\n" + ] + }, { "cell_type": "markdown", "id": "7yishbzt21d", @@ -453,4 +464,4 @@ }, "nbformat": 4, "nbformat_minor": 5 -} \ No newline at end of file +} diff --git a/examples/user_guide/29_Preview.ipynb b/examples/user_guide/29_Preview.ipynb index b31f3700f..d122cb7af 100644 --- a/examples/user_guide/29_Preview.ipynb +++ b/examples/user_guide/29_Preview.ipynb @@ -10,6 +10,15 @@ "When a raster is backed by dask (e.g., loaded lazily from Zarr or a stack of GeoTIFFs), calling `.compute()` to visualize it can blow up your memory. `xrspatial.preview()` downsamples the data to a target pixel size using block averaging, and the whole operation stays lazy until you ask for the result. Peak memory is bounded by the largest chunk plus the small output array." ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### See also\n", + "\n", + "This notebook is about lazy downsampling, not GeoTIFF I/O. If you do feed `preview` data loaded via `open_geotiff`, the GeoTIFF / COG reference page (`docs/source/reference/geotiff.rst`) records which reader paths sit at the `stable` versus `advanced` / `experimental` tier in `xrspatial.geotiff.SUPPORTED_FEATURES`.\n" + ] + }, { "cell_type": "markdown", "id": "x11ktiuo2cf", diff --git a/examples/user_guide/39_GeoTIFF_IO.ipynb b/examples/user_guide/39_GeoTIFF_IO.ipynb index 7e6746bc2..b24eddd22 100644 --- a/examples/user_guide/39_GeoTIFF_IO.ipynb +++ b/examples/user_guide/39_GeoTIFF_IO.ipynb @@ -9,6 +9,17 @@ "GeoTIFF is the standard raster format in geospatial work. xarray-spatial has a pure-Python reader and writer (no GDAL) that follows xarray naming: `open_geotiff` to read, `to_geotiff` to write." ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Tier note\n", + "\n", + "`open_geotiff` and `to_geotiff` against local files, the lossless codecs (`none`, `deflate`, `lzw`, `zstd`, `packbits`), axis-aligned 2D / 3D rasters, and dask reads / writes are tagged `stable` in `xrspatial.geotiff.SUPPORTED_FEATURES`. The VRT mosaic section at the bottom exercises `write_vrt` / `read_vrt`, which sit at the `advanced` tier (`reader.vrt`): the supported subset is a flat mosaic of compatible GeoTIFF tiles, not the full GDAL VRT spec.\n", + "\n", + "**See also:** the GeoTIFF / COG reference page at `docs/source/reference/geotiff.rst` lists every feature in `xrspatial.geotiff.SUPPORTED_FEATURES` against its tier (`stable`, `advanced`, `experimental`, `internal_only`) and links the release gate that locks each promise.\n" + ] + }, { "cell_type": "markdown", "metadata": {}, diff --git a/examples/user_guide/40_JPEG2000_Compression.ipynb b/examples/user_guide/40_JPEG2000_Compression.ipynb index 229f58803..592d4c938 100644 --- a/examples/user_guide/40_JPEG2000_Compression.ipynb +++ b/examples/user_guide/40_JPEG2000_Compression.ipynb @@ -6,6 +6,19 @@ "source": "# Xarray-Spatial I/O: JPEG 2000 compression\n\nSatellite imagery (Sentinel-2, Landsat) often ships in JPEG 2000 format. The `geotiff` module lets you write and read J2K-compressed GeoTIFFs on CPU (via glymur/OpenJPEG) or GPU (via nvJPEG2000).", "metadata": {} }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Experimental tier callout\n", + "\n", + "The `jpeg2000` / `j2k` codec is tagged `experimental` in `xrspatial.geotiff.SUPPORTED_FEATURES` (`codec.jpeg2000`, `codec.j2k`). Cross-backend numerical parity, external GDAL / libtiff interop, and round-trip stability across releases are not contracted yet. Writers require the explicit `allow_experimental_codecs=True` opt-in. The GPU path (`reader.gpu` / `writer.gpu`) is also `experimental` and depends on nvJPEG2000 being available at import time.\n", + "\n", + "Treat the recipes below as a working reference for the current code, not a stable API surface. If you need a contracted lossless codec, use `deflate`, `lzw`, `zstd`, or `packbits` from the stable tier instead.\n", + "\n", + "**See also:** the GeoTIFF / COG reference page at `docs/source/reference/geotiff.rst` lists every feature in `xrspatial.geotiff.SUPPORTED_FEATURES` against its tier (`stable`, `advanced`, `experimental`, `internal_only`) and links the release gate that locks each promise.\n" + ] + }, { "cell_type": "markdown", "id": "46a72497", @@ -130,4 +143,4 @@ }, "nbformat": 4, "nbformat_minor": 5 -} \ No newline at end of file +} diff --git a/examples/user_guide/46_GeoTIFF_Performance.ipynb b/examples/user_guide/46_GeoTIFF_Performance.ipynb index cacff7c9a..cc7ac2436 100644 --- a/examples/user_guide/46_GeoTIFF_Performance.ipynb +++ b/examples/user_guide/46_GeoTIFF_Performance.ipynb @@ -11,6 +11,17 @@ "arrays and chunked Dask arrays alike." ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Tier note\n", + "\n", + "The `dtype` and `compression_level` techniques below ride on the stable local read / write paths (`reader.local_file`, `writer.local_file`) and the stable lossless codecs. The third section (\"VRT tiled output\") drives `to_geotiff(..., vrt=True)`, which sits at the `advanced` tier (`reader.vrt`): the writer emits a flat mosaic VRT pointing at sibling tiles, which is a subset of the full GDAL VRT spec.\n", + "\n", + "**See also:** the GeoTIFF / COG reference page at `docs/source/reference/geotiff.rst` lists every feature in `xrspatial.geotiff.SUPPORTED_FEATURES` against its tier (`stable`, `advanced`, `experimental`, `internal_only`) and links the release gate that locks each promise.\n" + ] + }, { "cell_type": "markdown", "metadata": {}, @@ -246,4 +257,4 @@ }, "nbformat": 4, "nbformat_minor": 5 -} \ No newline at end of file +} diff --git a/examples/user_guide/47_Streaming_GeoTIFF_Write.ipynb b/examples/user_guide/47_Streaming_GeoTIFF_Write.ipynb index 4a89a1c23..105be3e95 100644 --- a/examples/user_guide/47_Streaming_GeoTIFF_Write.ipynb +++ b/examples/user_guide/47_Streaming_GeoTIFF_Write.ipynb @@ -10,6 +10,17 @@ "Only one tile-row lives in memory at once, so you can write rasters larger than RAM without switching to VRT output." ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Tier note\n", + "\n", + "The streaming write path itself rides on `writer.local_file` (stable): a dask-backed `to_geotiff` call streams tile-row by tile-row out to a single TIFF using the stable lossless codecs. The \"Stream-write to a VRT mosaic\" section uses `to_geotiff(..., vrt=True)`, which sits at the `advanced` tier (`reader.vrt`): the VRT is a flat sibling-tile mosaic, not the full GDAL VRT spec.\n", + "\n", + "**See also:** the GeoTIFF / COG reference page at `docs/source/reference/geotiff.rst` lists every feature in `xrspatial.geotiff.SUPPORTED_FEATURES` against its tier (`stable`, `advanced`, `experimental`, `internal_only`) and links the release gate that locks each promise.\n" + ] + }, { "cell_type": "markdown", "metadata": {}, diff --git a/examples/user_guide/52_COG_Overview_Generation.ipynb b/examples/user_guide/52_COG_Overview_Generation.ipynb index 68133e3af..15d83052f 100644 --- a/examples/user_guide/52_COG_Overview_Generation.ipynb +++ b/examples/user_guide/52_COG_Overview_Generation.ipynb @@ -14,7 +14,23 @@ }, { "cell_type": "markdown", - "source": "### Stable COG contract\n\nThe local COG writer and the local COG reader are tagged `stable` in `xrspatial.geotiff.SUPPORTED_FEATURES` (`writer.cog` and `reader.local_cog`). Axis-aligned 2D / 3D rasters, the lossless codecs (`none`, `deflate`, `lzw`, `zstd`, `packbits`), internal overviews, and normal CRS / transform / nodata round-trip are covered by the parity and compliance suites that gate every CI build, so the examples in this notebook all sit inside the stable contract.\n\nA few combinations stay outside the stable contract and keep their existing `advanced` or `experimental` tier:\n\n- The HTTP COG reader (`reader.http_cog`) -- range fetching, redirect handling, and cache behaviour are not contracted yet. Use with care.\n- GPU COG read / write.\n- Experimental codecs (`lerc`, `jpeg2000` / `j2k`, `lz4`) and the internal-only `jpeg` codec.\n- Rotated transforms, external `.tif.ovr` sidecars, file-like destinations with `cog=True`.\n- BigTIFF COG (tracked separately).\n\nSee the *Stable COG contract* section of the GeoTIFF / COG reference page for the full list.", + "source": [ + "### Stable COG contract\n", + "\n", + "The local COG writer and the local COG reader are tagged `stable` in `xrspatial.geotiff.SUPPORTED_FEATURES` (`writer.cog` and `reader.local_cog`). Axis-aligned 2D / 3D rasters, the lossless codecs (`none`, `deflate`, `lzw`, `zstd`, `packbits`), internal overviews, and normal CRS / transform / nodata round-trip are covered by the parity and compliance suites that gate every CI build, so the examples in this notebook all sit inside the stable contract.\n", + "\n", + "A few combinations stay outside the stable contract and keep their existing `advanced` or `experimental` tier:\n", + "\n", + "- The HTTP COG reader (`reader.http_cog`) -- range fetching, redirect handling, and cache behaviour are not contracted yet. Use with care.\n", + "- GPU COG read / write.\n", + "- Experimental codecs (`lerc`, `jpeg2000` / `j2k`, `lz4`) and the internal-only `jpeg` codec.\n", + "- Rotated transforms, external `.tif.ovr` sidecars, file-like destinations with `cog=True`.\n", + "- BigTIFF COG (tracked separately).\n", + "\n", + "See the *Stable COG contract* section of the GeoTIFF / COG reference page for the full list.\n", + "\n", + "**See also:** the full feature / tier matrix lives in `docs/source/reference/geotiff.rst` and is sourced from `xrspatial.geotiff.SUPPORTED_FEATURES`.\n" + ], "metadata": {} }, { @@ -278,4 +294,4 @@ }, "nbformat": 4, "nbformat_minor": 4 -} \ No newline at end of file +} From 89a6d5cbb163ea23c9497b5eb83e4a00817515a2 Mon Sep 17 00:00:00 2001 From: Brendan Collins Date: Mon, 25 May 2026 07:51:54 -0700 Subject: [PATCH 2/2] Address review nits: tighten tier wording, drop duplicate See-also (#2382) Review pass on PR #2385: - 39: separate 'stable local read/write' from the dask claim; reader.dask is the explicit stable key, dask writes ride on writer.local_file. - 40: nvJPEG2000 is loaded lazily on the first GPU call, not at import time -- update wording and name the loader-path failure mode. - 46 / 47: separate the per-tile write (writer.local_file, stable) from the VRT round-trip read (reader.vrt, advanced) so a reader does not conclude the write side itself is advanced. - 29: trim the see-also to one sentence. - 52: drop the duplicate See-also we appended -- the existing 'See the Stable COG contract section' line already points at the same page. --- examples/user_guide/29_Preview.ipynb | 2 +- examples/user_guide/39_GeoTIFF_IO.ipynb | 2 +- examples/user_guide/40_JPEG2000_Compression.ipynb | 2 +- examples/user_guide/46_GeoTIFF_Performance.ipynb | 2 +- examples/user_guide/47_Streaming_GeoTIFF_Write.ipynb | 2 +- examples/user_guide/52_COG_Overview_Generation.ipynb | 4 +--- 6 files changed, 6 insertions(+), 8 deletions(-) diff --git a/examples/user_guide/29_Preview.ipynb b/examples/user_guide/29_Preview.ipynb index d122cb7af..28d80f3ad 100644 --- a/examples/user_guide/29_Preview.ipynb +++ b/examples/user_guide/29_Preview.ipynb @@ -16,7 +16,7 @@ "source": [ "### See also\n", "\n", - "This notebook is about lazy downsampling, not GeoTIFF I/O. If you do feed `preview` data loaded via `open_geotiff`, the GeoTIFF / COG reference page (`docs/source/reference/geotiff.rst`) records which reader paths sit at the `stable` versus `advanced` / `experimental` tier in `xrspatial.geotiff.SUPPORTED_FEATURES`.\n" + "If you feed `preview` data loaded via `open_geotiff`, `docs/source/reference/geotiff.rst` records which reader paths are `stable`, `advanced`, or `experimental` in `xrspatial.geotiff.SUPPORTED_FEATURES`.\n" ] }, { diff --git a/examples/user_guide/39_GeoTIFF_IO.ipynb b/examples/user_guide/39_GeoTIFF_IO.ipynb index b24eddd22..dcbf66875 100644 --- a/examples/user_guide/39_GeoTIFF_IO.ipynb +++ b/examples/user_guide/39_GeoTIFF_IO.ipynb @@ -15,7 +15,7 @@ "source": [ "### Tier note\n", "\n", - "`open_geotiff` and `to_geotiff` against local files, the lossless codecs (`none`, `deflate`, `lzw`, `zstd`, `packbits`), axis-aligned 2D / 3D rasters, and dask reads / writes are tagged `stable` in `xrspatial.geotiff.SUPPORTED_FEATURES`. The VRT mosaic section at the bottom exercises `write_vrt` / `read_vrt`, which sit at the `advanced` tier (`reader.vrt`): the supported subset is a flat mosaic of compatible GeoTIFF tiles, not the full GDAL VRT spec.\n", + "`open_geotiff` and `to_geotiff` against local files, the lossless codecs (`none`, `deflate`, `lzw`, `zstd`, `packbits`), and axis-aligned 2D / 3D rasters are tagged `stable` in `xrspatial.geotiff.SUPPORTED_FEATURES`. Dask reads (`reader.dask`) and dask streaming writes (covered by `writer.local_file`) are stable too. The VRT mosaic section at the bottom exercises `write_vrt` / `read_vrt`, which sit at the `advanced` tier (`reader.vrt`): the supported subset is a flat mosaic of compatible GeoTIFF tiles, not the full GDAL VRT spec.\n", "\n", "**See also:** the GeoTIFF / COG reference page at `docs/source/reference/geotiff.rst` lists every feature in `xrspatial.geotiff.SUPPORTED_FEATURES` against its tier (`stable`, `advanced`, `experimental`, `internal_only`) and links the release gate that locks each promise.\n" ] diff --git a/examples/user_guide/40_JPEG2000_Compression.ipynb b/examples/user_guide/40_JPEG2000_Compression.ipynb index 592d4c938..81df2ce3d 100644 --- a/examples/user_guide/40_JPEG2000_Compression.ipynb +++ b/examples/user_guide/40_JPEG2000_Compression.ipynb @@ -12,7 +12,7 @@ "source": [ "### Experimental tier callout\n", "\n", - "The `jpeg2000` / `j2k` codec is tagged `experimental` in `xrspatial.geotiff.SUPPORTED_FEATURES` (`codec.jpeg2000`, `codec.j2k`). Cross-backend numerical parity, external GDAL / libtiff interop, and round-trip stability across releases are not contracted yet. Writers require the explicit `allow_experimental_codecs=True` opt-in. The GPU path (`reader.gpu` / `writer.gpu`) is also `experimental` and depends on nvJPEG2000 being available at import time.\n", + "The `jpeg2000` / `j2k` codec is tagged `experimental` in `xrspatial.geotiff.SUPPORTED_FEATURES` (`codec.jpeg2000`, `codec.j2k`). Cross-backend numerical parity, external GDAL / libtiff interop, and round-trip stability across releases are not contracted yet. Writers require the explicit `allow_experimental_codecs=True` opt-in. The GPU path (`reader.gpu` / `writer.gpu`) is also `experimental` and probes for nvJPEG2000 lazily on the first GPU call -- if `libnvjpeg2k.so` is not on the loader path, the GPU codec is unavailable and the call falls back or fails.\n", "\n", "Treat the recipes below as a working reference for the current code, not a stable API surface. If you need a contracted lossless codec, use `deflate`, `lzw`, `zstd`, or `packbits` from the stable tier instead.\n", "\n", diff --git a/examples/user_guide/46_GeoTIFF_Performance.ipynb b/examples/user_guide/46_GeoTIFF_Performance.ipynb index cc7ac2436..02babef64 100644 --- a/examples/user_guide/46_GeoTIFF_Performance.ipynb +++ b/examples/user_guide/46_GeoTIFF_Performance.ipynb @@ -17,7 +17,7 @@ "source": [ "### Tier note\n", "\n", - "The `dtype` and `compression_level` techniques below ride on the stable local read / write paths (`reader.local_file`, `writer.local_file`) and the stable lossless codecs. The third section (\"VRT tiled output\") drives `to_geotiff(..., vrt=True)`, which sits at the `advanced` tier (`reader.vrt`): the writer emits a flat mosaic VRT pointing at sibling tiles, which is a subset of the full GDAL VRT spec.\n", + "The `dtype` and `compression_level` techniques below ride on the stable local read / write paths (`reader.local_file`, `writer.local_file`) and the stable lossless codecs. The third section (\"VRT tiled output\") drives `to_geotiff(..., vrt=True)`: each per-tile write itself rides on `writer.local_file` (stable), and the round-trip read through the VRT XML uses `reader.vrt`, which sits at the `advanced` tier. The supported VRT subset is a flat mosaic of compatible sibling tiles, not the full GDAL VRT spec.\n", "\n", "**See also:** the GeoTIFF / COG reference page at `docs/source/reference/geotiff.rst` lists every feature in `xrspatial.geotiff.SUPPORTED_FEATURES` against its tier (`stable`, `advanced`, `experimental`, `internal_only`) and links the release gate that locks each promise.\n" ] diff --git a/examples/user_guide/47_Streaming_GeoTIFF_Write.ipynb b/examples/user_guide/47_Streaming_GeoTIFF_Write.ipynb index 105be3e95..778e5cdd4 100644 --- a/examples/user_guide/47_Streaming_GeoTIFF_Write.ipynb +++ b/examples/user_guide/47_Streaming_GeoTIFF_Write.ipynb @@ -16,7 +16,7 @@ "source": [ "### Tier note\n", "\n", - "The streaming write path itself rides on `writer.local_file` (stable): a dask-backed `to_geotiff` call streams tile-row by tile-row out to a single TIFF using the stable lossless codecs. The \"Stream-write to a VRT mosaic\" section uses `to_geotiff(..., vrt=True)`, which sits at the `advanced` tier (`reader.vrt`): the VRT is a flat sibling-tile mosaic, not the full GDAL VRT spec.\n", + "The streaming write path itself rides on `writer.local_file` (stable): a dask-backed `to_geotiff` call streams tile-row by tile-row out to a single TIFF using the stable lossless codecs. The \"Stream-write to a VRT mosaic\" section also uses `writer.local_file` for the per-tile writes; the `advanced` tier (`reader.vrt`) only applies on the round-trip read through the VRT XML, where the supported subset is a flat sibling-tile mosaic rather than the full GDAL VRT spec.\n", "\n", "**See also:** the GeoTIFF / COG reference page at `docs/source/reference/geotiff.rst` lists every feature in `xrspatial.geotiff.SUPPORTED_FEATURES` against its tier (`stable`, `advanced`, `experimental`, `internal_only`) and links the release gate that locks each promise.\n" ] diff --git a/examples/user_guide/52_COG_Overview_Generation.ipynb b/examples/user_guide/52_COG_Overview_Generation.ipynb index 15d83052f..2580cc5dc 100644 --- a/examples/user_guide/52_COG_Overview_Generation.ipynb +++ b/examples/user_guide/52_COG_Overview_Generation.ipynb @@ -27,9 +27,7 @@ "- Rotated transforms, external `.tif.ovr` sidecars, file-like destinations with `cog=True`.\n", "- BigTIFF COG (tracked separately).\n", "\n", - "See the *Stable COG contract* section of the GeoTIFF / COG reference page for the full list.\n", - "\n", - "**See also:** the full feature / tier matrix lives in `docs/source/reference/geotiff.rst` and is sourced from `xrspatial.geotiff.SUPPORTED_FEATURES`.\n" + "See the *Stable COG contract* section of the GeoTIFF / COG reference page for the full list.\n" ], "metadata": {} },