Region Properties Performance Overhaul - Part 1: Basic Properties

[grlee77]

regionprops_table performance overhaul (part 1)

This and subsequent parts will resolve #241, providing at least an order of magnitude improvement to nearly all region properties.

Design

General approach

The general approach in the new implementations is to compute a property for all labels in an image from a single
CUDA kernel call. This is in contrast to the approach from the RegionProperties class which first splits the full image into small sub-images corresponding to each region and then loops over these small sub-images, computing the requested property for each small region in turn. That approach is not amenable to good acceleration on the GPU as individual regions are often too small to saturate GPU resources and there is kernel launch overhead of launching separate kernels for each region.

Note that the functions introduced here are not being added to the public API. In a follow-up MR, they will be used behind the scenes from regionprops_table to enable orders of magnitude faster computation of region properties for all labels in an image.

Properties implemented in this MR

Part 1 provides batch implementation that computes the following properties for all properties in a single kernel call:

• bbox
• label_filled (creates version of label_image with all holes filled)
• num_pixels
• num_pixels_filled
• num_perimeter_pixels (number of pixels at perimeter of each labeled region)
• num_boundary_pixels (number of pixels touching the image boundary for each region)

The bbox property kernel is essentially the same one reviewed recently for cupyx.scipy.ndimage.find_objects, except that the version here also has the option to sum up the number of pixels during the same pass.

The following properties are simple transformations of the properties above and have negligable additional cost to compute (e.g. computing them involves much smaller arrays with shape (max_label,) or (max_label, 2*ndim) instead of the full pixel arrays):

• area
• area_bbox
• area_filled
• equivalent_diameter_area
• equivalent_spherical_perimeter (as in ITK)
• extent
• perimeter_on_border_ratio (as in ITK)
• slice

Finally, the following split the label image into a tuple of sub-images (or subsets of coordinates) where each element in the list corresponds to a label. The background of the label image has value 0 and is not represented in the sequences. Sequence entry i corresponds to label i + 1. In most cases, these will not be needed as properties are now computed for all regions at once from the labels image, but they are provided for completeness and to match the scikit-image API.

• coords
• coords_scaled
• image (label mask subimages)
• image_convex (convex label mask subimages)
• image_intensity (intensity_image subimages)
• image_filled (subimages of label mask but with holes filled)
• label (sequence of integer label ids)

Test cases are added that compare the results of these batch computations to results from scikit-image regionprops_table.

regionprops_dict

The regionprops_dict class introduced here in the 2nd commit is what will eventually be called from cucim.skimage.measure.regionprops_table to quickly compute multiple requested properties. This class will

• Ensure any dependent properties are calculated before those that depend on them
• Handle deprecated property names in the same way as regionprops_table (via the existing PROPS dict)
• By default this function does NOT split non-scalar measurements such as bbox into a separate column/key for each coordinate in the bounding box. That option will be added later to enable returning data in the same format as reginoprops_table.

Benchmarks

Performance vs. Image Size (with # regions fixed)

The following show performance for a small fixed number of label regions at different spatial scale in both 2D and 3D

In 2D, there are 16 labeled regions for shapes ranging from (64, 64) up to (8192, 8192)

In 3D, there are 8 labeled regions for shapes ranging from (32, 32) up to (512, 512, 512)

Note that "multi-basic" is the time to compute the following list of region properties rather than just a single property

properties = ["bbox", "num_pixels", "area", "area_bbox", "equivalent_diameter_area", "extent"]

Performance vs. Region Size (with image shape fixed)

Here a single large 2D image (7680, 4320) is used, but with varying numbers of labeled regions within it. The total % of foreground vs. background voxels remains similar (i.e. regions are larger when there are fewer of them). The number of regions range from 4 up through 16,384.

Here a single large 3D image (384, 384, 384) is used, but with varying numbers of labeled regions within it. The number of regions range from 8 up through 1,728.

Benchmark conclusions

Note: The results for the older GPU-based regionprops from cuCIM are not shown here. However, for many properties that implementation became much slower as the number of regions increased. We can see that for the new implementation proposed here, performance is roughly independent of the number of regions present. As expected, the relative acceleration that can be achieved becomes larger as image sizes increase, eventually starting to plateau at the larger sizes shown.