Skip to content

Image Viewer

Jump to bottom
Alejandro Noguerón edited this page Aug 12, 2021 · 2 revisions

ImageViewer()

Welcome to the IPLabViewer wiki! Here you will find all the information on how to use IPLabViewer and on all its functionalities

Overview

The IPLabViewer class is an interactive image visualization tool, that allows a user to display an image (or list of images) and interact with it.You can easily change the brightness and contrast of your image, display a histogram , plot the image with different ranges and in different colormaps, perform operations on your image and access the statistics of an image (or a region of it). Plotted on top of the histogram, you will have a line that demonstrates the minimum and maximum values that are being used with respect to the original (the histogram will always show the original). The parameters, widgets, attributes and methods are described below.

IPLabViewer relies on the dynamic environment provided by matplotlib for Jupyter Notebook. It is not meant to be used outside of this environment. In general, we will be importing it (and calling it in the code sections of this wiki) as viewer.

Instructions

The requirements for it to run are:

To use it in your Jupyter Notebook, type the following commands:

$ To activate dynamic environment
%matplotlib widget

# To get the module path
import sys  
sys.path.insert(0, PATH)

# Import
from iplabs import IPLabViewer

where PATH is the location of the file. In this repository, the file is located in source/lib/iplabs.py.

If you include the lib directory in the same path as your notebook, you can exclude the two lines to get the module path, and instead load as:

from lib.iplabs import IPLabViewer

Content

Constructor

viewer(image, title = 'title', widgets = False, hist = False, axis = False, cmap = 'gray', pixel_grid = False, binary = False)

The construction of instance variables is very flexible. The only strictly required argument is an image or list of images (with a valid matplotlib image shape, e.i. a numpy array with shapes (M, N), (M, N, 3/4)). Then, the most basic way to instantiate and IPLabViewer object is by calling it simply with an image as a first argument (if a list of images is given, the default behavior is to display only one at a time, and use widgets to navigate through them (see Widgets)).

image_viewer_object = viewer(img)

This will display:

  • The image with the default settings (using the stringified variable as title, without axis nor colorbar, and with a 'gray' colormap when applicable),
  • Matplotlib's dynamic environment toolbar, which includes four buttons:
    • A button to reset zoom (house): Click on it and the zoom will restore automatically.
    • A button to zoom (square): click it and then click and drag on an image to select a region to zoom into,
    • A button to pan (cross): click it and then click and drag on your image to pan through it,
    • A button to save image in png format (floppy disk),
    • A button (top button) to hide the toolbar.
  • A button with the legend Show Widgets, located below the image.

The use case is for a very quick visualization of an image. From this initial view, widgets can be displayed either by clicking the button or by calling set_widgets(widgets = True) on the object. The rest of the parameters are optional, and are explained below.

Parameters

  • image_list (list of numpy arrays): Only mandatory argument, contains the images.
  • axis (boolean): Display the axis (with pixels as the units) of the image,
  • callbacks (list of one function): The callback for your activation button when you want to include extra widgets (see new_widgets) to perform an operation/transformation on your image. This callback should have as only parameter an image (numpy array) and return an image of the same size. It should get any parameters required for your transformation from other widgets, and then call your actual transformation (see User Defined Widgets),
  • clip_range (list or tuple of ints): Indicates the min and max values To which all the images will be clipped.
  • cmap (string): A string with the colormap desired for the images (currently accepted are 'gray', 'viridis', 'inferno', 'ocean', 'nipy_spectral', 'copper')
  • colorbar (boolean): Decides whether to set or not the colorbar from the beginning. The colorbar can later be set through the buttons.
  • hist (boolean): Display the histogram,
  • new_widgets (list of ipywidgets): List of user-defined widgets. This functionality is meant to be used when the user wants to define an operation/transformation on the image, and see the results in real time withour the need to call the viewer again. The first widgets in the list should define the parameters of the operation (sliders, dropdown menus, text, etc.) and the last widget in the list is a button the activates a callback (see callbacks, User Defined Widgets).
  • normalize (boolean): Scale the values of the image to the range [0,1].
  • pixel_grid (boolean): Plot a grid over each pixel.
  • scale_range (list or tuple of ints): Indicates the min and max values to which all images should be scaled.
  • subplots (list or tuple of ints): If given, the Axes in the Figures (both for images and histograms) will have the given shape. If missing, the default behavior will be set (one single image at a time)
  • title (list of strings): Titles of each of the images. The titles should be given in the same order as the images.
  • widgets (boolean): Display the widget menu. If set to False (default) , only a button Show Widgets will be displayed.

Thus, a more complex way of instantiation would be the following:

image_viewer_object = viewer([image1, image2, image3, ...], title = ['title_image1', 'title_image2', 'title_image3', ...], \
                      widgets = True, hist = True, subplots = [2, 2], clip_range = [0, 1], cmap = 'nipy_spectral')

This will display the images in a grid (if there are less than 3 images, the extra space will be left empty, if there are more than 3, only the first four image will be displayed) each with its corresponding title (if titles are missing, the title will be set to the name of the variable of each image). To the right, the histograms will be shown (in the same grid and with the same title as the images). Further to the right, you will find the widget menu (see Widgets) , including a line that shows the color scaling used. Examples are found in this repository in the file source/IPLabViewer_Tutorial.ipynb

Widgets

The widgets are organized in two main groups, where each group is displayed separately (excluding the simple view with only the Show Widgets button).

  • Inital Menu

    • Brightness & Contrast Slider: Use the slider to adjust the minimum and maximum values of the images (in percentage of the maximum).
    • Show/Hide Histogram Button: On click, displays/hides the histogram of the image to the right of the image. If there are several images, it displays a histogram for each figure, arranged accordingly.
    • Options Button: Switch to the Options menu
    • Reset Button: Sets all parameters their original state.
    • Next and Prev Buttons: Browse through the images (removed if IPLabViewer was called with only one image, or if the parameter subplots was given).

  • Options Menu

    • Colormap Dropdown Menu: choose one of the available colormaps.
    • Show/Hide Axis Button: Show or hide the axis of the images, with pixels as units.
    • Show/Hide Colorbar Button: Show or hide a colorbar next to each image.
    • Back Button: Returns to the Initial view.

All the views include a text box with the statistics of the images, which is updated when applying any transformation to the image.

User Defined Widgets

One of the goals of IPLabViewer was for it to be as intuitive and simple as possible, but at the same time to offer as much functionality as possible to an interested user. The result is the possibility to add User Defined Widgets. These serve the purpose of applying a specific operation or transformation to your images, a transformation that might depend on one or more parameters. IPLabViewer allows you to create a function in a Jupyter cell and apply it simultaneously to all images within your IPLabViewer object with the help of a set of sliders. The function or transformation will take as parameters:

  • an image (NumPy array), and
  • one or more parameters.

Your function will then apply an operation on the image that depends on the parameters. Without advanced knowledge of Matplotlib, you would have to manually run the same process several times, and visualize the results each time. With IPLabViewer, you can simply declare the widgets(s) that choose the parameters and an activation function as parameters to the viewer, and it will call your function and update the images for you.

Additional to the core function that actually performs the operation, you need to declare:

  • widgets to set the parameters of your operation (sliders, dropdown menus, text inputs, see ipywidgets documentation)
  • an callback that will take as input only an image, and will get the necessary parameters from the widgets. This activation function will subsequently call your transformation.
  • an ipywidgets.Button with a meaningful description, that will call your activation function

To activate this functionality, you will pass all the widgets (both the ones to set the parameters and the button to apply the transformation) through the parameter new_widgets = [widget1, widget2, ..., button], and the callback through the parameter callbacks = [callback]. This will alter the widgets menus accordingly:

  • The Initial View will have an additional button, Extra Widgets. This button will let you access the Extra Widgets Menus,
  • Extra Widgets Menu, contains:
    • Additional Widgets: The ones you declared through the parameter new_widgets arranged vertically,
    • Activation Button: The button (also declared through the parameter new_widgets) that will call your activation function (declared through callbacks)
    • Back Button: Returns to the Initial View.

Check our tutorial notebook for a detailed example.

Public Methods

The main methods of the class are listed next. These can be used either to change the state of the IPLabViewer, or to extract information about the images.

get_histogram()

bins, hist, axs_hist = viewer.get_histogram()

Parameters: None

Returns:

  • bins (list of numpy array): bin edges of the histogram. The element of the list corresponds to the image.
  • hist (list of numpy array): values of the histogram on each bin. The element of the list corresponds to the .
  • axs_hist (list of matplotlib Axes): list of the matplotlib.Axes type bar containers which show the plot.

The bins and the hist (values of each bin) are obtained through the numpy.histogram() method.

get_statistics()

mean, std, min_value, max_value, num_channels, size, xlim, ylim, description = viewer.get_statistics()

Parameters: None

Returns:

  • mean (list of floats): Mean of each of the plotted images. The element of the list corresponds to the . The same applies to the rest of the parameters
  • std (list of floats): Standard Deviation of each image (in order).
  • min_value (list of floats): minimum value of each image.
  • max_value (list of floats): maximum value of each image.
  • size (list of tuples): size of each image in pixels.
  • xlim (list of lists): limits of the axes at the time of calling the function.
  • ylim (list of lists): limits of the axes at the time of calling the function.
  • description (string): string that recaps the information.

save()

output = viewer.save()

Parameters: None

Returns: output (NumPy array or list of): Screenshot of the image being displayed (if there are several images, returns list of NumPy arrays). Keeps the zoom region, and any transformation applied to the image.

set_axis()

viewer.set_axis(axis= False)

Arguments:

  • axis (boolean, required): Set or hide the axis of the images.

Returns: Nothing

set_colormap()

image_viewer.set_colormap(colormap = 'gray')

Arguments:

  • colormap (string, required): one of the valid colormaps.

Returns: Nothing

set_widgets()

image_viewer.set_widgets(widgets= False)

Arguments:

  • widgets (boolean, required): Show or hide the axis of the images.

Returns: Nothing

show_histogram()

image_viewer.show_histogram(hist= False)

Arguments:

  • hist (boolean, required): show or hide the histograms of the images

Returns: Nothing

Attributes

The attributes are listed below.

General

  • self.bins - List of the bin values of each image
  • self.current_image - If parameter single_image = True, keeps track of the image currently in display. Else, set to None.
  • self.hist - List of the histogram values of each image
  • self.image_list - List conttaining the numpy arrays that represent the images
  • self.max - List of the maximum values of each image
  • self.min - List of the minimum values of each image
  • self.number_images- Number of images
  • self.xlim - List of lists of lists that stores the limits of the x axis
  • self.ylim - List of lists of lists that stores the limits of the y axis
  • self.view - Keeps track of the the menu that is currently displayed

Matplotlib objects

  • self.axs - List that holds the AxesSubplots of each image
  • self.axs_hist - List with the AxesSubplots of each histogram
  • self.im - List with the AxesImage object of each image
  • self.fig - Figure to holda all the plots (images)
  • self.fig_hist - Figure that holds the histograms

Widgets

  • self.b_and_c_view_rightb - Ipywidgets box to hold the color scaling menu
  • self.button_b_and_c- Button to switch to the color scaling menu
  • self.button_back- Button to switch from the options or color scaling menu to the main menu.
  • self.button_hist- Button to show or hide histograms
  • self.button_next - Button to browse between images (only when the parameter single_image was originally set to True)
  • self.button_options- Button to switch to the options menu
  • self.button_prev - Button to browse between images (only when the parameter single_image was originally set to True)
  • self.button_reset- Button to set all parameters of the object to the default
  • self.button_show_axis- Button to show or hide the axis of the image
  • self.button_show_widgets- Button to show widgets (only displayed when instantianing an objects with the parameter widgets = False)
  • self.dropdown_cmap - Dropdown menu to choose the colormap of the images
  • self.final_view_hist - Ipywidgets box that adds the figure holding the histograms to self.final_view_no_hist (see below)
  • self.final_view_no_hist - Ipywidgets box to hold the images (self.out_fig) and the widgets
  • self.init_view_rightb - Ipywidgets box to hold the main menu
  • self.out_image_options - Ipywidgets box display histograms (display self.out_hist, see below)
  • self.out_fig - Output widget that holds sef.fig
  • self.out_hist - Output widget that holds sef.fig_hist
  • self.slider_clim - Slider to define the min and max values for color scaling
  • self.stats_text - Widget to display all the statistics of the images.

Clone this wiki locally