Raindrop Trace

Overview of the elevation-based raindrop trace algorithm used by the NLDI pygeoapi processing services.

Overview

The raindrop trace algorithm is an elevation-driven method that determines
the path a drop of water would take from a given coordinate to the nearest valid
flowline. This algorithm is implemented in the NLDI using Python packages
(nldi-flowtools and nldi-xstool) and is exposed as a pygeoapi OGC API process.

The algorithm plays a central role in:

  • The hydrolocation endpoint
  • Basin generation workflows
  • Standalone pygeoapi processing services

How the Algorithm Works

When a point is provided to the raindrop trace process:

  1. Elevation data is sampled around the input coordinate.
  2. The algorithm follows the direction of steepest descent downstream.
  3. The trace continues until it intersects a valid NHDPlusV2 flowline.
  4. The resulting intersection location becomes the hydrologic reference point.

This provides hydrologically correct snapping, especially in locations where a
coordinate is closer to a tributary in Euclidean space but hydrologically
belongs on a larger mainstem.

Relationship to Hydrolocation

The NLDI hydrolocation endpoint behaves as follows:

  • If the given point lies within 200 meters of a flowline, it is snapped directly.
  • If not, the raindrop trace algorithm determines the downstream path to the
    appropriate flowline.

This ensures that hydrolocations are always associated with the correct catchment
and are not misassigned to nearby but hydrologically unrelated tributaries.

Use in Basin Delineation

For basin computation, raindrop trace provides the precise starting location
along a flowline that defines the downstream limit of the basin.
This starting point is then used by the split catchment algorithm and upstream
catchment accumulation to construct a custom drainage basin.

Figures Referenced in Source Material

The blog post references several illustrative images:

  • map_base.png — context map showing a drainage basin
  • basin_zoom.png — example of a raindrop trace intersecting a flowline

These images must be added manually to the Hugo static directory in final site assembly.

Notes & TODOs

  • TODO: Add parameter specifications (coordinate input, buffer behavior, SRID).
  • TODO: Document typical failure cases (e.g., point outside DEM coverage).
  • TODO: Add usage examples once the Python process endpoints are finalized.