pycroglia.core.skeletonize.raytracing package

Submodules

class pycroglia.core.skeletonize.raytracing.euler.Euler(step_size, gradient_volume)

Bases: Stepper

Euler integration stepper for gradient-based tracing.

This stepper implements the explicit Euler method to trace along the negative gradient of a distance map or potential field. It works in both 2D and 3D volumes.

Parameters:

• step_size (float)

• gradient_volume (ndarray)

step_size

The integration step size.

Type:

float

gradient_volume

The gradient field of the distance map. Shape is (…, dim), where dim is 2 or 3.

Type:

np.ndarray

step(start_point)

Performs one Euler ray tracing step in a 2D or 3D gradient field.

Parameters:

start_point (np.ndarray) – The starting position (2D or 3D float coordinates).

Returns:

New point after the Euler step. Returns [0, 0] or [0, 0, 0] if out of bounds.

Return type:

np.ndarray

class pycroglia.core.skeletonize.raytracing.factory.StepperType(value)

Bases: Enum

Enumeration of stepping strategies for skeleton path tracing.

This enum defines the available numerical methods or heuristics used by the stepper classes when following gradients through a distance map to extract skeleton paths.

RK4

Runge-Kutta 4th-order integration method. Provides high accuracy in tracing smooth paths at the cost of higher computation.

Type:

int

Euler

First-order Euler integration method. Simpler and faster than RK4, but less accurate and more prone to drift in noisy data.

Type:

int

Simple

A heuristic stepping method that moves to the neighboring pixel/voxel with the lowest value. Useful as a baseline or when accuracy is less critical.

Type:

int

Euler = 1

RK4 = 0

Simple = 2

pycroglia.core.skeletonize.raytracing.factory.make_stepper(distance_map, type=StepperType.RK4, step_size=0.5)

Create a stepper object for shortest-path tracing based on the specified method.

Parameters:

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

• type (StepperType) – The integration method to use. Options are: - StepperType.RK4: 4th-order Runge-Kutta integration. - StepperType.Euler: First-order Euler integration. - StepperType.Simple: Discrete descent using local minima.

• step_size (float) – The integration step size for RK4 or Euler methods.

Returns:

A stepper object (RK4, Euler, or Simple) with a .step(point, field, step_size) method.

Return type:

Stepper

class pycroglia.core.skeletonize.raytracing.rk4.RK4(step_size, gradient_volume)

Bases: Stepper

Runge-Kutta 4 (RK4) stepper for gradient-based tracing.

This stepper integrates along the negative gradient of a vector field using the fourth-order Runge-Kutta method. It provides more accurate tracing than Euler integration at the cost of additional interpolation.

Parameters:

• step_size (float)

• gradient_volume (ndarray)

step_size

Integration step size.

Type:

float

gradient_volume

Vector field with shape (…, dim),

Type:

np.ndarray

where dim is 2 or 3.

step(start_point)

Efficient single RK4 step in a 2D or 3D vector field.

Parameters:

• start_point (np.ndarray) – Start coordinate (x, y) or (x, y, z).

• gradient_volume (np.ndarray) – Vector field (H, W, 2) or (D, H, W, 3).

• step_size (float) – Step size for integration.

Returns:

New point after RK4 step, or zeros if outside domain.

Return type:

np.ndarray

class pycroglia.core.skeletonize.raytracing.simple.Simple(distance_map)

Bases: Stepper

Stepper implementation that selects the lowest-valued neighbor.

This class implements a simple stepping strategy for following the gradient in a distance map (2D or 3D). At each step, it searches in an expanding local neighborhood around a given start point and moves to the coordinate with the lowest distance-map value, if such a location exists.

Parameters:

distance_map (ndarray)

distance_map

The 2D or 3D distance map used to guide stepping.

Type:

np.ndarray

step(start_point)

Finds a lower pixel location in a local neighborhood.

This function searches within an expanding local neighborhood around a given start point in a 2D or 3D volume and returns the coordinates of the location with the lowest value, if one exists.

Parameters:

start_point (np.ndarray) – A 2D or 3D coordinate indicating the starting location in the volume.

Returns:

The coordinates of the new location with lower value if found;

otherwise, returns the original start point.

Return type:

np.ndarray

class pycroglia.core.skeletonize.raytracing.stepper.Stepper

Bases: ABC

Abstract base class for stepper strategies.

A stepper defines how to move from a given starting point in a distance map (2D or 3D). Different subclasses implement different stepping strategies (e.g., Simple, Euler, Runge-Kutta).

Subclasses must implement the step() method.

abstract step(start_point)

Compute the next point from a given starting location.

Parameters:

start_point (np.ndarray) – A 1D coordinate array (2D or 3D) indicating the current location.

Returns:

The next location as a coordinate array.

Return type:

np.ndarray

Module contents