Add terrain metrics module: TRI, TPI, and Roughness (#919)

Implement three widely-used terrain morphometry metrics as 3×3 focal
window operations on elevation values (no cellsize needed):

- TRI (Terrain Ruggedness Index) — Riley et al. 1999
- TPI (Topographic Position Index) — Weiss 2001
- Roughness — GDAL definition (max - min in 3×3 window)

All three support four backends (numpy, cupy, dask+numpy, dask+cupy),
boundary modes (nan, nearest, reflect, wrap), and Dataset input via
@supports_dataset. NaN propagates through all kernels for consistency
between numpy and dask paths (standard GDAL behavior).

Author: brendancol

README.md

@@ -227,8 +227,11 @@ In the GIS world, rasters are used for representing continuous phenomena (e.g. e
 | [Aspect](xrspatial/aspect.py) | Computes downslope direction of each cell in degrees | ✅️ | ✅️ | ✅️ | ✅️ |
 | [Curvature](xrspatial/curvature.py) | Measures rate of slope change (concavity/convexity) at each cell | ✅️ |✅️ |✅️ | ✅️  |
 | [Hillshade](xrspatial/hillshade.py) | Simulates terrain illumination from a given sun angle and azimuth | ✅️ | ✅️ | ✅️ | ✅️ |
+| [Roughness](xrspatial/terrain_metrics.py) | Computes local relief as max minus min elevation in a 3×3 window | ✅️ | ✅️ | ✅️ | ✅️ |
 | [Slope](xrspatial/slope.py) | Computes terrain gradient steepness at each cell in degrees | ✅️  | ✅️  | ✅️ | ✅️  |
 | [Terrain Generation](xrspatial/terrain.py) | Generates synthetic terrain elevation using fractal noise | ✅️ | ✅️ | ✅️ | ✅️ |
+| [TPI](xrspatial/terrain_metrics.py) | Computes Topographic Position Index (center minus mean of neighbors) | ✅️ | ✅️ | ✅️ | ✅️ |
+| [TRI](xrspatial/terrain_metrics.py) | Computes Terrain Ruggedness Index (local elevation variation) | ✅️ | ✅️ | ✅️ | ✅️ |
 | [Viewshed](xrspatial/viewshed.py) | Determines visible cells from a given observer point on terrain | ✅️ | ✅️ | ✅️ | ✅️ |
 | [Min Observable Height](xrspatial/experimental/min_observable_height.py) | Finds the minimum observer height needed to see each cell *(experimental)* | ✅️ | | | |
 | [Perlin Noise](xrspatial/perlin.py) | Generates smooth continuous random noise for procedural textures | ✅️ | ✅️ | ✅️ | ✅️ |

benchmarks/benchmarks/terrain_metrics.py

@@ -0,0 +1,27 @@
+from xrspatial import tri, tpi, roughness
+
+from .common import Benchmarking
+
+
+class TRI(Benchmarking):
+    def __init__(self):
+        super().__init__(func=tri)
+
+    def time_tri(self, nx, type):
+        return self.time(nx, type)
+
+
+class TPI(Benchmarking):
+    def __init__(self):
+        super().__init__(func=tpi)
+
+    def time_tpi(self, nx, type):
+        return self.time(nx, type)
+
+
+class Roughness(Benchmarking):
+    def __init__(self):
+        super().__init__(func=roughness)
+
+    def time_roughness(self, nx, type):
+        return self.time(nx, type)

xrspatial/__init__.py

@@ -36,6 +36,9 @@
 from xrspatial.surface_distance import surface_direction  # noqa
 from xrspatial.surface_distance import surface_distance  # noqa
 from xrspatial.terrain import generate_terrain  # noqa
+from xrspatial.terrain_metrics import roughness  # noqa
+from xrspatial.terrain_metrics import tpi  # noqa
+from xrspatial.terrain_metrics import tri  # noqa
 from xrspatial.polygonize import polygonize  # noqa
 from xrspatial.viewshed import viewshed  # noqa
 from xrspatial.zonal import apply as zonal_apply  # noqa

xrspatial/accessor.py

@@ -39,6 +39,20 @@ def curvature(self, **kwargs):
         from .curvature import curvature
         return curvature(self._obj, **kwargs)
 
+    # ---- Terrain Metrics ----
+
+    def tri(self, **kwargs):
+        from .terrain_metrics import tri
+        return tri(self._obj, **kwargs)
+
+    def tpi(self, **kwargs):
+        from .terrain_metrics import tpi
+        return tpi(self._obj, **kwargs)
+
+    def roughness(self, **kwargs):
+        from .terrain_metrics import roughness
+        return roughness(self._obj, **kwargs)
+
     def viewshed(self, x, y, **kwargs):
         from .viewshed import viewshed
         return viewshed(self._obj, x, y, **kwargs)
@@ -221,6 +235,20 @@ def curvature(self, **kwargs):
         from .curvature import curvature
         return curvature(self._obj, **kwargs)
 
+    # ---- Terrain Metrics ----
+
+    def tri(self, **kwargs):
+        from .terrain_metrics import tri
+        return tri(self._obj, **kwargs)
+
+    def tpi(self, **kwargs):
+        from .terrain_metrics import tpi
+        return tpi(self._obj, **kwargs)
+
+    def roughness(self, **kwargs):
+        from .terrain_metrics import roughness
+        return roughness(self._obj, **kwargs)
+
     # ---- Classification ----
 
     def natural_breaks(self, **kwargs):