Differentials#

The preferred public name is splineops.differentials.Differentials; the historical lowercase differentials name remains available. Scalar 2-D images and 3-D volumes are supported. The class computes differentials using cubic B-spline interpolation, including:

  • Gradient Magnitude - the rate of intensity change.

  • Gradient Direction - the 2-D orientation of maximum change.

  • Laplacian - the sum of second-order derivatives.

  • Largest Hessian Eigenvalue - the maximal curvature.

  • Smallest Hessian Eigenvalue - the minimal curvature.

  • Hessian Orientation - the 2-D principal direction of curvature.

run() returns a raw result and preserves the source array. Visualization normalization is opt-in through normalize=True and is rejected for angular outputs. Physical spacing contains one value per axis. gradient_components() returns derivatives in increasing axis order; hessian_components() uses packed upper-triangular order (00, 01, 11) in 2-D and (00, 01, 02, 11, 12, 22) in 3-D.

For changing arrays with fixed shape and spacing, DifferentialPlan computes gradient, Hessian, and Laplacian outputs through one per-call cached workspace. It accepts explicit spatial_axes for batch and channel arrays, independent gradient/hessian/laplacian selection, and exact structured DifferentialResult output buffers. Laplacian-only execution computes only diagonal second derivatives. Output buffers are prevalidated for shape, dtype, writability, and non-overlap before numerical work begins. The legacy Differentials object intentionally remains scalar.

class splineops.differentials.differentials.DifferentialResult(gradient: tuple[ndarray, ...] | None, hessian: tuple[ndarray, ...] | None, laplacian: ndarray | None)#

Bases: object

Multi-output result returned by DifferentialPlan.

Hessian entries use packed upper-triangular order: (00, 01, 11) in 2-D and (00, 01, 02, 11, 12, 22) in 3-D.

__init__(gradient: tuple[ndarray, ...] | None, hessian: tuple[ndarray, ...] | None, laplacian: ndarray | None) → None#
class splineops.differentials.differentials.DifferentialPlan(shape, spacing=None)#

Bases: object

Reusable shape/spacing contract for 2-D and 3-D spline derivatives.

__init__(shape, spacing=None)#
property retained_bytes#

Persistent numerical-array storage retained by the plan.

property configuration#

Copy of the fixed spatial derivative contract.

apply(image, *, gradient=True, hessian=True, laplacian=None, spatial_axes=None, out=None)#

Compute requested derivative families through one cached workspace.

spatial_axes selects the two or three dimensions represented by the plan. Unselected batch or channel slices are mathematically independent but execute together, and each returned component has the full input shape. laplacian=None follows hessian for backward compatibility. out must mirror the selected result families with exact-shape, exact-dtype arrays.

class splineops.differentials.differentials.Differentials(image, spacing=None)#

Bases: object

Class for computing image differentials using cubic B-spline interpolation.

This class provides methods to compute first- and second-order derivatives of a grayscale image by reconstructing the image as a continuous function using cubic B-spline interpolation. Supported operations include gradient magnitude, gradient direction, Laplacian, largest and smallest Hessian eigenvalues, and Hessian orientation.

GRADIENT_DIRECTION#

The gradient direction operation.

Type:

int

GRADIENT_MAGNITUDE#

The gradient magnitude operation.

Type:

int

HESSIAN_ORIENTATION#

The Hessian orientation operation.

Type:

int

LAPLACIAN#

The Laplacian operation.

Type:

int

LARGEST_HESSIAN#

The largest Hessian eigenvalue operation.

Type:

int

SMALLEST_HESSIAN#

The smallest Hessian eigenvalue operation.

Type:

int

FLT_EPSILON#

Constant for single precision floats.

Type:

float

__init__(image, spacing=None)#

Initialize a new differentials instance.

Parameters:

  • image (ndarray) – Input scalar image or volume as a 2D or 3D NumPy array.

  • spacing (tuple of float, optional) – Positive physical sample spacing for every axis. The default is unit spacing.

run(operation=None, *, normalize=False)#

Execute the selected differential operation on the image.

Parameters:

  • operation (int, optional) – Operation to perform. If None, the default operation (Laplacian) is used.

  • normalize (bool, optional) – If true, scale non-angular results to the interval [0, 1]. The default is false so the numerical API returns raw derivatives.

Returns:

A newly computed differential image. The source stored in image is not replaced, so repeated calls are independent.

Return type:

ndarray

horizontal_gradient()#

Return the derivative along increasing column coordinates.

vertical_gradient()#

Return the derivative along increasing row coordinates.

gradient_components()#

Return first derivatives in increasing axis order.

horizontal_hessian()#

Return the second derivative along column coordinates.

vertical_hessian()#

Return the second derivative along row coordinates.

cross_hessian()#

Return the mixed row-column second derivative.

hessian_components()#

Return packed upper-triangular Hessian components.

get_cross_hessian(image, tolerance)#

Compute the cross (mixed) Hessian term of the image.

Parameters:

  • image (ndarray) – Input image array.

  • tolerance (float) – Tolerance parameter for spline coefficient computation.

Returns:

Element-wise cross hessian.

Return type:

ndarray

get_horizontal_gradient(image, tolerance)#

Compute the horizontal gradient of the image.

Parameters:

  • image (ndarray) – Input image array.

  • tolerance (float) – Tolerance parameter for spline coefficient computation.

Returns:

Horizontal gradient of the image.

Return type:

ndarray

get_horizontal_hessian(image, tolerance)#

Compute the horizontal second derivative (Hessian) of the image.

Parameters:

  • image (ndarray) – Input image array.

  • tolerance (float) – Tolerance parameter for spline coefficient computation.

Returns:

Horizontal Hessian of the image.

Return type:

ndarray

get_vertical_gradient(image, tolerance)#

Compute the vertical gradient of the image.

Parameters:

  • image (ndarray) – Input image array.

  • tolerance (float) – Tolerance parameter for spline coefficient computation.

Returns:

Vertical gradient of the image.

Return type:

ndarray

get_vertical_hessian(image, tolerance)#

Compute the vertical second derivative (Hessian) of the image.

Parameters:

  • image (ndarray) – Input image array.

  • tolerance (float) – Tolerance parameter for spline coefficient computation.

Returns:

Vertical Hessian of the image.

Return type:

ndarray

anti_symmetric_fir_mirror_on_bounds(h, c)#

Apply an anti-symmetric FIR filter with mirror boundary extension.

Parameters:

  • h (ndarray) – Filter coefficients (expected length 2, with h[0] == 0.0).

  • c (ndarray) – Signal (or coefficient array) to be filtered.

Returns:

Filtered signal.

Return type:

ndarray

symmetric_fir_mirror_on_bounds(h, c)#

Apply a symmetric FIR filter with mirror boundary extension.

Parameters:

  • h (ndarray) – Filter coefficients (expected length 2).

  • c (ndarray) – Signal (or coefficient array) to be filtered.

Returns:

Filtered signal.

Return type:

ndarray

get_gradient(c)#

Compute the first derivative (gradient) of a 1D signal using an anti-symmetric filter.

Parameters:

c (ndarray) – 1D array of spline coefficients.

Returns:

Computed gradient of the input signal.

Return type:

ndarray

get_hessian(c)#

Compute the second derivative (Hessian) of a 1D signal using a symmetric filter.

Parameters:

c (ndarray) – 1D array of spline coefficients.

Returns:

Computed Hessian of the input signal.

Return type:

ndarray

get_spline_interpolation_coefficients(c, tolerance)#

Compute the cubic B-spline interpolation coefficients for a 1D signal.

This method adjusts the input signal c in place using a recursive scheme based on a cubic B-spline and a specified tolerance.

Parameters:

  • c (ndarray) – 1D array representing the signal to be interpolated.

  • tolerance (float) – Tolerance parameter controlling the trade-off between speed and accuracy.

get_initial_causal_coefficient_mirror_on_bounds(c, z, tolerance)#

Compute the initial causal coefficient for spline interpolation with mirror boundary conditions.

Parameters:

  • c (ndarray) – 1D array of spline coefficients.

  • z (float) – Pole of the filter.

  • tolerance (float) – Tolerance parameter to limit the recursion depth.

Returns:

The initial causal coefficient.

Return type:

float

get_initial_anti_causal_coefficient_mirror_on_bounds(c, z, tolerance)#

Compute the initial anti-causal coefficient for spline interpolation with mirror boundary conditions.

Parameters:

  • c (ndarray) – 1D array of spline coefficients.

  • z (float) – Pole of the filter.

  • tolerance (float) – Tolerance parameter.

Returns:

The initial anti-causal coefficient.

Return type:

float

gradient_magnitude()#

Compute the gradient magnitude of the image.

Returns:

Image representing the gradient magnitude.

Return type:

ndarray

gradient_direction()#

Compute the gradient direction of the image.

Returns:

Image representing the gradient direction (in radians).

Return type:

ndarray

laplacian()#

Compute the Laplacian of the image.

Returns:

Image representing the Laplacian.

Return type:

ndarray

largest_hessian()#

Compute the largest eigenvalue of the Hessian matrix of the image.

Returns:

Image representing the largest Hessian eigenvalue.

Return type:

ndarray

smallest_hessian()#

Compute the smallest eigenvalue of the Hessian matrix of the image.

Returns:

Image representing the smallest Hessian eigenvalue.

Return type:

ndarray

hessian_orientation()#

Compute the orientation of the Hessian of the image.

Returns:

Image representing the Hessian orientation (in radians).

Return type:

ndarray

splineops.differentials.differentials.differentials#

alias of Differentials