SegmentationImage

class photutils.SegmentationImage(data)[source]

Bases: object

Class for a segmentation image.

Parameters:
data : array_like (int)

A 2D segmentation image where source regions are labeled by different positive integer values. A value of zero is reserved for the background.

Attributes Summary

areas A 1D array of areas (in pixel**2) of the non-zero labeled regions.
data The 2D segmentation image.
data_ma A MaskedArray version of the segmentation image where the background (label = 0) has been masked.
data_masked

Deprecated since version 0.5.

is_consecutive Determine whether or not the non-zero labels in the segmenation image are consecutive (i.e.
is_sequential

Deprecated since version 0.5.

labels The sorted non-zero labels in the segmentation image.
max

Deprecated since version 0.5.

max_label The maximum non-zero label in the segmentation image.
missing_labels A 1D ndarray of the sorted non-zero labels that are missing in the consecutive sequence from zero to the maximum label number.
nlabels The number of non-zero labels in the segmentation image.
segments A list of Segment objects.
shape The shape of the 2D segmentation image.
slices A list of tuples, where each tuple contains two slices representing the minimal box that contains the labeled region.

Methods Summary

area(labels)

Deprecated since version 0.5.

check_label(label[, allow_zero])

Deprecated since version 0.5.

check_labels(labels) Check that the input label(s) are valid label numbers within the segmentation image.
cmap([background_color, random_state]) A matplotlib colormap consisting of random (muted) colors.
copy() Return a deep copy of this class instance.
keep_labels(labels[, relabel]) Keep only the specified label numbers.
outline_segments([mask_background]) Outline the labeled segments.
relabel(labels, new_label) Relabel one or more label numbers.
relabel_consecutive([start_label]) Relabel the label numbers consecutively, such that there are no missing label numbers (up to the maximum label number).
relabel_sequential([start_label])

Deprecated since version 0.5.

remove_border_labels(border_width[, …]) Remove labeled segments near the image border.
remove_labels(labels[, relabel]) Remove one or more label numbers.
remove_masked_labels(mask[, …]) Remove labeled segments located within a masked region.

Attributes Documentation

areas

A 1D array of areas (in pixel**2) of the non-zero labeled regions.

The ndarray starts with the non-zero label The returned array has a length equal to the maximum label number. If a label number is missing, then 0 is returned for that array element.

data

The 2D segmentation image.

data_ma

A MaskedArray version of the segmentation image where the background (label = 0) has been masked.

data_masked

Deprecated since version 0.5: The data_masked function is deprecated and may be removed in a future version. Use data_ma instead.

is_consecutive

Determine whether or not the non-zero labels in the segmenation image are consecutive (i.e. no missing values).

is_sequential

Deprecated since version 0.5: The is_sequential function is deprecated and may be removed in a future version. Use is_consecutive instead.

labels

The sorted non-zero labels in the segmentation image.

max

Deprecated since version 0.5: The max function is deprecated and may be removed in a future version. Use max_label instead.

max_label

The maximum non-zero label in the segmentation image.

missing_labels

A 1D ndarray of the sorted non-zero labels that are missing in the consecutive sequence from zero to the maximum label number.

nlabels

The number of non-zero labels in the segmentation image.

segments

A list of Segment objects.

The list starts with the non-zero label. The returned list has a length equal to the maximum label number. If a label number is missing from the segmentation image, then None is returned instead of a Segment object.

shape

The shape of the 2D segmentation image.

slices

A list of tuples, where each tuple contains two slices representing the minimal box that contains the labeled region.

The list starts with the non-zero label. The returned list has a length equal to the maximum label number. If a label number is missing, then None is returned for that list element instead of a slice.

Methods Documentation

area(labels)[source]

Deprecated since version 0.5: The area function is deprecated and may be removed in a future version. Use areas[labels-1] instead.

The areas (in pixel**2) of the regions for the input labels.

Parameters:
labels : int, 1D array-like (int)

The label(s) for which to return areas.

Returns:
areas : ndarray

The areas of the labeled regions.

check_label(label, allow_zero=False)[source]

Deprecated since version 0.5: The check_label function is deprecated and may be removed in a future version. Use check_labels instead.

Check for a valid label label number within the segmentation image.

Parameters:
label : int

The label number to check.

allow_zero : bool

If True then a label of 0 is valid, otherwise 0 is invalid.

Raises:
ValueError

If the input label is invalid.

check_labels(labels)[source]

Check that the input label(s) are valid label numbers within the segmentation image.

Parameters:
labels : int, 1D array-like (int)

The label(s) to check.

Raises:
ValueError

If any input labels are invalid.

cmap(background_color='#000000', random_state=None)[source]

A matplotlib colormap consisting of random (muted) colors.

This is very useful for plotting the segmentation image.

Parameters:
background_color : str or None, optional

A hex string in the “#rrggbb” format defining the first color in the colormap. This color will be used as the background color (label = 0) when plotting the segmentation image. The default is black.

random_state : int or RandomState, optional

The pseudo-random number generator state used for random sampling. Separate function calls with the same random_state will generate the same colormap.

copy()[source]

Return a deep copy of this class instance.

keep_labels(labels, relabel=False)[source]

Keep only the specified label numbers.

Parameters:
labels : int, array-like (1D, int)

The label number(s) to keep. Labels of zero and those not in the segmentation image will be ignored.

relabel : bool, optional

If True, then the segmentation image will be relabeled such that the labels are in consecutive order starting from 1.

Examples

>>> from photutils import SegmentationImage
>>> segm = SegmentationImage([[1, 1, 0, 0, 4, 4],
...                           [0, 0, 0, 0, 0, 4],
...                           [0, 0, 3, 3, 0, 0],
...                           [7, 0, 0, 0, 0, 5],
...                           [7, 7, 0, 5, 5, 5],
...                           [7, 7, 0, 0, 5, 5]])
>>> segm.keep_labels(labels=3)
>>> segm.data
array([[0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0],
       [0, 0, 3, 3, 0, 0],
       [0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0]])
>>> segm = SegmentationImage([[1, 1, 0, 0, 4, 4],
...                           [0, 0, 0, 0, 0, 4],
...                           [0, 0, 3, 3, 0, 0],
...                           [7, 0, 0, 0, 0, 5],
...                           [7, 7, 0, 5, 5, 5],
...                           [7, 7, 0, 0, 5, 5]])
>>> segm.keep_labels(labels=[5, 3])
>>> segm.data
array([[0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0],
       [0, 0, 3, 3, 0, 0],
       [0, 0, 0, 0, 0, 5],
       [0, 0, 0, 5, 5, 5],
       [0, 0, 0, 0, 5, 5]])
outline_segments(mask_background=False)[source]

Outline the labeled segments.

The “outlines” represent the pixels just inside the segments, leaving the background pixels unmodified. This corresponds to the mode='inner' in skimage.segmentation.find_boundaries.

Parameters:
mask_background : bool, optional

Set to True to mask the background pixels (labels = 0) in the returned image. This is useful for overplotting the segment outlines on an image. The default is False.

Returns:
boundaries : 2D ndarray or MaskedArray

An image with the same shape of the segmenation image containing only the outlines of the labeled segments. The pixel values in the outlines correspond to the labels in the segmentation image. If mask_background is True, then a MaskedArray is returned.

Examples

>>> from photutils import SegmentationImage
>>> segm = SegmentationImage([[0, 0, 0, 0, 0, 0],
...                           [0, 2, 2, 2, 2, 0],
...                           [0, 2, 2, 2, 2, 0],
...                           [0, 2, 2, 2, 2, 0],
...                           [0, 2, 2, 2, 2, 0],
...                           [0, 0, 0, 0, 0, 0]])
>>> segm.outline_segments()
array([[0, 0, 0, 0, 0, 0],
       [0, 2, 2, 2, 2, 0],
       [0, 2, 0, 0, 2, 0],
       [0, 2, 0, 0, 2, 0],
       [0, 2, 2, 2, 2, 0],
       [0, 0, 0, 0, 0, 0]])
relabel(labels, new_label)[source]

Relabel one or more label numbers.

The input labels will all be relabeled to new_label.

Parameters:
labels : int, array-like (1D, int)

The label numbers(s) to relabel.

new_label : int

The relabeled label number.

Examples

>>> from photutils import SegmentationImage
>>> segm = SegmentationImage([[1, 1, 0, 0, 4, 4],
...                           [0, 0, 0, 0, 0, 4],
...                           [0, 0, 3, 3, 0, 0],
...                           [7, 0, 0, 0, 0, 5],
...                           [7, 7, 0, 5, 5, 5],
...                           [7, 7, 0, 0, 5, 5]])
>>> segm.relabel(labels=[1, 7], new_label=2)
>>> segm.data
array([[2, 2, 0, 0, 4, 4],
       [0, 0, 0, 0, 0, 4],
       [0, 0, 3, 3, 0, 0],
       [2, 0, 0, 0, 0, 5],
       [2, 2, 0, 5, 5, 5],
       [2, 2, 0, 0, 5, 5]])
relabel_consecutive(start_label=1)[source]

Relabel the label numbers consecutively, such that there are no missing label numbers (up to the maximum label number).

Parameters:
start_label : int, optional

The starting label number, which should be a positive integer. The default is 1.

Examples

>>> from photutils import SegmentationImage
>>> segm = SegmentationImage([[1, 1, 0, 0, 4, 4],
...                           [0, 0, 0, 0, 0, 4],
...                           [0, 0, 3, 3, 0, 0],
...                           [7, 0, 0, 0, 0, 5],
...                           [7, 7, 0, 5, 5, 5],
...                           [7, 7, 0, 0, 5, 5]])
>>> segm.relabel_consecutive()
>>> segm.data
array([[1, 1, 0, 0, 3, 3],
       [0, 0, 0, 0, 0, 3],
       [0, 0, 2, 2, 0, 0],
       [5, 0, 0, 0, 0, 4],
       [5, 5, 0, 4, 4, 4],
       [5, 5, 0, 0, 4, 4]])
relabel_sequential(start_label=1)[source]

Deprecated since version 0.5: The relabel_sequential function is deprecated and may be removed in a future version. Use relabel_consecutive() instead.

remove_border_labels(border_width, partial_overlap=True, relabel=False)[source]

Remove labeled segments near the image border.

Labels within the defined border region will be removed.

Parameters:
border_width : int

The width of the border region in pixels.

partial_overlap : bool, optional

If this is set to True (the default), a segment that partially extends into the border region will be removed. Segments that are completely within the border region are always removed.

relabel : bool, optional

If True, then the segmentation image will be relabeled such that the labels are in consecutive order starting from 1.

Examples

>>> from photutils import SegmentationImage
>>> segm = SegmentationImage([[1, 1, 0, 0, 4, 4],
...                           [0, 0, 0, 0, 0, 4],
...                           [0, 0, 3, 3, 0, 0],
...                           [7, 0, 0, 0, 0, 5],
...                           [7, 7, 0, 5, 5, 5],
...                           [7, 7, 0, 0, 5, 5]])
>>> segm.remove_border_labels(border_width=1)
>>> segm.data
array([[0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0],
       [0, 0, 3, 3, 0, 0],
       [0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0]])
>>> segm = SegmentationImage([[1, 1, 0, 0, 4, 4],
...                           [0, 0, 0, 0, 0, 4],
...                           [0, 0, 3, 3, 0, 0],
...                           [7, 0, 0, 0, 0, 5],
...                           [7, 7, 0, 5, 5, 5],
...                           [7, 7, 0, 0, 5, 5]])
>>> segm.remove_border_labels(border_width=1,
...                           partial_overlap=False)
>>> segm.data
array([[0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0],
       [0, 0, 3, 3, 0, 0],
       [7, 0, 0, 0, 0, 5],
       [7, 7, 0, 5, 5, 5],
       [7, 7, 0, 0, 5, 5]])
remove_labels(labels, relabel=False)[source]

Remove one or more label numbers.

Parameters:
labels : int, array-like (1D, int)

The label number(s) to remove. Labels of zero and those not in the segmentation image will be ignored.

relabel : bool, optional

If True, then the segmentation image will be relabeled such that the labels are in consecutive order starting from 1.

Examples

>>> from photutils import SegmentationImage
>>> segm = SegmentationImage([[1, 1, 0, 0, 4, 4],
...                           [0, 0, 0, 0, 0, 4],
...                           [0, 0, 3, 3, 0, 0],
...                           [7, 0, 0, 0, 0, 5],
...                           [7, 7, 0, 5, 5, 5],
...                           [7, 7, 0, 0, 5, 5]])
>>> segm.remove_labels(labels=5)
>>> segm.data
array([[1, 1, 0, 0, 4, 4],
       [0, 0, 0, 0, 0, 4],
       [0, 0, 3, 3, 0, 0],
       [7, 0, 0, 0, 0, 0],
       [7, 7, 0, 0, 0, 0],
       [7, 7, 0, 0, 0, 0]])
>>> segm = SegmentationImage([[1, 1, 0, 0, 4, 4],
...                           [0, 0, 0, 0, 0, 4],
...                           [0, 0, 3, 3, 0, 0],
...                           [7, 0, 0, 0, 0, 5],
...                           [7, 7, 0, 5, 5, 5],
...                           [7, 7, 0, 0, 5, 5]])
>>> segm.remove_labels(labels=[5, 3])
>>> segm.data
array([[1, 1, 0, 0, 4, 4],
       [0, 0, 0, 0, 0, 4],
       [0, 0, 0, 0, 0, 0],
       [7, 0, 0, 0, 0, 0],
       [7, 7, 0, 0, 0, 0],
       [7, 7, 0, 0, 0, 0]])
remove_masked_labels(mask, partial_overlap=True, relabel=False)[source]

Remove labeled segments located within a masked region.

Parameters:
mask : array_like (bool)

A boolean mask, with the same shape as the segmentation image (.data), where True values indicate masked pixels.

partial_overlap : bool, optional

If this is set to True (default), a segment that partially extends into a masked region will also be removed. Segments that are completely within a masked region are always removed.

relabel : bool, optional

If True, then the segmentation image will be relabeled such that the labels are in consecutive order starting from 1.

Examples

>>> from photutils import SegmentationImage
>>> segm = SegmentationImage([[1, 1, 0, 0, 4, 4],
...                           [0, 0, 0, 0, 0, 4],
...                           [0, 0, 3, 3, 0, 0],
...                           [7, 0, 0, 0, 0, 5],
...                           [7, 7, 0, 5, 5, 5],
...                           [7, 7, 0, 0, 5, 5]])
>>> mask = np.zeros_like(segm.data, dtype=np.bool)
>>> mask[0, :] = True    # mask the first row
>>> segm.remove_masked_labels(mask)
>>> segm.data
array([[0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0],
       [0, 0, 3, 3, 0, 0],
       [7, 0, 0, 0, 0, 5],
       [7, 7, 0, 5, 5, 5],
       [7, 7, 0, 0, 5, 5]])
>>> segm = SegmentationImage([[1, 1, 0, 0, 4, 4],
...                           [0, 0, 0, 0, 0, 4],
...                           [0, 0, 3, 3, 0, 0],
...                           [7, 0, 0, 0, 0, 5],
...                           [7, 7, 0, 5, 5, 5],
...                           [7, 7, 0, 0, 5, 5]])
>>> segm.remove_masked_labels(mask, partial_overlap=False)
>>> segm.data
array([[0, 0, 0, 0, 4, 4],
       [0, 0, 0, 0, 0, 4],
       [0, 0, 3, 3, 0, 0],
       [7, 0, 0, 0, 0, 5],
       [7, 7, 0, 5, 5, 5],
       [7, 7, 0, 0, 5, 5]])