Fix review findings: proximity units, terrain dtype, missing pages (#1133)

- Proximity EUCLIDEAN returns coordinate-unit distances, not pixels
- Great-circle returns metres, not kilometres
- Terrain metrics output float64, not float32; drop Horn attribution
- Add admonitions to multispectral, zonal, and pathfinding pages
- Clarify haversine section title

Author: brendancol

docs/source/reference/multispectral.rst

@@ -4,6 +4,13 @@
 Multispectral
 *************
 
+.. note::
+
+   All spectral indices output **float32**.  Division by zero (e.g.
+   NDVI where NIR + Red = 0) produces NaN or inf silently.  Clean
+   the result with ``xr.where(np.isfinite(result), result, np.nan)``
+   if needed.
+
 Atmospherically Resistant Vegetation Index (ARVI)
 =================================================
 .. autosummary::

docs/source/reference/pathfinding.rst

@@ -4,6 +4,17 @@
 Pathfinding
 ***********
 
+.. caution::
+
+   A* allocates about 65 bytes per pixel and will raise ``MemoryError``
+   if the required memory exceeds 80 % of available RAM.  Use Dask or
+   set ``search_radius`` to limit the search area for large rasters.
+
+.. warning::
+
+   NaN and non-positive friction values are treated as impassable
+   barriers.  Cells must have finite positive friction to be traversable.
+
 A* Pathfinding
 ==============
 .. autosummary::

docs/source/reference/proximity.rst

@@ -6,10 +6,10 @@ Proximity
 
 .. warning::
 
-   ``proximity()`` returns distances in **pixel units** by default
-   (``distance_metric='EUCLIDEAN'``).  Multiply by cell size to get
-   real-world units, or use ``'GREAT_CIRCLE'`` for lat/lon data
-   (returns kilometres).
+   ``proximity()`` with ``distance_metric='EUCLIDEAN'`` (the default)
+   returns distances in the **coordinate units** of the DataArray.
+   With default integer indices this equals pixel counts.  Use
+   ``'GREAT_CIRCLE'`` for lat/lon data (returns metres).
 
 .. caution::
 

docs/source/reference/terrain_metrics.rst

@@ -6,9 +6,9 @@ Terrain Metrics
 
 .. note::
 
-   Terrain metrics use a 3x3 kernel and output **float32**.  Edge cells
-   are NaN by default.  These functions use the planar (Horn) algorithm
-   and assume the input is on a regular grid with uniform cell spacing.
+   Terrain metrics use a 3x3 neighbourhood and output **float64**.  Edge
+   cells are NaN.  These functions assume the input is on a regular grid
+   with uniform cell spacing.
 
 Roughness
 =========

docs/source/reference/zonal.rst

@@ -4,6 +4,11 @@
 Zonal
 *****
 
+.. note::
+
+   NaN values are excluded from all zonal aggregations.  A zone where
+   every cell is NaN returns NaN (not zero) for sum, mean, etc.
+
 Apply
 =====
 .. autosummary::

docs/source/user_guide/caveats.rst

@@ -118,41 +118,41 @@ the output cell is NaN.  The exact behaviour varies by function:
    ``boundary='reflect'`` if you need values at the edges.
 
 
-Proximity defaults to pixel units
-==================================
+Proximity distances depend on coordinate units
+================================================
 
 .. warning::
 
-   ``proximity()`` returns distances in **pixel units** when
-   ``distance_metric='EUCLIDEAN'`` (the default).  It does not automatically
-   convert to metres or kilometres.
+   ``proximity()`` with ``distance_metric='EUCLIDEAN'`` (the default)
+   computes distances in whatever units the DataArray's coordinates use.
+   If coordinates are default integer indices (0, 1, 2, ...), the result
+   is in pixel counts.  If coordinates are in metres (UTM), the result is
+   in metres.  If coordinates are in degrees, the result is in degrees.
 
-To get distances in real-world units with Euclidean mode, multiply the
-result by your cell size.  Or switch to ``distance_metric='GREAT_CIRCLE'``
-if your data is in degrees, which returns kilometres.
+Switch to ``distance_metric='GREAT_CIRCLE'`` for lat/lon data to get
+distances in **metres** (the radius used is 6 378 137 m).
 
 .. tip::
 
    .. code-block:: python
 
       from xrspatial.proximity import proximity
 
-      # Pixel-unit result
+      # EUCLIDEAN with default coords = pixel-count distances
       dist_px = proximity(raster)
 
-      # Convert to metres (assumes square cells)
-      cell_m = 30.0  # e.g. Landsat 30 m resolution
-      dist_m = dist_px * cell_m
+      # GREAT_CIRCLE with lat/lon coords = distances in metres
+      dist_m = proximity(raster, distance_metric='GREAT_CIRCLE')
 
 
-Haversine uses the semi-major axis
-====================================
+Great-circle distances assume sphere radius = semi-major axis
+==============================================================
 
 .. note::
 
    Great-circle distances in ``proximity()`` and ``surface_distance()``
-   use the WGS84 **semi-major axis** (6 378 137 m) as the Earth radius,
-   not the mean radius (6 371 km).
+   model the Earth as a sphere with radius = WGS84 semi-major axis
+   (6 378 137 m), not the mean radius (~6 371 km).
 
 The difference is about 0.1 %.  This is negligible for most use cases but
 worth knowing if you're comparing against a reference that uses the mean