pyepri.displayers

This module provides static & interactive tools for image display.

Interactive image displayers

Tools for displaying images (3D images & 4D spectral-spatial images) and interacting with the display through mouse and keyboard interactive commands (interactions are not available using notebooks).

Static (but updatable) image displayers

Static image displayers can be used to display different kind of images (mono & multisource 2D & 3D images, spectral-spatial 4D images) in different execution environments (console & notebooks).

They come with the possibility to update the displayed image at any moment (useful in an iterative framework).

Attributes

__EMPTY_ARRAY__

Classes

Displayer

Class for display and update of different kind of images, in different running environments.

Functions

is_notebook(→ bool)	Infer whether code is executed using IPython notebook or not.
isosurf3d(u[, isovalue, color, cmap, show_grid, ...])	Interactive isosurface displayer for 3D images.
imshow3d(u[, xgrid, ygrid, zgrid, indexes, units, ...])	Interactive slice displayer for 3D images.
imshow4d(u[, xgrid, ygrid, zgrid, Bgrid, ...])	Interactive displayer for 4D spectral-spatial images.
init_display_monosrc_2d(u[, newfig, figsize, ...])	Initialize display for a single 2D image.
update_display_monosrc_2d(u, fg[, is_notebook, ...])	Update single 2D image display.
init_display_monosrc_3d(u[, newfig, figsize, ...])	Initialize display for a single 3D image (display the three central slices of a 3D volume).
update_display_monosrc_3d(u, fg[, is_notebook, ...])	Update single 3D image display.
init_display_spectralspatial_4d(u[, newfig, figsize, ...])	Initialize display for a spectral-spatial 4D image.
update_display_spectralspatial_4d(u, hdl[, ...])	Update spectral-spatial 4D image display.
init_display_multisrc_2d(u[, newfig, figsize, ...])	Initialize display for a sequence of 2D images.
update_display_multisrc_2d(u, fg[, is_notebook, ...])	Update display for a sequence of 2D images.
init_display_multisrc_3d(u[, newfig, figsize, ...])	Initialize display for a sequence of 3D images.
update_display_multisrc_3d(u, fg[, is_notebook, ...])	Update display for a sequence of 3D images.
create_2d_displayer([nsrc, newfig, figsize, ...])	Instantiate a single 2D image displayer.
create_3d_displayer([nsrc, newfig, figsize, ...])	Instantiate a single 3D image displayer.
create_spectralspatial_4d_displayer([newfig, figsize, ...])
create(u[, newfig, figsize, displayFcn, time_sleep, ...])	Instantiate a Displayer object suited to the input parameter.
get_number(fg)	Retrieve displayed figure number.
_check_inputs_([nsrc, ndim, displayFcn, time_sleep, ...])	Factorized consistency checks for functions in this pyepri.displayers submodule.

Module Contents

pyepri.displayers.__EMPTY_ARRAY__

pyepri.displayers.is_notebook() → bool

Infer whether code is executed using IPython notebook or not.

pyepri.displayers.isosurf3d(u, isovalue=None, color='#f7fe00', cmap=None, show_grid=True, xlabel='X', ylabel='Y', zlabel='Z', xlim=None, ylim=None, zlim=None, config=None)

Interactive isosurface displayer for 3D images.

Parameters:

• u (ndarray) –

  Three dimensional array containing the values of the 3D image ordered as follows:

  • axis 0 = spatial vertical axis (or Y-axis);

  • axis 1 = spatial horizontal axis (or X-axis);

  • axis 2 = saptial depth axis (or Z-axis).

• isovalue (float, optional) – Isovalue to display (default setting corresponds to Otsu’s threshold which maximizes the inter-class variance between background and foreground).

• color (str or RBG tuple or RGBA tuple, optional) –

  Isosurface color, provided in PyVista compatible format, see several examples below:

  • predefined color names : “red”, “green”, “blue”, “yellow”, “magenta”, “cyan”, “orange”, “purple”, “black”, “white”, …

  • hexadecimal color: ‘#F7FE00’, “#FF5733”, …

  • RGB tuple : for instance (1.0, 0.5, 0.0)

  • RGBA tuple : for instance (0.2, 0.4, 0.6, 0.8)

  See PyVista documentation for more details.

• cmap (str or pyvista.LookupTable, optional) –

  Colormap to apply when rendering scalar values on the slices.

  • If None, the default colormap is used.

  • Can be any string recognized by Matplotlib, e.g., ‘viridis’, ‘jet’, ‘coolwarm’, …

  • Can also be a pyvista.LookupTable for custom color mapping.

• show_grid (bool, optional) – Grid visibility at startup (toogle visibility using key ‘g’)

• xlabel (str, optional) – Label for the X axis

• ylabel (str, optional) – Label for the Y axis

• zlabel (str, optional) – Label for the Z axis

• xlim (tuple of float, optional) – Limits for the x-axis as a tuple (xmin, xmax). If provided, sets the visible range of the X-axis. If None, the limits are determined automatically based on the data.

• ylim (tuple of float, optional) – Limits for the x-axis as a tuple (ymin, ymax). If provided, sets the visible range of the Y-axis. If None, the limits are determined automatically based on the data.

• zlim (tuple of float, optional) – Limits for the x-axis as a tuple (zmin, zmax). If provided, sets the visible range of the Z-axis. If None, the limits are determined automatically based on the data.

• config (dict, optional) –

  Dictionary containing custom settings. The following keys may be used:

  • ’surface_opacity’ : float, initial value for the isosurface opacity slider

  • ’slices_opacity’ : float, initial value for the slices opacity slider

  • ’step1’ : float, proportion of the slider range to use at slider increment/decrement when the keys ‘right’ and ‘left’ are pressed

  • ’step2’ : float, proportion of the slider range to use at slider increment/decrement when the keys ‘ctrl+right’ and ‘ctrl+left’ are pressed

  Specifying only a subset of them is allowed.

Returns:

plotter – The plotter instance containing the rendered scene.

Return type:

pyvista.Plotter

pyepri.displayers.imshow3d(u, xgrid=None, ygrid=None, zgrid=None, indexes=None, units='', figsize=None, valfmt='%0.3g', show_colorbar=True, cmap=None, origin='lower', aspect='equal', boundaries='same', interpolation='nearest', sx_color=None, sy_color=None, sz_color=None, xlim=None, ylim=None, zlim=None)

Interactive slice displayer for 3D images.

Display slices of a 3D image, and explore its content through many interactive commands (once the figure is displayed, press the h key of your keyboard to display the list of interactive commands, also listed below).

Parameters:

• u (ndarray) –

  Three dimensional array containing the values of the 3D image ordered as follows:

  • axis 0 = spatial vertical axis (or Y-axis);

  • axis 1 = spatial horizontal axis (or X-axis);

  • axis 2 = saptial depth axis (or Z-axis).

• xgrid (ndarray, optional) – Monodimensional ndarray with length u.shape[1] containing the sampling nodes associated to the X-axis (axis 1) of the 3D image u.

• ygrid (ndarray, optional) – Monodimensional ndarray with length u.shape[0] containing the sampling nodes associated to the Y-axis (axis 0) of the 3D image u.

• zgrid (ndarray, optional) – Monodimensional ndarray with length u.shape[2] containing the sampling nodes associated to the Z-axis (axis 2) of the 3D image u.

• indexes (sequence of int, optional) –

  When given, indexes must be a sequence of three int, indexes = (id0, id1, id2), such that id0, id1 and id2 correspond to the indexes used along each axis of the 3D volume to extract the slices to be displayed (using None to keep a particular index to its default value is possible).

  The default setting is indexes = (u.shape[0]//2, u.shape[1]//2, u.shape[2]//2).

• units (str, optional) – Units associated to the X, Y and Z axes (handling of different axes units is not provided).

• figsize ((float, float), optional) – When given, figsize must be a tuple with length two and such that figsize[0] and figsize[1] are the width and height in inches of the figure to be displayed. When not given, the default setting is that of matplotlib (see key ‘figure.figsize’ of the matplotlib configuration parameter rcParams).

• valfmt (str, optional) – %-format string used to format the slider values.

• show_colorbar (bool, optional) – Specify whether a colorbar should be displayed next to each slice image.

• cmap (str, optional) – The registered colormap name used to map scalar data to colors in matplotlib.imshow.

• origin (str in {'upper', 'lower'}, optional) – Place the [0, 0] index of the array in the upper left or lower left corner of the Axes. When not given, the default setting is that of matplotlib (see key ‘image.origin’ of the matplotlib configuration parameter rcParams).

• aspect (str in {'equal', 'auto'} or float or None, optional) –

  The aspect ratio of the Axes. This parameter is particularly relevant for images since it determines whether data pixels are square (see matplotlib.imshow documentation).

  When not given, the default setting is that of matplotlib (see key ‘image.aspect’ of the matplotlib configuration parameter rcParams).

• boundaries (str in {'auto', 'same'}) – Use boundaries = 'same' to give all subplots the same axes boundaries (in particular, this ensures that all slice images will be displayed on the screen using the same pixel size). Otherwise, a tight extent is used for each displayed slice image.

• interpolation (str, optional) – The interpolation method used (see matplotlib documentation for the possible choices).

• sx_color (str or None, optional) – The name of a matplotlib color for the X-slice slider progress bar (the default color is used when this optionnal input is set to None).

• sy_color (str or None, optional) – The name of a matplotlib color for the Y-slice slider progress bar (the default color is used when this optionnal input is set to None).

• sz_color (str or None, optional) – The name of a matplotlib color for the Z-slice slider progress bar (the default color is used when this optionnal input is set to None).

• xlim (tuple of float, optional) – Limits for the x-axis as a tuple (xmin, xmax). If provided, sets the visible range of the x-axis. If None, the limits are determined automatically based on the data. Note that the use of this option jointly with boundaries='same' is discouraged and may lead to unexpected behavior.

• ylim (tuple of float, optional) – Limits for the y-axis as a tuple (ymin, ymax). If provided, sets the visible range of the y-axis. If None, the limits are determined automatically based on the data. Note that the use of this option jointly with boundaries='same' is discouraged and may lead to unexpected behavior.

• zlim (tuple of float, optional) – Limits for the z-axis as a tuple (zmin, zmax). If provided, sets the visible range of the z-axis. If None, the limits are determined automatically based on the data. Note that the use of this option jointly with boundaries='same' is discouraged and may lead to unexpected behavior.

Returns:

params – A dictionary containing all graphical objects and state parameters.

Return type:

dict

Mouse and keyboard Interactive commands

• x : select the X-slice slider

• y : select the Y-slice slider

• z : select the Z-slice slider

• left : move the active slider back by one step

• right : move the active slider forward by one step

• ctrl + left : move the active slider back by 10% of its range

• ctrl + right : move the active slider forward by 10% of its range

• shift + left : move the active slider back by 5% of its range

• shift + right : move the active slider forward by 5% of its range

• up : toogle forward the slider selection (X -> Y -> Z)

• down : toogle back the slider selection (Z -> Y -> X)

• c : maximize the contrast among the three displayed slices

• h : display help

pyepri.displayers.imshow4d(u, xgrid=None, ygrid=None, zgrid=None, Bgrid=None, spatial_unit='', B_unit='', figsize=None, valfmt='%0.3g', show_legend=True, legend_loc='upper right', show_colorbar=True, cmap=None, origin='lower', aspect='equal', boundaries='same', interpolation='nearest', sx_color=None, sy_color=None, sz_color=None, sb_color='g', xlim=None, ylim=None, zlim=None)

Interactive displayer for 4D spectral-spatial images.

Display slices & spectra of a 4D spectral-spatial image, and explore its content through many interactive commands (once the figure is displayed, press the h key of your keyboard to display the list of interactive commands, also listed below).

Parameters:

• u (ndarray) –

  Four dimensional array containing the values of the 4D spectral-spatial image ordered as follows:

  • axis 0 = homogeneous magnetic field intensity axis (or B-axis);

  • axis 1 = spatial vertical axis (or Y-axis);

  • axis 2 = spatial horizontal axis (or X-axis);

  • axis 3 = saptial depth axis (or Z-axis).

• xgrid (ndarray, optional) – Monodimensional ndarray with length u.shape[2] containing the sampling nodes associated to the X-axis (axis 2) of the 4D spectral-spatial image u.

• ygrid (ndarray, optional) – Monodimensional ndarray with length u.shape[1] containing the sampling nodes associated to the Y-axis (axis 1) of the 4D spectral-spatial image u.

• zgrid (ndarray, optional) – Monodimensional ndarray with length u.shape[3] containing the sampling nodes associated to the Z-axis (axis 3) of the 4D spectral-spatial image u.

• Bgrid (ndarray, optional) – Monodimensional ndarray with length u.shape[0] containing the sampling nodes associated to the B-axis (axis 0) of the 4D spectral-spatial image u.

• spatial_unit (str, optional) – Units associated to the X, Y and Z axes (handling of different axes units is not provided).

• B_unit (str, optional) – Units associated to the homogeneous magnetic field intensity (B) axis.

• figsize ((float, float), optional) – When given, figsize must be a tuple with length two and such that figsize[0] and figsize[1] are the width and height in inches of the figure to be displayed. When not given, the default setting is that of matplotlib (see key ‘figure.figsize’ of the matplotlib configuration parameter rcParams).

• valfmt (str, optional) – %-format string used to format the slider values.

• show_legend (bool, optional) – Decide whether the legend in the spectrum display area should be visible or not when the figure is drawn (note that once the figure is drawn, you can always show or hide the legend by pressing the ‘S’ key on your keyboard).

• legend_loc (str, optional) – The location of the legend in the spectrum display area (see matplotlib documentation for possible choices).

• show_colorbar (bool, optional) – Specify whether a colorbar should be displayed next to each slice image.

• cmap (str, optional) – The registered colormap name used to map scalar data to colors in matplotlib.imshow.

• origin (str in {'upper', 'lower'}, optional) – Place the [0, 0] index of the array in the upper left or lower left corner of the Axes. When not given, the default setting is that of matplotlib (see key ‘image.origin’ of the matplotlib configuration parameter rcParams).

• aspect (str in {'equal', 'auto'} or float or None, optional) –

  The aspect ratio of the Axes. This parameter is particularly relevant for images since it determines whether data pixels are square (see matplotlib.imshow documentation).

  When not given, the default setting is that of matplotlib (see key ‘image.aspect’ of the matplotlib configuration parameter rcParams).

• boundaries (str in {'auto', 'same'}) – Use boundaries = 'same' to give all subplots the same axes boundaries (in particular, this ensures that all slice images will be displayed on the screen using the same pixel size). Otherwise, a tight extent is used for each displayed slice image.

• interpolation (str, optional) – The interpolation method used (see matplotlib documentation for the possible choices).

• sx_color (str or None, optional) – The name of a matplotlib color for the X-slice slider progress bar (the default color is used when this optionnal input is set to None).

• sy_color (str or None, optional) – The name of a matplotlib color for the Y-slice slider progress bar (the default color is used when this optionnal input is set to None).

• sz_color (str or None, optional) – The name of a matplotlib color for the Z-slice slider progress bar (the default color is used when this optionnal input is set to None).

• sb_color (str or None, optional) – The name of a matplotlib color for the B slider progress bar (the default color is used when this optionnal input is set to None).

• xlim (tuple of float, optional) – Limits for the x-axis as a tuple (xmin, xmax). If provided, sets the visible range of the x-axis. If None, the limits are determined automatically based on the data. Note that the use of this option jointly with boundaries='same' is discouraged and may lead to unexpected behavior.

• ylim (tuple of float, optional) – Limits for the y-axis as a tuple (ymin, ymax). If provided, sets the visible range of the y-axis. If None, the limits are determined automatically based on the data. Note that the use of this option jointly with boundaries='same' is discouraged and may lead to unexpected behavior.

• zlim (tuple of float, optional) – Limits for the z-axis as a tuple (zmin, zmax). If provided, sets the visible range of the z-axis. If None, the limits are determined automatically based on the data. Note that the use of this option jointly with boundaries='same' is discouraged and may lead to unexpected behavior.

Returns:

params – A dictionary containing all graphical objects and state parameters.

Return type:

dict

Mouse and keyboard Interactive commands

• single left click : keep the display for the spectrum under the mouse cursor

• x : select the X-slice slider

• y : select the Y-slice slider

• z : select the Z-slice slider

• b : select the B-value slider

• left : move the active slider back by one step

• right : move the active slider forward by one step

• ctrl + left : move the active slider back by 10% of its range

• ctrl + right : move the active slider forward by 10% of its range

• shift + left : move the active slider back by 5% of its range

• shift + right : move the active slider forward by 5% of its range

• up : toogle forward the slider selection (B -> X -> Y -> Z)

• down : toogle back the slider selection (Z -> Y -> X -> B)

• space : keep the display for spectrum under the mouse cursor

• r : maximize the dynamic range of the last displayed spectrum

• R : maximize the dynamic range of for all currently displayed spectra

• c : maximize the contrast among the three displayed slices

• d : remove the last displayed spectrum

• D : remove all currently displayed spectra

• S : show/hide legend

• h : display help

pyepri.displayers.init_display_monosrc_2d(u, newfig=True, figsize=None, time_sleep=0.01, units=None, display_labels=False, displayFcn=None, cmap=None, grids=None, origin='lower', aspect=None, is_notebook=False)

Initialize display for a single 2D image.

Parameters:

• u (ndarray) – Two-dimensional array

• newfig (bool, optional) – Specify whether the display must be done into a new figure or not.

• figsize ((float, float), optional) – When given, figsize must be a tuple with length two and such that figsize[0] and figsize[1] are the width and height in inches of the figure to be displayed. When not given, the default setting is that of matplotlib (see key ‘figure.figsize’ of the matplotlib configuration parameter rcParams).

• time_sleep (float, optional) – Duration in seconds of pause or sleep (depending on the running environment) to perform after image drawing.

• units (str, optional) – Units associated to the X and Y axes (handling of different axes units is not provided).

• display_labels (bool, optional) – Set display_labels = True to display axes labels (including units when given).

• displayFcn (<class 'function'>, optional) – Function with prototype im = displayFcn(u) that changes the 2D image u into another 2D image. When displayFcn is given, the displayed image is im = displayFcn(u) instead of u.

• cmap (str, optional) – The registered colormap name used to map scalar data to colors in matplotlib.imshow.

• grids (sequence, optional) –

  A sequence (tuple or list) of two monodimensional ndarrays, such that grids[0] and grids[1] contain the sampling nodes associated to axes 0 (Y-axis) and 1 (X-axis) of the input array u.

  When given, the input grids are used to set the extent of the displayed image (see matplotlib.imshow documentation).

• origin (str in {'upper', 'lower'}, optional) – Place the [0, 0] index of the array in the upper left or lower left corner of the Axes. When not given, the default setting is that of matplotlib (see key ‘image.origin’ of the matplotlib configuration parameter rcParams).

• aspect (str in {'equal', 'auto'} or float or None, optional) –

  The aspect ratio of the Axes. This parameter is particularly relevant for images since it determines whether data pixels are square (see matplotlib.imshow documentation).

  When not given, the default setting is that of matplotlib (see key ‘image.aspect’ of the matplotlib configuration parameter rcParams).

• is_notebook (bool, optional) – Indicate whether the running environment is an interactive notebook (is_notebook = True) or not (is_notebook = False).

Returns:

fg – Produced image instance.

Return type:

<class ‘matplotlib.image.AxesImage’>

See also

update_display_monosrc_2d

pyepri.displayers.update_display_monosrc_2d(u, fg, is_notebook=False, displayFcn=None, adjust_dynamic=True, time_sleep=0.01)

Update single 2D image display.

Parameters:

• u (ndarray) – Two-dimensional array

• fg (<class 'matplotlib.image.AxesImage'>) – Image instance to be updated.

• is_notebook (bool, optional) – Indicate whether the running environment is an interactive notebook (is_notebook = True) or not (is_notebook = False).

• displayFcn (<class 'function'>, optional) – Function with prototype im = displayFcn(u) that changes the 2D image u into another 2D image. When displayFcn is given, the displayed image is im = displayFcn(u) instead of u.

• adjust_dynamic (bool, optional) – Set adjust_dynamic = True to maximize the dynamic of the displayed image during the updating process, otherwise, set adjust_dynamic = False to keep the displayed dynamic unchanged.

• time_sleep (float, optional) – Duration in seconds of pause or sleep (depending on the running environment) to perform after image drawing.

Return type:

None

See also

init_display_monosrc_2d

pyepri.displayers.init_display_monosrc_3d(u, newfig=True, figsize=None, time_sleep=0.01, units=None, display_labels=False, displayFcn=None, cmap=None, grids=None, origin='lower', aspect=None, boundaries='auto', is_notebook=False, indexes=None)

Initialize display for a single 3D image (display the three central slices of a 3D volume).

Parameters:

• u (ndarray) – Three-dimensional array

• newfig (bool, optional) – Specify whether the display must be done into a new figure or not.

• figsize ((float, float), optional) – When given, figsize must be a tuple with length two and such that figsize[0] and figsize[1] are the width and height in inches of the figure to be displayed. When not given, the default setting is that of matplotlib (see key ‘figure.figsize’ of the matplotlib configuration parameter rcParams).

• time_sleep (float, optional) – Duration in seconds of pause or sleep (depending on the running environment) to perform after image drawing.

• units (str, optional) – Units associated to the X, Y & Z axes (handling of different axes units is not provided).

• display_labels (bool, optional) – Set display_labels = True to display axes labels (including units when given).

• displayFcn (<class 'function'>, optional) – Function with prototype im = displayFcn(u) that changes the 3D image u into another 3D image. When displayFcn is given, the displayed image is im = displayFcn(u) instead of u.

• cmap (str, optional) – The registered colormap name used to map scalar data to colors in matplotlib.imshow.

• grids (sequence, optional) –

  A sequence (tuple or list) of three monodimensional ndarrays, such that grids[0], grids[1] and grids[2] contain the sampling nodes associated to axes 0 (Y-axis), axe 1 (X-axis), and axe 2 (Z-axis) of the input array u.

  When given, the input grids are used to set the extent of the displayed slices (see matplotlib.imshow documentation).

• origin (str in {'upper', 'lower'}, optional) – Place the [0, 0] index of the array in the upper left or lower left corner of the Axes. When not given, the default setting is that of matplotlib (see key ‘image.origin’ of the matplotlib configuration parameter rcParams).

• aspect (str in {'equal', 'auto'} or float or None, optional) –

  The aspect ratio of the Axes. This parameter is particularly relevant for images since it determines whether data pixels are square (see matplotlib.imshow documentation).

  When not given, the default setting is that of matplotlib (see key ‘image.aspect’ of the matplotlib configuration parameter rcParams).

• boundaries (str in {'auto', 'same'}) –

  Use boundaries = 'same' to give all subplots the same axes boundaries (in particular, this ensures that all slice images will be displayed on the screen using the same pixel size).

  Otherwise, set boundaries = 'auto' to use tight extent for each displayed slice image.

• is_notebook (bool, optional) – Indicate whether the running environment is an interactive notebook (is_notebook = True) or not (is_notebook = False).

• indexes (sequence of int, optional) –

  When given, indexes must be a sequence of three int, index = (id0, id1, id2), such that id0, id1 and id2 correspond to the indexes used along each axis of the 3D volume to extract the slices to be displayed (using None to keep a particular index to its default value is possible).

  The default setting is indexes = (u.shape[0]//2, u.shape[1]//2, u.shape[2]//2).

Returns:

fg – Sequence of produced image instance (one instance per subplot)

Return type:

sequence of <class ‘matplotlib.image.AxesImage’>

See also

update_display_monosrc_3d

pyepri.displayers.update_display_monosrc_3d(u, fg, is_notebook=False, displayFcn=None, adjust_dynamic=True, time_sleep=0.01, indexes=None)

Update single 3D image display.

Parameters:

• u (ndarray) – Three-dimensional array

• fg (<class 'matplotlib.image.AxesImage'>) – Image instance to be updated.

• is_notebook (bool, optional) – Indicate whether the running environment is an interactive notebook (is_notebook = True) or not (is_notebook = False).

• displayFcn (<class 'function'>, optional) – Function with prototype im = displayFcn(u) that changes the 3D image u into another 3D image. When displayFcn is given, the displayed image is im = displayFcn(u) instead of u.

• adjust_dynamic (bool, optional) – Set adjust_dynamic = True to maximize the dynamic of the displayed slices during the updating process (the displayed dynamic will be [min, max] where min and max denote the min and max values among the three displayed slices), otherwise, set adjust_dynamic = False to keep the displayed dynamic unchanged.

• time_sleep (float, optional) – Duration in seconds of pause or sleep (depending on the running environment) to perform after image drawing.

• indexes (sequence of int, optional) –

  When given, indexes must be a sequence of three int, index[j] = (id0, id1, id2), such that id0, id1 and id2 correspond to the indexes used along each axis of the 3D volume to extract the slices to be displayed (using None to keep a particular index to its default value is possible).

  The default setting is indexes = (u.shape[0]//2, u.shape[1]//2, u.shape[2]//2).

Return type:

None

See also

init_display_monosrc_3d

pyepri.displayers.init_display_spectralspatial_4d(u, newfig=True, figsize=None, time_sleep=0.01, displayFcn=None, cmap=None, grids=None, display_labels=True, origin='lower', aspect=None, boundaries='auto', is_notebook=False, interpolation='nearest', slice_indexes=None, spec_indexes=None, show_legend=True, legend_loc='upper right', custom_spec=[], spec_normalization=False)

Initialize display for a spectral-spatial 4D image.

Parameters:

• u (ndarray) – Three-dimensional array

• newfig (bool, optional) – Specify whether the display must be done into a new figure or not.

• figsize ((float, float), optional) – When given, figsize must be a tuple with length two and such that figsize[0] and figsize[1] are the width and height in inches of the figure to be displayed. When not given, the default setting is that of matplotlib (see key ‘figure.figsize’ of the matplotlib configuration parameter rcParams).

• time_sleep (float, optional) – Duration in seconds of pause or sleep (depending on the running environment) to perform after image drawing.

• displayFcn (<class 'function'>, optional) – Function with prototype im = displayFcn(u) that changes the 4D image u into another 4D image. When displayFcn is given, the displayed image is im = displayFcn(u) instead of u.

• cmap (str, optional) – The registered colormap name used to map scalar data to colors in matplotlib.imshow.

• grids (sequence, optional) –

  A sequence (tuple or list) of four monodimensional ndarrays, such that grids[0], grids[1], grids[2] and grids[3] contain the sampling nodes associated to axes 0 (B-axis), axe 1 (Y-axis), axe 2 (X-axis) and axe 3 (Z-axis) of the input array u.

  When given, the input grids are used to set the extent of the displayed slices (see matplotlib.imshow documentation).

• display_labels (bool, optional) – Set display_labels = True to display axes labels.

• origin (str in {'upper', 'lower'}, optional) – This parameter only affects the 2D slice image axes. Place the [0, 0] index of the array in the upper left or lower left corner of the Axes. When not given, the default setting is that of matplotlib (see key ‘image.origin’ of the matplotlib configuration parameter rcParams).

• aspect (str in {'equal', 'auto'} or float or None, optional) –

  This parameter only affects the 2D slice image axes. Set aspect ratio of the Axes. This parameter is particularly relevant for images since it determines whether data pixels are square (see matplotlib.imshow documentation).

  When not given, the default setting is that of matplotlib (see key ‘image.aspect’ of the matplotlib configuration parameter rcParams).

• boundaries (str in {'auto', 'same'}) –

  This parameter only affects the 2D slice image axes. Use boundaries = 'same' to give all subplots the same axes boundaries (in particular, this ensures that all slice images will be displayed on the screen using the same pixel size).

  Otherwise, set boundaries = 'auto' to use tight extent for each displayed slice image.

• is_notebook (bool, optional) – Indicate whether the running environment is an interactive notebook (is_notebook = True) or not (is_notebook = False).

• interpolation (str, optional) – The interpolation method used (see matplotlib documentation for the possible choices).

• slice_indexes (sequence of four int, optional) –

  Indexes used to extract slices of spectral-spatial image, the sequence must contain four integer indexes, slice_indexes = (id0, id1, id2, id3), that are used to extract and display 2D slices from the 4D spectral-spatial image:

  • u[id0, :, id2, :] : YZ slice (for B = Bgrid[id0] and X = xgrid[id2])

  • u[id0, id1, :, :] : ZX slice (for B = Bgrid[id0] and Y = ygrid[id1])

  • u[id0, :, :, id3] : YX slice (for B = Bgrid[id0] and Z = zgrid[id3])

  When not given, the default setting is slice_indexes[i] = u.shape[i]//2, The slice indexes can be partially given, e.g., using slice_indexes = (5, None, 10, None), in this case, the not given indexes will be automatically replaced by their default values described above.

• spec_indexes (sequence of sequences of 3 int, optional) –

  Each element spec_indexes[i] is a sequence containing 3 integers, corresponding to the spatial indexes along the three spatial axes of the 4D image, and use to extract and display profiles.

  More precisely, the extracted and displayed profiles are the u[:, id[0], id[1], id[2]] for id in spec_indexes.

  When not given, the default setting is spec_indexes = ((u.shape[1]//2, u.shape[2]//2, u.shape[3]//2)).

• show_legend (bool, optional) – Decide whether the legend in the spectrum display area should be visible or not when the figure is drawn.

• legend_loc (str, optional) – The location of the legend in the spectrum display area (see matplotlib documentation for possible choices).

• custom_spec (sequence of dict, optional) –

  This parameter can be used to specify some custom profiles to be displayed in the bottom axes.

  When given, each element of custom_spec must be a dictionary with the following key-values:

  • ’spec’ : the custom profile to be displayed (monodimensional numpy array)

  • ’B’ : the sampling grid (B axis) associated to the custom profile (monodimensional numpy array)

  • ’label’ : label of the custom profile (str)

• spec_normalization (bool, optional) – Decide whether the displayed spectra should be normalized or not. When spectra normalization is enabled, each displayed spectrum is divided by its maximum value (normalization occurs at display only, it does not affect the latent image)

Returns:

fg – Contains axes and handles of the produced image instance

Return type:

dict

See also

update_display_spectralspatial_4d

pyepri.displayers.update_display_spectralspatial_4d(u, hdl, is_notebook=False, displayFcn=None, adjust_dynamic=True, time_sleep=0.01, slice_indexes=None, spec_indexes=None, spec_normalization=False)

Update spectral-spatial 4D image display.

Parameters:

• u (ndarray) – Three-dimensional array

• hdl (dict) – Contains the handles and axes of the image instance to be updated (output of py:func:init_display_spectralspatial_4d)

• is_notebook (bool, optional) – Indicate whether the running environment is an interactive notebook (is_notebook = True) or not (is_notebook = False).

• displayFcn (<class 'function'>, optional) – Function with prototype im = displayFcn(u) that changes the 4D image u into another 4D image. When displayFcn is given, the displayed image is im = displayFcn(u) instead of u.

• adjust_dynamic (bool, optional) – Set adjust_dynamic = True to maximize the dynamic of the displayed slices and profiles during the updating process. Otherwise, set adjust_dynamic = False to keep the displayed dynamic unchanged.

• time_sleep (float, optional) – Duration in seconds of pause or sleep (depending on the running environment) to perform after image drawing.

• slice_indexes (sequence of four int, optional) –

  Indexes used to extract slices of spectral-spatial image, the sequence must contain four integer indexes, slice_indexes = (id0, id1, id2, id3), that are used to extract and display 2D slices from the 4D spectral-spatial image:

  • u[id0, :, id2, :] : YZ slice (for B = Bgrid[id0] and X = xgrid[id2])

  • u[id0, id1, :, :] : ZX slice (for B = Bgrid[id0] and Y = ygrid[id1])

  • u[id0, :, :, id3] : YX slice (for B = Bgrid[id0] and Z = zgrid[id3])

  When not given, the default setting is slice_indexes[i] = u.shape[i]//2, The slice indexes can be partially given, e.g., using slice_indexes = (5, None, 10, None), in this case, the not given indexes will be automatically replaced by their default values described above.

• spec_indexes (sequence of sequences of 3 int, optional) –

  Each element spec_indexes[i] is a sequence containing 3 integers, corresponding to the spatial indexes along the three spatial axes of the 4D image, and use to extract and display profiles.

  More precisely, the extracted and displayed profiles are the u[:, id[0], id[1], id[2]] for id in spec_indexes.

  When not given, the default setting is spec_indexes = ((u.shape[1]//2, u.shape[2]//2, u.shape[3]//2)).

• spec_normalization (bool, optional) – Decide whether the displayed spectra should be normalized or not. When spectra normalization is enabled, each displayed spectrum is divided by its maximum value (normalization occurs at display only, it does not affect the latent image)

Return type:

None

See also

init_display_spectralspatial_4d

pyepri.displayers.init_display_multisrc_2d(u, newfig=True, figsize=None, time_sleep=0.01, units=None, display_labels=False, displayFcn=None, cmap=None, grids=None, origin='lower', aspect=None, boundaries='auto', is_notebook=False, src_labels=None)

Initialize display for a sequence of 2D images.

Parameters:

• u (sequence of ndarray) – The sequence (tuple or list) of two-dimensional images to be displayed.

• newfig (bool, optional) – Specify whether the display must be done into a new figure or not.

• figsize ((float, float), optional) – When given, figsize must be a tuple with length two and such that figsize[0] and figsize[1] are the width and height in inches of the figure to be displayed. When not given, the default setting is that of matplotlib (see key ‘figure.figsize’ of the matplotlib configuration parameter rcParams).

• time_sleep (float, optional) – Duration in seconds of pause or sleep (depending on the running environment) to perform after image drawing.

• units (str, optional) – Units associated to the X & Y axes of the different source images (handling of different axes units is not provided).

• display_labels (bool, optional) – Set display_labels = True to display axes labels (including units when given).

• displayFcn (<class 'function'>, optional) – Function with prototype im = displayFcn(u) that changes the 3D image u into another 3D image. When displayFcn is given, the displayed image is im = displayFcn(u) instead of u.

• cmap (str, optional) – The registered colormap name used to map scalar data to colors in matplotlib.imshow.

• grids (sequence, optional) –

  A sequence with same length as u, such that grids[j] is a sequence containing two monodimensional arrays (grids[j][0] and grids[j][1]) corresponding to the sampling nodes associated to axes 0 (Y-axis), axe 1 (X-axis) of the j-th source image u[j].

  When given, the input grids are used to set the extent of the displayed source images (see matplotlib.imshow documentation).

• origin (str in {'upper', 'lower'}, optional) – Place the [0, 0] index of the array in the upper left or lower left corner of the Axes. When not given, the default setting is that of matplotlib (see key ‘image.origin’ of the matplotlib configuration parameter rcParams).

• aspect (str in {'equal', 'auto'} or float or None, optional) –

  The aspect ratio of the Axes. This parameter is particularly relevant for images since it determines whether data pixels are square (see matplotlib.imshow documentation).

  When not given, the default setting is that of matplotlib (see key ‘image.aspect’ of the matplotlib configuration parameter rcParams).

• boundaries (str in {'auto', 'same'}) –

  Use boundaries = 'same' to give all subplots the same axes boundaries (in particular, this ensures that all source images will be displayed on the screen using the same pixel size).

  Otherwise, set boundaries = 'auto' to use tight extent for each displayed slice image.

• is_notebook (bool, optional) – Indicate whether the running environment is an interactive notebook (is_notebook = True) or not (is_notebook = False).

• src_labels (sequence of str, optional) – When given, src_label must be a sequence with same length as u such that src_labels[j] corresponds to the label of the j-th source u[j] (that is, a str to be added to the j-th source suptitle).

Returns:

fg – Sequence of produced image instance (one instance per subplot).

Return type:

sequence of <class ‘matplotlib.image.AxesImage’>

See also

update_display_multisrc_2d

pyepri.displayers.update_display_multisrc_2d(u, fg, is_notebook=False, displayFcn=None, adjust_dynamic=True, time_sleep=0.01)

Update display for a sequence of 2D images.

Parameters:

• u (sequence of ndarray) – The sequence (tuple or list) of two-dimensional images to be displayed.

• fg (sequence of <class 'matplotlib.image.AxesImage'>) – The sequence of image instances to be updated.

• is_notebook (bool, optional) – Indicate whether the running environment is an interactive notebook (is_notebook = True) or not (is_notebook = False).

• displayFcn (<class 'function'>, optional) – Function with prototype im = displayFcn(u) that changes the sequence u into another sequence of 2D images (with same length). When displayFcn is given, the displayed image is im = displayFcn(u) instead of u.

• adjust_dynamic (bool, optional) – Set adjust_dynamic = True to maximize the dynamic of the displayed sequence of images during the updating process (the displayed dynamic will be [min, max] where min and max denote the min and max values among all the images in u), otherwise, set adjust_dynamic = False to keep the displayed dynamic unchanged.

• time_sleep (float, optional) – Duration in seconds of pause or sleep (depending on the running environment) to perform after image drawing.

Return type:

None

See also

init_display_multisrc_2d

pyepri.displayers.init_display_multisrc_3d(u, newfig=True, figsize=None, time_sleep=0.01, units=None, display_labels=False, displayFcn=None, cmap=None, grids=None, origin='lower', aspect=None, boundaries='auto', is_notebook=False, indexes=None, src_labels=None)

Initialize display for a sequence of 3D images.

Parameters:

• u (sequence of ndarray) – The sequence (tuple or list) of three-dimensional images to be displayed.

• newfig (bool, optional) – Specify whether the display must be done into a new figure or not.

• figsize ((float, float), optional) – When given, figsize must be a tuple with length two and such that figsize[0] and figsize[1] are the width and height in inches of the figure to be displayed. When not given, the default setting is that of matplotlib (see key ‘figure.figsize’ of the matplotlib configuration parameter rcParams).

• time_sleep (float, optional) – Duration in seconds of pause or sleep (depending on the running environment) to perform after image drawing.

• units (str, optional) – Units associated to the X, Y & Z axes of the different source images (handling of different axes units is not provided).

• display_labels (bool, optional) – Set display_labels = True to display axes labels (including units when given).

• displayFcn (<class 'function'>, optional) – Function with prototype im = displayFcn(u) that changes the 3D image u into another 3D image. When displayFcn is given, the displayed image is im = displayFcn(u) instead of u.

• cmap (str, optional) – The registered colormap name used to map scalar data to colors in matplotlib.imshow.

• grids (sequence, optional) –

  A sequence with same length as u, such that grids[j] is a sequence containing three monodimensional arrays (grids[j][0], grids[j][1], grids[j][2]) corresponding to the sampling nodes associated to axes 0 (Y-axis), axe 1 (X-axis) and axe 2 (Z-axis) of the j-th source image u[j].

  When given, the input grids are used to set the extent of the displayed source images (see matplotlib.imshow documentation).

• origin (str in {'upper', 'lower'}, optional) – Place the [0, 0] index of the array in the upper left or lower left corner of the Axes. When not given, the default setting is that of matplotlib (see key ‘image.origin’ of the matplotlib configuration parameter rcParams).

• aspect (str in {'equal', 'auto'} or float or None, optional) –

  The aspect ratio of the Axes. This parameter is particularly relevant for images since it determines whether data pixels are square (see matplotlib.imshow documentation).

  When not given, the default setting is that of matplotlib (see key ‘image.aspect’ of the matplotlib configuration parameter rcParams).

• boundaries (str in {'auto', 'same'}) –

  Use boundaries = 'same' to give all subplots the same axes boundaries (in particular, this ensures that all source images will be displayed on the screen using the same pixel size).

  Otherwise, set boundaries = 'auto' to use tight extent for each displayed slice image.

• is_notebook (bool, optional) – Indicate whether the running environment is an interactive notebook (is_notebook = True) or not (is_notebook = False).

• indexes (sequence, optional) –

  When given, indexes must be a sequence with lenght nsrc such that indexes[j] = (id0, id1, id2) is a sequence of three indexes corresponding to the indexes used along each axis of the j-th source image u[j] to extract the slices to be displayed (using None to keep a particular index to its default value is possible).

  The default setting is indexes = [[im.shape[0]//2, u.shape[1]//2, u.shape[2]//2] for im in u].

• src_labels (sequence of str, optional) – When given, src_label must be a sequence with same length as u such that src_labels[j] corresponds to the label of the j-th source u[j] (that is, a str to be added to the j-th source suptitle).

Returns:

fg – A sequence with same lenght as u and such that fg[j] is as sequence of three <class ‘matplotlib.image.AxesImage’> corresponding to the image instances produced when displaying the three slices of u[j].

Return type:

sequence of sequence of <class ‘matplotlib.image.AxesImage’>

See also

update_display_multisrc_3d

pyepri.displayers.update_display_multisrc_3d(u, fg, is_notebook=False, displayFcn=None, adjust_dynamic=True, time_sleep=0.01, indexes=None)

Update display for a sequence of 3D images.

Parameters:

• u (sequence of ndarray) – The sequence (tuple or list) of two-dimensional images to be displayed.

• fg (sequence of sequence of <class 'matplotlib.image.AxesImage'>) – The sequence of sequences of image instances to be updated (see update_display_multisrc_3d output).

• is_notebook (bool, optional) – Indicate whether the running environment is an interactive notebook (is_notebook = True) or not (is_notebook = False).

• displayFcn (<class 'function'>, optional) – Function with prototype im = displayFcn(u) that changes the sequence u into another sequence of 2D images (with same length). When displayFcn is given, the displayed image is im = displayFcn(u) instead of u.

• adjust_dynamic (bool, optional) – Set adjust_dynamic = True to maximize the dynamic of the displayed sequence of images during the updating process (the displayed dynamic will be [min, max] where min and max denote the min and max values among all displayed slices computed from u), otherwise, set adjust_dynamic = False to keep the displayed dynamic unchanged.

• time_sleep (float, optional) – Duration in seconds of pause or sleep (depending on the running environment) to perform after image drawing.

• indexes (sequence, optional) –

  When given, indexes must be a sequence with lenght nsrc such that indexes[j] = (id0, id1, id2) is a sequence of three indexes corresponding to the indexes used along each axis of the j-th source image u[j] to extract the slices to be displayed (using None to keep a particular index to its default value is possible).

  The default setting is indexes = [[im.shape[0]//2, u.shape[1]//2, u.shape[2]//2] for im in u].

Return type:

None

See also

init_display_multisrc_3d

pyepri.displayers.create_2d_displayer(nsrc=1, newfig=True, figsize=None, displayFcn=None, time_sleep=0.01, units=None, adjust_dynamic=True, display_labels=False, cmap=None, grids=None, origin='lower', aspect=None, boundaries='auto', indexes=None, src_labels=None)

Instantiate a single 2D image displayer.

This function instantiate a pyepri.Displayer class instance using ndim=3 and passing all the other args & kwargs to the pyepri.displayers.Displayer default constructor (type help(pyepri.displayers) for more details).

pyepri.displayers.create_3d_displayer(nsrc=1, newfig=True, figsize=None, displayFcn=None, time_sleep=0.01, units=None, extents=None, adjust_dynamic=True, display_labels=False, cmap=None, grids=None, origin='lower', aspect=None, boundaries='auto', indexes=None, src_labels=None)

Instantiate a single 3D image displayer.

This function instantiate a pyepri.Displayer class instance using ndim=3 and passing all the other args & kwargs to the pyepri.displayers.Displayer default constructor (type help(pyepri.displayers) for more details).

pyepri.displayers.create_spectralspatial_4d_displayer(newfig=True, figsize=None, displayFcn=None, time_sleep=0.01, adjust_dynamic=True, cmap=None, grids=None, display_labels=True, origin='lower', aspect=None, boundaries='auto', interpolation='nearest', slice_indexes=None, spec_indexes=None, show_legend=True, legend_loc='upper right', custom_spec=[], spec_normalization=False)

pyepri.displayers.create(u, newfig=True, figsize=None, displayFcn=None, time_sleep=0.01, units=None, extents=None, adjust_dynamic=True, display_labels=False, cmap=None, grids=None, origin='lower', aspect=None, boundaries='auto', indexes=None, src_labels=None, interpolation='nearest', slice_indexes=None, spec_indexes=None, show_legend=True, legend_loc='upper right', custom_spec=[], spec_normalization=False)

Instantiate a Displayer object suited to the input parameter.

This function instantiate a pyepri.Displayer class instance using nsrc and ndim values inferred from u and passing all the other args & kwargs to the pyepri.displayers.Displayer default constructor (type help(pyepri.displayers) for more details).

pyepri.displayers.get_number(fg)

Retrieve displayed figure number.

Parameters:

fg (<class 'matplotlib.image.AxesImage'> or sequence of <class 'matplotlib.image.AxesImage'> or dict) – Image instance or sequence of image instances that belong to the same figure or dict with ‘fg’ key and <class ‘matplotlib.figure.Figure’> associated value.

Returns:

fgnum – Figure number.

Return type:

int

pyepri.displayers._check_inputs_(nsrc=None, ndim=None, displayFcn=None, time_sleep=None, units=None, adjust_dynamic=None, display_labels=None, cmap=None, grids=None, origin=None, aspect=None, boundaries=None, u=__EMPTY_ARRAY__, newfig=None, figsize=None, indexes=None, src_labels=None, interpolation=None, legend_loc=None, show_legend=None, spec_normalization=None, slice_indexes=None, spec_indexes=None, custom_spec=None)

Factorized consistency checks for functions in this pyepri.displayers submodule.

class pyepri.displayers.Displayer(nsrc, ndim, newfig=True, figsize=None, displayFcn=None, time_sleep=0.01, units=None, adjust_dynamic=True, display_labels=False, cmap=None, grids=None, origin='lower', aspect=None, boundaries='auto', force_multisrc=False, indexes=None, src_labels=None, interpolation='nearest', slice_indexes=None, spec_indexes=None, show_legend=True, legend_loc='upper right', custom_spec=[], spec_normalization=False)

Class for display and update of different kind of images, in different running environments.

Supported images

• single 2D image : the input signal is a two-dimensional array

• single 3D image : the input signal is a three-dimensional array

• multisources 2D images : the input signal is a sequence of two-dimensional arrays (each array being called a source)

• multisources 3D images : the input signal is a sequence of three-dimensional arrays (each array being called a source)

Displaying rules

• single 2D image : the image is displayed using matplotlib.imshow

• single 3D image : the three central slices (along each axis) of the image are drawn using matplotlib.imshow into a single row of subplots.

• multisources 2D images : the source images are drawn using matplotlib.imshow into a single row of subplots.

• multisources 3D images : each source image is represented using a row of subplots. Each row contains the three central slices of the considered source image.

In all situations described above, several display customization are proposed (axes labels, axes boundaries, colormap, aspect, …) through the kwargs of the default constructor.

Class attributes

init_display<class ‘function’>

Function with prototype fg = init_display(u) that can be used to draw the input image u according to the rules described above. The returned fg is the produced image instance (when u is a single 2D image) or a sequence of image instances (when u is a single 3D image or a multisources 2D or 3D image) corresponding to the image instances of each produced subplot.

update_display<class ‘function’>

Function with prototype None = update_display(u, fg) that can be used to replace the image displayed in fg (the ouptut of the init_display attribute described above) by u.

get_number<class ‘function’>

Function with prototype fgnum = get_number(fg) that return the figure number from the output of the init_display attribute described above.

title<class ‘function’>

Function with prototype None = title(str) that can be used to update the title (or suptitle when subplots are used) of the current figure.

notebookbool

A bool that specified whether the detected environment is an interactive notebook environments (notebook = True) or not (notebook = False)

pause<class ‘function’>

Function with prototype None = pause(t=time_sleep) used to pause (or sleep in interactive python environment) during of t seconds, the default value of time_sleep is defined during the pyepri.displayers.Display object instanciation.

clear_output<class ‘function’>

Function with prototype None = clear_output() used to clear the currently displayed image within an interactive notebook running environment.

clear_output

get_number