def regionprops(label_image,
intensity_image=None,
cache=True,
coordinates=None):
r"""Measure properties of labeled image regions.
Parameters
----------
label_image : (N, M) ndarray
Labeled input image. Labels with value 0 are ignored.
.. versionchanged:: 0.14.1
Previously, ``label_image`` was processed by ``numpy.squeeze`` and
so any number of singleton dimensions was allowed. This resulted in
inconsistent handling of images with singleton dimensions. To
recover the old behaviour, use
``regionprops(cp.squeeze(label_image), ...)``.
intensity_image : (N, M) ndarray, optional
Intensity (i.e., input) image with same size as labeled image.
Default is None.
cache : bool, optional
Determine whether to cache calculated properties. The computation is
much faster for cached properties, whereas the memory consumption
increases.
coordinates : DEPRECATED
This argument is deprecated and will be removed in a future version
of scikit-image.
See :ref:`Coordinate conventions <numpy-images-coordinate-conventions>`
for more details.
.. deprecated:: 0.16.0
Use "rc" coordinates everywhere. It may be sufficient to call
``numpy.transpose`` on your label image to get the same values as
0.15 and earlier. However, for some properties, the transformation
will be less trivial. For example, the new orientation is
:math:`\frac{\pi}{2}` plus the old orientation.
Returns
-------
properties : list of RegionProperties
Each item describes one labeled region, and can be accessed using the
attributes listed below.
Notes
-----
The following properties can be accessed as attributes or keys:
**area** : int
Number of pixels of the region.
**bbox** : tuple
Bounding box ``(min_row, min_col, max_row, max_col)``.
Pixels belonging to the bounding box are in the half-open interval
``[min_row; max_row)`` and ``[min_col; max_col)``.
**bbox_area** : int
Number of pixels of bounding box.
**centroid** : array
Centroid coordinate tuple ``(row, col)``.
**convex_area** : int
Number of pixels of convex hull image, which is the smallest convex
polygon that encloses the region.
**convex_image** : (H, J) ndarray
Binary convex hull image which has the same size as bounding box.
**coords** : (N, 2) ndarray
Coordinate list ``(row, col)`` of the region.
**eccentricity** : float
Eccentricity of the ellipse that has the same second-moments as the
region. The eccentricity is the ratio of the focal distance
(distance between focal points) over the major axis length.
The value is in the interval [0, 1).
When it is 0, the ellipse becomes a circle.
**equivalent_diameter** : float
The diameter of a circle with the same area as the region.
**euler_number** : int
Euler characteristic of region. Computed as number of objects (= 1)
subtracted by number of holes (8-connectivity).
**extent** : float
Ratio of pixels in the region to pixels in the total bounding box.
Computed as ``area / (rows * cols)``
**filled_area** : int
Number of pixels of the region will all the holes filled in. Describes
the area of the filled_image.
**filled_image** : (H, J) ndarray
Binary region image with filled holes which has the same size as
bounding box.
**image** : (H, J) ndarray
Sliced binary region image which has the same size as bounding box.
**inertia_tensor** : ndarray
Inertia tensor of the region for the rotation around its mass.
**inertia_tensor_eigvals** : tuple
The eigenvalues of the inertia tensor in decreasing order.
**intensity_image** : ndarray
Image inside region bounding box.
**label** : int
The label in the labeled input image.
**local_centroid** : array
Centroid coordinate tuple ``(row, col)``, relative to region bounding
box.
**major_axis_length** : float
The length of the major axis of the ellipse that has the same
normalized second central moments as the region.
**max_intensity** : float
Value with the greatest intensity in the region.
**mean_intensity** : float
Value with the mean intensity in the region.
**min_intensity** : float
Value with the least intensity in the region.
**minor_axis_length** : float
The length of the minor axis of the ellipse that has the same
normalized second central moments as the region.
**moments** : (3, 3) ndarray
Spatial moments up to 3rd order::
m_ij = sum{ array(row, col) * row^i * col^j }
where the sum is over the `row`, `col` coordinates of the region.
**moments_central** : (3, 3) ndarray
Central moments (translation invariant) up to 3rd order::
mu_ij = sum{ array(row, col) * (row - row_c)^i * (col - col_c)^j }
where the sum is over the `row`, `col` coordinates of the region,
and `row_c` and `col_c` are the coordinates of the region's centroid.
**moments_hu** : tuple
Hu moments (translation, scale and rotation invariant).
**moments_normalized** : (3, 3) ndarray
Normalized moments (translation and scale invariant) up to 3rd order::
nu_ij = mu_ij / m_00^[(i+j)/2 + 1]
where `m_00` is the zeroth spatial moment.
**orientation** : float
Angle between the 0th axis (rows) and the major
axis of the ellipse that has the same second moments as the region,
ranging from `-pi/2` to `pi/2` counter-clockwise.
**perimeter** : float
Perimeter of object which approximates the contour as a line
through the centers of border pixels using a 4-connectivity.
**slice** : tuple of slices
A slice to extract the object from the source image.
**solidity** : float
Ratio of pixels in the region to pixels of the convex hull image.
**weighted_centroid** : array
Centroid coordinate tuple ``(row, col)`` weighted with intensity
image.
**weighted_local_centroid** : array
Centroid coordinate tuple ``(row, col)``, relative to region bounding
box, weighted with intensity image.
**weighted_moments** : (3, 3) ndarray
Spatial moments of intensity image up to 3rd order::
wm_ij = sum{ array(row, col) * row^i * col^j }
where the sum is over the `row`, `col` coordinates of the region.
**weighted_moments_central** : (3, 3) ndarray
Central moments (translation invariant) of intensity image up to
3rd order::
wmu_ij = sum{ array(row, col) * (row - row_c)^i * (col - col_c)^j }
where the sum is over the `row`, `col` coordinates of the region,
and `row_c` and `col_c` are the coordinates of the region's weighted
centroid.
**weighted_moments_hu** : tuple
Hu moments (translation, scale and rotation invariant) of intensity
image.
**weighted_moments_normalized** : (3, 3) ndarray
Normalized moments (translation and scale invariant) of intensity
image up to 3rd order::
wnu_ij = wmu_ij / wm_00^[(i+j)/2 + 1]
where ``wm_00`` is the zeroth spatial moment (intensity-weighted area).
Each region also supports iteration, so that you can do::
for prop in region:
print(prop, region[prop])
See Also
--------
label
References
----------
.. [1] Wilhelm Burger, Mark Burge. Principles of Digital Image Processing:
Core Algorithms. Springer-Verlag, London, 2009.
.. [2] B. Jähne. Digital Image Processing. Springer-Verlag,
Berlin-Heidelberg, 6. edition, 2005.
.. [3] T. H. Reiss. Recognizing Planar Objects Using Invariant Image
Features, from Lecture notes in computer science, p. 676. Springer,
Berlin, 1993.
.. [4] https://en.wikipedia.org/wiki/Image_moment
Examples
--------
>>> from skimage import data, util
>>> from skimage.measure import label
>>> img = util.img_as_ubyte(data.coins()) > 110
>>> label_img = label(img, connectivity=img.ndim)
>>> props = regionprops(label_img)
>>> # centroid of first labeled object
>>> props[0].centroid
(22.72987986048314, 81.91228523446583)
>>> # centroid of first labeled object
>>> props[0]['centroid']
(22.72987986048314, 81.91228523446583)
"""
if label_image.ndim not in (2, 3):
raise TypeError("Only 2-D and 3-D images supported.")
if not cp.issubdtype(label_image.dtype, cp.integer):
if cp.issubdtype(label_image.dtype, cp.bool):
raise TypeError("Non-integer image types are ambiguous: "
"use skimage.measure.label to label the connected"
"components of label_image,"
"or label_image.astype(np.uint8) to interpret"
"the True values as a single label.")
else:
raise TypeError("Non-integer label_image types are ambiguous")
if coordinates is not None:
if coordinates == "rc":
msg = ("The coordinates keyword argument to skimage.measure."
"regionprops is deprecated. All features are now computed "
"in rc (row-column) coordinates. Please remove "
'`coordinates="rc"` from all calls to regionprops before '
"updating scikit-image.")
warn(msg, stacklevel=2, category=FutureWarning)
else:
msg = ('Values other than "rc" for the "coordinates" argument '
"to skimage.measure.regionprops are no longer supported. "
'You should update your code to use "rc" coordinates and '
'stop using the "coordinates" argument, or use skimage '
"version 0.15.x or earlier.")
raise ValueError(msg)
regions = []
# warn("host/device transfer required: ndimage.find_objects not implemented "
# " on the GPU.")
objects = cpu_find_objects(cp.asnumpy(label_image))
for i, sl in enumerate(objects):
if sl is None:
continue
label = i + 1
props = RegionProperties(sl, label, label_image, intensity_image,
cache)
regions.append(props)
return regions
def peak_local_max(
image,
min_distance=1,
threshold_abs=None,
threshold_rel=None,
exclude_border=True,
indices=True,
num_peaks=cp.inf,
footprint=None,
labels=None,
num_peaks_per_label=cp.inf,
p_norm=cp.inf,
):
"""Find peaks in an image as coordinate list or boolean mask.
Peaks are the local maxima in a region of `2 * min_distance + 1`
(i.e. peaks are separated by at least `min_distance`).
If both `threshold_abs` and `threshold_rel` are provided, the maximum
of the two is chosen as the minimum intensity threshold of peaks.
.. versionchanged:: 0.18
Prior to version 0.18, peaks of the same height within a radius of
`min_distance` were all returned, but this could cause unexpected
behaviour. From 0.18 onwards, an arbitrary peak within the region is
returned. See issue gh-2592.
Parameters
----------
image : ndarray
Input image.
min_distance : int, optional
The minimal allowed distance separating peaks. To find the
maximum number of peaks, use `min_distance=1`.
threshold_abs : float, optional
Minimum intensity of peaks. By default, the absolute threshold is
the minimum intensity of the image.
threshold_rel : float, optional
Minimum intensity of peaks, calculated as `max(image) * threshold_rel`.
exclude_border : int, tuple of ints, or bool, optional
If positive integer, `exclude_border` excludes peaks from within
`exclude_border`-pixels of the border of the image.
If tuple of non-negative ints, the length of the tuple must match the
input array's dimensionality. Each element of the tuple will exclude
peaks from within `exclude_border`-pixels of the border of the image
along that dimension.
If True, takes the `min_distance` parameter as value.
If zero or False, peaks are identified regardless of their distance
from the border.
indices : bool, optional
If True, the output will be an array representing peak
coordinates. The coordinates are sorted according to peaks
values (Larger first). If False, the output will be a boolean
array shaped as `image.shape` with peaks present at True
elements. ``indices`` is deprecated and will be removed in
version 0.20. Default behavior will be to always return peak
coordinates. You can obtain a mask as shown in the example
below.
num_peaks : int, optional
Maximum number of peaks. When the number of peaks exceeds `num_peaks`,
return `num_peaks` peaks based on highest peak intensity.
footprint : ndarray of bools, optional
If provided, `footprint == 1` represents the local region within which
to search for peaks at every point in `image`.
labels : ndarray of ints, optional
If provided, each unique region `labels == value` represents a unique
region to search for peaks. Zero is reserved for background.
num_peaks_per_label : int, optional
Maximum number of peaks for each label.
p_norm : float
Which Minkowski p-norm to use. Should be in the range [1, inf].
A finite large p may cause a ValueError if overflow can occur.
``inf`` corresponds to the Chebyshev distance and 2 to the
Euclidean distance.
Returns
-------
output : ndarray or ndarray of bools
* If `indices = True` : (row, column, ...) coordinates of peaks.
* If `indices = False` : Boolean array shaped like `image`, with peaks
represented by True values.
Notes
-----
The peak local maximum function returns the coordinates of local peaks
(maxima) in an image. Internally, a maximum filter is used for finding local
maxima. This operation dilates the original image. After comparison of the
dilated and original image, this function returns the coordinates or a mask
of the peaks where the dilated image equals the original image.
See also
--------
skimage.feature.corner_peaks
Examples
--------
>>> import cupy as cp
>>> img1 = cp.zeros((7, 7))
>>> img1[3, 4] = 1
>>> img1[3, 2] = 1.5
>>> img1
array([[0. , 0. , 0. , 0. , 0. , 0. , 0. ],
[0. , 0. , 0. , 0. , 0. , 0. , 0. ],
[0. , 0. , 0. , 0. , 0. , 0. , 0. ],
[0. , 0. , 1.5, 0. , 1. , 0. , 0. ],
[0. , 0. , 0. , 0. , 0. , 0. , 0. ],
[0. , 0. , 0. , 0. , 0. , 0. , 0. ],
[0. , 0. , 0. , 0. , 0. , 0. , 0. ]])
>>> peak_local_max(img1, min_distance=1)
array([[3, 2],
[3, 4]])
>>> peak_local_max(img1, min_distance=2)
array([[3, 2]])
>>> img2 = cp.zeros((20, 20, 20))
>>> img2[10, 10, 10] = 1
>>> img2[15, 15, 15] = 1
>>> peak_idx = peak_local_max(img2, exclude_border=0)
>>> peak_idx
array([[10, 10, 10],
[15, 15, 15]])
>>> peak_mask = cp.zeros_like(img2, dtype=bool)
>>> peak_mask[tuple(peak_idx.T)] = True
>>> np.argwhere(peak_mask)
array([[10, 10, 10],
[15, 15, 15]])
"""
if (footprint is None or footprint.size == 1) and min_distance < 1:
warnings.warn(
"When min_distance < 1, peak_local_max acts as finding "
"image > max(threshold_abs, threshold_rel * max(image)).",
RuntimeWarning,
stacklevel=2,
)
border_width = _get_excluded_border_width(image, min_distance,
exclude_border)
threshold = _get_threshold(image, threshold_abs, threshold_rel)
if footprint is None:
size = 2 * min_distance + 1
footprint = cp.ones((size, ) * image.ndim, dtype=bool)
else:
footprint = cp.asarray(footprint)
if labels is None:
# Non maximum filter
mask = _get_peak_mask(image, footprint, threshold)
mask = _exclude_border(mask, border_width)
# Select highest intensities (num_peaks)
coordinates = _get_high_intensity_peaks(image, mask, num_peaks,
min_distance, p_norm)
else:
_labels = _exclude_border(labels.astype(int), border_width)
if np.issubdtype(image.dtype, np.floating):
bg_val = cp.finfo(image.dtype).min
else:
bg_val = cp.iinfo(image.dtype).min
# For each label, extract a smaller image enclosing the object of
# interest, identify num_peaks_per_label peaks
labels_peak_coord = []
# For each label, extract a smaller image enclosing the object of
# interest, identify num_peaks_per_label peaks and mark them in
# variable out.
# TODO: use GPU version of find_objects
try:
objects = cupyx_ndi.find_objects(_labels)
except AttributeError:
objects = cpu_find_objects(cp.asnumpy(_labels))
for label_idx, roi in enumerate(objects):
if roi is None:
continue
# Get roi mask
label_mask = labels[roi] == label_idx + 1
# Extract image roi
img_object = image[roi]
# Ensure masked values don't affect roi's local peaks
img_object[np.logical_not(label_mask)] = bg_val
mask = _get_peak_mask(img_object, footprint, threshold, label_mask)
coordinates = _get_high_intensity_peaks(img_object, mask,
num_peaks_per_label,
min_distance, p_norm)
# transform coordinates in global image indices space
for idx, s in enumerate(roi):
coordinates[:, idx] += s.start
labels_peak_coord.append(coordinates)
if labels_peak_coord:
coordinates = cp.vstack(labels_peak_coord)
else:
coordinates = cp.empty((0, 2), dtype=int)
if len(coordinates) > num_peaks:
out = cp.zeros_like(image, dtype=np.bool_)
out[tuple(coordinates.T)] = True
coordinates = _get_high_intensity_peaks(image, out, num_peaks,
min_distance, p_norm)
if indices:
return coordinates
else:
out = cp.zeros_like(image, dtype=np.bool_)
out[tuple(coordinates.T)] = True
return out
def peak_local_max(
image,
min_distance=1,
threshold_abs=None,
threshold_rel=None,
exclude_border=True,
indices=True,
num_peaks=cp.inf,
footprint=None,
labels=None,
num_peaks_per_label=cp.inf,
):
"""Find peaks in an image as coordinate list or boolean mask.
Peaks are the local maxima in a region of `2 * min_distance + 1`
(i.e. peaks are separated by at least `min_distance`).
If there are multiple local maxima with identical pixel intensities
inside the region defined with `min_distance`,
the coordinates of all such pixels are returned.
If both `threshold_abs` and `threshold_rel` are provided, the maximum
of the two is chosen as the minimum intensity threshold of peaks.
Parameters
----------
image : ndarray
Input image.
min_distance : int, optional
Minimum number of pixels separating peaks in a region of `2 *
min_distance + 1` (i.e. peaks are separated by at least
`min_distance`).
To find the maximum number of peaks, use `min_distance=1`.
threshold_abs : float, optional
Minimum intensity of peaks. By default, the absolute threshold is
the minimum intensity of the image.
threshold_rel : float, optional
Minimum intensity of peaks, calculated as `max(image) * threshold_rel`.
exclude_border : int, tuple of ints, or bool, optional
If positive integer, `exclude_border` excludes peaks from within
`exclude_border`-pixels of the border of the image.
If tuple of non-negative ints, the length of the tuple must match the
input array's dimensionality. Each element of the tuple will exclude
peaks from within `exclude_border`-pixels of the border of the image
along that dimension.
If True, takes the `min_distance` parameter as value.
If zero or False, peaks are identified regardless of their distance
from the border.
indices : bool, optional
If True, the output will be an array representing peak
coordinates. The coordinates are sorted according to peaks
values (Larger first). If False, the output will be a boolean
array shaped as `image.shape` with peaks present at True
elements.
num_peaks : int, optional
Maximum number of peaks. When the number of peaks exceeds `num_peaks`,
return `num_peaks` peaks based on highest peak intensity.
footprint : ndarray of bools, optional
If provided, `footprint == 1` represents the local region within which
to search for peaks at every point in `image`. Overrides
`min_distance`.
labels : ndarray of ints, optional
If provided, each unique region `labels == value` represents a unique
region to search for peaks. Zero is reserved for background.
num_peaks_per_label : int, optional
Maximum number of peaks for each label.
Returns
-------
output : ndarray or ndarray of bools
* If `indices = True` : (row, column, ...) coordinates of peaks.
* If `indices = False` : Boolean array shaped like `image`, with peaks
represented by True values.
Notes
-----
The peak local maximum function returns the coordinates of local peaks
(maxima) in an image. A maximum filter is used for finding local maxima.
This operation dilates the original image. After comparison of the dilated
and original image, this function returns the coordinates or a mask of the
peaks where the dilated image equals the original image.
See also
--------
skimage.feature.corner_peaks
Examples
--------
>>> import cupy as cp
>>> img1 = cp.zeros((7, 7))
>>> img1[3, 4] = 1
>>> img1[3, 2] = 1.5
>>> img1
array([[0. , 0. , 0. , 0. , 0. , 0. , 0. ],
[0. , 0. , 0. , 0. , 0. , 0. , 0. ],
[0. , 0. , 0. , 0. , 0. , 0. , 0. ],
[0. , 0. , 1.5, 0. , 1. , 0. , 0. ],
[0. , 0. , 0. , 0. , 0. , 0. , 0. ],
[0. , 0. , 0. , 0. , 0. , 0. , 0. ],
[0. , 0. , 0. , 0. , 0. , 0. , 0. ]])
>>> peak_local_max(img1, min_distance=1)
array([[3, 2],
[3, 4]])
>>> peak_local_max(img1, min_distance=2)
array([[3, 2]])
>>> img2 = cp.zeros((20, 20, 20))
>>> img2[10, 10, 10] = 1
>>> peak_local_max(img2, exclude_border=0)
array([[10, 10, 10]])
"""
out = cp.zeros_like(image, dtype=cp.bool)
threshold_abs = threshold_abs if threshold_abs is not None else image.min()
if isinstance(exclude_border, bool):
exclude_border = (min_distance if exclude_border else 0, ) * image.ndim
elif isinstance(exclude_border, int):
if exclude_border < 0:
raise ValueError("`exclude_border` cannot be a negative value")
exclude_border = (exclude_border, ) * image.ndim
elif isinstance(exclude_border, tuple):
if len(exclude_border) != image.ndim:
raise ValueError(
"`exclude_border` should have the same length as the "
"dimensionality of the image.")
for exclude in exclude_border:
if not isinstance(exclude, int):
raise ValueError(
"`exclude_border`, when expressed as a tuple, must only "
"contain ints.")
if exclude < 0:
raise ValueError(
"`exclude_border` cannot contain a negative value")
else:
raise TypeError(
"`exclude_border` must be bool, int, or tuple with the same "
"length as the dimensionality of the image.")
# no peak for a trivial image
# if cp.all(image == image.flat[0]):
if cp.all(image == image.ravel()[0]):
if indices is True:
return cp.empty((0, image.ndim), cp.int)
else:
return out
# In the case of labels, call ndi on each label
if labels is not None:
label_values = cp.unique(labels)
# Reorder label values to have consecutive integers (no gaps)
if cp.any(cp.diff(label_values) != 1):
mask = labels >= 1
labels[mask] = 1 + rank_order(labels[mask])[0].astype(labels.dtype)
labels = labels.astype(cp.int32)
# create a mask for the non-exclude region
inner_mask = _exclude_border(cp.ones_like(labels, dtype=bool),
exclude_border)
# For each label, extract a smaller image enclosing the object of
# interest, identify num_peaks_per_label peaks and mark them in
# variable out.
warnings.warn(
"host/device transfers necessary: ndimage.find_objects unimplemented on the GPU"
)
objects = cpu_find_objects(cp.asnumpy(labels))
for label_idx, obj in enumerate(objects):
img_object = image[obj] * (labels[obj] == label_idx + 1)
mask = _get_peak_mask(
img_object,
min_distance,
footprint,
threshold_abs,
threshold_rel,
)
if exclude_border:
# remove peaks fall in the exclude region
mask &= inner_mask[obj]
coordinates = _get_high_intensity_peaks(img_object, mask,
num_peaks_per_label)
nd_indices = tuple(coordinates.T)
mask.fill(False)
mask[nd_indices] = True
out[obj] += mask
if not indices and cp.isinf(num_peaks):
return out
coordinates = _get_high_intensity_peaks(image, out, num_peaks)
if indices:
return coordinates
else:
out.fill(False)
nd_indices = tuple(coordinates.T)
out[nd_indices] = True
return out
# Non maximum filter
mask = _get_peak_mask(image, min_distance, footprint, threshold_abs,
threshold_rel)
mask = _exclude_border(mask, exclude_border)
# Select highest intensities (num_peaks)
coordinates = _get_high_intensity_peaks(image, mask, num_peaks)
if indices is True:
return coordinates
else:
nd_indices = tuple(coordinates.T)
out[nd_indices] = True
return out
def regionprops(label_image,
intensity_image=None,
cache=True,
coordinates=None,
*,
extra_properties=None):
r"""Measure properties of labeled image regions.
Parameters
----------
label_image : (M, N[, P]) ndarray
Labeled input image. Labels with value 0 are ignored.
.. versionchanged:: 0.14.1
Previously, ``label_image`` was processed by ``numpy.squeeze`` and
so any number of singleton dimensions was allowed. This resulted in
inconsistent handling of images with singleton dimensions. To
recover the old behaviour, use
``regionprops(np.squeeze(label_image), ...)``.
intensity_image : (M, N[, P][, C]) ndarray, optional
Intensity (i.e., input) image with same size as labeled image, plus
optionally an extra dimension for multichannel data.
Default is None.
.. versionchanged:: 0.18.0
The ability to provide an extra dimension for channels was added.
cache : bool, optional
Determine whether to cache calculated properties. The computation is
much faster for cached properties, whereas the memory consumption
increases.
coordinates : DEPRECATED
This argument is deprecated and will be removed in a future version
of scikit-image.
See `Coordinate conventions
<https://scikit-image.org/docs/0.18.x/user_guide/numpy_images.html#coordinate-conventions>`_
for more details.
.. deprecated:: 0.16.0
Use "rc" coordinates everywhere. It may be sufficient to call
``numpy.transpose`` on your label image to get the same values as
0.15 and earlier. However, for some properties, the transformation
will be less trivial. For example, the new orientation is
:math:`\frac{\pi}{2}` plus the old orientation.
extra_properties : Iterable of callables
Add extra property computation functions that are not included with
skimage. The name of the property is derived from the function name,
the dtype is inferred by calling the function on a small sample.
If the name of an extra property clashes with the name of an existing
property the extra property wil not be visible and a UserWarning is
issued. A property computation function must take a region mask as its
first argument. If the property requires an intensity image, it must
accept the intensity image as the second argument.
Returns
-------
properties : list of RegionProperties
Each item describes one labeled region, and can be accessed using the
attributes listed below.
Notes
-----
The following properties can be accessed as attributes or keys:
**area** : int
Number of pixels of the region.
**bbox** : tuple
Bounding box ``(min_row, min_col, max_row, max_col)``.
Pixels belonging to the bounding box are in the half-open interval
``[min_row; max_row)`` and ``[min_col; max_col)``.
**bbox_area** : int
Number of pixels of bounding box.
**centroid** : array
Centroid coordinate tuple ``(row, col)``.
**convex_area** : int
Number of pixels of convex hull image, which is the smallest convex
polygon that encloses the region.
**convex_image** : (H, J) ndarray
Binary convex hull image which has the same size as bounding box.
**coords** : (N, 2) ndarray
Coordinate list ``(row, col)`` of the region.
**eccentricity** : float
Eccentricity of the ellipse that has the same second-moments as the
region. The eccentricity is the ratio of the focal distance
(distance between focal points) over the major axis length.
The value is in the interval [0, 1).
When it is 0, the ellipse becomes a circle.
**equivalent_diameter** : float
The diameter of a circle with the same area as the region.
**euler_number** : int
Euler characteristic of the set of non-zero pixels.
Computed as number of connected components subtracted by number of
holes (input.ndim connectivity). In 3D, number of connected
components plus number of holes subtracted by number of tunnels.
**extent** : float
Ratio of pixels in the region to pixels in the total bounding box.
Computed as ``area / (rows * cols)``
**feret_diameter_max** : float
Maximum Feret's diameter computed as the longest distance between
points around a region's convex hull contour as determined by
``find_contours``. [5]_
**filled_area** : int
Number of pixels of the region will all the holes filled in. Describes
the area of the filled_image.
**filled_image** : (H, J) ndarray
Binary region image with filled holes which has the same size as
bounding box.
**image** : (H, J) ndarray
Sliced binary region image which has the same size as bounding box.
**inertia_tensor** : ndarray
Inertia tensor of the region for the rotation around its mass.
**inertia_tensor_eigvals** : tuple
The eigenvalues of the inertia tensor in decreasing order.
**intensity_image** : ndarray
Image inside region bounding box.
**label** : int
The label in the labeled input image.
**local_centroid** : array
Centroid coordinate tuple ``(row, col)``, relative to region bounding
box.
**major_axis_length** : float
The length of the major axis of the ellipse that has the same
normalized second central moments as the region.
**max_intensity** : float
Value with the greatest intensity in the region.
**mean_intensity** : float
Value with the mean intensity in the region.
**min_intensity** : float
Value with the least intensity in the region.
**minor_axis_length** : float
The length of the minor axis of the ellipse that has the same
normalized second central moments as the region.
**moments** : (3, 3) ndarray
Spatial moments up to 3rd order::
m_ij = sum{ array(row, col) * row^i * col^j }
where the sum is over the `row`, `col` coordinates of the region.
**moments_central** : (3, 3) ndarray
Central moments (translation invariant) up to 3rd order::
mu_ij = sum{ array(row, col) * (row - row_c)^i * (col - col_c)^j }
where the sum is over the `row`, `col` coordinates of the region,
and `row_c` and `col_c` are the coordinates of the region's centroid.
**moments_hu** : tuple
Hu moments (translation, scale and rotation invariant).
**moments_normalized** : (3, 3) ndarray
Normalized moments (translation and scale invariant) up to 3rd order::
nu_ij = mu_ij / m_00^[(i+j)/2 + 1]
where `m_00` is the zeroth spatial moment.
**orientation** : float
Angle between the 0th axis (rows) and the major
axis of the ellipse that has the same second moments as the region,
ranging from `-pi/2` to `pi/2` counter-clockwise.
**perimeter** : float
Perimeter of object which approximates the contour as a line
through the centers of border pixels using a 4-connectivity.
**perimeter_crofton** : float
Perimeter of object approximated by the Crofton formula in 4
directions.
**slice** : tuple of slices
A slice to extract the object from the source image.
**solidity** : float
Ratio of pixels in the region to pixels of the convex hull image.
**weighted_centroid** : array
Centroid coordinate tuple ``(row, col)`` weighted with intensity
image.
**weighted_local_centroid** : array
Centroid coordinate tuple ``(row, col)``, relative to region bounding
box, weighted with intensity image.
**weighted_moments** : (3, 3) ndarray
Spatial moments of intensity image up to 3rd order::
wm_ij = sum{ array(row, col) * row^i * col^j }
where the sum is over the `row`, `col` coordinates of the region.
**weighted_moments_central** : (3, 3) ndarray
Central moments (translation invariant) of intensity image up to
3rd order::
wmu_ij = sum{ array(row, col) * (row - row_c)^i * (col - col_c)^j }
where the sum is over the `row`, `col` coordinates of the region,
and `row_c` and `col_c` are the coordinates of the region's weighted
centroid.
**weighted_moments_hu** : tuple
Hu moments (translation, scale and rotation invariant) of intensity
image.
**weighted_moments_normalized** : (3, 3) ndarray
Normalized moments (translation and scale invariant) of intensity
image up to 3rd order::
wnu_ij = wmu_ij / wm_00^[(i+j)/2 + 1]
where ``wm_00`` is the zeroth spatial moment (intensity-weighted area).
Each region also supports iteration, so that you can do::
for prop in region:
print(prop, region[prop])
See Also
--------
label
References
----------
.. [1] Wilhelm Burger, Mark Burge. Principles of Digital Image Processing:
Core Algorithms. Springer-Verlag, London, 2009.
.. [2] B. Jähne. Digital Image Processing. Springer-Verlag,
Berlin-Heidelberg, 6. edition, 2005.
.. [3] T. H. Reiss. Recognizing Planar Objects Using Invariant Image
Features, from Lecture notes in computer science, p. 676. Springer,
Berlin, 1993.
.. [4] https://en.wikipedia.org/wiki/Image_moment
.. [5] W. Pabst, E. Gregorová. Characterization of particles and particle
systems, pp. 27-28. ICT Prague, 2007.
https://old.vscht.cz/sil/keramika/Characterization_of_particles/CPPS%20_English%20version_.pdf
Examples
--------
>>> from skimage import data, util
>>> from cucim.skimage.measure import label, regionprops
>>> img = cp.asarray(util.img_as_ubyte(data.coins()) > 110)
>>> label_img = label(img, connectivity=img.ndim)
>>> props = regionprops(label_img)
>>> # centroid of first labeled object
>>> props[0].centroid
(22.72987986048314, 81.91228523446583)
>>> # centroid of first labeled object
>>> props[0]['centroid']
(22.72987986048314, 81.91228523446583)
Add custom measurements by passing functions as ``extra_properties``
>>> from skimage import data, util
>>> from cucim.skimage.measure import label, regionprops
>>> import numpy as np
>>> img = cp.asarray(util.img_as_ubyte(data.coins()) > 110)
>>> label_img = label(img, connectivity=img.ndim)
>>> def pixelcount(regionmask):
... return np.sum(regionmask)
>>> props = regionprops(label_img, extra_properties=(pixelcount,))
>>> props[0].pixelcount
7741
>>> props[1]['pixelcount']
42
"""
if label_image.ndim not in (2, 3):
raise TypeError('Only 2-D and 3-D images supported.')
if not cp.issubdtype(label_image.dtype, cp.integer):
if cp.issubdtype(label_image.dtype, bool):
raise TypeError('Non-integer image types are ambiguous: '
'use skimage.measure.label to label the connected'
'components of label_image,'
'or label_image.astype(np.uint8) to interpret'
'the True values as a single label.')
else:
raise TypeError('Non-integer label_image types are ambiguous')
if coordinates is not None:
if coordinates == 'rc':
msg = ('The coordinates keyword argument to skimage.measure.'
'regionprops is deprecated. All features are now computed '
'in rc (row-column) coordinates. Please remove '
'`coordinates="rc"` from all calls to regionprops before '
'updating scikit-image.')
warn(msg, stacklevel=2, category=FutureWarning)
else:
msg = ('Values other than "rc" for the "coordinates" argument '
'to skimage.measure.regionprops are no longer supported. '
'You should update your code to use "rc" coordinates and '
'stop using the "coordinates" argument, or use skimage '
'version 0.15.x or earlier.')
raise ValueError(msg)
regions = []
# CuPy Backend: ndimage.find_objects not implemented
objects = cpu_find_objects(cp.asnumpy(label_image)) # synchronize!
for i, sl in enumerate(objects):
if sl is None:
continue
label = i + 1
props = RegionProperties(sl,
label,
label_image,
intensity_image,
cache,
extra_properties=extra_properties)
regions.append(props)
return regions