fastmorph 1.0.2

Morphological image processing for 3D multi-label images.

fastmorph: multilabel 3D morphological image processing functions.

This is a collection of morphological 3D image operations that are tuned for working with dense 3D labeled images.

We provide the following multithreaded operations:

• Multi-Label Stenciled Dilation, Erosion, Opening, Closing
• Multi-Label Spherical Erosion
• Binary Spherical Dilation, Opening, and Closing
• Multi-Label Fill Voids

Highlights compared to other libraries:

• Handles multi-labeled images
• Multithreaded
• High performance single-threaded
• Low memory usage
• Dilate computes mode of surrounding labels

Disadvantages versus other libraries:

• Not ideal for grayscale images
• Stencil (structuring element) is fixed size 3x3x3 and all on.

import fastmorph

# may be binary or unsigned integer 2D or 3D image
labels = np.load("my_labels.npy")


# multi-label capable morphological operators
# they use a 3x3x3 all on structuring element
# dilate picks the mode of surrounding labels

# by default only background (0) labels are filled
morphed = fastmorph.dilate(labels, parallel=2)
# processes every voxel
morphed = fastmorph.dilate(labels, background_only=False, parallel=2)

morphed = fastmorph.erode(labels)
morphed = fastmorph.opening(labels, parallel=2)
morphed = fastmorph.closing(labels, parallel=2)

# Dilate only supports binary images at this time.
# Radius is specified in physical units, but
# by default anisotropy = (1,1,1) so it is the 
# same as voxels.
morphed = fastmorph.spherical_dilate(labels, radius=1, parallel=2, anisotropy=(1,1,1))

# open and close require dialate to work and so are binary only for now
morphed = fastmorph.spherical_open(labels, radius=1, parallel=2, anisotropy=(1,1,1))
morphed = fastmorph.spherical_close(labels, radius=1, parallel=2, anisotropy=(1,1,1))

# The rest support multilabel images.
morphed = fastmorph.spherical_erode(labels, radius=1, parallel=2, anisotropy=(1,1,1))

# Note: for boolean images, this function will directly call fill_voids
# and return a scalar for ct 
# For integer images, more processing will be done to deal with multiple labels.
# A dict of { label: num_voxels_filled } for integer images will be returned.
# Note that for multilabel images, by default, if a label is totally enclosed by another,
# a FillError will be raised. If remove_enclosed is True, the label will be overwritten.
filled_labels, ct = fastmorph.fill_holes(labels, return_fill_count=True, remove_enclosed=False)

Performance

A test run on an M1 Macbook Pro on connectomics.npy.ckl, a 512³ volume with over 2000 dense labels had the following results.

erode / 1 thread: 1.977 sec
erode / 2 threads: 1.104 sec
erode / 4 threads: 0.831 sec
dilate / background_only=True / 1 thread: 1.078 sec
dilate / background_only=True / 2 threads: 0.637 sec
dilate / background_only=True / 4 threads: 0.456 sec
dilate / background_only=False / 1 thread: 14.597 sec
dilate / background_only=False / 2 threads: 7.394 sec
dilate / background_only=False / 4 threads: 4.983 sec
dilate / background_only=False / 8 threads: 4.105 sec
scipy grey_dilation / 1 thread 14.648 sec
scipy grey_erode / 1 thread: 14.412 sec
skimage expand_labels / 1 thread: 62.248 sec

Here is the performance on a completely zeroed 512³ volume:

erode / 1 thread: 0.462 sec
erode / 2 threads: 0.270 sec
erode / 4 threads: 0.245 sec
dilate / background_only=True / 1 thread: 4.752 sec
dilate / background_only=True / 2 threads: 2.530 sec
dilate / background_only=True / 4 threads: 1.717 sec
dilate / background_only=False / 1 thread: 4.572 sec
dilate / background_only=False / 2 threads: 2.419 sec
dilate / background_only=False / 4 threads: 1.493 sec
dilate / background_only=False / 8 threads: 1.201 sec
scipy grey_dilation / 1 thread 10.508 sec
scipy grey_erode / 1 thread: 10.650 sec
skimage expand_labels / 1 thread: 33.353 sec

Memory Profiles