fatf.utils.data.segmentation.QuickShift

class fatf.utils.data.segmentation.QuickShift(image: numpy.ndarray, segmentation_mask: Optional[numpy.ndarray] = None, ratio: float = 0.2, kernel_size: float = 4, max_dist: float = 200)

Wraps the quickshift segmentation algorithm implemented in scikit-image.

New in version 0.1.1.

This class provides an interface for the quickshift segmentation implemented by the skimage.segmentation.quickshift function.

For the documentation see the specification of the fatf.utils.data.segmentation.Segmentation abstract class. The initialisation parameters specific to the quickshift segmenter are documented below. The parameter values for ratio, kernel_size and max_dist are by default set to the values used by the official LIME implementation.

Parameters

rationumber, optional (default=0.2)

Balances color-space proximity and image-space proximity. Higher values give more weight to color-space. Between 0 and 1.

kernel_sizenumber, optional (default=4)

Width of Gaussian kernel used in smoothing the sample density. Higher means fewer clusters.

max_distnumber, optional (default=200)

Cut-off point for data distances. Higher means fewer clusters.

Attributes

segments

Retrieves the segments.

Raises

TypeError

The ratio, kernel size or max dist parameter is not an integer.

ValueError

The ratio parameter is outside of the 0–1 range.

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

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

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

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

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

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)

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.