`fatf.utils.data.occlusion`.Occlusion¶

class fatf.utils.data.occlusion.Occlusion(image: numpy.ndarray, segments: numpy.ndarray, colour: Union[str, int, Tuple[int, int, int], None] = None)[source]¶

Implements functionality for (partiall) occlusion a segmented image.

New in version 0.1.1.

This class allows to occlude specified segments of an image with a selected colouring strategy. 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 colouring strategy used by this class can be overwritten either with the set_colouring_strategy method or by directly setting the colouring_strategy attribute, both of which will perform the necessary validation.

Parameters

imagenumpy.ndarray: A numpy array representing an image to be occluded.
segmentsnumpy.ndarray: A 2-dimensional numpy array defining segmentation of an image (each unique integer – in sequence starting at 1 – indicates segment id of the pixel at this coordinate).
colourstring, integer or tuple(integer, integer, integer), optional (default=None): One of the colour specifier strings: 'mean', 'black', 'white', 'red', 'green', 'blue', 'pink', 'random', 'random-patch', 'randomise' or 'randomise-patch'. For black-and-white and grayscale images it can be an integer specifying respectively black or white (0 or 255) and intensity (0–255). RGB images, on the other hand, accept RGB triplets. See the documentation of the fatf.utils.data.occlusion.Occlusion.set_colouring_strategy method for more details. By default (None) the mean-colour occlusion is selected for colour and grayscale images, and black occlusion for black-and-white images.

Attributes

imagenumpy.ndarray: A numpy array representing an image to be occluded.
segmentsnumpy.ndarray: A 2-dimensional numpy array representing segmentation of the image.
is_rgbboolean: Indicates whether the image is RGB or grayscale/black-and-white.
is_bnwboolean: Indicates whether the image is black-and-white.
unique_segmentsnumpy.ndarray: A 1-D numpy array holding unique segmentation ids.
segments_numberinteger: The number of segments.
colouring_strategycallable(image indices): Retrieves the colouring strategy.

Raises

IncorrectShapeError: The input image is neither a 2- nor 3-dimensional numpy array. 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.
RuntimeError: A black-and-white image does not use 0 as black and 1 or 255 as white. The mean-colour occlusion was selected for a black-and-white image.
TypeError: The input image is either a structured numpy array or it is not a numerical array. The segments array is either a structured numpy array or it is not an integer-valued array. The colour specifier is neither None, a string, an integer or a tuple; or one of the tuple elements is not an integer.
ValueError: The elements of the input image are not integers in the 0–255 range. The unique elements of the segments array do not form a continuous sequence starting at 1. The colour string specifier refers to an unknown colouring strategy name. An colour integer specifier for a black-and-white image is neither 0 for black nor 1 or 255 for white. A colour component for an RGB image or pixel intensity for a grayscale image is outside of the 0–255 range. An RGB colour specifier is not a 3-tuple.

Methods

`occlude_segments`(segments_subset, …)	Generates the image with a specified subset of segments occluded.
`occlude_segments_vectorised`(…)	Generates multiple images with a selected subsets of segments occluded.
`set_colouring_strategy`(colour, int, …)	Selects the colouring strategy.

colouring_strategy¶: Retrieves the colouring strategy.

occlude_segments(segments_subset: Union[int, List[int]], image: Optional[numpy.ndarray] = None, colour: Union[str, int, Tuple[int, int, int], None] = None) → numpy.ndarray[source]¶

Generates the image with a specified subset of segments occluded.

The occlusion is applied on top of the image used to initialise this class; alternatively, an external image of the same type and dimensions can be supplied. If a colouring strategy different to the one of the class is desired, it can be specified via the colour parameter.

Parameters

segments_subsetintiger or list(integer): An id of a specific segment or a list of segment ids to be occluded.
imagenumpy.ndarray, optional (default=None): If provided, this image will be occluded instead of the one used to initialise this class.
colourstring, integer, tuple(integer, integer, integer), optional (default=None): A colour specifier. By default (colour=None) the colouring strategy of the class is used. See the documentation of the fatf.utils.data.occlusion.Occlusion.set_colouring_strategy method for more details.

Returns

image_occludednumpy.ndarray: A numpy array holding the image with the selected subset of segments occluded.

Raises

IncorrectShapeError: The input image is neither a 2- nor 3-dimensional numpy array. The the height, width or the number of channels in the image array does not agree with the same parameters of the class image.
TypeError: The segments_subset parameter is neither an integer nor 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 or some of its elements are duplicated.

occlude_segments_vectorised(vectorised_segments_subset: numpy.ndarray, image: Optional[numpy.ndarray] = None, colour: Union[str, int, Tuple[int, int, int], None] = None) → numpy.ndarray[source]¶

Generates multiple images with a selected subsets of segments occluded.

The segments to be occluded are provided as boolean vectors; either a 1-D numpy array of length equal to the number of segments to produce a single occluded image, or a 2-D array where each row represents a separate occlusion pattern. In this format the n-th element or column corresponds to the the n+1 segment id; 1 indicates that the segment should be preserved and 0 that it should be occluded.

Parameters

vectorised_segments_subsetnumpy.ndarray: A 1-D boolean occlusion vector of the length equal to the number of segments or a 2-D boolean matrix of the (number of occlusion images to generate X number of segments) shape.
imagenumpy.ndarray, optional (default=None): If provided, this image will be occluded instead of the one used to initialise this class.
colourstring, integer, tuple(integer, integer, integer), optional (default=None): A colour specifier. By default (colour=None) the colouring strategy of the class is used. See the documentation of the fatf.utils.data.occlusion.Occlusion.set_colouring_strategy method for more details.

Returns

image_occludednumpy.ndarray: A numpy array holding the image(s) with the selected subset(s) of segments occluded.

Raises

IncorrectShapeError: The vectorised_segments_subset numpy array is neither 1- nor 2-dimensional. The number of elements in vectorised_segments_subset (when it is 1-D) does not correspond to the number of segments. The number of columns in vectorised_segments_subset (when it is 2-D) does not correspond to the number of segments. The input image is neither a 2- nor 3-dimensional numpy array. The the height, width or the number of channels in the image array does not agree with the same parameters of the class image.
TypeError: The vectorised_segments_subset numpy array is not boolean.

set_colouring_strategy(colour: Union[str, int, Tuple[int, int, int]])[source]¶

Selects the colouring strategy.

For colour images this can be specified with one of the following strings:

'mean' – the mean RGB colour of each segment;
'black' – RGB black (0, 0, 0);
'white' – RGB white (255, 255, 255);
'red' – RGB white (255, 0, 0);
'green' – RGB white (0, 255, 0);
'blue' – RGB white (0, 0, 255);
'pink' – RGB white (255, 192, 203);
'random' – a single random RGB colour for all the segments;
'random-patch' – a separate random RGB colour for each segment;
'randomise' – for each occlusion procedure randomly select a single RGB occlusion colour for all the segments; or
'randomise-patch' – for each occlusion procedure randomly select a separate random RGB colour for each segment.

Alternatively, it can be a user-defined RGB colour provided as a 3-tuple with values in the 0–255 range. For black-and-white and grayscale images the string specifier can be one of:

'black' – black (0);
'white' – white (255);
'random' – a single random 0–255 intensity for all the segments for grayscale images and one of 0 or 255 for black-and-white images;
'random-patch' – a separate random intensity for each segment;
'randomise' – for each occlusion procedure randomly select a single occlusion intensity for all the segments; or
'randomise-patch' – for each occlusion procedure randomly select a separate random intensity for each segment.

Alternatively, it can be a user-defined intensity provided as an integer with values in the 0–255 range for grayscale images or 0 or 255 for black-and-white images.

The colouring strategy is constructed as a callable object (a function) that takes in a boolean numpy array of the same dimensions as segments and returns a numpy array with the colours generated according to the desired colouring strategy.

Note

When None is passed as the colour, the mean-colour occlusion is selected.

Parameters

colourstring, integer, tuple(integer, integer, integer) or None: A colour specifier.

Raises

RuntimeError: The mean-colour occlusion was selected for a black-and-white image.
TypeError: The colour specifier is neither None, a string, an integer or a tuple; or one of the tuple elements is not an integer.
ValueError: The colour string specifier refers to an unknown colouring strategy name. An colour integer specifier for a black-and-white image is neither 0 for black nor 1 or 255 for white. A colour component for an RGB image or pixel intensity for a grayscale image is outside of the 0–255 range. An RGB colour specifier is not a 3-tuple.

fatf.utils.data.occlusion.Occlusion¶

`fatf.utils.data.occlusion`.Occlusion¶