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:
2dimensional arrays for grayscale (0–255 range) and blackandwhite (0 and 255 valued) images; and
3dimensional 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 thecolouring_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 2dimensional 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'
,'randompatch'
,'randomise'
or'randomisepatch'
. For blackandwhite 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 thefatf.utils.data.occlusion.Occlusion.set_colouring_strategy
method for more details. By default (None
) the meancolour occlusion is selected for colour and grayscale images, and black occlusion for blackandwhite images.
 Attributes
 imagenumpy.ndarray
A numpy array representing an image to be occluded.
 segmentsnumpy.ndarray
A 2dimensional numpy array representing segmentation of the
image
. is_rgbboolean
Indicates whether the
image
is RGB or grayscale/blackandwhite. is_bnwboolean
Indicates whether the
image
is blackandwhite. unique_segmentsnumpy.ndarray
A 1D numpy array holding unique segmentation ids.
 segments_numberinteger
The number of segments.
colouring_strategy
callable(image indices)Retrieves the colouring strategy.
 Raises
 IncorrectShapeError
The input
image
is neither a 2 nor 3dimensional numpy array. Thesegments
array is not 2dimensional. The the height or width thesegments
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. The meancolour occlusion was selected for a blackandwhite image.
 TypeError
The input
image
is either a structured numpy array or it is not a numerical array. Thesegments
array is either a structured numpy array or it is not an integervalued array. The colour specifier is neitherNone
, 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 thesegments
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 blackandwhite 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 3tuple.
Methods
occlude_segments
(segments_subset, …)Generates the image with a specified subset of segments occluded.
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 thecolour
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 3dimensional numpy array. The the height, width or the number of channels in theimage
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 1D numpy array of length equal to the number of segments to produce a single occluded image, or a 2D array where each row represents a separate occlusion pattern. In this format the nth 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.
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 thecolour
parameter. Parameters
 vectorised_segments_subsetnumpy.ndarray
A 1D boolean occlusion vector of the length equal to the number of segments or a 2D 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 thefatf.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 2dimensional. The number of elements invectorised_segments_subset
(when it is 1D) does not correspond to the number of segments. The number of columns invectorised_segments_subset
(when it is 2D) does not correspond to the number of segments. The inputimage
is neither a 2 nor 3dimensional numpy array. The the height, width or the number of channels in theimage
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;'randompatch'
– 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'randomisepatch'
– for each occlusion procedure randomly select a separate random RGB colour for each segment.
Alternatively, it can be a userdefined RGB colour provided as a 3tuple with values in the 0–255 range. For blackandwhite 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 blackandwhite images;'randompatch'
– a separate random intensity for each segment;'randomise'
– for each occlusion procedure randomly select a single occlusion intensity for all the segments; or'randomisepatch'
– for each occlusion procedure randomly select a separate random intensity for each segment.
Alternatively, it can be a userdefined intensity provided as an integer with values in the 0–255 range for grayscale images or 0 or 255 for blackandwhite 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 thecolour
, the meancolour occlusion is selected. Parameters
 colourstring, integer, tuple(integer, integer, integer) or None
A colour specifier.
 Raises
 RuntimeError
The meancolour occlusion was selected for a blackandwhite 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 blackandwhite 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 3tuple.