9.7. figure

class itom.figure(handle=- 1, rows=1, cols=1) → creates figure window.

Bases: itom.uiItem

The class itom.figure represents a standalone figure window, that can have various subplots. If an instance of this class is created without further parameters a new figure is created and opened having one subplot area (currently empty) and the numeric handle to this figure is returned:

h = figure() 

Subplots are arranged in a regular grid whose size is defined by the optional parameters ‘rows’ and ‘cols’. If you create a figure instance with a given handle, the instance is either a reference to an existing figure that has got this handle or if it does not exist, a new figure with the desired handle is opened and the handle is returned, too.

Using the parameters width and height, it is possible to control the size of the figure. If one of both parameters are not set or <= 0 (default), no size adjustment is done at all.

The size and position control can afterwards done using the property ‘geometry’ of the figure.

Parameters

handle : {int}

numeric handle of the desired figure.

rows : {int, default: 1}

number of rows this figure should have (defines the size of the subplot-grid)

cols : {int, default: 1}

number of columns this figure should have (defines the size of the subplot-grid)

x0 : {int, default: -1}

horizontal position of figure

y0 : {int, default: -1}

vertical position of figure

width : {int, default: -1}

width of figure or -1 if the width should be unchanged

height : {int, default: -1}

height of figure or -1 if the height should be unchanged

static close(handle|'all') -> static method to close any specific or all open figures (unless any figure-instance still keeps track of them)

This method closes and deletes any specific figure (given by handle) or all opened figures.

Parameters

handle : {dataIO-Instance}

any figure handle (>0) or ‘all’ in order to close all opened figures

Notes

If any instance of class ‘figure’ still keeps a reference to any figure, it is only closed and deleted if the last instance is deleted, too.

hide() → hides figure without deleting it
liveImage(cam, areaIndex = <currentArea>, className = '', properties = {}) → shows a camera live image in the current or given area of this figure

Creates a plot-image (2D) and automatically grabs images into this window. This function is not blocking.

If no ‘className’ is given, the type of the plot is chosen depending on the type and the size of the object. The defaults for several plot classes can be adjusted in the property dialog of itom.

You can also set a class name of your preferred plot plugin (see also property dialog of itom). If your preferred plot is not able to display the given object, a warning is returned and the default plot type is used again. For dataObjects, it is also possible to simply set ‘className’ to ‘1D’ or ‘2D’ in order to choose the default plot type depending on these aliases.

Every plot has several properties that can be configured in the Qt Designer (if the plot is embedded in a GUI), or by the property toolbox in the plot itself or by using the info() method of the corresponding itom.uiItem instance.

Use the ‘properties’ argument to pass a dictionary with properties you want to set to a certain value.

Parameters

cam : {dataIO-Instance}

Camera grabber device from which images are acquired.

areaIndex: {int}, optional :

Area number where the plot should be put if subplots have been created

className : {str}, optional

class name of desired plot (if not indicated default plot will be used (see application settings)

properties : {dict}, optional

optional dictionary of properties that will be directly applied to the plot widget.

Returns

plotHandle: {plotItem} :

Handle of the subplot. This handle is used to control the properties of the plot, connect to its signals or call slots of the subplot.

matplotlibFigure(areaIndex = <currentArea>, properties = {}) → create matplotlib canvas

Creates and returns a matplotlib canvas at the given area or returns an existing one. This canvas can be used as canvas argument for pyplot.figure of matplotlib and is internally used by the itom backend of matplotlib.

Parameters

areaIndex: {int}, optional :

Area number where the plot should be put if subplots have been created

properties : {dict}, optional

optional dictionary of properties that will be directly applied to the plot widget.

Returns

plotHandle: {plotItem} :

Handle of the subplot. This handle is used to control the properties of the plot, connect to its signals or call slots of the subplot.

plot(data, areaIndex = <currentArea>, className = '', properties = {}) → plots an existing dataObject, pointCloud or polygonMesh in the current or given area of this figure

The style of the plot depends on the object dimensions.

If no ‘className’ is given, the type of the plot is chosen depending on the type and the size of the object. The defaults for several plot classes can be adjusted in the property dialog of itom.

You can also set a class name of your preferred plot plugin (see also property dialog of itom). If your preffered plot is not able to display the given object, a warning is returned and the default plot type is used again. For dataObjects, it is also possible to simply set ‘className’ to ‘1D’, ‘2D’ or ‘2.5D’ in order to choose the default plot type depending on these aliases. For pointCloud and polygonMesh only the alias ‘2.5D’ is valid.

Every plot has several properties that can be configured in the Qt Designer (if the plot is embedded in a GUI), or by the property toolbox in the plot itself or by using the info() method of the corresponding itom.uiItem instance.

Use the ‘properties’ argument to pass a dictionary with properties you want to set to a certain value.

Parameters

data : {DataObject}

Is the data object whose region of interest will be plotted.

areaIndex: {int}, optional :

Area number where the plot should be put if subplots have been created

className : {str}, optional

class name of desired plot (if not indicated default plot will be used, see application settings)

properties : {dict}, optional

optional dictionary of properties that will be directly applied to the plot widget.

Returns

plotHandle: {plotItem} :

Handle of the subplot. This handle is used to control the properties of the plot, connect to its signals or call slots of the subplot.

plot1(data, xData = None, areaIndex = <currentArea>, className = '', properties = {}) → creates an 1d plot of an existing dataObject in the current or given area of this figure

The plot type of this function is ‘1D’. If the 1D plot is not able to display the given object, a warning is returned and the default plot type is used again.

Every plot has several properties that can be configured in the Qt Designer (if the plot is embedded in a GUI), or by the property toolbox in the plot itself or by using the info() method of the corresponding itom.uiItem instance.

Use the ‘properties’ argument to pass a dictionary with properties you want to set to a certain value.

Parameters

data : {DataObject}

Is the data object whose region of interest will be plotted.

xData : {DataObject}, optional

Is the data object whose values are used for the axis.

areaIndex: {int}, optional :

Area number where the plot should be put if subplots have been created

className : {str}, optional

class name of the desired 1D plot (if not indicated default plot will be used, see application settings)

properties : {dict}, optional

optional dictionary of properties that will be directly applied to the plot widget.

Returns

plotHandle: {plotItem} :

Handle of the subplot. This handle is used to control the properties of the plot, connect to its signals or call slots of the subplot.

plot2(data, areaIndex = <currentArea>, className = '', properties = {}) → creates an 2d plot of an existing dataObject in the current or given area of this figure

The plot type of this function is ‘2D’. If the 2D plot is not able to display the given object, a warning is returned and the default plot type is used again.

Every plot has several properties that can be configured in the Qt Designer (if the plot is embedded in a GUI), or by the property toolbox in the plot itself or by using the info() method of the corresponding itom.uiItem instance.

Use the ‘properties’ argument to pass a dictionary with properties you want to set to a certain value.

Parameters

data : {DataObject}

Is the data object whose region of interest will be plotted.

areaIndex: {int}, optional :

Area number where the plot should be put if subplots have been created

className : {str}, optional

class name of the desired 2D plot (if not indicated default plot will be used, see application settings)

properties : {dict}, optional

optional dictionary of properties that will be directly applied to the plot widget.

Returns

plotHandle: {plotItem} :

Handle of the subplot. This handle is used to control the properties of the plot, connect to its signals or call slots of the subplot.

plot25(data, areaIndex = <currentArea>, className = '', properties = {}) → creates an 2.5d plot of an existing dataObject, pointCloud or polygonMesh in the current or given area of this figure

The plot type of this function is ‘2.5D’. If the 2.5D plot is not able to display the given object, a warning is returned and the default plot type is used again.

Every plot has several properties that can be configured in the Qt Designer (if the plot is embedded in a GUI), or by the property toolbox in the plot itself or by using the info() method of the corresponding itom.uiItem instance.

Use the ‘properties’ argument to pass a dictionary with properties you want to set to a certain value.

Parameters

data : {DataObject, PointCloud, PolygonMesh}

Is the data object whose region of interest will be plotted.

areaIndex: {int}, optional :

Area number where the plot should be put if subplots have been created

className : {str}, optional

class name of the desired 2.5D plot (if not indicated default plot will be used, see application settings)

properties : {dict}, optional

optional dictionary of properties that will be directly applied to the plot widget.

Returns

plotHandle: {plotItem} :

Handle of the subplot. This handle is used to control the properties of the plot, connect to its signals or call slots of the subplot.

show() → shows figure if it is currently hidden
subplot(index) → returns plotItem of desired subplot
Parameters

index : {unsigned int}

index to desired subplot. The subplot at the top, left position has the index 0 whereas the index is incremented row-wise.

docked

dock status of figure (True|False)

this attribute controls the dock appearance of this figure. If it is docked, the figure is integrated into the main window of itom, else it is a independent window.

handle

returns handle of figure