# magni.imaging.visualisation module¶

Module providing functionality for visualising images.

The module provides functionality for adjusting the intensity of an image. It provides a wrapper of the matplotlib.pyplot.imshow function that may exploit the provided functions for adjusting the image intensity. Also it include a function may be used to display a set of related images using a common colormapping.

## Routine listings¶

imshow(X, ax=None, intensity_func=None, intensity_args=(), **kwargs)
Function that may be used to display an image.
imsubplot(imgs, rows, titles=None, x_labels=None, y_labels=None,
x_ticklabels=None, y_ticklabels=None, cbar_label=None, normalise=True, fixed_clim=None, **kwargs) Function that may be used to display a set of related images.
mask_img_from_coords(img, coords)
Function for masking certain parts of an image based on coordinates.
shift_mean(x_mod, x_org)
Function for shifting mean intensity of an image based on another image.
stretch_image(img, max_val, min_val=0)
Function for stretching the intensity of an image.
magni.imaging.visualisation.imshow(X, ax=None, intensity_func=None, intensity_args=(), show_axis='frame', **kwargs)[source]

Display an image.

Wrap matplotlib.pyplot.imshow to display a possibly intensity manipulated version of the image X.

Parameters: X (ndarray) – The image to be displayed. ax (matplotlib.axes.Axes, optional) – The axes on which the image is displayed (the default is None, which implies that the current axes is used). intensity_func (FunctionType, optional) – The handle to the function used to manipulate the image intensity before the image is displayed (the default is None, which implies that no intensity manipulation is used). intensity_args (list or tuple, optional) – The arguments that are passed to the intensity_func (the default is (), which implies that no arguments are passed). show_axis ({‘none’, ‘top’, ‘inherit’, ‘frame’}) – How the x- and y-axis are display. If ‘none’, no axis are displayed. If ‘top’, the x-axis is displayed at the top of the image. If ‘inherit’, the axis display is inherited from matplotlib.pyplot.imshow. If ‘frame’ only the frame is shown and not the ticks. im_out (matplotlib.image.AxesImage) – The AxesImage returned by matplotlibs imshow.

See also

matplotlib.pyplot.imshow()
Matplotlib’s imshow function.

Examples

For example,

>>> import numpy as np
>>> from magni.imaging.visualisation import imshow
>>> X = np.arange(4).reshape(2, 2)
>>> add_k = lambda X, k: X + k
>>> im_out = imshow(X, intensity_func=add_k, intensity_args=(2,))

magni.imaging.visualisation.imsubplot(imgs, rows, titles=None, x_labels=None, y_labels=None, x_ticklabels=None, y_ticklabels=None, cbar_label=None, normalise=True, fixed_clim=None, **kwargs)[source]

Display a set of related images as subplots in a figure.

The images imgs are shown in a figure with a subplot layout based on the number of rows. The titles, x_labels, y_labels, x_ticklabels, and y_ticklabels are shown in the subplots. If normalise is True, all the images will share the same normalised colorbar/colormapping i.e. a particular colour will correspond to the same value across all images.

Parameters: imgs (list or tuple) – The images (as ndarrays) that is to be displayed. rows (int) – The number of rows to use in the subplot layout. titles (list or tuple) – The titles (as strings) to use for each of the subplots (the default is None, which implies that no titles are displayed). x_labels (list or tuple) – The x_labels (as strings) to use for each of the subplots (the default is None, which implies that no x_labels are displayed). y_labels (list or tuple) – The y_labels (as strings) to use for each of the subplots (the default is None, which implies that no y_labels are displayed). x_ticklabels (list or tuple) – The x_ticklabels (as strings or lists of strings) to use for the subplots (the default is None, which implies that no x_ticklabels are displayed). y_ticklabels (list or tuple) – The y_ticklabels (as strings or lists of strings) to use for the subplots (the default is None, which implies that no y_ticklabels are displayed). cbar_label (str) – The colorbar label to use with a normalised colormapping (the default is None, which implies that no colorbar label is displayed). fixed_clim (list or tuple) – The colorbar limits as a (min, max) sequence (the default is None, which implies that the colorbar limits are inferred from the data). normalise (bool) – The flag that indicates whether to use a normalised colormapping. fig (matplotlib.figure.Figure) – The resulting figure instance.

See also

matplotlib.pyplot.subplots()
Underlying subplot function.

Notes

The x_ticklabels and y_ticklabels may be either a collection of strings or a collections of collections of strings depending on wherther the labels should be shared across all subplots or different labels are to be used for each subplot.

Additional kwargs given to the function will be passed to the underlying suplot instantiation function matplotlib.pyplot.subplots.

If normalise is True, the common colorbar is shown below the subplots.

The implementation of the normalisation feature is based on the Pylab example: http://matplotlib.org/examples/pylab_examples/multi_image.html.

Examples

For example, show two images next to each other with a common colormapping:

>>> import numpy as np
>>> from magni.imaging.visualisation import imsubplot
>>> img1 = np.arange(4).reshape(2, 2)
>>> img2 = np.ones((4, 4))
>>> fig = imsubplot([img1, img2], 1, titles=['arange', 'ones'],
... x_labels=['x1', 'x2'], y_labels=['y1', 'y2'], cbar_label='Example',
... normalise=True)


or show the same images with shared ticklabels and fixed colorbar limits:

>>> common_x_ticklabels = ['a', 'b']
>>> common_y_ticklabels = ['c', 'd']
>>> fig = imsubplot([img1, img2], 1, x_ticklabels=common_x_ticklabels,
... y_ticklabels=common_y_ticklabels, fixed_clim=(0, 2), normalise=True)


or show the same images with different colormappings and ticklabels:

>>> x_ticklabels = [['a', 'b'], ['aa', 'bb']]
>>> y_ticklabels = [['c', 'd'], ['cc', 'dd']]
>>> fig = imsubplot([img1, img2], 1, x_ticklabels=x_ticklabels,
... y_ticklabels=y_ticklabels, normalise=False)

magni.imaging.visualisation.mask_img_from_coords(img, coords)[source]

Mask coordinates in an image.

The coordinates coords in the image img are masked such that only the cooordinates are shown.

Parameters: img (ndarray) – The image to mask. coords (ndarray) – The coordinates arranged into a 2D array, such that each row is a coordinate pair (x, y). masked_img (numpy.ma.MaskedArray) – The masked image.

See also

magni.imaging.measurements()
Further description of the coordinate format.

Examples

For example, display only center pixel in a 3-by-3 image

>>> import numpy as np
>>> from magni.imaging.visualisation import mask_img_from_coords
>>> img = np.arange(9).reshape(3, 3)
>>> coords = np.array([[1, 1]])
>>> mask_img_from_coords(img, coords)
masked_array(data =
[[-- -- --]
[-- 4 --]
[-- -- --]],
mask =
[[ True  True  True]
[ True False  True]
[ True  True  True]],
fill_value = 999999)

magni.imaging.visualisation.shift_mean(x_mod, x_org)[source]

Shift the mean value of x_mod such that it equals the mean of x_org.

Parameters: x_org (ndarray) – The array which hold the “true” mean value. x_mod (ndarray) – The modified copy of x_org which must have its mean value shifted. shifted_x_mod (ndarray) – A copy of x_mod with the same mean value as x_org.

Examples

For example,

>>> import numpy as np
>>> from magni.imaging.visualisation import shift_mean
>>> x_org = np.arange(4).reshape(2, 2)
>>> x_mod = np.ones((2, 2))
>>> print('{:.1f}'.format(x_org.mean()))
1.5
>>> print('{:.1f}'.format(x_mod.mean()))
1.0
>>> shifted_x_mod = shift_mean(x_mod, x_org)
>>> print('{:.1f}'.format(shifted_x_mod.mean()))
1.5
>>> np.set_printoptions(suppress=True)
>>> shifted_x_mod
array([[ 1.5,  1.5],
[ 1.5,  1.5]])

magni.imaging.visualisation.stretch_image(img, max_val, min_val=0)[source]

Stretch image such that pixels values are in [min_val, max_val].

Parameters: img (ndarray) – The (float) image that is to be stretched. max_val (int or float) – The maximum value in the stretched image. min_val (int or float) – The minimum value in the stretched image. stretched_img (ndarray) – A stretched copy of the input image.

Notes

The pixel values in the input image are scaled to lie in the interval [min_val, max_val] using a linear stretch.

Examples

For example, stretch an image between 0 and 1

>>> import numpy as np
>>> from magni.imaging.visualisation import stretch_image
>>> img = np.arange(4, dtype=np.float).reshape(2, 2)
>>> stretched_img = stretch_image(img, 1)
>>> np.set_printoptions(suppress=True)
>>> stretched_img
array([[ 0.        ,  0.33333333],
[ 0.66666667,  1.        ]])


or stretch the image between -1 and 1

>>> stretched_img = stretch_image(img, 1.0, min_val=-1.0)
>>> stretched_img
array([[-1.        , -0.33333333],
[ 0.33333333,  1.        ]])


or re-stretch the strecthed image between -3.0 and -1.5

>>> stretched_img = stretch_image(stretched_img, -1.5, min_val=-3.0)
>>> stretched_img
array([[-3. , -2.5],
[-2. , -1.5]])


or re-stretch that image between 1.25 and 8.00

>>> stretched_img = stretch_image(stretched_img, 8.00, min_val=1.25)
>>> stretched_img
array([[ 1.25,  3.5 ],
[ 5.75,  8.  ]])

magni.imaging.visualisation._handle_ticklabels(ax, k, x_ticklabels, y_ticklabels)[source]

Handle and format ticks and ticklabels for use in imsubplot.

The imsubplot function creates a figure showing an abitrary number of subplots. The imsubplot function allows for custom ticklabels along the x- and y-axes. This function handles the formatting of the ticklabels for a given subplot.

Parameters: ax (matplotlib.axes.Axes) – The matplotlib axes (subplot) to format ticklabels for. k (int) – The axes index, i.e. the subplot number out of the total number of subplots. x_ticklabels (list or tuple) – The x_ticklabels (as strings or lists of strings) to use for the subplots (the default is None, which implies that no x_ticklabels are displayed). y_ticklabels (list or tuple) – The y_ticklabels (as strings or lists of strings) to use for the subplots (the default is None, which implies that no y_ticklabels are displayed).
class magni.imaging.visualisation._ImageColourTracker(tracker)[source]

Bases: object

Track a common ‘clim’ in a set of matplotlib image subplots.

Parameters: tracker (matplotlib.image.AxesImage) – The image instance that must track a given ‘clim’.
__call__(tracked)[source]