foa3d.slicing¶

foa3d.slicing.adjust_axis_range(ax_iter, img_shp, slc_per_ax, start, stop, ovlp=0)¶

Trim slice axis range at image boundaries and adjust padded ranges accordingly.

Parameters

ax_iter (int) – iteration counter along axis
img_shp (int) – total image shape along axis [px]
slc_per_ax (int) – slices along axis
start (int) – start coordinate [px]
stop (int) – stop coordinate [px]
ovlp (int) – overlapping range between slices along each axis [px]

Returns

start (int) – adjusted start coordinate [px]
stop (int) – adjusted stop coordinate [px]
pad (numpy.ndarray (shape=(2,), dtype=int)) – lower and upper padding ranges [px]

foa3d.slicing.check_background(img, ts_msk=None, ts_thr=0.0001)¶

Check whether the input image predominantly includes background voxels.

Parameters

img (numpy.ndarray (axis order=(Z,Y,X))) –
ts_msk (numpy.ndarray (axis order=(Z,Y,X), dtype=bool)) – tissue reconstruction binary mask
ts_thr (float) – relative threshold on non-zero voxels

Returns

not_bg – foreground boolean flag

Return type

bool

foa3d.slicing.compute_axis_range(ax, ax_iter, slc_shp, img_shp, slc_per_dim, ovlp=0, flip=False)¶

Adjust image slice coordinates at boundaries.

Parameters

ax (int) – image axis
ax_iter (int) – iteration counter along axis (see pipeline.iterate_frangi_on_slices)
slc_shp (numpy.ndarray (shape=(3,), dtype=int)) – shape of the basic image slices analyzed using parallel threads [px]
img_shp (numpy.ndarray (shape=(3,), dtype=int)) – total image shape [px]
slc_per_dim (numpy.ndarray (shape=(3,), dtype=int)) – image slices along each axis
ovlp (int) – overlapping range between slices along each axis [px]
flip (bool) – flip axes

Returns

start (int) – start index [px]
stop (int) – stop index [px]
pad (numpy.ndarray (shape=(2,), dtype=int)) – lower and upper padding ranges [px]

foa3d.slicing.compute_overlap(smooth_sigma, frangi_sigma_um, rsz_ratio=None, trunc=2)¶

Compute lateral slice extension range for coping with smoothing-related boundary artifacts.

Parameters

smooth_sigma (numpy.ndarray (shape=(3,), dtype=int)) – 3D standard deviation of the smoothing Gaussian filter [px]
frangi_sigma_um (numpy.ndarray (dtype=float)) – analyzed spatial scales [μm]
rsz_ratio (numpy.ndarray (shape=(3,), dtype=float)) – 3D image resize ratio
trunc (int) – neglect the Gaussian smoothing kernel after this many standard deviations

Returns

ovlp – overlapping range between image slices along each axis [px]

Return type

int

foa3d.slicing.compute_slice_range(ax_iter, slc_shp, img_shp, slc_per_dim, ovlp=0, flip=False)¶

Compute basic slice coordinates from microscopy volume image.

Parameters

ax_iter (tuple) – iteration counters along each axis
slc_shp (numpy.ndarray (shape=(3,), dtype=int)) – shape of the basic image slices analyzed using parallel threads [px]
img_shp (numpy.ndarray (shape=(3,), dtype=int)) – total image shape [px]
slc_per_dim (numpy.ndarray (shape=(3,), dtype=int)) – image slices along each axis
ovlp (int) – overlapping range between slices along each axis [px]
flip (bool) – flip axes

Returns

rng (np.ndarray) – 3D slice index ranges [px]
pad (np.ndarray (shape=(3,2), dtype=int)) – slice padding range [px]

foa3d.slicing.compute_slice_shape(img_shp, item_sz, slc_sz=1000000.0, ovlp=0)¶

Compute basic image chunk shape depending on its maximum size (in bytes).

Parameters

img_shp (numpy.ndarray (shape=(3,), dtype=int)) – total image shape [px]
item_sz (int) – image item size [B]
slc_sz (float) – maximum memory size of the basic image slices analyzed using parallel threads [B]
ovlp (int) – overlapping range between image slices along each axis [px]

Returns

slc_shp – shape of the basic image slices analyzed using parallel threads [px]

Return type

numpy.ndarray (shape=(3,), dtype=int)

foa3d.slicing.crop(img, rng, ovlp=None, flip=())¶

Shrink image slice at total volume boundaries, for overall shape consistency.

Parameters

img (numpy.ndarray (axis order=(Z,Y,X))) – 3D microscopy image
rng (tuple) – 3D slice index range
ovlp (numpy.ndarray (axis order=(Z,Y,X), dtype=int)) – overlapping range between image slices [px]
flip (tuple) – flipped axes

Returns

img_out – cropped microscopy image

Return type

numpy.ndarray

foa3d.slicing.crop_img_dict(img_dict, rng, ovlp=None, flip=())¶

Shrink list of image slices at total volume boundaries, for overall shape consistency.

Parameters

img_dict (list) – dictionary of image data to be cropped
rng (tuple) – 3D slice index range
ovlp (int) – overlapping range between image slices along each axis [px]
flip (tuple) – flipped axes

Returns

img_dict – dictionary of cropped image slices

Return type

list

foa3d.slicing.generate_slice_ranges(in_img, cfg)¶

Generate image slice ranges for the Frangi filtering stage.

Parameters

in_img (dict) –
input image dictionary

data: numpy.ndarray or NumPy memory-map object (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

rsz: numpy.ndarray (shape=(3,), dtype=float)
3D image resize ratio

ram: float
maximum RAM available to the Frangi filter stage [B]

jobs: int
number of parallel jobs (threads) used by the Frangi filter stage

batch: int
slice batch size

slc_shp: numpy.ndarray (shape=(3,), dtype=int)
shape of the basic image slices analyzed using parallel threads [px]

ovlp: int
overlapping range between image slices along each axis [px]

tot_slc: int
total number of image slices

z_out: NumPy slice object
output z-range

Returns

slc_rng –

in: np.ndarray: 3D input slice range [px]
pad: np.ndarray: 3D slice padding range [px]
out: np.ndarray: 3D output slice range [px]
bc: np.ndarray: (optional) brain cell soma slice range

Return type

list of dictionaries

foa3d.slicing.get_slicing_config(in_img, frangi_cfg, mem_growth=149.7, shp_thr=7)¶

Compute size and number of the batches of basic microscopy image slices analyzed in parallel.

Parameters

in_img (dict) –
input image dictionary

data: numpy.ndarray or NumPy memory-map object (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]
frangi_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

rsz: numpy.ndarray (shape=(3,), dtype=float)
3D image resize ratio

ram: float
maximum RAM available to the Frangi filter stage [B]

jobs: int
number of parallel jobs (threads) used by the Frangi filter stage
mem_growth (float) – empirical memory growth factor of the Frangi filtering stage
shp_thr (int) – minimum slice side [px]

Return type

None

foa3d.slicing.slice_image(img, rng, ch_ax, ch, ts_msk=None)¶

Slice desired channel from input image volume.

Parameters

img (numpy.ndarray) – 3D microscopy image
rng (tuple (dtype=int)) – 3D index ranges
ch (int) – channel
ch_ax (int) – RGB image channel axis (either 1 or 3, or None for grayscale images)
ts_msk (numpy.ndarray (dtype=bool)) – tissue binary mask

Returns

img_slc (numpy.ndarray) – image slice
ts_msk_slc (numpy.ndarray (dtype=bool)) – tissue mask slice