`fatf.utils.data.segmentation`.Segmentation¶

class fatf.utils.data.segmentation.Segmentation(image: numpy.ndarray, segmentation_mask: Optional[numpy.ndarray] = None, **kwargs)[source]¶

An abstract class implementing image segmentation functionality.

New in version 0.1.1.

An abstract class that all segmentation classes should inherit from. It contains an abstract _segment method to be implemented by individual segmenters. This methods should return a 2-dimensional numpy array assigning each pixel of an image to a segment by using unique integers from a sequence starting at 1. The kwargs attribute can be used to collect optional parameters upon initialising this class that can be used within the _segment method.

This class is designed for images represented as numpy arrays with their values in the 0–255 range:

2-dimensional arrays for grayscale (0–255 range) and black-and-white (0 and 255 valued) images; and
3-dimensional arrays for colour images.

The segmentation stored by this class can be overwritten either with the set_segments method or by directly setting the segments attribute, both of which will perform the necessary validation.

Parameters

imagenumpy.ndarray: A numpy array representing an image to be segmented.
segmentation_masknumpy.ndarray, optional (default=None): A numpy array representing an image to be used for generating the segmentation. If this parameter is not provided, the image will be used to generate the segmentation.
**kwargsdictionary: A list of named parameters saved to the kwargs attribute, which can be used to pass configuration options to the _segment method.

Attributes

imagenumpy.ndarray: A numpy array representing an image to be segmented.
segmentation_masknumpy.ndarray: A numpy array representing an image used to perform segmentation.
is_rgbboolean: Indicates whether the image is RGB or black-and-white.
kwargsdictionary: A list of named parameters stored as a dictionary; it is used to pass configuration options to the _segment method.
segmentsnumpy.ndarray: Retrieves the segments.
segments_numberinteger: The number of segments.

Raises

IncorrectShapeError: The input image is neither a 2- nor 3-dimensional numpy array. The width and height of image and segmentation_mask do not agree. The segmentation array is not 2-dimensional. The the height or width the segmentation array does not agree with the dimensions of the segmented image.
RuntimeError: A black-and-white image does not use 0 as black and 1 or 255 as white.
TypeError: The input image is either a structured numpy array or it is not a numerical array. The segmentation array is either a structured numpy array or it is not an integer-valued array.
ValueError: The elements of the input image are not integers in the 0–255 range. The unique elements of the segmentation array do not form a continuous sequence starting at 1.

Warns

UserWarning: Inform the user that only a single segment was found.

Methods

`grayout_segments`(segments_subset, List[int], …)	Grays out a selected subset of segments in the RGB image.
`highlight_segments`(segments_subset, …)	Highlights image segments by translucently colouring them.
`mark_boundaries`(mask, image, colour, int, …)	Marks segment boundaries atop the image used to initialise this class.
`merge_segments`(segments_grouping, …)	Merges segments based on the provided grouping.
`number_segments`(segments_subset, List[int], …)	Plots segment numbers on top of the image.
`set_segments`(segments)	Manually overwrites the segmentation with custom `segments`.

grayout_segments(segments_subset: Union[int, List[int], None] = None, mask: bool = False, image: Optional[numpy.ndarray] = None) → numpy.ndarray[source]¶

Grays out a selected subset of segments in the RGB image.

The graying out can either be applied on top of the image or segmentation mask (mask=True) used to initialise this class. Alternatively, an external RGB image of the same dimensions can be supplied. By default all the segments are grayed out; a selected subset of segments can be grayed out by providing the segments_subset parameter.

Parameters

segments_subsetinteger or list(integer), optional (default=None): A number of a specific segment or a list of segments to be grayed out. By default (None) all the segments are grayed out.
maskboolean, optional (default=False): If True, gray out the segmentation mask; if False, gray out the image (default).
imagenumpy.ndarray, optional (default=None): If provided, this image will be grayed out instead of the one used to initialise this segmenter.

Returns

image_grayscalenumpy.ndarray: A numpy array holding the image with the selected subset of segments grayed out.

Raises

IncorrectShapeError: The the height or width the image array does not agree with the dimensions of the class image or the image is not RGB.
RuntimeError: The class has been initialised with a black-and-white or grayscale image.
TypeError: The mask parameter is not a boolean. The segments_subset parameter is neither None, an integer, or a list of integers; one of the segment ids in this list is not an integer.
ValueError: One of the segment ids provided via segments_subset is invalid for the class segmentation, the list of segments is empty or some of its elements are duplicated.

highlight_segments(segments_subset: Union[int, List[int], None] = None, mask: bool = False, image: Optional[numpy.ndarray] = None, colour: Union[Tuple[int, int, int], List[Tuple[int, int, int]], None] = None) → numpy.ndarray[source]¶

Highlights image segments by translucently colouring them.

The highlighting can either be applied on top of the image or segmentation mask (mask=True) used to initialise this class. Alternatively, an external image of the same dimensions can be supplied. By default all the segments are highlighted; a selected subset of segments can be highlighted by providing the segments_subset parameter. The segments are highlighted with different colours by default (colour=None); alternatively, a single colour can be supplied with the colour parameter. It is also possible to specify a unique colour for each segment by setting colour to a list of RGB triplets; in this case the list must have the same length as the number of segments being highlighted.

Parameters

segments_subsetintiger or list(integer), optional (default=None): A number of a specific segment or a list of segments to be highlighted. By default (None) all the segments are highlighted.
maskboolean, optional (default=False): If True, highlight the segmentation mask; if False, highlight the image (default).
imagenumpy.ndarray, optional (default=None): If provided, this image will be highlighted instead of the one used to initialise this segmenter.
colourtuple(integer, integer, integer) or list(tuple(integer, integer, integer)), optional (default=None): If provided, the regions will be highlighted with a single RGB colour or each segment will be highlighted with its unique colour. By default (None) every segment receives a unique colour.

Returns

image_highlightednumpy.ndarray: A numpy array holding the image with the selected subset of segments highlighted.

Raises

IncorrectShapeError: The the height or width the image array does not agree with the dimensions of the class image.
TypeError: The mask parameter is not a boolean. The colour parameter is neither of None, a tuple or a list of tuples; or one of its elements is not an integer. The segments_subset parameter is neither None, an integer, or a list of integers; one of the segment ids in this list is not an integer.
ValueError: If colour is provided as a list, the list is either empty or the number of colours provided is not the same as the number of segments chosen to be highlighted. A colour is not a 3-tuple or one of its elements is outside of the 0–255 range. One of the segment ids provided via segments_subset is invalid for the class segmentation, the list of segments is empty or some of its elements are duplicated.

mark_boundaries(mask: bool = False, image: Optional[numpy.ndarray] = None, colour: Optional[Tuple[int, int, int]] = None) → numpy.ndarray[source]¶

Marks segment boundaries atop the image used to initialise this class.

The boundaries can either be overlaid on top of the image or segmentation mask (mask=True) used to initialise this class. Alternatively, an external image of the same dimensions can be supplied.

Note

If the image is grayscale, it will be converted to RGB to display the segment boundaries.

Parameters

maskboolean, optional (default=False): If True, plot the segment boundaries on top of the segmentation mask; if False, plot the segment boundaries atop the image.
imagenumpy.ndarray, optional (default=None): If provided, the segment boundaries will be overlaid atop this image instead of the one used to initialise this segmenter.
colourtuple(integer, integer, integer), optional (default=None): If provided, the segment boundaries will be plotted with this RGB colour.

Returns

marked_imagenumpy.ndarray: A numpy array holding the image with overlaid segment boundaries.

Raises

IncorrectShapeError: The the height or width the image array does not agree with the dimensions of the class image.
TypeError: The mask parameter is not a boolean. The colour parameter is neither a tuple nor a None; or one of its elements is not an integer.
ValueError: The colour parameter is not a 3-tuple, one of its elements is outside of the 0–255 range.

merge_segments(segments_grouping: Union[List[int], List[List[int]]], inplace: bool = True, segments: Optional[numpy.ndarray] = None) → numpy.ndarray[source]¶

Merges segments based on the provided grouping.

The merging can either be applied to the segmentation stored in the class to a segmentation passed as a parameter (segments). By default (inplace=True) the segmentation stored in the class will be updated to the merged segmentation.

Parameters

segments_groupinglist(integer) or list(list(integer)): A collection or a set of collections of segment ids to be merged.
inplaceboolean, optional (default=True): If True, overwrite the segmentation stored in the class.
segmentsnumpy.ndarray, optional (default=None): If provided, the merging will be performed on this segmentation instead of the one stored in the class.

Returns

merged_segmentsnumpy.ndarray: A 2-dimensional numpy array holding the merged segmentation.

Raises

IncorrectShapeError: The segments array is not 2-dimensional. The the height or width the segments array does not agree with the dimensions of the segmented image.
TypeError: The segments array is either a structured numpy array or it is not an integer-valued array. The inplace parameter is not a boolean. The segments grouping is not a list of integers or lists. One of the segment ids is not an integer.
ValueError: The unique elements of the segments array do not form a continuous sequence starting at 1. The segments grouping is an empty lists or the list has duplicates. One of the segment ids is invalid or appears across different groupings.

Warns

UserWarning: Inform the user that only a single segment is being created.

number_segments(segments_subset: Union[int, List[int], None] = None, mask: bool = False, image: Optional[numpy.ndarray] = None, colour: Optional[Tuple[int, int, int]] = None) → numpy.ndarray[source]¶

Plots segment numbers on top of the image.

The numbering can either be overlaid on top of the image or segmentation mask (mask=True) used to initialise this class. Alternatively, an external image of the same dimensions can be supplied. By default all the segments are numbered; a selected subset of segments can be numbered by providing the segments_subset parameter. The colour of the numbers can be specified via the colour parameter by passing an RGB triplet.

Note

The numbers may not be printed within the bounds of their respective segments when these are not convex.

Parameters

segments_subsetintiger or list(integer), optional (default=None): A number of a specific segment to be numbered or a list of segments to be numbered. By default (None) all the segments are numbered.
maskboolean, optional (default=False): If True, number the segmentation mask; if False, number the image (default).
imagenumpy.ndarray, optional (default=None): If provided, this image will be numbered instead of the one used to initialise this segmenter.
colourtuple(integer, integer, integer), optional (default=None): If provided, the numbers will be plotted with this RGB colour.

Returns

numbered_imagenumpy.ndarray: A numpy array holding the image with the selected subset of segments numbered.

Raises

IncorrectShapeError: The the height or width the image array does not agree with the dimensions of the class image.
TypeError: The mask parameter is not a boolean. The colour parameter is neither a tuple nor a None; or one of its elements is not an integer. The segments_subset parameter is neither None, an integer, or a list of integers; one of the segment ids in this list is not an integer.
ValueError: The colour parameter is not a 3-tuple, one of its elements is outside of the 0–255 range. One of the segment ids provided via segments_subset is invalid for the class segmentation, the list of segments is empty or some of its elements are duplicated.

segments¶: Retrieves the segments.

set_segments(segments: numpy.ndarray)[source]¶

Manually overwrites the segmentation with custom segments.

segments must be a non-structured, 2-dimensional, integer-valued numpy array with a continuous sequence of unique elements starting at 1, which indicate the segment assignment of each pixel. The dimension of segments must agree with the width and height of the segmented image.

Note

The same can be achieved by directly setting the self.segments with my_segmenter.segments = segments. (A dedicated setter method takes care of validating the correctness of segments.)

Parameters

segmentsnumpy.ndarray: A 2-dimensional numpy array representing a segmentation.

Raises

IncorrectShapeError: The segments array is not 2-dimensional. The the height or width the segments array does not agree with the dimensions of the segmented image.
TypeError: The segments array is either a structured numpy array or it is not an integer-valued array.
ValueError: The unique elements of the segments array do not form a continuous sequence starting at 1.

Warns

UserWarning: Inform the user that the segmentation has only one segment.

fatf.utils.data.segmentation.Segmentation¶

`fatf.utils.data.segmentation`.Segmentation¶