Document categorical rasterize: docstring + user guide section (#3482)

Author: brendancol

docs/source/user_guide/rasterize.ipynb

@@ -3,7 +3,7 @@
   {
    "cell_type": "markdown",
    "id": "jb1yj58wq4q",
-   "source": "## Rasterize\n\n`xrspatial.rasterize` converts vector geometries (polygons, lines, points) into a 2D `xr.DataArray`. No GDAL dependency required.\n\nThis guide covers:\n- [Basic rasterization](#Basic-rasterization) -- polygons, lines, and points\n- [Merge modes](#Merge-modes) -- controlling how overlapping geometries combine\n- [Custom merge functions](#Custom-merge-functions) -- user-defined numba-jitted merge logic\n- [Dask parallel rasterization](#Dask-parallel-rasterization) -- tile-based output chunking",
+   "source": "## Rasterize\n\n`xrspatial.rasterize` converts vector geometries (polygons, lines, points) into a 2D `xr.DataArray`. No GDAL dependency required.\n\nThis guide covers:\n- [Basic rasterization](#Basic-rasterization) -- polygons, lines, and points\n- [Categorical columns](#Categorical-columns) -- burn string/categorical labels, readable in QGIS\n- [Merge modes](#Merge-modes) -- controlling how overlapping geometries combine\n- [Custom merge functions](#Custom-merge-functions) -- user-defined numba-jitted merge logic\n- [Dask parallel rasterization](#Dask-parallel-rasterization) -- tile-based output chunking",
    "metadata": {}
   }
  ],

examples/user_guide/28_Rasterize.ipynb

@@ -18,20 +18,21 @@
     "### What you'll build\n",
     "\n",
     "1. Rasterize land-use zones with the `.xrs` accessor\n",
-    "2. Handle overlapping polygons and interior holes\n",
-    "3. Burn lines and points into a raster\n",
-    "4. Compare merge modes for overlapping features\n",
-    "5. Write a custom numba merge function\n",
-    "6. Use multi-column properties for density mapping\n",
-    "7. Run Dask parallel rasterization\n",
-    "8. Combine rasterization with zonal statistics\n",
-    "9. Compare default vs. `all_touched` rasterization\n",
-    "10. Use the standalone `rasterize()` function with geometry pairs\n",
+    "2. Burn a string or categorical column into a labeled raster\n",
+    "3. Handle overlapping polygons and interior holes\n",
+    "4. Burn lines and points into a raster\n",
+    "5. Compare merge modes for overlapping features\n",
+    "6. Write a custom numba merge function\n",
+    "7. Use multi-column properties for density mapping\n",
+    "8. Run Dask parallel rasterization\n",
+    "9. Combine rasterization with zonal statistics\n",
+    "10. Compare default vs. `all_touched` rasterization\n",
+    "11. Use the standalone `rasterize()` function with geometry pairs\n",
     "\n",
     "![Rasterize preview](images/rasterize_preview.png)\n",
     "\n",
     "**Jump to a section:**\n",
-    "[Basic rasterization](#Basic-rasterization) | [Overlapping polygons](#Overlapping-polygons) | [Lines and points](#Lines-and-points) | [Merge modes](#Merge-modes) | [Custom merge](#Custom-merge) | [Multi-column properties](#Multi-column-properties) | [Dask parallel](#Dask-parallel) | [Zonal statistics](#Zonal-statistics) | [All touched](#All-touched) | [Standalone function](#Standalone-function)"
+    "[Basic rasterization](#Basic-rasterization) | [Categorical columns](#Categorical-columns) | [Overlapping polygons](#Overlapping-polygons) | [Lines and points](#Lines-and-points) | [Merge modes](#Merge-modes) | [Custom merge](#Custom-merge) | [Multi-column properties](#Multi-column-properties) | [Dask parallel](#Dask-parallel) | [Zonal statistics](#Zonal-statistics) | [All touched](#All-touched) | [Standalone function](#Standalone-function)"
    ]
   },
   {
@@ -120,6 +121,58 @@
     "plt.tight_layout()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "cat3482md",
+   "metadata": {},
+   "source": [
+    "## Categorical columns\n",
+    "\n",
+    "Pass a string or categorical column straight to `column=` and `rasterize` label-encodes it for you. Each distinct label becomes an integer code, the output is an `int32` band with a `-1` nodata value, and the label map rides along in `result.attrs['category_names']` (the list index is the pixel code). A matching `attrs['category_colors']` holds one RGBA per class.\n",
+    "\n",
+    "The plot below burns the land-use `label` column directly, with no manual encoding step."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "id": "cat3482code",
+   "metadata": {},
+   "source": [
+    "# Burn the string 'label' column directly -- no manual encoding\n",
+    "landcover = template.xrs.rasterize(gdf, column='label')\n",
+    "\n",
+    "names = landcover.attrs['category_names']\n",
+    "print('category_names:', names)\n",
+    "print('dtype:', landcover.dtype, '| nodata:', landcover.attrs['nodata'])\n",
+    "\n",
+    "# Colors the encoder assigned, scaled to 0-1 for matplotlib\n",
+    "colors = [tuple(c / 255 for c in rgba)\n",
+    "          for rgba in landcover.attrs['category_colors']]\n",
+    "cmap = ListedColormap(colors)\n",
+    "\n",
+    "fig, ax = plt.subplots(figsize=(10, 4))\n",
+    "landcover.where(landcover >= 0).plot.imshow(\n",
+    "    ax=ax, cmap=cmap, add_colorbar=False, vmin=0, vmax=len(names) - 1)\n",
+    "ax.legend(handles=[Patch(facecolor=colors[i], label=name)\n",
+    "                   for i, name in enumerate(names)],\n",
+    "          loc='upper right', fontsize=10, framealpha=0.9)\n",
+    "ax.set_title('Rasterized by string label')\n",
+    "ax.set_axis_off()\n",
+    "plt.tight_layout()"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cat3482alert",
+   "metadata": {},
+   "source": [
+    "<div class=\"alert alert-block alert-info\">\n",
+    "<b>Labels travel to QGIS.</b> Writing this result with <code>to_geotiff(landcover, 'landcover.tif')</code> also writes a <code>landcover.tif.aux.xml</code> sidecar holding the category names and colors. GDAL reads the sidecar, so the file opens in QGIS showing the class names instead of bare codes. Keep the sidecar next to the <code>.tif</code> when you move the file. <code>open_geotiff</code> restores <code>category_names</code> / <code>category_colors</code> back onto <code>attrs</code>.\n",
+    "</div>"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "wtyzoml2vc",
@@ -596,4 +649,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

xrspatial/rasterize.py

@@ -4189,6 +4189,18 @@ def rasterize(
         Name of the GeoDataFrame column whose values are burned into
         the raster.  Ignored when ``geometries`` is a list of pairs.
         Mutually exclusive with ``columns``.
+
+        A string or categorical column is label-encoded: each distinct
+        label gets an integer code ``0..N-1`` and the result is an
+        ``int32`` band with a ``-1`` nodata sentinel (unless ``dtype`` /
+        ``fill`` are passed explicitly).  Plain string/object columns are
+        ordered lexically; an existing pandas ``Categorical`` keeps its
+        declared order.  The label map is stored on the result as
+        ``attrs['category_names']`` (index == pixel code) plus an
+        auto-generated ``attrs['category_colors']`` (one RGBA per class).
+        ``to_geotiff`` writes these to a PAM ``<file>.aux.xml`` sidecar
+        so GDAL/QGIS display the class names, and ``open_geotiff`` reads
+        them back.
     columns : list of str, optional
         Names of multiple GeoDataFrame columns to pass as a properties
         array to the merge function.  Mutually exclusive with ``column``.