Figure ManagementΒΆ

Technically, every plot widget, hence the plot containing the axes and the content, is represented as an instance of plotItem. If you show the plot in its own window, this window is called figure and represented as an instance of figure. Every figure is also able to show various sub-plots arranged in a regular grid of m rows and n columns. Plots, integrated in an user-defined interface, are directly integrated there without being part of a special figure.

If you want to continuously use the same figure window for sequentially plotting different data or if you want to use the sub-plot mechanism, it is useful to firstly create or access a specific figure and then plot data objects or camera live images using the specific commands of this figure.

Every figure has a specific handle (integer value). Therefore you can have access to any figure by its figure instance or via the handle value.

In the following example, a new figure is created and opened. The instance is saved in the variable fig:

fig = figure()

Assuming, that you want to access an already existing figure or create a new figure with your desired handle number, give the handle as first argument (keyword: handle):

fig = figure(1)
fig = figure(handle = 1)

fig is then an instance of figure. This class is derived from uiItem and therefore has the same functionality like any other widget that is represented by uiItem (see Creating advanced dialogs and windows). If you provide no further parameter (besides handle) to the figure constructor, a figure with one plot area is created. If you want to create a grid of more plot areas, you need to give the number of rows and columns as argument to the constructor:

fig = figure(rows = 2, cols = 3)

Not only the module itom has the methods liveImage() in order to plot data objects or camera streams. In the same way, the class figure has these methods, too:

With method signature:

itom.figure.plot((data, [areaIndex, ...) Plot an existing dataObject in not dockable, not blocking window.
itom.figure.liveImage((cam, [areaIndex, ...) Creates a plot-image (2D) and automatically grabs images into this window.

Both have the optional keyword parameter areaIndex, such that you define in which sub-plotting area the requested plot or live image should be depicted. If you don’t provide the areaIndex parameter, the first area (top, left) is assumed (this is also the default in case that you don’t use subplots). The areaIndex value is a fixed-point number beginning with 0 for the top-left area of the figure. Then, the index iterates row-wise through the entire grid of sub-plots.

In the following example, a 2x1 grid is created where the left plot shows a 1D data object and the right plot contains the live stream of the dummy grabber camera instance:

fig = figure(rows = 1, cols = 2)
data1d = dataObject.randN([1,100])
fig.plot(data1d, 0)
cam = dataIO("DummyGrabber")
fig.liveImage(cam, 1)

The result looks like this:


The currently depicted toolbar is provided by the active subplot, marked by a border. You can switch the active subplot by choosing your desired one in the figure’s menu subplot. In order to get the instance of itom.plotItem of any sublot, use the following command:

plotLeft = fig.subplot(0)
plotRight = fig.subplot(1)


If you have an instance to a plotItem only in python and the window is closed, the window is finally deleted and the plotItem becomes invalid. In difference, a handle to a figure keeps the figure alive until all references to the figure’s instance are deleted. Therefore you can always show or hide a figure using its instance and the methods show() or hide().

The figure also provides a static method close() to close and delete a figure defined by its specific integer handle or to close all figures using the string ‘all’ as parameter. Please note, that only these figures are finally deleted where no other python references exist to them.

#close figure with handle 7

#close all figures

Previous topic

Quick tutorial to plots and figures

Next topic

line plots (1D)

This Page