priority_flow.stream_traverse
=============================

.. py:module:: priority_flow.stream_traverse

.. autoapi-nested-parse::

   Stream Traverse functions for PriorityFlow.

   Line-by-line translation of `Stream_Traverse.R` (StreamTraverse) from the
   PriorityFlow R package.

   This processes stream networks by walking upstream on D4 neighbors in a river
   mask. Where no D4 neighbors exist, it looks for D8 neighbors and creates D4
   bridges to these diagonal cells.



Functions
---------

.. autoapisummary::

   priority_flow.stream_traverse.stream_traverse


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

.. py:function:: stream_traverse(dem: numpy.ndarray, mask: numpy.ndarray, queue: numpy.ndarray, marked: numpy.ndarray, step: Optional[numpy.ndarray] = None, direction: Optional[numpy.ndarray] = None, basins: Optional[numpy.ndarray] = None, d4: Tuple[int, int, int, int] = (1, 2, 3, 4), printstep: bool = False, epsilon: float = 0.0) -> Dict[str, numpy.ndarray]

   DEM processing of stream networks.

   Function to process stream networks walking upstream on d4 neigbors
   in a river mask. Where no D4 neigbhors exist it looks for d8 neigbors
   and creates d4 bridges to these diagonal cells.

   :param dem: Digital Elevation Model matrix (nx x ny).
   :type dem: np.ndarray
   :param mask: Mask with zeros for non-river cells and 1 for river cells.
   :type mask: np.ndarray
   :param queue: Priority queue to start from; columns: x (row), y (col), elevation.
   :type queue: np.ndarray
   :param marked: Matrix of which cells have been marked already.
   :type marked: np.ndarray
   :param step: Matrix of the step number for processed cells. Defaults to zeros.
   :type step: np.ndarray, optional
   :param direction: Matrix of flow directions for processed cells. Defaults to NaN.
   :type direction: np.ndarray, optional
   :param basins: Matrix of basin numbers (e.g., from InitQueue). If provided, every
                  newly added cell inherits the basin of the cell that adds it.
   :type basins: np.ndarray, optional
   :param d4: D4 direction numbering (down, left, up, right). Default (1,2,3,4).
   :type d4: tuple of int, optional
   :param printstep: If True, print step number and queue size.
   :type printstep: bool, optional
   :param epsilon: Amount to add to filled areas to avoid creating flats.
   :type epsilon: float, optional

   :returns: Dictionary with keys: "dem", "mask", "marked", "step", "direction",
             and "basins".
   :rtype: Dict[str, np.ndarray]