imgaug.augmentables.heatmaps

Classes to represent heatmaps, i.e. float arrays of [0.0, 1.0].

class imgaug.augmentables.heatmaps.HeatmapsOnImage(arr, shape, min_value=0.0, max_value=1.0)

Bases: imgaug.augmentables.base.IAugmentable

Object representing heatmaps on a single image.

Parameters:

• arr ((H,W) ndarray or (H,W,C) ndarray) – Array representing the heatmap(s) on a single image. Multiple heatmaps may be provided, in which case C is expected to denote the heatmap index. The array must be of dtype float32.
• shape (tuple of int) – Shape of the image on which the heatmap(s) is/are placed. Not the shape of the heatmap(s) array, unless it is identical to the image shape (note the likely difference between the arrays in the number of channels). This is expected to be (H, W) or (H, W, C) with C usually being 3. If there is no corresponding image, use (H_arr, W_arr) instead, where H_arr is the height of the heatmap(s) array (analogous W_arr).
• min_value (float, optional) – Minimum value for the heatmaps that arr represents. This will usually be 0.0.
• max_value (float, optional) – Maximum value for the heatmaps that arr represents. This will usually be 1.0.

Methods

avg_pool(self, block_size)	Average-pool the heatmap(s) array using a given block/kernel size.
change_normalization(arr, source, target)	Change the value range of a heatmap array.
copy(self)	Create a shallow copy of the heatmaps object.
deepcopy(self)	Create a deep copy of the heatmaps object.
draw(self[, size, cmap])	Render the heatmaps as RGB images.
draw_on_image(self, image[, alpha, cmap, resize])	Draw the heatmaps as overlays over an image.
from_0to1(arr_0to1, shape[, min_value, …])	Create a heatmaps object from a [0.0, 1.0] float array.
from_uint8(arr_uint8, shape[, min_value, …])	Create a float-based heatmaps object from an uint8 array.
get_arr(self)	Get the heatmap’s array in value range provided to __init__().
invert(self)	Invert each component in the heatmap.
max_pool(self, block_size)	Max-pool the heatmap(s) array using a given block/kernel size.
pad(self[, top, right, bottom, left, mode, cval])	Pad the heatmaps at their top/right/bottom/left side.
pad_to_aspect_ratio(self, aspect_ratio[, …])	Pad the heatmaps until they match a target aspect ratio.
resize(self, sizes[, interpolation])	Resize the heatmap(s) array given a target size and interpolation.
scale(self, *args, **kwargs)	Deprecated.
to_uint8(self)	Convert this heatmaps object to an uint8 array.

avg_pool(self, block_size)

Average-pool the heatmap(s) array using a given block/kernel size.

Parameters:block_size (int or tuple of int) – Size of each block of values to pool, aka kernel size. See pool() for details. Returns:Heatmaps after average pooling. Return type:imgaug.augmentables.heatmaps.HeatmapsOnImage

classmethod change_normalization(arr, source, target)

Change the value range of a heatmap array.

E.g. the value range may be changed from the interval [0.0, 1.0] to [-1.0, 1.0].

Parameters:

• arr (ndarray) – Heatmap array to modify.
• source (tuple of float) – Current value range of the input array, given as a tuple (min, max), where both are float values.
• target (tuple of float) – Desired output value range of the array, given as a tuple (min, max), where both are float values.

Returns:

Input array, with value range projected to the desired target value range.

Return type:

ndarray

copy(self)

Create a shallow copy of the heatmaps object.

Returns:Shallow copy. Return type:imgaug.augmentables.heatmaps.HeatmapsOnImage

deepcopy(self)

Create a deep copy of the heatmaps object.

Returns:Deep copy. Return type:imgaug.augmentables.heatmaps.HeatmapsOnImage

draw(self, size=None, cmap='jet')

Render the heatmaps as RGB images.

Parameters:

• size (None or float or iterable of int or iterable of float, optional) – Size of the rendered RGB image as (height, width). See imresize_single_image() for details. If set to None, no resizing is performed and the size of the heatmaps array is used.
• cmap (str or None, optional) – Name of the matplotlib color map to use when convert the heatmaps to RGB images. If set to None, no color map will be used and the heatmaps will be converted to simple intensity maps.

Returns:

Rendered heatmaps as uint8 arrays. Always a list containing one RGB image per heatmap array channel.

Return type:

list of (H,W,3) ndarray

draw_on_image(self, image, alpha=0.75, cmap='jet', resize='heatmaps')

Draw the heatmaps as overlays over an image.

Parameters:

• image ((H,W,3) ndarray) – Image onto which to draw the heatmaps. Expected to be of dtype uint8.
• alpha (float, optional) – Alpha/opacity value to use for the mixing of image and heatmaps. Larger values mean that the heatmaps will be more visible and the image less visible.
• cmap (str or None, optional) – Name of the matplotlib color map to use. See HeatmapsOnImage.draw() for details.
• resize ({‘heatmaps’, ‘image’}, optional) – In case of size differences between the image and heatmaps, either the image or the heatmaps can be resized. This parameter controls which of the two will be resized to the other’s size.

Returns:

Rendered overlays as uint8 arrays. Always a list containing one RGB image per heatmap array channel.

Return type:

list of (H,W,3) ndarray

static from_0to1(arr_0to1, shape, min_value=0.0, max_value=1.0)

Create a heatmaps object from a [0.0, 1.0] float array.

Parameters:

• arr_0to1 ((H,W) or (H,W,C) ndarray) – Heatmap(s) array, where H is the height, W is the width and C is the number of heatmap channels. Expected dtype is float32.
• shape (tuple of ints) – Shape of the image on which the heatmap(s) is/are placed. Not the shape of the heatmap(s) array, unless it is identical to the image shape (note the likely difference between the arrays in the number of channels). If there is not a corresponding image, use the shape of the heatmaps array.
• min_value (float, optional) – Minimum value of the float heatmaps that the input array represents. This will usually be 0.0. In most other cases it will be close to the interval [0.0, 1.0]. Calling get_arr(), will automatically convert the interval [0.0, 1.0] float array to this [min, max] interval.
• max_value (float, optional) – Minimum value of the float heatmaps that the input array represents. This will usually be 1.0. See parameter min_value for details.

Returns:

Heatmaps object.

Return type:

imgaug.augmentables.heatmaps.HeatmapsOnImage

static from_uint8(arr_uint8, shape, min_value=0.0, max_value=1.0)

Create a float-based heatmaps object from an uint8 array.

Parameters:

• arr_uint8 ((H,W) ndarray or (H,W,C) ndarray) – Heatmap(s) array, where H is height, W is width and C is the number of heatmap channels. Expected dtype is uint8.
• shape (tuple of int) – Shape of the image on which the heatmap(s) is/are placed. Not the shape of the heatmap(s) array, unless it is identical to the image shape (note the likely difference between the arrays in the number of channels). If there is not a corresponding image, use the shape of the heatmaps array.
• min_value (float, optional) – Minimum value of the float heatmaps that the input array represents. This will usually be 0.0. In most other cases it will be close to the interval [0.0, 1.0]. Calling get_arr(), will automatically convert the interval [0.0, 1.0] float array to this [min, max] interval.
• max_value (float, optional) – Minimum value of the float heatmaps that the input array represents. This will usually be 1.0. See parameter min_value for details.

Returns:

Heatmaps object.

Return type:

imgaug.augmentables.heatmaps.HeatmapsOnImage

get_arr(self)

Get the heatmap’s array in value range provided to __init__().

The HeatmapsOnImage object saves heatmaps internally in the value range [0.0, 1.0]. This function converts the internal representation to [min, max], where min and max are provided to HeatmapsOnImage.__init__() upon instantiation of the object.

Returns:Heatmap array of dtype float32. Return type:(H,W) ndarray or (H,W,C) ndarray

invert(self)

Invert each component in the heatmap.

This shifts low values towards high values and vice versa.

This changes each value to:

v' = max - (v - min)

where v is the value at a spatial location, min is the minimum value in the heatmap and max is the maximum value. As the heatmap uses internally a 0.0 to 1.0 representation, this simply becomes v' = 1.0 - v.

This function can be useful e.g. when working with depth maps, where algorithms might have an easier time representing the furthest away points with zeros, requiring an inverted depth map.

Returns:Inverted heatmap. Return type:imgaug.augmentables.heatmaps.HeatmapsOnImage

max_pool(self, block_size)

Max-pool the heatmap(s) array using a given block/kernel size.

Parameters:block_size (int or tuple of int) – Size of each block of values to pool, aka kernel size. See pool() for details. Returns:Heatmaps after max-pooling. Return type:imgaug.augmentables.heatmaps.HeatmapsOnImage

pad(self, top=0, right=0, bottom=0, left=0, mode='constant', cval=0.0)

Pad the heatmaps at their top/right/bottom/left side.

Parameters:

• top (int, optional) – Amount of pixels to add at the top side of the heatmaps. Must be 0 or greater.
• right (int, optional) – Amount of pixels to add at the right side of the heatmaps. Must be 0 or greater.
• bottom (int, optional) – Amount of pixels to add at the bottom side of the heatmaps. Must be 0 or greater.
• left (int, optional) – Amount of pixels to add at the left side of the heatmaps. Must be 0 or greater.
• mode (string, optional) – Padding mode to use. See pad() for details.
• cval (number, optional) – Value to use for padding mode is constant. See pad() for details.

Returns:

Padded heatmaps of height H'=H+top+bottom and width W'=W+left+right.

Return type:

imgaug.augmentables.heatmaps.HeatmapsOnImage

pad_to_aspect_ratio(self, aspect_ratio, mode='constant', cval=0.0, return_pad_amounts=False)

Pad the heatmaps until they match a target aspect ratio.

Depending on which dimension is smaller (height or width), only the corresponding sides (left/right or top/bottom) will be padded. In each case, both of the sides will be padded equally.

Parameters:

• aspect_ratio (float) – Target aspect ratio, given as width/height. E.g. 2.0 denotes the image having twice as much width as height.
• mode (str, optional) – Padding mode to use. See pad() for details.
• cval (number, optional) – Value to use for padding if mode is constant. See pad() for details.
• return_pad_amounts (bool, optional) – If False, then only the padded instance will be returned. If True, a tuple with two entries will be returned, where the first entry is the padded instance and the second entry are the amounts by which each array side was padded. These amounts are again a tuple of the form (top, right, bottom, left), with each value being an integer.

Returns:

• imgaug.augmentables.heatmaps.HeatmapsOnImage – Padded heatmaps as HeatmapsOnImage instance.
• tuple of int – Amounts by which the instance’s array was padded on each side, given as a tuple (top, right, bottom, left). This tuple is only returned if return_pad_amounts was set to True.

resize(self, sizes, interpolation='cubic')

Resize the heatmap(s) array given a target size and interpolation.

Parameters:

• sizes (float or iterable of int or iterable of float) – New size of the array in (height, width). See imresize_single_image() for details.
• interpolation (None or str or int, optional) – The interpolation to use during resize. See imresize_single_image() for details.

Returns:

Resized heatmaps object.

Return type:

imgaug.augmentables.heatmaps.HeatmapsOnImage

scale(self, *args, **kwargs)

Deprecated. Use HeatmapsOnImage.resize() instead. resize() has the exactly same interface.

Resize the heatmap(s) array given a target size and interpolation.

to_uint8(self)

Convert this heatmaps object to an uint8 array.

Returns:Heatmap as an uint8 array, i.e. with the discrete value range [0, 255]. Return type:(H,W,C) ndarray