Audit GeoTIFF example notebooks for tier wording (#2345 PR 4, closes #2382)

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
-}
+}

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",
+    "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"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "x11ktiuo2cf",

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`), 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"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

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 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",
+    "**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
-}
+}

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)`: 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"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -246,4 +257,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

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 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"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

examples/user_guide/52_COG_Overview_Generation.ipynb

@@ -14,7 +14,21 @@
   },
   {
    "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"
+   ],
    "metadata": {}
   },
   {
@@ -278,4 +292,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 4
-}
+}