foa3d.frangi¶

foa3d.frangi.analyze_hessian_eigen(img, sigma, trunc=4)¶

Compute the eigenvalues of local Hessian matrices of the input image array, sorted by absolute value (in ascending order), along with the related (dominant) eigenvectors.

Parameters

img (numpy.ndarray (axis order=(Z,Y,X))) – 3D microscopy image
sigma (int) – spatial scale [px]
trunc (int) – truncate the Gaussian smoothing kernel at this many standard deviations

Returns

eigval (numpy.ndarray (axis order=(Z,Y,X,C), dtype=float)) – Hessian eigenvalues sorted by absolute value (ascending order)
dom_eigvec (numpy.ndarray (axis order=(Z,Y,X,C), dtype=float)) – Hessian eigenvectors related to the dominant (minimum) eigenvalue

foa3d.frangi.compute_dominant_eigen(hessian)¶

Compute the eigenvalues (sorted by absolute value) of symmetrical Hessian matrix, selecting the eigenvectors related to the dominant ones.

Parameters

hessian (numpy.ndarray (axis order=(Z,Y,X,C,C), dtype=float)) – input array of local Hessian matrices

Returns

srt_eigval (numpy.ndarray (axis order=(Z,Y,X,C), dtype=float)) – Hessian eigenvalues sorted by absolute value (ascending order)
dom_eigvec (numpy.ndarray (axis order=(Z,Y,X,C), dtype=float)) – Hessian eigenvectors related to the dominant (minimum) eigenvalue

foa3d.frangi.compute_fractional_anisotropy(eigenval)¶

Compute structure tensor fractional anisotropy as in Schilling et al. (2018).

Parameters: eigenval (numpy.ndarray (axis order=(Z,Y,X,C), dtype=float)) – structure tensor eigenvalues (at the best local spatial scale)
Returns: fa – fractional anisotropy
Return type: numpy.ndarray (shape=(3,), dtype=float)

foa3d.frangi.compute_frangi_features(eigen1, eigen2, eigen3, gamma)¶

Compute the basic image features employed by the Frangi filter.

Parameters

eigen1 (numpy.ndarray (axis order=(Z,Y,X), dtype=float)) – lowest Hessian eigenvalue (i.e., the dominant eigenvalue)
eigen2 (numpy.ndarray (axis order=(Z,Y,X), dtype=float)) – middle Hessian eigenvalue
eigen3 (numpy.ndarray (axis order=(Z,Y,X), dtype=float)) – highest Hessian eigenvalue
gamma (float) – background score sensitivity

Returns

ra (numpy.ndarray (axis order=(Z,Y,X), dtype=float)) – plate-like object score
rb (numpy.ndarray (axis order=(Z,Y,X), dtype=float)) – blob-like object score
s (numpy.ndarray (axis order=(Z,Y,X), dtype=float)) – second-order structureness
gamma (float) – background score sensitivity (automatically computed if not provided as input)

foa3d.frangi.compute_scaled_hessian(img, sigma=1, trunc=4)¶

Computes the scaled and normalized Hessian matrices of the input image. This is then used to estimate Frangi’s vesselness probability score.

Parameters

img (numpy.ndarray (axis order=(Z,Y,X))) – 3D microscopy image
sigma (int) – spatial scale [px]
trunc (int) – truncate the Gaussian smoothing kernel at this many standard deviations

Returns

hessian – Hessian matrix of image second derivatives

Return type

numpy.ndarray (axis order=(Z,Y,X,C,C), dtype=float)

foa3d.frangi.compute_scaled_orientation(scale_px, img, alpha=0.001, beta=1, gamma=None)¶

Compute fiber orientation vectors at the input spatial scale of interest

Parameters

scale_px (int) – spatial scale [px]
img (numpy.ndarray (axis order=(Z,Y,X))) – 3D microscopy image
alpha (float) – plate-like score sensitivity
beta (float) – blob-like score sensitivity
gamma (float) – background score sensitivity

Returns

frangi_img (numpy.ndarray (axis order=(Z,Y,X), dtype=float)) – Frangi’s vesselness likelihood image
eigvec (numpy.ndarray (axis order=(Z,Y,X,C), dtype=float)) – 3D orientation map at the input spatial scale
eigval (numpy.ndarray (axis order=(Z,Y,X,C), dtype=float)) – Hessian eigenvalues sorted by absolute value (ascending order)

foa3d.frangi.compute_scaled_vesselness(eigen1, eigen2, eigen3, alpha, beta, gamma)¶

Estimate Frangi’s vesselness probability.

Parameters

eigen1 (numpy.ndarray (axis order=(Z,Y,X), dtype=float)) – lowest Hessian eigenvalue (i.e., the dominant eigenvalue)
eigen2 (numpy.ndarray (axis order=(Z,Y,X), dtype=float)) – middle Hessian eigenvalue
eigen3 (numpy.ndarray (axis order=(Z,Y,X), dtype=float)) – highest Hessian eigenvalue
alpha (float) – plate-like score sensitivity
beta (float) – blob-like score sensitivity
gamma (float) – background score sensitivity

Returns

vesselness – Frangi’s vesselness likelihood image

Return type

numpy.ndarray (axis order=(Z,Y,X), dtype=float)

foa3d.frangi.frangi_filter(img, scales_px=1, alpha=0.001, beta=1.0, gamma=None, hsv=False, _fa=False)¶

Apply 3D Frangi filter to 3D microscopy image.

Parameters

img (numpy.ndarray (axis order=(Z,Y,X))) – 3D microscopy image
scales_px (int or numpy.ndarray (dtype=int)) – analyzed spatial scales [px]
alpha (float) – plate-like score sensitivity
beta (float) – blob-like score sensitivity
gamma (float) – background score sensitivity (if None, gamma is automatically tailored)
hsv (bool) – generate an HSV colormap of 3D fiber orientations
_fa (bool) – compute fractional anisotropy

Returns

out_slc –

slice output data

vec: numpy.ndarray (axis order=(Z,Y,X,C), dtype=float)
3D fiber orientation field

clr: numpy.ndarray (axis order=(Z,Y,X,C), dtype=uint8)
orientation colormap image

fa: numpy.ndarray (axis order=(Z,Y,X), dtype=uint8)
fractional anisotropy image

frangi: numpy.ndarray (axis order=(Z,Y,X), dtype=float)
Frangi’s vesselness likelihood image

Return type

dict

foa3d.frangi.init_frangi_arrays(in_img, cfg, tmp_dir)¶

Initialize the output datasets of the Frangi filter stage.

Parameters

in_img (dict) –
input image dictionary

data: numpy.ndarray (axis order=(Z,Y,X) or (Z,Y,X,C) or (Z,C,Y,X))
3D microscopy image

ts_msk: numpy.ndarray (dtype=bool)
tissue reconstruction binary mask

ch_ax: int
RGB image channel axis (either 1, 3, or None for grayscale images)

fb_ch: int
neuronal fibers channel

bc_ch: int
brain cell soma channel

msk_bc: bool
if True, mask neuronal bodies within the optionally provided channel

psf_fwhm: numpy.ndarray (shape=(3,), dtype=float)
3D FWHM of the PSF [μm]

px_sz: numpy.ndarray (shape=(3,), dtype=float)
pixel size [μm]

name: str
name of the 3D microscopy image

is_vec: bool
vector field flag

shape: numpy.ndarray (shape=(3,), dtype=int)
total image shape

shape_um: numpy.ndarray (shape=(3,), dtype=float)
total image shape [μm]

item_sz: int
image item size [B]
cfg (dict) –
Frangi filter configuration

alpha: float
plate-like score sensitivity

beta: float
blob-like score sensitivity

gamma: float
background score sensitivity

scales_px: numpy.ndarray (dtype=float)
Frangi filter scales [px]

scales_um: numpy.ndarray (dtype=float)
Frangi filter scales [μm]

smooth_sd: numpy.ndarray (shape=(3,), dtype=int)
3D standard deviation of the smoothing Gaussian filter [px]

px_sz: numpy.ndarray (shape=(3,), dtype=float)
pixel size [μm]

bc_ch: int
neuronal bodies channel

fb_ch: int
myelinated fibers channel

msk_bc: bool
if True, mask neuronal bodies within the optionally provided channel

hsv_cmap: bool
generate HSV colormap of 3D fiber orientations

exp_all: bool
export all images
tmp_dir (str) – path to temporary folder

Returns

out_img –

output image dictionary

vec: numpy.ndarray (axis order=(Z,Y,X,C), dtype=float32)
initialized fiber orientation 3D image

clr: numpy.ndarray (axis order=(Z,Y,X,C), dtype=uint8)
initialized orientation colormap image

fa: numpy.ndarray (axis order=(Z,Y,X), dtype=uint8)
initialized fractional anisotropy image

frangi: numpy.ndarray (axis order=(Z,Y,X), dtype=uint8)
initialized Frangi-enhanced image

iso: numpy.ndarray (axis order=(Z,Y,X), dtype=uint8)
initialized fiber image (isotropic resolution)

fbr_msk: numpy.ndarray (axis order=(Z,Y,X), dtype=uint8)
initialized fiber mask image

bc_msk: numpy.ndarray (axis order=(Z,Y,X), dtype=uint8)
initialized soma mask image

Return type

dict

foa3d.frangi.mask_background(out_slc, ref_img=None, method='yen', invert=False, ornt_keys=('vec', 'clr', 'fa'))¶

Mask fiber orientation data arrays.

Parameters

out_slc (dict) –
slice output dictionary

vec: numpy.ndarray (axis order=(Z,Y,X,C), dtype=float)
3D fiber orientation field

clr: numpy.ndarray (axis order=(Z,Y,X,C), dtype=uint8)
orientation colormap

fa: numpy.ndarray (axis order=(Z,Y,X), dtype=uint8)
fractional anisotropy

frangi: numpy.ndarray (axis order=(Z,Y,X), dtype=uint8)
Frangi-enhanced image slice (fiber probability image)

iso: numpy.ndarray (axis order=(Z,Y,X), dtype=uint8)
isotropic fiber image slice

ts_msk: numpy.ndarray (axis order=(Z,Y,X), dtype=uint8)
tissue mask slice

fbr_msk: numpy.ndarray (axis order=(Z,Y,X), dtype=uint8)
fiber mask slice

bc_msk: numpy.ndarray (axis order=(Z,Y,X), dtype=bool)
brain cell mask slice

rng: NumPy slice object
output range
ref_img (numpy.ndarray (axis order=(Z,Y,X)) – reference image used for thresholding
method (str) – thresholding method (refer to skimage.filters)
invert (bool) – mask inversion flag
ornt_keys (tuple) – fiber orientation data keys

Returns

out_slc (dict)
bg (numpy.ndarray (axis order=(Z,Y,X), dtype=bool)) – background mask

foa3d.frangi.reject_vesselness_background(vesselness, eigen2, eigen3)¶

Reject the fiber background, exploiting the sign of the “secondary” eigenvalues λ2 and λ3.

Parameters

vesselness (numpy.ndarray (axis order=(Z,Y,X))) – Frangi’s vesselness likelihood image
eigen2 (numpy.ndarray (axis order=(Z,Y,X), dtype=float)) – middle Hessian eigenvalue
eigen3 (numpy.ndarray (axis order=(Z,Y,X), dtype=float)) – highest Hessian eigenvalue

Returns

vesselness – masked Frangi’s vesselness likelihood image

Return type

numpy.ndarray (axis order=(Z,Y,X), dtype=float)

foa3d.frangi.sort_eigen(eigval, eigvec, axis=-1)¶

Sort eigenvalue and related eigenvector arrays by absolute value along the given axis.

Parameters

eigval (numpy.ndarray (axis order=(Z,Y,X,C), dtype=float)) – original eigenvalue array
eigvec (numpy.ndarray (axis order=(Z,Y,X,C,C), dtype=float)) – original eigenvector array
axis (int) – sorted axis

Returns

srt_eigval (numpy.ndarray (axis order=(Z,Y,X,C), dtype=float)) – sorted eigenvalue array (ascending order)
srt_eigvec (numpy.ndarray (axis order=(Z,Y,X,C,C), dtype=float)) – sorted eigenvector array

foa3d.frangi.write_frangi_arrays(out_img, out_slc, rng, z_out=None)¶

Fill the output arrays of the Frangi filter stage.

Parameters

out_img (dict) –
output image dictionary

vec: numpy.ndarray (axis order=(Z,Y,X,C), dtype=float32)
fiber orientation vector field

clr: numpy.ndarray (axis order=(Z,Y,X,C), dtype=uint8)
orientation colormap image

fa: numpy.ndarray (axis order=(Z,Y,X), dtype=uint8)
fractional anisotropy image

frangi: numpy.ndarray (axis order=(Z,Y,X), dtype=uint8)
Frangi-enhanced image (fiber probability image)

iso: numpy.ndarray (axis order=(Z,Y,X), dtype=uint8)
isotropic fiber image

fbr_msk: numpy.ndarray (axis order=(Z,Y,X), dtype=uint8)
fiber mask image

bc_msk: numpy.ndarray (axis order=(Z,Y,X), dtype=uint8)
soma mask image

px_sz: numpy.ndarray (shape=(3,), dtype=float)
output pixel size [μm]
out_slc (dict) –
slice output dictionary

vec: numpy.ndarray (axis order=(Z,Y,X,C), dtype=float)
3D fiber orientation field

clr: numpy.ndarray (axis order=(Z,Y,X,C), dtype=uint8)
orientation colormap

fa: numpy.ndarray (axis order=(Z,Y,X), dtype=uint8)
fractional anisotropy

frangi: numpy.ndarray (axis order=(Z,Y,X), dtype=uint8)
Frangi-enhanced image slice (fiber probability image)

iso: numpy.ndarray (axis order=(Z,Y,X), dtype=uint8)
isotropic fiber image slice

ts_msk: numpy.ndarray (axis order=(Z,Y,X), dtype=uint8)
tissue mask slice

fbr_msk: numpy.ndarray (axis order=(Z,Y,X), dtype=uint8)
fiber mask slice

bc_msk: numpy.ndarray (axis order=(Z,Y,X), dtype=bool)
brain cell mask slice
rng (NumPy slice object) – output range
z_out (NumPy slice object) – output z-range

Return type

None