Add preview() user guide notebook (#986)

Author: brendancol

examples/user_guide/26_Preview.ipynb

@@ -0,0 +1,125 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "rt7pp4omcq",
+   "source": "# Preview: memory-safe thumbnails of large rasters\n\nWhen a raster is backed by dask (e.g. loaded lazily from Zarr or a stack of GeoTIFFs),\ncalling `.compute()` to visualize it can blow up your memory.  `xrspatial.preview()`\ndownsamples the data to a target pixel size using block averaging, and the whole\noperation stays lazy until you ask for the result.  Peak memory is bounded by\nthe largest chunk plus the small output array.\n\nThis notebook generates a 1 TB dask-backed terrain raster and previews it at\n1000x1000 pixels.  A `dask.distributed` LocalCluster is started so you can\nwatch the task graph and worker memory in the dashboard.",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "ivhk3f6ui7",
+   "source": "import numpy as np\nimport xarray as xr\nimport dask.array as da\nimport matplotlib.pyplot as plt\n\nimport xrspatial\nfrom xrspatial import generate_terrain, preview",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "code",
+   "id": "lb7wkq291z",
+   "source": "from dask.distributed import Client, LocalCluster\n\ncluster = LocalCluster(n_workers=4, threads_per_worker=2, memory_limit=\"2GB\")\nclient = Client(cluster)\nprint(f\"Dashboard: {client.dashboard_link}\")\nclient",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ouvgm7ttw1",
+   "source": "## Generate a terrain tile\n\nFirst, create a 1024x1024 terrain tile using `generate_terrain`.  This is the\nbuilding block we'll replicate into a massive dask array.",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "yts07v5mgv9",
+   "source": "# 1024x1024 in-memory terrain tile\ncanvas = xr.DataArray(np.zeros((1024, 1024), dtype=np.float32), dims=[\"y\", \"x\"])\ntile = generate_terrain(canvas, seed=12345)\n\nfig, ax = plt.subplots(figsize=(6, 6))\ntile.plot(ax=ax, cmap=\"terrain\")\nax.set_title(f\"Terrain tile ({tile.shape[0]}x{tile.shape[1]}, {tile.nbytes / 1e6:.1f} MB)\")\nax.set_aspect(\"equal\")\nplt.tight_layout()",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "mc23kw3w94",
+   "source": "## Tile it into a 1 TB dask array\n\nWe replicate the tile 512x512 times using `dask.array.tile` to get a\n524,288 x 524,288 raster.  At float32 that's 1.1 TB of data.  Nothing is\nactually computed here -- dask just records the tiling as a lazy graph.",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "ire1hxtder",
+   "source": "# Tile the small terrain into a ~1 TB dask array\nreps = 512\nbig_dask = da.tile(\n    da.from_array(tile.values, chunks=(1024, 1024)),\n    (reps, reps),\n)\nrows, cols = big_dask.shape\nbig = xr.DataArray(\n    big_dask,\n    dims=[\"y\", \"x\"],\n    coords={\"y\": np.arange(rows, dtype=np.float64), \"x\": np.arange(cols, dtype=np.float64)},\n)\n\nprint(f\"Shape:      {big.shape[0]:,} x {big.shape[1]:,}\")\nprint(f\"Chunk size: {big_dask.chunksize}\")\nprint(f\"Num chunks: {big_dask.numblocks}\")\nprint(f\"Total size: {big_dask.nbytes / 1e12:.2f} TB\")\nprint(f\"Dtype:      {big_dask.dtype}\")",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3n94gc0t1tg",
+   "source": "## Preview at 1000x1000\n\n`preview()` builds a lazy coarsen-then-mean graph.  Calling `.compute()` on the\nresult materializes only the 1000x1000 output -- about 4 MB.",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "skqz0wfgial",
+   "source": "%%time\nsmall = preview(big, width=1000).compute()\n\nprint(f\"Output shape: {small.shape}\")\nprint(f\"Output size:  {small.nbytes / 1e6:.1f} MB\")",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "code",
+   "id": "2jif06ajupn",
+   "source": "fig, ax = plt.subplots(figsize=(8, 8))\nsmall.plot(ax=ax, cmap=\"terrain\")\nax.set_title(f\"1000x1000 preview of a {big_dask.nbytes / 1e12:.1f} TB raster\")\nax.set_aspect(\"equal\")\nplt.tight_layout()",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "nrbcb74q9oa",
+   "source": "## Different preview sizes\n\nYou can control both width and height.  Omitting height preserves the aspect ratio.",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "mqzjqxdvj4",
+   "source": "fig, axes = plt.subplots(1, 3, figsize=(14, 4))\nfor ax, w in zip(axes, [100, 500, 2000]):\n    p = preview(big, width=w).compute()\n    p.plot(ax=ax, cmap=\"terrain\", add_colorbar=False)\n    ax.set_title(f\"{p.shape[0]}x{p.shape[1]} ({p.nbytes / 1e6:.1f} MB)\")\n    ax.set_aspect(\"equal\")\nplt.tight_layout()",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "82h89j8n7em",
+   "source": "## Accessor syntax\n\nYou can also call `preview` directly on a DataArray or Dataset via the `.xrs` accessor.",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "jastfcpb3i",
+   "source": "# Accessor on a DataArray\nsmall = big.xrs.preview(width=500).compute()\nprint(f\"DataArray accessor: {small.shape}\")\n\n# Accessor on a Dataset\nds = xr.Dataset({\"elevation\": big, \"slope_proxy\": big * 0.1})\nsmall_ds = ds.xrs.preview(width=500)\nfor name, var in small_ds.data_vars.items():\n    print(f\"Dataset var '{name}': {var.shape}\")",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "code",
+   "id": "f2s7vgc81u5",
+   "source": "client.close()\ncluster.close()",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.10.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}