priority_flow.define_watershed
==============================

.. py:module:: priority_flow.define_watershed

.. autoapi-nested-parse::

   Define Watershed functions for PriorityFlow.

   This module provides functions to define the watershed (upstream area) from a point
   or set of outlet points based on the flow direction file.



Functions
---------

.. autoapisummary::

   priority_flow.define_watershed.delin_watershed


Module Contents
---------------

.. py:function:: delin_watershed(outlets: numpy.ndarray, direction: numpy.ndarray, d4: Tuple[int, int, int, int] = (1, 2, 3, 4), printflag: bool = False) -> Dict[str, numpy.ndarray]

   Function to define the watershed for a point or set of outlet points based on the flow direction file.

   NOTE: This function is not yet tested.

   :param outlets: x,y coordinates of the outlet points or points to mask upstream areas for.
                   This should be a 2D array with a separate row for each point.
   :type outlets: np.ndarray
   :param direction: Flow direction matrix
   :type direction: np.ndarray
   :param d4: Directional numbering system: down, left, top, right. Defaults to (1, 2, 3, 4)
   :type d4: Tuple[int, int, int, int], optional
   :param printflag: Optional flag to print out the number of cells in the queue during iterations.
                     Defaults to False
   :type printflag: bool, optional

   :returns: A dictionary containing:
             - 'watershed': Binary mask of the watershed area (1 for watershed cells, 0 otherwise)
             - 'xrange': Range of x coordinates covered by the watershed as numpy array [min_x, max_x]
             - 'yrange': Range of y coordinates covered by the watershed as numpy array [min_y, max_y]
   :rtype: Dict[str, np.ndarray]

   .. rubric:: Notes

   This function implements an upstream traversal algorithm that:
   1. Starts from specified outlet points
   2. Traverses upstream following flow directions
   3. Marks all cells that contribute flow to the outlet points
   4. Returns the complete watershed boundary and extent

   The algorithm uses a queue-based approach to efficiently process large watersheds.