pyepri.displayers

This module provides tools for displaying 2D & 3D, mono & multi source images, with possibility to update the displayed image at any moment (useful in an iterative framework). The display functionnalities of this modules are compatible with console and interactive Python (IPython notebook) environments.

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.
init_display_monosrc_2d(u[, figsize, time_sleep, ...])	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[, figsize, time_sleep, ...])	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_multisrc_2d(u[, figsize, time_sleep, ...])	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[, figsize, time_sleep, ...])	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, figsize, displayFcn, ...])	Instantiate a single 2D image displayer.
create_3d_displayer([nsrc, figsize, displayFcn, ...])	Instantiate a single 3D image displayer.
create(u[, figsize, displayFcn, time_sleep, units, ...])	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.init_display_monosrc_2d(u, 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

• figsize ((float, float), optional) – When given, figsize must be a tuple with length two and such taht 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, 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

• figsize ((float, float), optional) – When given, figsize must be a tuple with length two and such taht 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[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).

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_multisrc_2d(u, 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.

• figsize ((float, float), optional) – When given, figsize must be a tuple with length two and such taht 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, 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.

• figsize ((float, float), optional) – When given, figsize must be a tuple with length two and such taht 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, 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, 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(u, 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 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'>) – Image instance or sequence of image instances that belond to the same figure.

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__, figsize=None, indexes=None, src_labels=None)

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

class pyepri.displayers.Displayer(nsrc, ndim, 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)

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