pycroglia.core.skeletonize package

Subpackages

Submodules

class pycroglia.core.skeletonize.msfm.DerivativeResult(tm=array([0., 0., 0., 0.]), order=array([0, 0, 0, 0], dtype=uint8))[source]

Bases: object

Container for derivative results in MSFM2D.

Parameters:
order: ndarray[tuple[int, ...], dtype[uint8]] = array([0, 0, 0, 0], dtype=uint8)
tm: ndarray = array([0., 0., 0., 0.])
class pycroglia.core.skeletonize.msfm.FirstOrderStencil(t, i, j, frozen)[source]

Bases: object

First-order stencil for computing derivatives in the MSFM2D algorithm.

Parameters:
calculate_derivative()[source]

Compute first-order derivatives for the stencil.

Returns:

Contains travel time estimates (tm) and their corresponding derivative order flags (order).

Return type:

DerivativeResult

class pycroglia.core.skeletonize.msfm.SecondOrderStencil(first_order, order, t, i, j, frozen)[source]

Bases: object

Second-order stencil for refining derivatives in the MSFM2D algorithm.

Parameters:
calculate_derivative()[source]

Compute second-order derivatives, refining first-order estimates.

Returns:

Contains refined travel time estimates (tm) and updated derivative order flags (order).

Return type:

DerivativeResult

pycroglia.core.skeletonize.msfm.bounds_check(dims, i, j)[source]

Check if a 2D index is inside array bounds.

Parameters:

  • dims (Tuple[int, ...]) – Shape of the 2D array (rows, cols).

  • i (int) – Row index.

  • j (int) – Column index.

Returns:

True if (i, j) is within bounds, False otherwise.

Return type:

bool

Raises:

AssertionError – If dims is not 2D.

pycroglia.core.skeletonize.msfm.is_frozen2d(i, j, frozen)[source]

Check if a pixel is frozen in the fast marching method.

Parameters:

  • i (int) – Row index.

  • j (int) – Column index.

  • frozen (np.ndarray) – Boolean or binary mask where 1 indicates frozen.

Returns:

True if frozen[i, j] == 1, False otherwise.

Return type:

bool

pycroglia.core.skeletonize.msfm.msfm2d(speed_image, source_points, use_second=True, use_cross=True, skeletonize=False)[source]

Calculates the shortest distance from a list of points to all other pixels in an image using the Multistencil Fast Marching Method (MSFM).

This function implements the MSFM algorithm, which computes distance maps more accurately than the standard Fast Marching Method by incorporating second-order derivatives and cross-neighbor stencils.

Parameters:

  • speed_image (np.ndarray) – The speed function image. All values

  • zero (must be strictly greater than)

  • negative (any values are zero or)

  • be (those regions will never)

  • reached (i.e., infinite time)

  • source_points (np.ndarray) – A list of starting points with

  • shape (N, 2)

  • zero. (distance is initialized to)

  • use_second (bool, optional) – If True, the method will use both

  • True. (computations. Defaults to)

  • use_cross (bool, optional) – If True, the method will include

  • diagonal (cross)

  • True.

  • skeletonize (bool, optional) – If True, also returns a

  • skeletonization (Euclidean distance image (used in)

  • False. (contexts). Defaults to)

Returns:

A distance image T of the same shape as speed_image, where each pixel holds the shortest distance from any source point. If skeletonize is True, also returns a second image with Euclidean distances.

Return type:

np.ndarray or Tuple[np.ndarray, np.ndarray]

pycroglia.core.skeletonize.msfm.roots(coeffs)[source]

Compute roots of a quadratic equation with MSFM2D logic.

Solves the polynomial:

a * x^2 + b * x + c = 0

If a == 0, falls back to a linearized solution. The discriminant is clamped to non-negative values to avoid NaN results. Matches custom matlab implementation. :param coeffs: Coefficients [a, b, c]. :type coeffs: np.ndarray

Returns:

Array of two roots. May contain np.inf if denominator is zero.

Return type:

np.ndarray

Parameters:

coeffs (ndarray)

class pycroglia.core.skeletonize.shortest_path.ShortestPath(stepper_type=StepperType.RK4, step_size=0.5)[source]

Bases: object

Traces the shortest path in a 2D or 3D distance map using numerical integration.

This class supports path tracing via numerical integration methods such as: - Runge-Kutta 4th order (RK4) - Euler’s method - Simple gradient descent

The tracing starts from a given point and optionally stops early if a specified target (source) point is reached within a threshold distance.

Parameters:
type

The integration method to use.

Type:

StepperType

step_size

The step size used in the integration process.

Type:

float

calculate(distance_map, start_point, source_point=None)[source]

Traces the shortest path from a starting point in a 2D or 3D distance map.

This function iteratively follows the gradient of the distance map, using the selected stepping method to trace a path. If a source_point is given, the path terminates early if it gets sufficiently close to any source point.

Parameters:

  • distance_map (np.ndarray) – A 2D or 3D distance field array.

  • start_point (np.ndarray) – A point [x, y] or [x, y, z] indicating where to start the path.

  • source_point (np.ndarray | None, optional) – An array of shape (N, D) where each row is a source point in the same dimension as start_point. If not provided, the path will be traced until it reaches a boundary or stagnates.

Returns:

  • A NumPy array of shape (M, D) representing the traced shortest path. Each row is a point along the path.

  • A boolean flag indicating whether the path failed to reach a source point. If True, it did not reach any source point (e.g. due to early stop or divergence).

Return type:

tuple[np.ndarray, bool]

pycroglia.core.skeletonize.skeleton.skeleton(image, stepper_type=StepperType.RK4)[source]

Computes the skeleton (centerlines) of a 2D or 3D binary object using the Multistencil Fast Marching (MSFM) distance transform.

This function returns subvoxel-accurate centerlines of the object by repeatedly tracing shortest paths from medial points to the object’s boundary.

Parameters:

  • binary_image (np.ndarray) – A 2D or 3D binary image or volume representing the object.

  • stepper_type (factory.StepperType) – Algorithm used for raytracing.

  • image (ndarray)

Returns:

A list of (N x D) arrays, each representing one skeleton branch.

D is 2 for 2D input and 3 for 3D input.

Return type:

list[np.ndarray]

Module contents