spine.math.distance

Numba JIT compiled implementation of distance computation routines.

This module is entirely dedicated to 3D points, which is the core representation of objects targeted by this software package.

Functions

cdist(x1, x2[, metric_id, p])

Numba implementation of Euclidean scipy.spatial.distance.cdist(x, metric=p=2) in 3D.

chebyshev(x, y)

Compute the Chebyshev distance (Linf) between two 3D points.

cityblock(x, y)

Compute the cityblock distance (L1) between two 3D points.

closest_pair(x1, x2[, iterative, seed, ...])

Algorithm which finds the two points which are closest to each other from two separate sets.

closest_pair_legacy(x1, x2[, iterative, ...])

Legacy closest-pair implementation kept for model compatibility.

euclidean(x, y)

Compute the Euclidean distance (L2) between two 3D points.

farthest_pair(x[, iterative, metric_id, p])

Algorithm which finds the two points which are farthest from each other in a set, in the Euclidean sense.

get_metric_id(metric, p)

Checks on the metric name, returns an enumerated form of the metric.

minkowski(x, y, p)

Compute the Minkowski distance (Lp) between two 3D points.

pdist(x[, metric_id, p])

Numba implementation of scipy.spatial.distance.pdist(x, metric=metric, p=p) in 3D.

sqeuclidean(x, y)

Compute the squared Euclidean distance (L2) between two 3D points.
spine.math.distance.cityblock(x: ndarray, y: ndarray) → float[source]

Compute the cityblock distance (L1) between two 3D points.

Parameters:

  • x (np.ndarray) – (3,) Coordinates of the first point

  • y (np.ndarray) – (3,) Coordinates of the second point

Returns:

Cityblock distance

Return type:

float

spine.math.distance.euclidean(x: ndarray, y: ndarray) → float[source]

Compute the Euclidean distance (L2) between two 3D points.

Parameters:

  • x (np.ndarray) – (3,) Coordinates of the first point

  • y (np.ndarray) – (3,) Coordinates of the second point

Returns:

Euclidean distance

Return type:

float

spine.math.distance.sqeuclidean(x: ndarray, y: ndarray) → float[source]

Compute the squared Euclidean distance (L2) between two 3D points.

Parameters:

  • x (np.ndarray) – (3,) Coordinates of the first point

  • y (np.ndarray) – (3,) Coordinates of the second point

Returns:

Squared Euclidean distance

Return type:

float

spine.math.distance.minkowski(x: ndarray, y: ndarray, p: float) → float[source]

Compute the Minkowski distance (Lp) between two 3D points.

Parameters:

  • x (np.ndarray) – (3,) Coordinates of the first point

  • y (np.ndarray) – (3,) Coordinates of the second point

Returns:

Minkowski distance

Return type:

float

spine.math.distance.chebyshev(x: ndarray, y: ndarray) → float[source]

Compute the Chebyshev distance (Linf) between two 3D points.

Parameters:

  • x (np.ndarray) – (3,) Coordinates of the first point

  • y (np.ndarray) – (3,) Coordinates of the second point

Returns:

Chebyshev distance

Return type:

float

spine.math.distance.pdist(x: ndarray, metric_id: int = 2, p: float = 2.0) → ndarray[source]

Numba implementation of scipy.spatial.distance.pdist(x, metric=metric, p=p) in 3D.

Parameters:

  • x (np.ndarray) – (N, 3) array of point coordinates in the set

  • metric_id (int, default 2 (Euclidean)) – Distance metric enumerator

  • p (float, default 2.) – p-norm factor for the Minkowski metric, if used

Returns:

(N, N) array of pair-wise Euclidean distances

Return type:

np.ndarray

spine.math.distance.cdist(x1: ndarray, x2: ndarray, metric_id: int = 2, p: float = 2.0) → ndarray[source]

Numba implementation of Euclidean scipy.spatial.distance.cdist(x, metric=p=2) in 3D.

Parameters:

  • x1 (np.ndarray) – (N, 3) array of point coordinates in the first set

  • x2 (np.ndarray) – (M, 3) array of point coordinates in the second set

  • metric_id (int, default 2 (Euclidean)) – Distance metric enumerator

  • p (float, default 2.) – p-norm factor for the Minkowski metric, if used

Returns:

(N, M) array of pair-wise Euclidean distances

Return type:

np.ndarray

spine.math.distance.farthest_pair(x: ndarray, iterative: bool = False, metric_id: int = 2, p: float = 2.0) → tuple[int, int, float][source]

Algorithm which finds the two points which are farthest from each other in a set, in the Euclidean sense.

Two algorithms are available:

  • brute: computes all pairwise distances and uses argmax.

  • iterative: repeatedly jumps to the current farthest point until convergence. It is not exact, but it is fast.

Parameters:

  • x (np.ndarray) – (N, 3) array of point coordinates

  • iterative (bool) – If True, uses an iterative, fast approximation

  • metric_id (int, default 2 (Euclidean)) – Distance metric enumerator

  • p (float) – p-norm factor for the Minkowski metric, if used

Returns:

  • int – ID of the first point that makes up the pair

  • int – ID of the second point that makes up the pair

  • float – Distance between the two points

spine.math.distance.closest_pair(x1: ndarray, x2: ndarray, iterative: bool = False, seed: bool = True, metric_id: int = 2, p: float = 2.0) → tuple[int, int, float][source]

Algorithm which finds the two points which are closest to each other from two separate sets.

Two algorithms are available:

  • brute: computes all cross-distances and uses argmin.

  • iterative: repeatedly jumps to the current closest point until convergence. It is not exact, but it is fast.

Parameters:

  • x1 (np.ndarray) – (N, 3) array of point coordinates in the first set

  • x2 (np.ndarray) – (M, 3) array of point coordinates in the second set

  • iterative (bool) – If True, uses an iterative, fast approximation

  • seed (bool) – Whether or not to use the two farthest points in one of the two sets to seed the iterative algorithm

  • metric_id (int, default 2 (Euclidean)) – Distance metric enumerator

  • p (float, default 2.) – p-norm factor for the Minkowski metric, if used

Returns:

  • int – ID of the first point that makes up the pair

  • int – ID of the second point that makes up the pair

  • float – Distance between the two points

spine.math.distance.closest_pair_legacy(x1: ndarray, x2: ndarray, iterative: bool = False, seed: bool = True, metric_id: int = 2, p: float = 2.0) → tuple[int, int, float][source]

Legacy closest-pair implementation kept for model compatibility.

This preserves the historical iterative behavior, including the missing set switch after each closest-point update. New code should use closest_pair().