How do we interpret bounding box slices?

[jchubber]

(Important Preface: THANK YOU for sharing this software. I greatly appreciate you for doing this! I'm a hobbyist using CC3D for a personal project, and really enjoying it!)

I'm unsure how to interpret the bounding_boxes returned by cc3d.statistics(). I'm assuming that the bounding box slices mean "here's the range of x/y/z coordinates needed to fully contain the component", but I'm not understanding the data that I'm getting for bounding boxes. The README.md doesn't directly speak to how to interpret bounding box values, and I haven't found any prior discussion here in Github related to it (but if I've missed something, please feel free to direct me to it).

Example

array(
    {
        "voxel_counts": array(
            [2146482952, 177614, 187470, 203816, 206556, 225240], dtype=uint64
        ),
        "bounding_boxes": [
            (slice(0, 4096, None), slice(0, 128, None), slice(0, 4096, None)),
            (slice(3873, 3888, None), slice(0, 128, None), slice(2647, 2935, None)),
            (slice(1, 14, None), slice(0, 128, None), slice(1613, 2062, None)),
            (slice(788, 800, None), slice(0, 128, None), slice(1696, 1992, None)),
            (slice(3921, 3936, None), slice(0, 128, None), slice(3593, 3934, None)),
            (slice(771, 784, None), slice(0, 128, None), slice(1693, 2118, None)),
        ],
        "centroids": array(
            [
                [2047.59790422, 63.49990168, 2047.33163892],
                [3881.70964564, 64.4173939, 2810.15527492],
                [5.79887982, 63.79729557, 1856.19388702],
                [793.57173137, 63.7300997, 1817.91493308],
                [3928.47374562, 63.04395418, 3778.4389415],
                [777.17011188, 63.67610549, 1830.16461552],
            ]
        ),
    },
    dtype=object,
)

In this example, let's say I want to understand the bounding box for the final component (with voxel_counts = 225240). The corresponding bounding box is (slice(771, 784, None), slice(0, 128, None), slice(1693, 2118, None)). What is the None in each slice representing? Does the first slice mean that all of the x coordinates lie between x=771 and x=784?

Thanks so much in advance for any clarification you may be able to offer!

[william-silversmith]

Thank you for writing in! I really appreciate that you're getting a lot of use out of this library!

The bounding boxes are designed to make it easy to obtain a cutout from the output connected component labels (let's call them cc_labels). The dimensions of the bounding boxes are a close crop (the minimum sized box) needed to enclose a label with a parallelepiped geometry.

Let's assume I want to access the cutout of connected component label 5:

cc_labels, N = cc3d.connected_components(labels, return_N=True)
assert N >= 5, "Not enough connected components"
stats = cc3d.statistics(cc_labels)
bboxes = stats["bounding_boxes"]

cutout = cc_labels[bboxes[5]]

This is kind of similar to how scipy does it: https://docs.scipy.org/doc/scipy/reference/generated/scipy.ndimage.find_objects.html

However, a big difference is that scipy doesn't calculate the bounding box of the background value 0, so the index into the array is offset by -1. e.g.

bboxes = scipy.ndimage.find_objects(cc_labels)
cutout = cc_labels[bboxes[5 - 1]]

EDIT: Forgot to answer your question.

What is the None in each slice representing? Does the first slice mean that all of the x coordinates lie between x=771 and x=784?

A slice is a builtin python object. A slice of slc = slice(0, 20, None); arr[slc] means the same as this syntax: arr[0:20]. If you want to perform a multidimensional slice, you pack them into a tuple object. You can access the attributes of a slice with slice.start, slice.stop, and slice.step. None indicates the start, stop, or step is unspecified. For example, slice(None, None, None) means arr[:]. slice(10, None, None) means arr[10:]. slice(None, None, 2) means arr[::2].

Read more about slice: https://docs.python.org/3/library/functions.html?highlight=slice#slice

[jchubber]

Thanks for the explanation of how slice() corresponds to arr[] -- Super clear!