priority_flow.peak_distance
===========================

.. py:module:: priority_flow.peak_distance

.. autoapi-nested-parse::

   Peak Distance functions for PriorityFlow.

   This module provides functions to calculate the maximum and minimum distance
   from headwater cells to topographic peaks using a topological sorting approach.



Functions
---------

.. autoapisummary::

   priority_flow.peak_distance.peak_dist


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

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

   Calculate distance to topographic peaks.

   Calculates the maximum and minimum distance from a headwater cell to
   topographic peaks using a topological sorting approach. This function
   identifies headwater cells and propagates distance information downstream
   following flow directions.

   NOTE: This function has not yet been tested and is not fully implemented.

   :param direction: Flow direction matrix
   :type direction: np.ndarray
   :param mask: Processing mask. Defaults to processing everything
   :type mask: np.ndarray, optional
   :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: Whether to print progress information. Defaults to False
   :type printflag: bool, optional

   :returns: A dictionary containing:
             - 'mindist': Matrix containing the minimum distance from headwaters to each cell
             - 'maxdist': Matrix containing the maximum distance from headwaters to each cell
   :rtype: Dict[str, np.ndarray]

   .. rubric:: Notes

   This function implements a distance calculation algorithm that:
   1. Identifies headwater cells (cells with no upstream neighbors)
   2. Uses topological sorting to process cells in correct order
   3. Propagates distance information downstream following flow directions
   4. Tracks both minimum and maximum distances from headwaters

   The algorithm handles:
   - Border detection and processing
   - D4 neighbor connectivity
   - Upstream neighbor counting
   - Topological sorting for correct distance propagation
   - Masked area handling