10.7. figure

class itom.figure(handle=-1, rows=1, cols=1, x0=-1, y0=-1, width=-1, height=-1)

Bases: uiItem

Creates a new figure window.

The class 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 integer handle to this figure is returned:

h: int = 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:

handleint

integer handle of the desired figure.

rowsint, optional

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

colsint, optional

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

x0int, optional

If x0 is != -1, its left position is set to this value.

y0int, optional

If y0 is != -1, its top position is set to this value.

widthint, optional

If width is != -1, the width of the figure window is set to this value.

heightint, optional

If height is != -1, the height of the figure window is set to this value.

Returns:

figure

is the reference to the newly created figure object.

static close(handle) → None

static close(all='all') → None

Closes a specific or all opened figures.

This method closes and deletes either one specific figure (if handle is given and valid), or all opened figures (if the string argument "all" is given). All figure can only be closed, if no other figure references this figure (e.g. line cut of an image plot (2D).

Parameters:

handleint

a valid figure handle, whose reference figure should be closed. This figure handle is for instance obtained by the first value of the returned tuple of plot(), plot1(), plot2() among others.

all{“all”}

Pass the string "all" if all closeable opened figures should be closed.

See also

itom.close

Notes

If a figure instance still keeps a reference to any figure, it is only closed and will be deleted after that the last referencing instance has been deleted.

hide()

Hides the figure, but does not delete it.

liveImage(cam, areaIndex=currentAreaIndex, className='', properties={}) → plotItem

Shows a camera live image in the current or given area of this figure.

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 certain values.

Parameters:

camdataIO

Camera grabber device from which images are acquired.

areaIndexint, optional

Area index where the plot canvas should be created (if subplots exists). The default areaIndex is the current subplot area, hence, 0 if only one plot area exists in the figure.

classNamestr, optional

class name of desired plot (if not indicated or if the className cannot be found, the default plot will be used (see application settings)

propertiesdict, optional

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

Returns:

plotHandleplotItem

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

matplotlibFigure(areaIndex=currentAreaIndex, properties={}) → plotItem

Creates a matplotlib canvas at the given area in the figure.

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

Parameters:

areaIndexint, optional

Area index where the plot canvas should be created (if subplots exists). The default areaIndex is the current subplot area, hence, 0 if only one plot area exists in the figure.

propertiesdict, optional

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

Returns:

plotHandleplotItem

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

plot(data, areaIndex=currentAreaIndex, className='', properties={}) → plotItem

Plots a dataObject, pointCloud or polygonMesh in the current or given area of this figure.

Plots an existing dataObject, pointCloud or polygonMesh in the newly created plot. 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 preferred plot is not able to display the given object, a warning is returned and the default plot type is used again. For dataObject, 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 certain values.

Parameters:

datadataObject or pointCloud or polygonMesh

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

areaIndexint, optional

Area index where the plot canvas should be created (if subplots exists). The default areaIndex is the current subplot area, hence, 0 if only one plot area exists in the figure.

classNamestr, optional

class name of desired plot (if not indicated or if the className cannot be found, the default plot will be used (see application settings)

propertiesdict, optional

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

Returns:

plotHandleplotItem

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

plot1(data, xData=None, areaIndex=currentAreaIndex, className='', properties={}) → plotItem

Creates a 1D plot of a dataObject data in the current or given area of this figure.

If xData is given, the plot uses this vector for the values of the x-axis of the plot.

The plot type of this function is 1D (see method figure.plot()). If a className is given, that does not support the given type of data (or xData) a warning is returned and the default plot class for the given data 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 uiItem instance.

Use the properties argument to pass a dictionary with properties you want to set.

Parameters:

datadataObject

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

xDatadataObject, optional

1D plots can optionally accept this dataObject. If given, the values are not displayed on an equally distributed x-scale but with the values given by xData.

areaIndexint, optional

Area index where the plot canvas should be created (if subplots exists). The default areaIndex is the current subplot area, hence, 0 if only one plot area exists in the figure.

classNamestr, optional

class name of desired plot (if not indicated or if the className cannot be found, the default plot will be used (see application settings)

propertiesdict, optional

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

Returns:

plotHandleplotItem

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

plot2(data, areaIndex=currentAreaIndex, className='', properties={}) → plotItem

Creates a 2D plot of a dataObject data in the current or given area of this figure.

This method plots an existing dataObject in the new 2D plot. The style of the plot depends on the object dimensions. The plot type of this function is 2D (see method figure.plot()).

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 uiItem instance.

Use the properties argument to pass a dictionary with properties you want to set.

Parameters:

datadataObject

is the data, that should be plotted. If a className it must support dataObjects as accepted data type. Else, the default className for 2D dataObject is chosen (see itom application settings for default plot types.

areaIndexint, optional

Area index where the plot canvas should be created (if subplots exists). The default areaIndex is the current subplot area, hence, 0 if only one plot area exists in the figure.

classNamestr, optional

class name of desired plot (if not indicated or if the className cannot be found, the default plot will be used (see application settings)

propertiesdict, optional

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

Returns:

plotHandleplotItem

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

plot25(data, areaIndex=currentAreaIndex, className='', properties={}) → plotItem

Creates a 2.5D plot of a dataObject, pointCloud or polygonMesh in the current or given area of this figure.

This method plots data object in the new plot. The style of the plot depends on the object dimensions, its plot type is 2.5D (see method figure.plot()).

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 uiItem instance.

Use the properties argument to pass a dictionary with properties you want to set.

Parameters:

datadataObject or pointCloud or polygonMesh

is the data, that should be plotted. If a className is given, only the type of data, supported by this class, can be displayed. Else, the default className for the kind of data is chosen (see itom application settings for default plot types.

areaIndexint, optional

Area index where the plot canvas should be created (if subplots exists). The default areaIndex is the current subplot area, hence, 0 if only one plot area exists in the figure.

classNamestr, optional

class name of desired plot (if not indicated or if the className cannot be found, the default plot will be used (see application settings)

propertiesdict, optional

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

Returns:

plotHandleplotItem

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

plotlyFigure(areaIndex=currentAreaIndex, properties={}) → plotItem

Creates a plotly canvas at the given area in the figure.

Creates and returns a plotly canvas at the given area or returns an existing one. If the itom plotly renderer is used, this renderer calls this method to send the html output to this widget.

Parameters:

areaIndexint, optional

Area index where the plot canvas should be created (if subplots exists). The default areaIndex is the current subplot area, hence, 0 if only one plot area exists in the figure.

propertiesdict, optional

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

Returns:

plotHandleplotItem

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

show()

Shows the figure if it is currently hidden.

subplot(index) → plotItem

Returns plotItem of desired subplot.

Parameters:

indexint

index to desired subplot in the range [0, n), where n is the number of subplots. The subplot at the top, left position has the index 0 and the index is incremented row-wise.

Returns:

plotItem

The plot item of the desired subplot.

docked

bool : gets or sets the docked status of this figure.

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

int : gets the handle of this figure.