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

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