tools: Tool widgets for PlotWidget

This package provides a set of widgets working with PlotWidget.

It provides some QToolBar and QWidget:

• InteractiveModeToolBar

• OutputToolBar

• ImageToolBar

• CurveToolBar

• LimitsToolBar

• PositionInfo

It also provides a roi module to handle interactive region of interest on a PlotWidget.

Tools API

Tools are divided into the following sub-modules:

• profile: Profile tool for PlotWidget

Other tools API

PositionInfo class

class PositionInfo(parent=None, plot=None, converters=None)

Bases: QWidget

QWidget displaying coords converted from data coords of the mouse.

Provide this widget with a list of couple:

• A name to display before the data

• A function that takes (x, y) as arguments and returns something that gets converted to a string. If the result is a float it is converted with ‘%.7g’ format.

To run the following sample code, a QApplication must be initialized. First, create a PlotWindow and add a QToolBar where to place the PositionInfo widget.

>>> from silx.gui.plot import PlotWindow
>>> from silx.gui import qt

>>> plot = PlotWindow()  # Create a PlotWindow to add the widget to
>>> toolBar = qt.QToolBar()  # Create a toolbar to place the widget in
>>> plot.addToolBar(qt.Qt.BottomToolBarArea, toolBar)  # Add it to plot

Then, create the PositionInfo widget and add it to the toolbar. The PositionInfo widget is created with a list of converters, here to display polar coordinates of the mouse position.

>>> import numpy
>>> from silx.gui.plot.tools import PositionInfo

>>> position = PositionInfo(plot=plot, converters=[
...     ('Radius', lambda x, y: numpy.sqrt(x*x + y*y)),
...     ('Angle', lambda x, y: numpy.degrees(numpy.arctan2(y, x)))])
>>> toolBar.addWidget(position)  # Add the widget to the toolbar
<...>
>>> plot.show()  # To display the PlotWindow with the position widget

Parameters:

• plot – The PlotWidget this widget is displaying data coords from.

• converters – List of 2-tuple: name to display and conversion function from (x, y) in data coords to displayed value. If None, the default, it displays X and Y.

• parent – Parent widget

getPlotWidget()

Returns the PlotWidget this widget is attached to or None.

Return type:

Union[PlotWidget,None]

getConverters()

Return the list of converters as 2-tuple (name, function).

updateInfo()

Update displayed information

SNAPPING_DISABLED = 0

No snapping occurs

SNAPPING_CROSSHAIR = 1

Snapping only enabled when crosshair cursor is enabled

SNAPPING_ACTIVE_ONLY = 2

Snapping only enabled for active item

SNAPPING_SYMBOLS_ONLY = 4

Snapping only when symbols are visible

SNAPPING_CURVE = 8

Snapping on curves

SNAPPING_SCATTER = 16

Snapping on scatter

setSnappingMode(mode)

Set the snapping mode.

The mode is a mask.

Parameters:

mode (int) – The mode to use

getSnappingMode()

Returns the snapping mode as a mask

Return type:

int

LimitsToolBar class

class LimitsToolBar(parent=None, plot=None, title='Limits')

Bases: QToolBar

QToolBar displaying and controlling the limits of a PlotWidget.

To run the following sample code, a QApplication must be initialized. First, create a PlotWindow:

>>> from silx.gui.plot import PlotWindow
>>> plot = PlotWindow()  # Create a PlotWindow to add the toolbar to

Then, create the LimitsToolBar and add it to the PlotWindow.

>>> from silx.gui import qt
>>> from silx.gui.plot.tools import LimitsToolBar

>>> toolbar = LimitsToolBar(plot=plot)  # Create the toolbar
>>> plot.addToolBar(qt.Qt.BottomToolBarArea, toolbar)  # Add it to the plot
>>> plot.show()  # To display the PlotWindow with the limits toolbar

Parameters:

• parent – See QToolBar.

• plot – PlotWidget instance on which to operate.

• title (str) – See QToolBar.

property plot

The PlotWidget the toolbar is attached to.

InteractiveModeToolBar class

class InteractiveModeToolBar(parent=None, plot=None, title='Plot Interaction')

Bases: QToolBar

Toolbar with interactive mode actions

Parameters:

• parent – See QWidget

• plot (silx.gui.plot.PlotWidget) – PlotWidget to control

• title (str) – Title of the toolbar.

getZoomModeAction()

Returns the zoom mode QAction.

Return type:

PlotAction

getPanModeAction()

Returns the pan mode QAction

Return type:

PlotAction

OutputToolBar class

class OutputToolBar(parent=None, plot=None, title='Plot Output')

Bases: QToolBar

Toolbar providing icons to copy, save and print a PlotWidget

Parameters:

• parent – See QWidget

• plot (silx.gui.plot.PlotWidget) – PlotWidget to control

• title (str) – Title of the toolbar.

getCopyAction()

Returns the QAction performing copy to clipboard of the PlotWidget

Return type:

PlotAction

getSaveAction()

Returns the QAction performing save to file of the PlotWidget

Return type:

PlotAction

getPrintAction()

Returns the QAction performing printing of the PlotWidget

Return type:

PlotAction

ImageToolBar class

class ImageToolBar(parent=None, plot=None, title='Image')

Bases: QToolBar

Toolbar providing PlotAction suited when displaying images

Parameters:

• parent – See QWidget

• plot (silx.gui.plot.PlotWidget) – PlotWidget to control

• title (str) – Title of the toolbar.

getResetZoomAction()

Returns the QAction to reset the zoom.

Return type:

PlotAction

getColormapAction()

Returns the QAction to control the colormap.

Return type:

PlotAction

getKeepDataAspectRatioButton()

Returns the QToolButton controlling data aspect ratio.

Return type:

QToolButton

getYAxisInvertedButton()

Returns the QToolButton controlling Y axis orientation.

Return type:

QToolButton

CurveToolBar class

class CurveToolBar(parent=None, plot=None, title='Image')

Bases: QToolBar

Toolbar providing PlotAction suited when displaying curves

Parameters:

• parent – See QWidget

• plot (silx.gui.plot.PlotWidget) – PlotWidget to control

• title (str) – Title of the toolbar.

getResetZoomAction()

Returns the QAction to reset the zoom.

Return type:

PlotAction

getXAxisAutoScaleAction()

Returns the QAction to toggle X axis autoscale.

Return type:

PlotAction

getYAxisAutoScaleAction()

Returns the QAction to toggle Y axis autoscale.

Return type:

PlotAction

getXAxisLogarithmicAction()

Returns the QAction to toggle X axis log/linear scale.

Return type:

PlotAction

getYAxisLogarithmicAction()

Returns the QAction to toggle Y axis log/linear scale.

Return type:

PlotAction

getGridAction()

Returns the action to toggle the plot grid.

Return type:

PlotAction

getCurveStyleAction()

Returns the QAction to change the style of all curves.

Return type:

PlotAction

ScatterToolBar class

class ScatterToolBar(parent=None, plot=None, title='Scatter Tools')

Bases: QToolBar

Toolbar providing PlotAction suited when displaying scatter plot

Parameters:

• parent – See QWidget

• plot (silx.gui.plot.PlotWidget) – PlotWidget to control

• title (str) – Title of the toolbar.

getResetZoomAction()

Returns the QAction to reset the zoom.

Return type:

PlotAction

getXAxisLogarithmicAction()

Returns the QAction to toggle X axis log/linear scale.

Return type:

PlotAction

getYAxisLogarithmicAction()

Returns the QAction to toggle Y axis log/linear scale.

Return type:

PlotAction

getGridAction()

Returns the action to toggle the plot grid.

Return type:

PlotAction

getColormapAction()

Returns the QAction to control the colormap.

Return type:

PlotAction

getKeepDataAspectRatioButton()

Returns the QToolButton controlling data aspect ratio.

Return type:

QToolButton

getScatterVisualizationToolButton()

Returns the QToolButton controlling the visualization mode.

Return type:

ScatterVisualizationToolButton

CurveLegendsWidget

This module provides a widget to display PlotWidget curve legends.

class CurveLegendsWidget(parent=None)

Bases: QWidget

Widget displaying curves legends in a plot

Parameters:

parent (QWidget) – See QWidget

sigCurveClicked

Signal emitted when the legend of a curve is clicked

It provides the corresponding curve.

layout(self) → QLayout | None

getPlotWidget()

Returns the associated PlotWidget

Return type:

Union[PlotWidget,None]

setPlotWidget(plot)

Set the associated PlotWidget

Parameters:

plot (PlotWidget) – Plot widget to attach

curveAt(*args)

Returns the curve object represented at the given position

Either takes a QPoint or x and y as input in widget coordinates.

Return type:

Union[Curve,None]

mousePressEvent(self, a0: QMouseEvent | None)

mouseMoveEvent(self, a0: QMouseEvent | None)

mouseReleaseEvent(self, a0: QMouseEvent | None)

roi: Region of interest

This module provides ROI interaction for PlotWidget.

RegionOfInterestManager class

class RegionOfInterestManager(parent)

Class handling ROI interaction on a PlotWidget.

It supports the multiple ROIs: points, rectangles, polygons, lines, horizontal and vertical lines.

See plotInteractiveImageROI.py sample code (Sample Code).

Parameters:

parent (silx.gui.plot.PlotWidget) – The plot widget in which to control the ROIs.

sigRoiAdded

Signal emitted when a new ROI has been added.

It provides the newly add RegionOfInterest object.

sigRoiAboutToBeRemoved

Signal emitted just before a ROI is removed.

It provides the RegionOfInterest object that is about to be removed.

sigRoiChanged

Signal emitted whenever the ROIs have changed.

sigCurrentRoiChanged

Signal emitted whenever a ROI is selected.

sigInteractiveModeStarted

Signal emitted when switching to ROI drawing interactive mode.

It provides the class of the ROI which will be created by the interactive mode.

sigInteractiveRoiCreated

Signal emitted when a ROI is created during the interaction. The interaction is still incomplete and can be aborted.

It provides the ROI object which was just been created.

sigInteractiveRoiFinalized

Signal emitted when a ROI creation is complet.

It provides the ROI object which was just been created.

sigInteractiveModeFinished

Signal emitted when leaving interactive ROI drawing mode.

classmethod getSupportedRoiClasses()

Returns the default available ROI classes

Return type:

List[class]

getInteractionModeAction(roiClass)

Returns the QAction corresponding to a kind of ROI

The QAction allows to enable the corresponding drawing interactive mode.

Parameters:

roiClass (class) – The ROI class which will be created by this action.

Return type:

QAction

Raises:

ValueError – If kind is not supported

setCurrentRoi(roi)

Set the currently selected ROI, and emit a signal.

Parameters:

• roi (Optional[RegionOfInterest]) – The ROI to select

• roi

getCurrentRoi()

Returns the currently selected ROI, else None.

Return type:

Optional[RegionOfInterest]

getRois()

Returns the list of ROIs.

It returns an empty tuple if there is currently no ROI.

Returns:

Tuple of arrays of objects describing the ROIs

Return type:

List[RegionOfInterest]

clear()

Reset current ROIs

Returns:

True if ROIs were reset.

Return type:

bool

containsRoi(roi)

Returns true if the ROI is part of this manager.

Parameters:

roi (roi_items.RegionOfInterest) – The ROI to add

Return type:

bool

addRoi(roi, index=None, useManagerColor=True)

Add the ROI to the list of ROIs.

Parameters:

• roi (roi_items.RegionOfInterest) – The ROI to add

• index (int) – The position where to insert the ROI, By default it is appended to the end of the list of ROIs

• useManagerColor (bool) – Whether to set the ROI color to the default one of the manager or not. (Default: True).

Raises:

RuntimeError – When ROI cannot be added because the maximum number of ROIs has been reached.

removeRoi(roi)

Remove a ROI from the list of ROIs.

Parameters:

roi (roi_items.RegionOfInterest) – The ROI to remove

Raises:

ValueError – When ROI does not belong to this object

getColor()

Return the default color of created ROIs

Return type:

QColor

setColor(color)

Set the default color to use when creating ROIs.

Existing ROIs are not affected.

Parameters:

color – The color to use for displaying ROIs as either a color name, a QColor, a list of uint8 or float in [0, 1].

getCurrentInteractionModeRoiClass()

Returns the current ROI class used by the interactive drawing mode.

Returns None if the ROI manager is not in an interactive mode.

Return type:

Union[class,None]

getInteractionSource()

Returns the object which have requested the ROI creation.

Returns None if the ROI manager is not in an interactive mode.

Return type:

Union[object,None]

isStarted()

Returns True if an interactive ROI drawing mode is active.

Return type:

bool

isDrawing()

Returns True if an interactive ROI is drawing.

Return type:

bool

start(roiClass, source=None)

Start an interactive ROI drawing mode.

Parameters:

• roiClass (class) – The ROI class to create. It have to inherite from roi_items.RegionOfInterest.

• source (object) – SOurce of the ROI interaction.

Returns:

True if interactive ROI drawing was started, False otherwise

Return type:

bool

Raises:

ValueError – If roiClass is not supported

stop()

Stop interactive ROI drawing mode.

Returns:

True if an interactive ROI drawing mode was actually stopped

Return type:

bool

exec(roiClass)

Block until quit() is called.

Parameters:

kind (class) – The class of the ROI which have to be created. See silx.gui.plot.items.roi.

Returns:

The list of ROIs

Return type:

tuple

quit()

Stop a blocking exec() and call stop()

InteractiveRegionOfInterestManager class

class InteractiveRegionOfInterestManager(parent)

RegionOfInterestManager with features for use from interpreter.

It is meant to be used through the exec(). It provides some messages to display in a status bar and different modes to end blocking calls to exec().

Parameters:

parent – See QObject

sigMessageChanged

Signal emitted when a new message should be displayed to the user

It provides the message as a str.

getMaxRois()

Returns the maximum number of ROIs or None if no limit.

Return type:

Union[int,None]

setMaxRois(max_)

Set the maximum number of ROIs.

Parameters:

max (Union[int,None]) – The max limit or None for no limit.

Raises:

ValueError – If there is more ROIs than max value

isMaxRois()

Returns True if the maximum number of ROIs is reached.

Return type:

bool

class ValidationMode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Mode of validation to leave blocking exec()

AUTO = 'auto'

Automatically ends the interactive mode once the user terminates the last ROI shape.

ENTER = 'enter'

Ends the interactive mode when the Enter key is pressed.

AUTO_ENTER = 'auto_enter'

Ends the interactive mode when reaching max ROIs or when the Enter key is pressed.

NONE = 'none'

Do not provide the user a way to end the interactive mode.

The end of exec() is done through quit() or timeout.

getValidationMode()

Returns the interactive mode validation in use.

Return type:

ValidationMode

setValidationMode(mode)

Set the way to perform interactive mode validation.

See ValidationMode enumeration for the supported validation modes.

Parameters:

mode (ValidationMode) – The interactive mode validation to use.

eventFilter(self, a0: QObject | None, a1: QEvent | None) → bool

getMessage()

Returns the current status message.

This message is meant to be displayed in a status bar.

Return type:

str

isExec()

Returns True if exec() is currently running.

Return type:

bool

exec(roiClass, timeout=0)

Block until ROI selection is done or timeout is elapsed.

quit() also ends this blocking call.

Parameters:

• roiClass (class) – The class of the ROI which have to be created. See silx.gui.plot.items.roi.

• timeout (int) – Maximum duration in seconds to block. Default: No timeout

Returns:

The list of ROIs

Return type:

List[RegionOfInterest]

RegionOfInterestTableWidget class

class RegionOfInterestTableWidget(parent=None)

Widget displaying the ROIs of a RegionOfInterestManager

setRegionOfInterestManager(manager)

Set the RegionOfInterestManager object to sync with

Parameters:

manager (RegionOfInterestManager)

getRegionOfInterestManager()

Returns the RegionOfInterestManager this widget supervise.

It returns None if not sync with an RegionOfInterestManager.

Return type:

RegionOfInterestManager

ColorBar: ColorBar Widget

Module containing several widgets associated to a colormap.

ColorBarWidget class

class ColorBarWidget(parent=None, plot=None, legend=None)

Colorbar widget displaying a colormap

It uses a description of colormap as dict compatible with Plot.

To run the following sample code, a QApplication must be initialized.

>>> from silx.gui.plot import Plot2D
>>> from silx.gui.plot.ColorBar import ColorBarWidget

>>> plot = Plot2D()  # Create a plot widget
>>> plot.show()

>>> colorbar = ColorBarWidget(plot=plot, legend='Colormap')  # Associate the colorbar with it
>>> colorbar.show()

Initializer parameters:

Parameters:

• parent – See QWidget

• plot – PlotWidget the colorbar is attached to (optional)

• legend (str) – the label to set to the colorbar

sigVisibleChanged

Emitted when the property visible have changed.

getPlot()

Returns the Plot associated to this widget or None

setPlot(plot)

Associate a plot to the ColorBar

Parameters:

plot – the plot to associate with the colorbar. If None will remove any connection with a previous plot.

setVisible(self, visible: bool)

showEvent(self, a0: QShowEvent | None)

hideEvent(self, a0: QHideEvent | None)

getColormap()

Returns the colormap displayed in the colorbar.

Return type:

Colormap

setColormap(colormap, data=None)

Set the colormap to be displayed.

Parameters:

• colormap (Colormap) – The colormap to apply on the ColorBarWidget

• data (Union[numpy.ndarray,ColormapMixin]) – The data to display or item, needed if the colormap require an autoscale

setLegend(legend)

Set the legend displayed along the colorbar

Parameters:

legend (str) – The label

getLegend()

Returns the legend displayed along the colorbar

Returns:

return the legend displayed along the colorbar

Return type:

str

getColorScaleBar()

Returns:

return the ColorScaleBar used to display ColorScale and ticks