equimagelab.jupyter package

JupyterLab interface.

Submodules

equimagelab.jupyter.backend_dash module

Dash backend for JupyterLab interface.

The following symbols are imported in the equimagelab namespace for convenience:

“Dashboard”.

class equimagelab.jupyter.backend_dash.Dashboard(port=8050, interval=500, debug=False)

Bases: object

Dashboad class.

__init__(port=8050, interval=500, debug=False)

Initialize dashboard.

This dashboard uses Dash to display images, histograms, statistics, etc… in a separate browser tab or window. It fetches updates from the Dash server at given intervals.

Parameters:

  • port (int, optional) – The port bound to the Dash server (default 8050).

  • interval (int, optional) – The time interval (ms) between dashboard updates (default 500).

  • debug (bool, optional) – If True, run Dash in debug mode (default False).

show(images, histograms=False, statistics=False, sampling=-1, filters=True, click=True, select=True, synczoom=True, trans=None)

Show image(s) on the dashboard.

Parameters:

  • images – A single/tuple/list/dict of Image object(s) or numpy.ndarray(s) with shape (height, width, 3) (for color images), (height, width, 1) or (height, width) (for grayscale images). Each image is displayed in a separate tab. The tabs are labelled according to the keys for a dictionary. Otherwise, the tabs are labelled “Image” & “Reference” if there are one or two images, and “Image #1”, “Image #2”… if there are more.

  • histograms (optional) – If True or a string, show the histograms of the image(s). The string lists the channels of the histograms (see Image.histograms()). True is substituted with “RGBL” (red, green, blue, luma). Default is False.

  • statistics (optional) – If True or a string, show the statistics of the image(s). The string lists the channels of the statistics (see Image.statistics()). True is substituted with “RGBL” (red, green, blue, luma). Default is False.

  • sampling (int, optional) – The downsampling rate (defaults to jupyter.params.sampling if negative). Only the pixels image[::sampling, ::sampling] of a given image are shown, to speed up display.

  • filters (bool, optional) – If True (default), add image filters menu (R, G, B, L channel filters, shadowed/highlighted pixels, images differences, partial histograms).

  • click (bool, optional) – If True (default), show image data on click.

  • select (bool, optional) – If True (default), allow rectangle, ellipse and lasso selections on the images.

  • synczoom (bool, optional) – If True (default), synchronize zooms over images. Zooms will be synchronized only if all images have the same size.

  • trans (optional) – A container with an histogram transformation (see Image.apply_channels()), plotted on top of the histograms of the “Reference” tab (default None).

show_t(image, channels='RGBL', sampling=-1, filters=True, click=True, select=True, synczoom=True)

Show the input and output images of an histogram transformation on the dashboard.

Displays the input image, histograms, statistics, and the transformation curve in tab “Reference”, and the output image, histograms, and statistics in tab “Image”.

Parameters:

  • image (Image) – The output image (must embed a transformation image.trans - see Image.apply_channels()).

  • channels (str, optional) – The channels of the histograms and statistics (default “” = “RGBL” for red, green, blue, luma). The channels of the transformation are automatically appended. See Image.histograms().

  • sampling (int, optional) – The downsampling rate (defaults to jupyter.params.sampling if negative). Only the pixels image[::sampling, ::sampling] of a given image are shown, to speed up display.

  • filters (bool, optional) – If True (default), add image filters menu (R, G, B, L channel filters, shadowed/highlighted pixels, images differences, partial histograms).

  • click (bool, optional) – If True (default), show image data on click.

  • select (bool, optional) – If True (default), allow rectangle, ellipse and lasso selections on the images.

  • synczoom (bool, optional) – If True (default), synchronize zooms over images.

show_wavelets(wt, absc=True, normalize=False, histograms=False, statistics=False, sampling=-1, filters=True, click=True, select=True, synczoom=True)

Show wavelet coefficients on the dashboard.

For a discrete wavelet transform, displays Mallat’s representation in a single tab. For a starlet transform, displays the final approximation and the successive starlet levels in different tabs. Not implemented for stationary wavelet (“à trous”) transforms.

Parameters:

  • wt (WaveletTransform) – The wavelet coefficients.

  • absc (bool, optional) – If True (default), display the absolute value of the wavelet coefficients.

  • normalize (bool, optional) – If True, normalize each set of wavelet coefficients (or their absolute value if absc is True) in the [0, 1] range. Default is False.

  • histograms (optional) – If True or a string, show the histograms of the image(s). The string lists the channels of the histograms (see Image.histograms()). True is substituted with “RGBL” (red, green, blue, luma). Default is False.

  • statistics (optional) – If True or a string, show the statistics of the image(s). The string lists the channels of the statistics (see Image.statistics()). True is substituted with “RGBL” (red, green, blue, luma). Default is False.

  • sampling (int, optional) – The downsampling rate (defaults to jupyter.params.sampling if negative). Only the pixels image[::sampling, ::sampling] of a given image are shown, to speed up display.

  • filters (bool, optional) – If True (default), add image filters menu (R, G, B, L channel filters, shadowed/highlighted pixels, images differences, partial histograms).

  • click (bool, optional) – If True (default), show image data on click.

  • select (bool, optional) – If True (default), allow rectangle, ellipse and lasso selections on the images.

  • synczoom (bool, optional) – If True (default), synchronize zooms over images. Zooms will be synchronized only if all images have the same size.

carousel(images, sampling=-1, interval=2000)

Show a carousel of images on the dashboard.

Parameters:

  • images – A tuple/list/dict of Image object(s) or numpy.ndarray(s) with shape (height, width, 3) (for color images), (height, width, 1) or (height, width) (for grayscale images). The images are labelled according to the keys for a dictionary. Otherwise, the images are labelled “Image” and “Reference” if there are two images, and “Image #1”, “Image #2”… if there are more.

  • sampling (int, optional) – The downsampling rate (defaults to jupyter.params.sampling if negative). Only the pixels image[::sampling, ::sampling] of a given image are shown, to speed up display.

  • interval (int, optional) – The interval (ms) between image changes in the carousel (default 2000).

slider(image1, image2, label1='Image', label2='Reference', sampling=-1)

Compare two images with a “before/after” slider on the dashboard.

Parameters:

  • image1 – The “after” image, an Image object or numpy.ndarray with shape (height, width, 3) (for a color image), (height, width, 1) or (height, width) (for a grayscale image).

  • image2 – The “before” image, an Image object or numpy.ndarray with shape (height, width, 3) (for a color image), (height, width, 1) or (height, width) (for a grayscale image).

  • label1 (str, optional) – The label of the first image (default “Image”).

  • label2 (str, optional) – The label of the second image (default “Reference”).

  • sampling (int, optional) – The downsampling rate (defaults to jupyter.params.sampling if negative). Only image1[::sampling, ::sampling] and image2[::sampling, ::sampling] are shown, to speed up display.

equimagelab.jupyter.backend_plotly module

Plotly backend for JupyterLab interface.

The following symbols are imported in the equimagelab namespace for convenience:

“show”, “show_t”, “show_histograms”, “show_statistics”, “light_curve”.

equimagelab.jupyter.backend_plotly.show(image, histograms=False, statistics=False, sampling=-1, width=-1, hover=False, renderer=None)

Show an image using plotly.

Parameters:

  • image – An Image object or numpy.ndarray with shape (height, width, 3) (for a color image), (height, width, 1) or (height, width) (for a grayscale image).

  • histograms (optional) – If True or a string, show the histograms of the image. The string lists the channels of the histograms (see Image.histograms()). True is substituted with “RGBL” (red, green, blue, luma). Default is False.

  • statistics (optional) – If True or a string, show the statistics of the image. The string lists the channels of the statistics (see Image.statistics()). True is substituted with “RGBL” (red, green, blue, luma). Default is False.

  • sampling (int, optional) – The downsampling rate (defaults to jupyter.params.sampling if negative). Only image[::sampling, ::sampling] is shown, to speed up display.

  • width (int, optional) – The width of the figure (defaults to jupyter.params.maxwidth if negative).

  • hover (bool, optional) – If True, show the image data on hover (default False). Warning: setting hover = True can slow down display a lot !

  • renderer (str, optional) – The plotly renderer (default None = “jupyterlab”).

equimagelab.jupyter.backend_plotly.show_histograms(image, channels='', log=True, width=-1, xlabel='Level', trans=None, renderer=None)

Plot the histograms of an image using plotly.

Parameters:

  • image – An Image object or numpy.ndarray with shape (height, width, 3) (for a color image), (height, width, 1) or (height, width) (for a grayscale image).

  • channels (str, optional) – The channels of the histograms (default “” = “RGBL” for red, green, blue, luma). See Image.histograms().

  • log (bool, optional) – If True (default), plot the histogram counts in log scale.

  • width (int, optional) – The width of the figure (defaults to jupyter.params.maxwidth if negative).

  • xlabel (str, optional) – The x axis label of the plot (default “Level”).

  • trans (optional) – A container with an histogram transformation (see Image.apply_channels()), plotted on top of the histograms (default None).

  • renderer (str, optional) – The plotly renderer (default None = “jupyterlab”).

equimagelab.jupyter.backend_plotly.show_statistics(image, channels='', width=-1, rowheight=-1, renderer=None)

Display a table with the statistics of an image using plotly.

Parameters:

  • image – An Image object or numpy.ndarray with shape (height, width, 3) (for a color image), (height, width, 1) or (height, width) (for a grayscale image).

  • channels (str, optional) – The channels of the statistics (default “” = “RGBL” for red, green, blue, luma). See Image.statistics().

  • width (int, optional) – The width of the table (defaults to jupyter.params.maxwidth if negative).

  • rowheight (int, optional) – The height of the rows (default to jupyter.params.rowheight if negative).

  • renderer (str, optional) – The plotly renderer (default None = “jupyterlab”).

equimagelab.jupyter.backend_plotly.show_t(image, channels='RGBL', sampling=-1, width=-1, hover=False, renderer=None)

Show an image embedding an histogram transformation using plotly.

Displays the input histograms with the transformation curve, the output histograms, and the output image.

Parameters:

  • image (Image) – The output image (must embed a transformation image.trans - see Image.apply_channels()).

  • channels (str, optional) – The channels of the histograms (default “” = “RGBL” for red, green, blue, luma). The channels of the transformation are automatically appended. See Image.histograms().

  • sampling (int, optional) – The downsampling rate (defaults to jupyter.params.sampling if negative). Only image[::sampling, ::sampling] is shown, to speed up display.

  • width (int, optional) – The width of the figure (defaults to jupyter.params.maxwidth if negative).

  • hover (bool, optional) – If True, show the image data on hover (default False). Warning: setting hover = True can slow down display a lot !

  • renderer (str, optional) – The plotly renderer (default None = “jupyterlab”).

equimagelab.jupyter.backend_plotly.light_curve(image, reference, maxpoints=32768, width=-1, renderer=None)

Plot light curve (scatter plot of an output image channel vs an input reference channel).

Parameters:

  • image (numpy.ndarray) – The output image channel (luma, …) as an array with shape (height, width).

  • reference (numpy.ndarray) – The input reference channel as an array with shape (height, width).

  • maxpoints (int, optional) – The maximum number of points in the scatter plot. The image and reference will be sampled accordingly (default 32768).

  • width (int, optional) – The width of the figure (defaults to jupyter.params.maxwidth if negative).

  • renderer (str, optional) – The plotly renderer (default None = “jupyterlab”).

equimagelab.jupyter.imports module

JupyterLab interface top-level symbols.

This imports relevant symbols from the jupyter submodules into the equimagelab namespace. These symbols are defined by the __all__ dictionary (if any) of each submodule, and listed in their docstring.

equimagelab.jupyter.params module

JupyterLab interface parameters.

equimagelab.jupyter.params.set_image_sampling(s)

Set image downsampling rate for display.

Parameters:

s (int) – The image downsampling rate in pixels.

equimagelab.jupyter.params.set_figure_max_width(w)

Set maximum figure width.

Parameters:

w (int) – The maximum figure width in pixels.

equimagelab.jupyter.params.set_figure_margins(left=None, right=None, bottom=None, top=None)

Set or update figure margins.

Parameters:

  • left (int, optional) – The left margin in pixels [unchanged if None (default)].

  • right (int, optional) – The right margin in pixels [unchanged if None (default)].

  • bottom (int, optional) – The bottom margin in pixels [unchanged if None (default)].

  • top (int, optional) – The top margin in pixels [unchanged if None (default)].

equimagelab.jupyter.params.set_table_row_height(h)

Set table row height.

Parameters:

h (int) – The table row height in pixels.

equimagelab.jupyter.utils module

Utils for JupyterLab interface.

The following symbols are imported in the equimagelab namespace for convenience:

“filter”, “shadowed”, “highlighted”, “differences”.

equimagelab.jupyter.utils.get_image_size(image)

Return the width and height of the input image.

Parameters:

image – An Image object or numpy.ndarray with shape (height, width, 3) (for a color image), (height, width, 1) or (height, width) (for a grayscale image).

Returns:

The (width, height) of the image in pixels.

Return type:

int

equimagelab.jupyter.utils.format_images(images, sampling=1, copy=False)

Format images for plotly and Dash.

Returns all images as numpy.ndarrays with shape (height, width, 3) (for color images), or (height, width) (for grayscale images).

Parameters:

  • images – A single/tuple/list of Image object(s) or numpy.ndarray(s) with shape (height, width, 3) (for color images), (height, width, 1) or (height, width) (for grayscale images).

  • sampling (int, optional) – The downsampling rate (default 1; set to jupyter.params.sampling if negative). Only the pixels image[::sampling, ::sampling] of a given image are processed, to speed up operations.

  • copy (bool, optional) – If False (default), the formatted images are (when possible) views of the original images; If True, they are always copies.

Returns:

A single/tuple/list of numpy.ndarray(s) with shape (height/sampling, width/sampling, 3) (for color images) or (height/sampling, width/sampling) (for grayscale images).

equimagelab.jupyter.utils.format_images_as_b64strings(images, sampling=1, compression=4)

Format images for plotly and Dash as PNGs encoded in base64 strings.

Returns all images as PNGs encoded in base64 strings.

Parameters:

  • images – A single/tuple/list of Image object(s) or numpy.ndarray(s) with shape (height, width, 3) (for color images), (height, width, 1) or (height, width) (for grayscale images).

  • sampling (int, optional) – The downsampling rate (default 1; set to jupyter.params.sampling if negative). Only the pixels image[::sampling, ::sampling] of a given image are processed, to speed up operations.

  • compression (int, optional) – The PNG compression level (default 4).

Returns:

A single/tuple/list of PNG image(s) encoded in base64 string(s).

equimagelab.jupyter.utils.filter(image, channels)

Filter the channels of a RGB image.

Returns a copy of the image with the selected red/green/blue channels set to zero.

Parameters:

  • image – An Image object or numpy.ndarray with shape (height, width, 3) (for a color image), (height, width, 1) or (height, width) (for a grayscale image).

  • channels (str) – The displayed channels. A combination of the letters “R” (red), “G” (green), and “B” (blue).

Returns:

A copy of the image as an array with shape (height, width, 3) and the non- selected channels set to zero.

Return type:

numpy.ndarray

equimagelab.jupyter.utils.shadowed(image, reference=None)

Highlight black pixels of an image.

Highlights black pixels on the input image with color jupyter.params.shadowcolor. If a reference image is provided, highlights pixels black on both input and reference images with color 0.5 * jupyter.params.shadowcolor.

Parameters:

  • image – An Image object or numpy.ndarray with shape (height, width, 3) (for a color image), (height, width, 1) or (height, width) (for a grayscale image).

  • reference (optional) – An Image object or numpy.ndarray with shape (height, width, 3) (for a color image), (height, width, 1) or (height, width) (for a grayscale image). Default is None.

Returns:

A copy of the image as an array with shape (height, width, 3) and the black pixels highlighted with color jupyter.params.shadowcolor.

Return type:

numpy.ndarray

equimagelab.jupyter.utils.highlighted(image, reference=None)

Highlight saturated pixels of an image.

A pixel is saturated if at least one channel is >= 1. Shows pixels saturated on the input image with color jupyter.params.highlightcolor. If a reference image is provided, shows pixels saturated on both input and reference images with color 0.5 * jupyter.params.highlightcolor.

Parameters:

  • image – An Image object or numpy.ndarray with shape (height, width, 3) (for a color image), (height, width, 1) or (height, width) (for a grayscale image).

  • reference (optional) – An Image object or numpy.ndarray with shape (height, width, 3) (for a color image), (height, width, 1) or (height, width) (for a grayscale image). Default is None.

Returns:

A copy of the image as an array with shape (height, width, 3) and the saturated pixels highlighted with color jupyter.params.highlightcolor.

Return type:

numpy.ndarray

equimagelab.jupyter.utils.differences(image, reference)

Highlight differences between an image and a reference.

Parameters:

  • image – An Image object or numpy.ndarray with shape (height, width, 3) (for a color image), (height, width, 1) or (height, width) (for a grayscale image).

  • reference (optional) – An Image object or numpy.ndarray with shape (height, width, 3) (for a color image), (height, width, 1) or (height, width) (for a grayscale image).

Returns:

A copy of the image as an array with shape (height, width, 3) and the differences with the reference highlighted with color jupyter.params.diffcolor.

Return type:

numpy.ndarray