Usage
=====

NLDI Flowtools provides two tools: **Split Catchment** for basin delineation
and **Flow Trace** for raindrop path tracing. Both accept WGS 84
longitude/latitude coordinates and return GeoJSON FeatureCollections.

.. code-block:: python

   from nldi_flowtools.nldi_flowtools import splitcatchment, flowtrace

.. tip::

   When delineating a point on a stream, run it through ``flowtrace`` first to
   snap the point to the flowline. Use the returned intersection point as input
   to ``splitcatchment`` for the most accurate basin boundary.


Flow Trace
----------

Traces the raindrop path from an input point downhill along a 30m flow
direction grid until it intersects an NHD flowline. Returns the traced path
and the intersected stream segment.

Parameters
^^^^^^^^^^

.. list-table::
   :widths: 15 10 75
   :header-rows: 1

   * - Name
     - Type
     - Description
   * - ``lon``
     - float
     - Longitude in WGS 84 decimal degrees.
   * - ``lat``
     - float
     - Latitude in WGS 84 decimal degrees.
   * - ``direction``
     - str
     - Which portion of the intersected flowline to return:
       ``"up"`` (upstream), ``"down"`` (downstream), or ``"none"`` (entire segment).

Returns
^^^^^^^

A GeoJSON FeatureCollection with two features:

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Feature ID
     - Description
   * - ``upstreamFlowline`` / ``downstreamFlowline`` / ``nhdFlowline``
     - The NHD stream segment (varies by ``direction``). Properties include
       ``comid``, ``gnis_name``, ``reachcode``, ``measure``,
       ``intersection_point``, and ``raindrop_pathDist``.
   * - ``raindropPath``
     - The traced flow path from the input point to the stream.

Examples
^^^^^^^^

Downstream trace:

.. code-block:: python

   flowtrace(-93.17298889291125, 41.99318001025908, "down")

.. image:: images/flowtrace1.png
   :width: 400

Upstream trace:

.. code-block:: python

   flowtrace(-93.17298889291125, 41.99318001025908, "up")

.. image:: images/flowtrace3.png
   :width: 400


Algorithm Details
^^^^^^^^^^^^^^^^^

- The raindrop path follows a 30m NHDPlus V2 flow direction grid from the
  query point downhill to an NHD flowline.
- The intersection point is constrained to a flow accumulation cell value of
  900 or greater, ensuring the trace lands on a meaningful stream cell.
- If the trace extends beyond the local catchment before reaching a flowline,
  an additional NLDI query fetches the downstream catchment and flowline data
  automatically.


Split Catchment
---------------

Identifies the NHD catchment containing a point and delineates the upstream
contributing area. Can return either the local split portion or the full
upstream drainage basin.

Parameters
^^^^^^^^^^

.. list-table::
   :widths: 15 10 75
   :header-rows: 1

   * - Name
     - Type
     - Description
   * - ``lon``
     - float
     - Longitude in WGS 84 decimal degrees.
   * - ``lat``
     - float
     - Latitude in WGS 84 decimal degrees.
   * - ``upstream``
     - bool
     - ``True``: return the full upstream drainage basin (if the point is on a
       flowline). ``False``: return only the local split catchment.
   * - ``simplified``
     - bool
     - ``True``: request a simplified upstream basin geometry from NLDI.
       ``False``: request the full-resolution geometry.

Returns
^^^^^^^

A GeoJSON FeatureCollection with two features:

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Feature ID
     - Description
   * - ``catchment``
     - The local NHD catchment polygon. Includes a ``catchmentID`` property.
   * - ``splitCatchment``
     - The portion of the catchment upstream of the point
       (returned when ``upstream=False``).
   * - ``drainageBasin``
     - The full upstream drainage basin
       (returned when ``upstream=True`` and the point is on a flowline).

Examples
^^^^^^^^

Full upstream basin:

.. code-block:: python

   splitcatchment(-93.02933761928982, 41.79037842455216, True, False)

.. image:: images/splitcatchment1.png
   :width: 400

Local split catchment only:

.. code-block:: python

   splitcatchment(-93.02933761928982, 41.79037842455216, False, False)

.. image:: images/splitcatchment2.png
   :width: 400

Notes
^^^^^

- Split Catchment does not snap the input point to the NHD flowline. For
  stream-based delineations, use ``flowtrace`` first to get the intersection
  point, then pass that to ``splitcatchment``.
- The ``simplified`` parameter only affects the upstream basin geometry
  requested from NLDI. The local split catchment is always full-resolution.