zennit.image

Functionality to convert arrays to images

Functions

get_cmap	Convenience function to lookup built-in color maps, or create color maps from a source code.
gridify	Align multiple arrays, described as an additional 0-th dimension, into a grid with the 0-th dimension removed.
imgify	Convert an array with 1 or 3 channels to a PIL image.
imsave	Convert an array to an image and save it using file fp.
interval_norm_bounds	Return the boundaries to normalize the data interval batch-wise between 0.
palette	Convenience function to create palettes from built-in colormaps, or from a source code if necessary.

zennit.image.get_cmap(cmap)

Convenience function to lookup built-in color maps, or create color maps from a source code.

Parameters:

cmap (str or ColorMap) – String to specify a built-in color map, code used to create a new color map, or a ColorMap instance.

Returns:

The built-in color map with key cmap in CMAPS, a new color map created from the code cmap, or cmap if it already was a ColorMap.

Return type:

ColorMap

zennit.image.gridify(obj, shape=None, fill_value=None)

Align multiple arrays, described as an additional 0-th dimension, into a grid with the 0-th dimension removed.

Parameters:

• obj (object) – An object that can be converted to a numpy array, with 3 (greyscale) or 4 (rgb) axes. The color channel’s position is automatically detected, and moved to the back of the shape.

• shape (tuple of size 2, optional) – Height and width of the produced grid. If None (default), create a square grid.

• fill_value (float or obj:numpy.ndarray) – A value to fill empty grid members. Default is the mean pixel value.

Returns:

obj – An array with the 0-th dimension absorbed into the height and width dimensions (then 0 and 1). The color dimension will be the last dimension, even if it was the first dimension before.

Return type:

numpy.ndarray

zennit.image.imgify(obj, vmin=None, vmax=None, cmap='bwr', level=1.0, symmetric=False, grid=False, gridfill=None)

Convert an array with 1 or 3 channels to a PIL image. The color dimension can be either the first or the last dimension.

Parameters:

• obj (object) – Anything that can be converted to a numpy array with 2 dimensions greyscale, or 3 dimensions with 1 or 3 values in the first or last dimension (color).

• vmin (float or obj:numpy.ndarray) – Manual minimum value of the array. Overrides the used norm’s minimum value.

• vmax (float or obj:numpy.ndarray) – Manual maximum value of the array. Overrides the used norm’s maximum value.

• cmap (str or ColorMap) – String to specify a built-in color map, code used to create a new color map, or a ColorMap instance, which will be used to create a palette. The color map will only be applied for arrays with only a single color channel. The color will be specified as a palette in the PIL Image.

• level (float) – The level of the color map. 1.0 is default. Values below 1.0 reduce the color range, with only a single color used at value 0.0. Values above 1.0 clip the value earlier towards the maximum, with an increasingly steep transition at the center of the pixel value distribution.

• symmetric (bool, optional) – Specifies whether the norm should be symmetric (True) or unaligned (False, default). If True, normalize with both minimum and maximum by the absolute maximum, which will cause 0. in the input to correspond to 0.5 in the result. Setting symmetric=False (default) will result in the minimum value to be directly mapped to 0 and the maximum value to be directly mapped to 1. vmin and vmax may be used to manually override the minimum and maximum value respectively.

• grid (bool or tuple of ints of size 2) – If true, assumes the first dimension to be the batch dimension. If True, creates a square grid of images in the batch dimension after normalizing each sample. If tuple of ints of size 2, creates the grid in the shape of (height, width). If False (default), does not assume a batch dimension.

• gridfill (np.uint8) – A value to fill empty grid members. Default is the mean pixel value. No effect when grid=False.

Returns:

image – The array visualized as a Pillow Image.

Return type:

obj:PIL.Image

zennit.image.imsave(fp, obj, vmin=None, vmax=None, cmap='bwr', level=1.0, grid=False, format=None, writer_params=None, symmetric=False, gridfill=None)

Convert an array to an image and save it using file fp. Internally, imgify is called to create a PIL Image, which is then saved using PIL.

Parameters:

• fp (str, obj:pathlib.Path or file) – Save target for PIL Image.

• obj (object) – Anything that can be converted to a numpy array with 2 dimensions greyscale, or 3 dimensions with 1 or 3 values in the first or last dimension (color).

• vmin (float or obj:numpy.ndarray) – Manual minimum value of the array. Overrides the used norm’s minimum value.

• vmax (float or obj:numpy.ndarray) – Manual maximum value of the array. Overrides the used norm’s maximum value.

• cmap (str or ColorMap) – String to specify a built-in color map, code used to create a new color map, or a ColorMap instance, which will be used to create a palette. The color map will only be applied for arrays with only a single color channel. The color will be specified as a palette in the PIL Image.

• level (float) – The level of the color map. 1.0 is default. Values below 1.0 reduce the color range, with only a single color used at value 0.0. Values above 1.0 clip the value earlier towards the maximum, with an increasingly steep transition at the center of the pixel value distribution.

• grid (bool or tuple of ints of size 2) – If true, assumes the first dimension to be the batch dimension. If True, creates a square grid of images in the batch dimension after normalizing each sample. If tuple of ints of size 2, creates the grid in the shape of (height, width). If False (default), does not assume a batch dimension.

• format (str) – Optional format override for PIL Image.save.

• writer_params (dict) – Extra params to the image writer in PIL.

• symmetric (bool, optional) – Specifies whether the norm should be symmetric (True) or unaligned (False, default). If True, normalize with both minimum and maximum by the absolute maximum, which will cause 0. in the input to correspond to 0.5 in the result. Setting symmetric=False (default) will result in the minimum value to be directly mapped to 0 and the maximum value to be directly mapped to 1. vmin and vmax may be used to manually override the minimum and maximum value respectively.

• gridfill (np.uint8) – A value to fill empty grid members. Default is the mean pixel value. No effect when grid=False.

zennit.image.interval_norm_bounds(input, symmetric=False, dim=None)

Return the boundaries to normalize the data interval batch-wise between 0. and 1. given the specified strategy.

Parameters:

• input (numpy.ndarray) – Array for which to return the boundaries.

• symmetric (bool, optional) – Specifies whether the norm should be symmetric (True) or unaligned (False, default). If True, normalize with both minimum and maximum by the absolute maximum, which will cause 0. in the input to correspond to 0.5 in the result. Setting symmetric=False (default) will result in the minimum value to be directly mapped to 0 and the maximum value to be directly mapped to 1.

• dim (tuple of ints, optional) – Set the channel dimensions over which the boundaries are computed (default is tuple(range(1, input.ndim)).

Returns:

The normalized array input along dim to lie in the interval [0, 1].

Return type:

numpy.ndarray

zennit.image.palette(cmap='bwr', level=1.0)

Convenience function to create palettes from built-in colormaps, or from a source code if necessary.

Parameters:

• cmap (str or ColorMap) – String to specify a built-in color map, code used to create a new color map, or a ColorMap instance, which will be used to create a palette.

• level (float) – The level of the color map palette. 1.0 is default. Values below zero reduce the color range, with only a single color used at value 0.0. Values above 1.0 clip the value earlier towards the maximum, with an increasingly steep transition at the center of the color map range.

Returns:

obj – The palette described by an unsigned 8-bit numpy array with 256 entries.

Return type:

numpy.ndarray