Add gradient/top-hat sections to morphology user guide notebook (#1025)

Author: brendancol

examples/user_guide/17_Morphological_Operators.ipynb

@@ -3,28 +3,12 @@
   {
    "cell_type": "markdown",
    "metadata": {},
-   "source": [
-    "# Xarray-Spatial Morphology: Erosion, dilation, opening, and closing\n",
-    "\n",
-    "Morphological operators filter rasters by sliding a structuring element (kernel) across the surface and picking the local minimum or maximum at each cell. They show up everywhere from cleaning noisy classification masks to smoothing elevation surfaces before further analysis. This notebook walks through the four operations in `xrspatial.morphology` on both continuous terrain and binary masks."
-   ]
+   "source": "# Xarray-Spatial Morphology\n\nMorphological operators filter rasters by sliding a structuring element (kernel) across the surface and picking the local minimum or maximum at each cell. They show up everywhere from cleaning noisy classification masks to smoothing elevation surfaces before further analysis. This notebook walks through the seven operations in `xrspatial.morphology` on both continuous terrain and binary masks."
   },
   {
    "cell_type": "markdown",
    "metadata": {},
-   "source": [
-    "### What you'll build\n",
-    "\n",
-    "1. Generate synthetic terrain and a hillshade base layer\n",
-    "2. Apply erosion and dilation to see how local min/max reshape the surface\n",
-    "3. Use opening and closing to selectively remove noise\n",
-    "4. Clean up a noisy binary classification mask\n",
-    "5. Compare square and circular structuring elements\n",
-    "\n",
-    "![Morphological operators preview](images/morphological_operators_preview.png)\n",
-    "\n",
-    "[Erosion and dilation](#Erosion-and-dilation) · [Opening and closing](#Opening-and-closing) · [Binary mask cleanup](#Binary-mask-cleanup) · [Circular structuring element](#Circular-structuring-element)"
-   ]
+   "source": "### What you'll build\n\n1. Generate synthetic terrain and a hillshade base layer\n2. Apply erosion and dilation to see how local min/max reshape the surface\n3. Use opening and closing to selectively remove noise\n4. Clean up a noisy binary classification mask\n5. Compare square and circular structuring elements\n6. Use gradient, white top-hat, and black top-hat to extract features\n\n![Morphological operators preview](images/morphological_operators_preview.png)\n\n[Erosion and dilation](#Erosion-and-dilation) · [Opening and closing](#Opening-and-closing) · [Binary mask cleanup](#Binary-mask-cleanup) · [Circular structuring element](#Circular-structuring-element) · [Gradient, white top-hat, black top-hat](#Gradient,-white-top-hat,-and-black-top-hat)"
   },
   {
    "cell_type": "markdown",
@@ -45,25 +29,7 @@
     }
    },
    "outputs": [],
-   "source": [
-    "%matplotlib inline\n",
-    "import numpy as np\n",
-    "import pandas as pd\n",
-    "import xarray as xr\n",
-    "\n",
-    "import matplotlib.pyplot as plt\n",
-    "from matplotlib.colors import ListedColormap\n",
-    "from matplotlib.patches import Patch\n",
-    "\n",
-    "import xrspatial\n",
-    "from xrspatial.morphology import (\n",
-    "    _circle_kernel,\n",
-    "    morph_closing,\n",
-    "    morph_dilate,\n",
-    "    morph_erode,\n",
-    "    morph_opening,\n",
-    ")"
-   ]
+   "source": "%matplotlib inline\nimport numpy as np\nimport pandas as pd\nimport xarray as xr\n\nimport matplotlib.pyplot as plt\nfrom matplotlib.colors import ListedColormap\nfrom matplotlib.patches import Patch\n\nimport xrspatial\nfrom xrspatial.morphology import (\n    _circle_kernel,\n    morph_black_tophat,\n    morph_closing,\n    morph_dilate,\n    morph_erode,\n    morph_gradient,\n    morph_opening,\n    morph_white_tophat,\n)"
   },
   {
    "cell_type": "markdown",
@@ -488,6 +454,23 @@
     "The square kernel reaches farther into the diagonal corners than the circular one, so it produces a slightly deeper erosion along ridges that run diagonally. The difference map and cross-section show that the disagreement concentrates on steep slopes where the extra corner pixels pull the minimum lower."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "source": "The gradient lights up wherever the terrain has steep transitions, making it a useful edge detector. The white top-hat pulls out peaks and ridges that are narrower than the 15x15 kernel, while the black top-hat does the same for small valleys and depressions. The bottom-right panel (white minus black) is positive on peaks and negative in valleys, giving a signed feature-size map.\n\nAll three results are non-negative by construction. The gradient equals the sum of the two top-hats (dilate - erode = (orig - opening) + (closing - orig) when opening <= orig <= closing), which you can verify in the cross-section.",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "source": "### References\n\n- [Erosion (morphology)](https://en.wikipedia.org/wiki/Erosion_(morphology)), Wikipedia\n- [Dilation (morphology)](https://en.wikipedia.org/wiki/Dilation_(morphology)), Wikipedia\n- [Opening (morphology)](https://en.wikipedia.org/wiki/Opening_(morphology)), Wikipedia\n- [Closing (morphology)](https://en.wikipedia.org/wiki/Closing_(morphology)), Wikipedia\n- [Morphological gradient](https://en.wikipedia.org/wiki/Morphological_gradient), Wikipedia\n- [Top-hat transform](https://en.wikipedia.org/wiki/Top-hat_transform), Wikipedia\n- [Mathematical morphology](https://en.wikipedia.org/wiki/Mathematical_morphology), Wikipedia\n- [Structuring element](https://en.wikipedia.org/wiki/Structuring_element), Wikipedia",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "source": "## Gradient, white top-hat, and black top-hat\n\nThese three operations are derived from the primitives above:\n\n| Operation | Formula | What it extracts |\n|-----------|---------|-----------------|\n| **Gradient** | dilate - erode | Edges and transitions |\n| **White top-hat** | original - opening | Bright features smaller than the kernel |\n| **Black top-hat** | closing - original | Dark features smaller than the kernel |\n\nEach is a single subtraction of two morphological results, so all four backends are supported automatically.",
+   "metadata": {}
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -567,4 +550,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 4
-}
+}