Add from_template(): empty study-area DataArrays for common regions (#3484) (#3487)

* Add from_template() study-area grid factory (#3484)

New xrspatial.templates module with from_template(name), exported at the
top level. Resolves curated region names (conus -> Albers EPSG:5070, nyc,
europe, world, ...) and ISO-3166 / GADM alpha-3 country codes (EPSG:4326)
to an empty NaN-filled DataArray that obeys the array contract. Supports
numpy, dask+numpy, cupy, and dask+cupy backends. Country bounding boxes
derived from Natural Earth 50m admin_0 (public domain).

* Add templates reference docs and README feature row (#3484)

* Add Templates user guide notebook (#3484)

* Address review: explicit dask+cupy meta, doc _MAX_CELLS, quiet slope test (#3484)

* Add preserve= to from_template: EPSG-coded projection by property (#3484)

preserve='area' returns an equal-area EPSG (curated national code, e.g.
5070/3035, or EPSG:8857 Equal Earth fallback); preserve='shape' returns a
conformal EPSG (the centroid's UTM/UPS zone, with curated overrides for
europe/world). attrs['crs'] stays an int EPSG. Reuses _edge_samples/
_transform_boundary to project the lon/lat bbox and query_utm_crs_info for
the zone; requires pyproj. distance/direction are not offered (no EPSG-coded
equidistant/azimuthal projections exist).

* Document preserve= in README and user guide notebook (#3484)

* Clamp world preserve-path latitude to +/-85 so shape (Mercator) doesn't diverge (#3484)

Author: brendancol

README.md

@@ -150,7 +150,7 @@ Each cell shows the **feature tier** for that function on that backend (see [iss
 
 ✅ stable · 🔼 advanced · 🧪 experimental · 🔧 internal · 🚫 unsupported
 
-[GeoTIFF / COG I/O](#geotiff--cog-io) · [Classification](#classification) · [Diffusion](#diffusion) · [Focal](#focal) · [Morphological](#morphological) · [Fire](#fire) · [Multispectral](#multispectral) · [Multivariate](#multivariate) · [MCDA](#multi-criteria-decision-analysis-mcda) · [Pathfinding](#pathfinding) · [Proximity](#proximity) · [Reproject / Merge](#reproject--merge) · [Raster / Vector Conversion](#raster--vector-conversion) · [Surface](#surface) · [Hydrology](#hydrology) · [Flood](#flood) · [Interpolation](#interpolation) · [Dasymetric](#dasymetric) · [Zonal](#zonal) · [Utilities](#utilities)
+[GeoTIFF / COG I/O](#geotiff--cog-io) · [Classification](#classification) · [Diffusion](#diffusion) · [Focal](#focal) · [Morphological](#morphological) · [Fire](#fire) · [Multispectral](#multispectral) · [Multivariate](#multivariate) · [MCDA](#multi-criteria-decision-analysis-mcda) · [Pathfinding](#pathfinding) · [Proximity](#proximity) · [Reproject / Merge](#reproject--merge) · [Raster / Vector Conversion](#raster--vector-conversion) · [Surface](#surface) · [Hydrology](#hydrology) · [Flood](#flood) · [Interpolation](#interpolation) · [Dasymetric](#dasymetric) · [Zonal](#zonal) · [Templates](#templates) · [Utilities](#utilities)
 
 -------
 ### **GeoTIFF / COG I/O**
@@ -270,6 +270,14 @@ Built-in Numba JIT and CUDA projection kernels bypass pyproj for per-pixel coord
 
 -----------
 
+### **Templates**
+
+| 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 | ✅ | 🔼 | 🔼 | 🔼 |
+
+-----------
+
 ### **Surface**
 
 | Name | Description | Source | NumPy xr.DataArray | Dask xr.DataArray | CuPy GPU xr.DataArray | Dask GPU xr.DataArray |

docs/source/reference/index.rst

@@ -29,6 +29,7 @@ Reference
    reproject
    resample
    surface
+   templates
    terrain_metrics
    utilities
    zonal

docs/source/reference/templates.rst

@@ -0,0 +1,17 @@
+..  _reference.templates:
+
+*********
+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.
+
+From Template
+=============
+.. autosummary::
+    :toctree: _autosummary
+
+    xrspatial.templates.from_template