Add major world cities as bounding-box templates in from_template

README.md

@@ -274,7 +274,7 @@ Built-in Numba JIT and CUDA projection kernels bypass pyproj for per-pixel coord
 
 | Name | Description | Source | NumPy xr.DataArray | Dask xr.DataArray | CuPy GPU xr.DataArray | Dask GPU xr.DataArray |
 |:----------:|:------------|:------:|:----------------------:|:--------------------:|:-------------------:|:------:|
-| [from_template](xrspatial/templates.py) | Empty study-area grid for a named region (CONUS, NYC, ...) or country code; `preserve='area'/'shape'` picks an EPSG projection by property | Custom | ✅ | 🔼 | 🔼 | 🔼 |
+| [from_template](xrspatial/templates.py) | Empty study-area grid for a named region (CONUS, NYC, ...), a world city (London, Tokyo, ... in its UTM zone) or country code; `preserve='area'/'shape'` picks an EPSG projection by property | Custom | ✅ | 🔼 | 🔼 | 🔼 |
 
 -----------
 

docs/source/reference/templates.rst

@@ -5,9 +5,11 @@ Templates
 *********
 
 Empty study-area grids you can start an analysis from. ``from_template`` turns
-a region name or country code into a NaN-filled :class:`xarray.DataArray` that
-follows the xarray-spatial array contract, so it feeds straight into the rest
-of the library.
+a region name, a world-city name, or a country code into a NaN-filled
+:class:`xarray.DataArray` that follows the xarray-spatial array contract, so it
+feeds straight into the rest of the library. Cities (national capitals, major
+regional metros, and recognizable US secondary cities) come back as a metro
+bounding box in their UTM zone.
 
 From Template
 =============

examples/user_guide/57_Templates.ipynb

@@ -836,6 +836,41 @@
     "</div>"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "city-templates-md",
+   "metadata": {},
+   "source": [
+    "## Major world cities\n",
+    "\n",
+    "Pass a city name and you get a metro-scale bounding box in that city's UTM zone\n",
+    "(a standard EPSG projection, not a custom one). Coverage is every national\n",
+    "capital, major regional metros worldwide, and a set of recognizable US\n",
+    "secondary cities (Austin, New Orleans, Nashville, ...). Names are lowercase;\n",
+    "where two cities share a name the larger keeps the bare name and the others\n",
+    "take an `_<iso2>` suffix (for example `hyderabad` vs `hyderabad_pk`)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "city-templates-code",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "tokyo = from_template(\"tokyo\")\n",
+    "print(\"crs:  \", tokyo.attrs[\"crs\"], \"-\", tokyo.attrs.get(\"grid_mapping_name\"))\n",
+    "print(\"shape:\", tokyo.shape, \"at\", tokyo.attrs[\"res\"], \"m\")\n",
+    "\n",
+    "# paint an east-west gradient so the metro extent is visible\n",
+    "xx = tokyo[\"x\"].broadcast_like(tokyo)\n",
+    "tokyo_painted = tokyo.copy(data=xx.values.astype(\"float32\"))\n",
+    "tokyo_painted.plot.imshow(size=6, aspect=tokyo.shape[1] / tokyo.shape[0],\n",
+    "                          cmap=\"cividis\", cbar_kwargs={\"label\": \"easting (m)\"})\n",
+    "plt.title(f\"Tokyo template (UTM, EPSG:{tokyo.attrs['crs']})\")\n",
+    "plt.gca().set_axis_off()"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "89e04cac",