priority_flow.linear_distance
=============================

.. py:module:: priority_flow.linear_distance

.. autoapi-nested-parse::

   Linear Distance functions for PriorityFlow.

   This module provides functions to calculate the minimum linear distance between
   every point in a 2D array and a mask of target points using a step-by-step
   distance checking algorithm.



Functions
---------

.. autoapisummary::

   priority_flow.linear_distance.lin_dist


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

.. py:function:: lin_dist(target_points: numpy.ndarray, mask: Optional[numpy.ndarray] = None, cell_size: float = 1.0, max_dist: Optional[float] = None, printflag: bool = False) -> numpy.ndarray

   Calculate the minimum linear distance from a feature set.

   Calculates the minimum linear distance between every point in a 2D array
   and a mask of target points. Note that this function assumes dx=dy, i.e.,
   square grid cells. If this is not the case, it will not work correctly.

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

   :param target_points: Matrix with a value of 1 for all cells that you would like to calculate
                         the distance to and 0 for all other cells
   :type target_points: np.ndarray
   :param mask: Processing mask. Defaults to processing everything
   :type mask: np.ndarray, optional
   :param cell_size: The size of a grid cell. Note that this function assumes dx=dy, i.e.,
                     square grid cells. Defaults to 1.0
   :type cell_size: float, optional
   :param max_dist: Maximum distance to check. All cells with no distance found <= max_dist
                    will be assigned max_dist. If None, checks out to the total size of the domain
   :type max_dist: float, optional
   :param printflag: Whether to print progress information. Defaults to False
   :type printflag: bool, optional

   :returns: Matrix containing the minimum distance from each cell to the nearest target point.
             Cells outside the mask are assigned NaN.
   :rtype: np.ndarray

   .. rubric:: Notes

   This function implements a step-by-step distance checking algorithm that:
   1. Creates an ordered list of distance steps and rotations to check
   2. Iteratively checks each distance incrementally
   3. Uses array shifting to efficiently count target points at each distance
   4. Assigns distances to cells as they are found
   5. Continues until all cells have been assigned distances or max_dist is reached

   The algorithm handles:
   - Square grid cells (dx = dy)
   - Configurable maximum distance limits
   - Efficient array operations for distance checking
   - Mask-based domain processing
   - Progressive distance assignment

   The function assumes square grid cells and uses Euclidean distance calculations.
   For non-square grids, results may be incorrect.