9.9. plotItem

class itom.plotItem(figure, subplotIdx=0) → plotItem
class itom.plotItem(uiItem) → plotItem
class itom.plotItem(figure, objectID=0) → plotItem

Bases: itom.uiItem

The plotItem is a special uiItem and represents itom plot designer widgets.

This constructor can be used to get a reference of a plot in a figure. The plot can also be in a subplot area of a figure. There are two main uses cases for the direct usage of this constructor:

  1. If a reference to a general uiItem is available, but the referenced widget / item is a plot, the uiItem can be cast to plotItem such that additional methods like pickPoints() or drawAndPickElements() become available.

  2. If a reference to a figure is available, that contains one or more plots, the reference to one of these plots can be obtained. The subplotIdx indicates the specific plot, that should be referenced. The default is 0. If the figure consists of more than one subplot, the index counts the subplots row-by-row.

The 3rd variant of this contructor, using the keyword-based argument objectID is only internally used and has no further meaning for a high-level usage. However, if it is used, objectID must be used as keyword argument, else subplotIdx is assumed to be initialized.

Parameters
figurefigure

The figure window, that contains an itom plot.

subplotIdxint, optional

The area index of the (sub)plot, that should be referenced. This index is considered to be row-wise, such that the center plot in the 2nd row with three plots in each row has the index 4. The first, left, plot in the first row has the index 0, which is the default.

objectIDint, optional

If the internal objectID of a uiItem is available, it can be tried to be casted to plotItem.

uiItemuiItem

Try to cast this uiItem to its inherited class plotItem. A RuntimeError is raised if this cast is not possible.

Returns
plotItem

The initialized plotItem.

drawAndPickElements(elementType, maxNrElements=1) → Tuple[shape]

This method forces the user to draw specific shapes on the canvas of the plot.

If this method is called, the script execution in paused until the requested maxNrElements of shapes of the given type elementType are drawn by the user on the canvas of the plot. The coordinates of the shapes is then returned by this method. If the script execution is aborted during the interactive operation or if the user presses the Esc key in the plot, this operation is stopped by a RuntimeError.

Parameters
elementTypeint

The element type that the user should interactively draw on the canvas of the plot. Allowed types are:

  • plotItem.PrimitivePoint

  • plotItem.PrimitiveLine

  • plotItem.PrimitiveRectangle

  • plotItem.PrimitiveSquare

  • plotItem.PrimitiveEllipse

  • plotItem.PrimitiveCircle

  • plotItem.PrimitivePolygon

maxNrElementsint, optional

Number of elements of the given type, the user has to draw. The operation can be aborted by clicking the Esc key. If this is the case, a RuntimeError is raised.

Returns
tuple of shape

A tuple with all drawn elements, represented as shape objects is returned.

Raises
RuntimeError

if the user interrupts the selection (by pressing the Esc key).

pickPoints(points, maxNrPoints=- 1)

-> method to let the user pick points on a plot (only if plot supports this)

This method lets the user select one or multiple points (up to maxNrPoints) in the canvas of the current plot (if the plot supports this). The operation can be aborted by pressing the Esc key. Then a RuntimeError` is raised. It can also be quit earlier by pressing the ``Space key. This is also required if an unlimited number of points can be selected (maxNrPoints = -1).

A pick-points operation is not supported by all plot classes. It is for instance available for the classes itom1dqwtplot (see section line plots (1D)) or itom2dqwtplot (see section image plots (2D)).

Parameters
pointsdataObject

This object will be a 2 x nrOfSelectedPoints dataObject of dtype float64 after the successful call of this method. The first row contains the x coordinates of the selected points, the 2nd row the y coordinates.

maxNrPointsint, optional

Let the user select up to this number of points. The selection can be stopped by pressing Space or Esc. maxNrPoints must be -1 for an unlimited number of picked points (default) or a number >= 1.

Raises
RuntimeError

if the specific plot class does not provide the necessary methods to support this operation.

RuntimeError

if the operation has been interrupted by the user. points is an empty dataObject then. An interruption can occur if the plot is closed or if the user pressed the escape key during the operation.

PrimitiveCircle = 64
PrimitiveEllipse = 32
PrimitiveLine = 4
PrimitiveMultiPointPick = 1
PrimitivePoint = 2
PrimitivePolygon = 128
PrimitiveRectangle = 8
PrimitiveSquare = 16