numarray Manual

21.10 Object measurements

Given an array of labeled objects, the properties of the individual objects can be measured. The find_objects function can be used to generate a list of slices that for each object, give the smallest sub-array that fully contains the object:

find_objects( input, max_label=0)

The find_objects finds all objects in a labeled array and returns a list of slices that correspond to the smallest regions in the array that contains the object. For instance:

>>> a = array([[0,1,1,0,0,0],[0,1,1,0,1,0],[0,0,0,1,1,1],[0,0,0,0,1,0]])
>>> l, n = label(a)
>>> f = find_objects(l)
>>> print a[f[0]]
[[1 1]
 [1 1]]
>>> print a[f[1]]
[[0 1 0]
 [1 1 1]
 [0 1 0]]

find_objects returns slices for all objects, unless the max_label parameter is larger then zero, in which case only the first max_label objects are returned. If an index is missing in the label array, None is return instead of a slice. For example:

>>> print find_objects([1, 0, 3, 4], max_label = 3)
[(slice(0, 1, None),), None, (slice(2, 3, None),)]

The list of slices generated by find_objects is useful to find the position and dimensions of the objects in the array, but can also be used to perform measurements on the individual objects. Say we want to find the sum of the intensities of an object in image:

>>> image = arange(4*6,shape=(4,6))
>>> mask = array([[0,1,1,0,0,0],[0,1,1,0,1,0],[0,0,0,1,1,1],[0,0,0,0,1,0]])
>>> labels = label(mask)[0]
>>> slices = find_objects(labels)

Then we can calculate the sum of the elements in the second object:

>>> print where(labels[slices[1]] == 2, image[slices[1]], 0).sum()
80

That is however not particularly efficient, and may also be more complicated for other types of measurements. Therefore a few measurements functions are defined that accept the array of object labels and the index of the object to be measured. For instance calculating the sum of the intensities can be done by:

>>> print sum(image, labels, 2)
80.0

For large arrays and small objects it is more efficient to call the measurement functions after slicing the array:

>>> print sum(image[slices[1]], labels[slices[1]], 2)
80.0

Alternatively, we can do the measurements for a number of labels with a single function call, returning a list of results. For instance, to measure the sum of the values of the background and the second object in our example we give a list of labels:

>>> print sum(image, labels, [0, 2])
[178.0, 80.0]

The measurement functions described below all support the index parameter to indicate which object(s) should be measured. The default value of index is None. This indicates that all elements where the label is larger than zero should be treated as a single object and measured. Thus, in this case the labels array is treated as a mask defined by the elements that are larger than zero. If index is a number or a sequence of numbers it gives the labels of the objects that are measured. If index is a sequence, a list of the results is returned. Functions that return more than one result, return their result as a tuple if index is a single number, or as a tuple of lists, if index is a sequence.

sum( input, labels=None, index=None): The sum function calculates the sum of the elements of the object with label(s) given by index, using the labels array for the object labels. If index is None, all elements with a non-zero label value are treated as a single object. If label is None, all elements of input are used in the calculation.

mean( input, labels=None, index=None): The mean function calculates the mean of the elements of the object with label(s) given by index, using the labels array for the object labels. If index is None, all elements with a non-zero label value are treated as a single object. If label is None, all elements of input are used in the calculation.

variance( input, labels=None, index=None): The variance function calculates the variance of the elements of the object with label(s) given by index, using the labels array for the object labels. If index is None, all elements with a non-zero label value are treated as a single object. If label is None, all elements of input are used in the calculation.

standard_deviation( input, labels=None, index=None): The standard_deviation function calculates the standard deviation of the elements of the object with label(s) given by index, using the labels array for the object labels. If index is None, all elements with a non-zero label value are treated as a single object. If label is None, all elements of input are used in the calculation.

minimum( input, labels=None, index=None): The minimum function calculates the minimum of the elements of the object with label(s) given by index, using the labels array for the object labels. If index is None, all elements with a non-zero label value are treated as a single object. If label is None, all elements of input are used in the calculation.

maximum( input, labels=None, index=None): The maximum function calculates the maximum of the elements of the object with label(s) given by index, using the labels array for the object labels. If index is None, all elements with a non-zero label value are treated as a single object. If label is None, all elements of input are used in the calculation.

minimum_position( input, labels=None, index=None): The minimum_position function calculates the position of the minimum of the elements of the object with label(s) given by index, using the labels array for the object labels. If index is None, all elements with a non-zero label value are treated as a single object. If label is None, all elements of input are used in the calculation.

maximum_position( input, labels=None, index=None): The maximum_position function calculates the position of the maximum of the elements of the object with label(s) given by index, using the labels array for the object labels. If index is None, all elements with a non-zero label value are treated as a single object. If label is None, all elements of input are used in the calculation.

extrema( input, labels=None, index=None): The extrema function calculates the minimum, the maximum, and their positions, of the elements of the object with label(s) given by index, using the labels array for the object labels. If index is None, all elements with a non-zero label value are treated as a single object. If label is None, all elements of input are used in the calculation. The result is a tuple giving the minimum, the maximum, the position of the mininum and the postition of the maximum. The result is the same as a tuple formed by the results of the functions minimum, maximum, minimum_position, and maximum_position that are described above.

center_of_mass( input, labels=None, index=None): The center_of_mass function calculates the center of mass of the of the object with label(s) given by index, using the labels array for the object labels. If index is None, all elements with a non-zero label value are treated as a single object. If label is None, all elements of input are used in the calculation.

histogram( input, min, max, bins, labels=None, index=None): The histogram function calculates a histogram of the of the object with label(s) given by index, using the labels array for the object labels. If index is None, all elements with a non-zero label value are treated as a single object. If label is None, all elements of input are used in the calculation. Histograms are defined by their minimum (min), maximum (max) and the number of bins (bins). They are returned as one-dimensional arrays of type Int32.

Send comments to the NumArray community.