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 2dimensional numpy array assigning each pixel of an image to a segment by using unique integers from a sequence starting at 1. Thekwargs
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:
2dimensional arrays for grayscale (0–255 range) and blackandwhite (0 and 255 valued) images; and
3dimensional arrays for colour images.
The segmentation stored by this class can be overwritten either with the
set_segments
method or by directly setting thesegments
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 blackandwhite. kwargsdictionary
A list of named parameters stored as a dictionary; it is used to pass configuration options to the
_segment
method.segments
numpy.ndarrayRetrieves the segments.
 segments_numberinteger
The number of segments.
 Raises
 IncorrectShapeError
The input
image
is neither a 2 nor 3dimensional numpy array. The width and height ofimage
andsegmentation_mask
do not agree. The segmentation array is not 2dimensional. The the height or width the segmentation array does not agree with the dimensions of the segmented image. RuntimeError
A blackandwhite 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 integervalued 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 RGBimage
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 thesegments_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; ifFalse
, 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 theimage
is not RGB. RuntimeError
The class has been initialised with a blackandwhite or grayscale image.
 TypeError
The
mask
parameter is not a boolean. Thesegments_subset
parameter is neitherNone
, 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 externalimage
of the same dimensions can be supplied. By default all the segments are highlighted; a selected subset of segments can be highlighted by providing thesegments_subset
parameter. The segments are highlighted with different colours by default (colour=None
); alternatively, a single colour can be supplied with thecolour
parameter. It is also possible to specify a unique colour for each segment by settingcolour
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; ifFalse
, 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. Thecolour
parameter is neither ofNone
, a tuple or a list of tuples; or one of its elements is not an integer. Thesegments_subset
parameter is neitherNone
, 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 3tuple or one of its elements is outside of the 0–255 range. One of the segment ids provided viasegments_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 externalimage
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; ifFalse
, 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. Thecolour
parameter is neither a tuple nor aNone
; or one of its elements is not an integer. ValueError
The
colour
parameter is not a 3tuple, 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 2dimensional numpy array holding the merged segmentation.
 Raises
 IncorrectShapeError
The
segments
array is not 2dimensional. The the height or width thesegments
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 integervalued 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 externalimage
of the same dimensions can be supplied. By default all the segments are numbered; a selected subset of segments can be numbered by providing thesegments_subset
parameter. The colour of the numbers can be specified via thecolour
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; ifFalse
, 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. Thecolour
parameter is neither a tuple nor aNone
; or one of its elements is not an integer. Thesegments_subset
parameter is neitherNone
, 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 3tuple, one of its elements is outside of the 0–255 range. One of the segment ids provided viasegments_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 nonstructured, 2dimensional, integervalued numpy array with a continuous sequence of unique elements starting at 1, which indicate the segment assignment of each pixel. The dimension ofsegments
must agree with the width and height of the segmented image.Note
The same can be achieved by directly setting the
self.segments
withmy_segmenter.segments = segments
. (A dedicated setter method takes care of validating the correctness ofsegments
.) Parameters
 segmentsnumpy.ndarray
A 2dimensional numpy array representing a segmentation.
 Raises
 IncorrectShapeError
The
segments
array is not 2dimensional. The the height or width thesegments
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 integervalued 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.