Curvature Module

This module implements a GPU-accelerated and CPU-only principal curvature calculations.

These routines are needed for curvature-based seeded watershed to segment densely-packed nuclei: https://www.mdpi.com/2313-433X/2/4/31

scout.curvature.dx(x, xum=1.0)

Compute the gradient in the X direction

Note that this function does not pad the image so the output is reduced in size.

Parameters

  • x (ndarray) – Input array

  • xum (float) – microns per voxel in the X direction

Returns

dx – The gradient in the X direction, reduced in size by one at each edge

Return type

ndarray

scout.curvature.dy(x, yum=1.0)

Compute the gradient in the Y direction

Note that this function does not pad the image so the output is reduced in size.

Parameters

  • y (ndarray) – Input array

  • yum (float) – The number of microns per voxel in the Y direction

Returns

dy – The gradient in the Y direction, reduced in size by one at each edge

Return type

ndarray

scout.curvature.dz(x, zum=1.0)

Compute the gradient in the Z direction

Note that this function does not pad the image so the output is reduced in size.

Parameters

  • x (ndarray) – Input array

  • zum (float) – microns per voxel in the z direction

Returns

dz – The gradient in the Z direction, reduced in size by one at each edge

Return type

ndarray

scout.curvature.eigen3(A)

The eigenvalues of a 3x3 matrix of arrays

Parameters

A (ndarray) – a 3x3 matrix of arrays, e.g. a list of lists

Returns

eigenvals – a 3 tuple of arrays - the eigenvalues of each 3x3 of the matrix in ascending order.

Return type

tuple

scout.curvature.eigvals_of_weingarten(x, ew_block_size=64, zum=1, yum=1, xum=1)

Find the eigenvalues of the weingarten operator

Parameters

  • x (ndarray) – an NxMxP 3D array

  • ew_block_size (int) – the block size for the blocks to be processed. The algorithm needs approximately 128 bytes per voxel processed.

  • zum (float) – size of a voxel in the z direction - defaults to 1.0 micron

  • yum (float) – size of a voxel in the y direction - defaults to 1.0 micron

  • xum (float) – size of a voxel in the x direction - defaults to 1.0 micron

Returns

eigvals – an NxMxPx3 array of the 3 eigenvalues of the weingarten operator for the space.

Return type

ndarray

scout.curvature.gradient(x, zum=1.0, yum=1.0, xum=1.0)

Compute the gradient in all three directions

Note that the images returned are reduced in size by 1 - there is no padding

Parameters

  • x (ndarray) – Input array

  • zum (float) – size of a voxel in the z direction - defaults to 1.0 micron

  • yum (float) – size of a voxel in the y direction - defaults to 1.0 micron

  • xum (float) – size of a voxel in the x direction - defaults to 1.0 micron

Returns

grad – A tuple of the z, y, and x gradients.

Return type

tuple

scout.curvature.gradient_numpy(data, zum=1.0, yum=1.0, xum=1.0)

Compute the gradient in units of intensity / micron

Parameters

  • data (ndarray) – 3d numpy array

  • zum (float) – size of a voxel in the z direction - defaults to 1.0 micron

  • yum (float) – size of a voxel in the y direction - defaults to 1.0 micron

  • xum (float) – size of a voxel in the x direction - defaults to 1.0 micron

Returns

grad – A 4-dimensional matrix with the last dimension being the z==0, y==1, x==2 selector of the gradient direction

Return type

ndarray

scout.curvature.structure_tensor(dz, dy, dx)

Construct the structure tensor from the gradient

The structure tensor is the cross product of the gradient with itself: dz * dz dy * dz dx * dz dz * dy dy * dy dx * dy dz * dx dy * dx dx * dx

Note - the arrays of the structure tensor are reduced in size by 1 on each side to match the dimensions of the Hessian

Parameters

  • dz (ndarray) – The gradient in the Z direction

  • dy (ndarray) – The gradient in the Y direction

  • dx (ndarray) – The gradient in the X direction

Returns

result – A 3 tuple of 3 tuples representing the structure tensor of the gradient

Return type

ndarray

scout.curvature.weingarten(x, zum=1, yum=1, xum=1)

The Weingarten shape operator on a 3D image

See http://mathworld.wolfram.com/ShapeOperator.html for instance.

Parameters

  • x (ndarray) – The 3-D image to be processed

  • zum (float) – size of a voxel in the z direction - defaults to 1.0 micron

  • yum (float) – size of a voxel in the y direction - defaults to 1.0 micron

  • xum (float) – size of a voxel in the x direction - defaults to 1.0 micron

Returns

weingarten – A 3 tuple of 3 tuples representing the 3 x 3 matrix of the shape operator per voxel. The 3D elements of the matrix are reduced in size by 2 at each edge (a total of 4 voxels smaller in each dimension) because of the double differentiation of the Hessian.

Return type

tuple