SegmentationImage

class photutils.SegmentationImage(data)[source]

Bases: object

Class for a segmentation image.

Parameters:

data : array_like (int)

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

Attributes Summary

areas The areas (in pixel**2) of all labeled regions.
array The 2D segmentation image.
data The 2D segmentation image.
data_masked A MaskedArray version of the segmentation image where the background (label = 0) has been masked.
is_sequential Determine whether or not the non-zero labels in the segmenation image are sequential (with no missing values).
labels The sorted non-zero labels in the segmentation image.
max The maximum non-zero label in the segmentation image.
nlabels The number of non-zero labels in the segmentation image.
shape The shape of the 2D segmentation image.
slices The minimal bounding box slices for each labeled region.

Methods Summary

area(labels) The areas (in pixel**2) of the regions for the input labels.
check_label(label[, allow_zero]) Check for a valid label label number 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_sequential([start_label]) Relabel the label numbers sequentially, such that there are no missing label numbers (up to the maximum label number).
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

The areas (in pixel**2) of all labeled regions.

array

The 2D segmentation image.

data

The 2D segmentation image.

data_masked

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

is_sequential

Determine whether or not the non-zero labels in the segmenation image are sequential (with no missing values).

labels

The sorted non-zero labels in the segmentation image.

max

The maximum non-zero label in the segmentation image.

nlabels

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

shape

The shape of the 2D segmentation image.

slices

The minimal bounding box slices for each labeled region.

Methods Documentation

area(labels)[source]

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

Parameters:

labels : int, array-like (1D, 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]

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.

cmap(background_color=u'#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.

Deep copy is used so that all attributes and values are copied.

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 sequential 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_sequential(start_label=1)[source]

Relabel the label numbers sequentially, 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_sequential()
>>> 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]])
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 sequential 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 sequential 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 (the 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 sequential 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]])