priority_flow.linear_distance

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

lin_dist(→ numpy.ndarray)

Calculate the minimum linear distance from a feature set.

Module Contents

priority_flow.linear_distance.lin_dist(target_points: numpy.ndarray, mask: numpy.ndarray | None = None, cell_size: float = 1.0, max_dist: float | None = None, printflag: bool = False) → numpy.ndarray[source]

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.

Parameters:

  • target_points (np.ndarray) – Matrix with a value of 1 for all cells that you would like to calculate the distance to and 0 for all other cells

  • mask (np.ndarray, optional) – Processing mask. Defaults to processing everything

  • cell_size (float, optional) – The size of a grid cell. Note that this function assumes dx=dy, i.e., square grid cells. Defaults to 1.0

  • max_dist (float, optional) – 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

  • printflag (bool, optional) – Whether to print progress information. Defaults to False

Returns:

Matrix containing the minimum distance from each cell to the nearest target point. Cells outside the mask are assigned NaN.

Return type:

np.ndarray

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.