ROI — pyqtgraph 0.11.0rc0 documentation

# ROI

class `pyqtgraph.` `ROI`(pos, size=Point(1.000000, 1.000000), angle=0.0, invertible=False, maxBounds=None, snapSize=1.0, scaleSnap=False, translateSnap=False, rotateSnap=False, parent=None, pen=None, movable=True, rotatable=True, resizable=True, removable=False)

  Generic region-of-interest widget.

  Can be used for implementing many types of selection box with rotate/translate/scale handles. ROIs can be customized to have a variety of shapes (by subclassing or using any of the built-in subclasses) and any combination of draggable handles that allow the user to manipulate the ROI.

  Default mouse interaction:

  - Left drag moves the ROI

  - Left drag + Ctrl moves the ROI with position snapping

  - Left drag + Alt rotates the ROI

  - Left drag + Alt + Ctrl rotates the ROI with angle snapping

  - Left drag + Shift scales the ROI

  - Left drag + Shift + Ctrl scales the ROI with size snapping

  In addition to the above interaction modes, it is possible to attach any number of handles to the ROI that can be dragged to change the ROI in various ways (see the ROI.add____Handle methods).

  Arguments |
  pos | (length-2 sequence) Indicates the position of the ROI’s origin. For most ROIs, this is the lower-left corner of its bounding rectangle.
  size | (length-2 sequence) Indicates the width and height of the ROI.
  angle | (float) The rotation of the ROI in degrees. Default is 0.
  invertible | (bool) If True, the user may resize the ROI to have negative width or height (assuming the ROI has scale handles). Default is False.
  maxBounds | (QRect, QRectF, or None) Specifies boundaries that the ROI cannot be dragged outside of by the user. Default is None.
  snapSize | (float) The spacing of snap positions used when scaleSnap or translateSnap are enabled. Default is 1.0.
  scaleSnap | (bool) If True, the width and height of the ROI are forced to be integer multiples of snapSize when being resized by the user. Default is False.
  translateSnap | (bool) If True, the x and y positions of the ROI are forced to be integer multiples of snapSize when being resized by the user. Default is False.
  rotateSnap | (bool) If True, the ROI angle is forced to a multiple of the ROI’s snap angle (default is 15 degrees) when rotated by the user. Default is False.
  parent | (QGraphicsItem) The graphics item parent of this ROI. It is generally not necessary to specify the parent.
  pen | (QPen or argument to pg.mkPen) The pen to use when drawing the shape of the ROI.
  movable | (bool) If True, the ROI can be moved by dragging anywhere inside the ROI. Default is True.
  rotatable | (bool) If True, the ROI can be rotated by mouse drag + ALT
  resizable | (bool) If True, the ROI can be resized by mouse drag + SHIFT
  removable | (bool) If True, the ROI will be given a context menu with an option to remove the ROI. The ROI emits sigRemoveRequested when this menu action is selected. Default is False.

  Signals |
  sigRegionChangeFinished | Emitted when the user stops dragging the ROI (or one of its handles) or if the ROI is changed programatically.
  sigRegionChangeStarted | Emitted when the user starts dragging the ROI (or one of its handles).
  sigRegionChanged | Emitted any time the position of the ROI changes, including while it is being dragged by the user.
  sigHoverEvent | Emitted when the mouse hovers over the ROI.
  sigClicked | Emitted when the user clicks on the ROI. Note that clicking is disabled by default to prevent stealing clicks from objects behind the ROI. To enable clicking, call roi.setAcceptedMouseButtons(QtCore.Qt.LeftButton). See QtGui.QGraphicsItem documentation for more details.
  sigRemoveRequested | Emitted when the user selects ‘remove’ from the ROI’s context menu (if available).

  `addFreeHandle`(pos=None, axes=None, item=None, name=None, index=None)

    Add a new free handle to the ROI. Dragging free handles has no effect on the position or shape of the ROI.

    Arguments |
    pos | (length-2 sequence) The position of the handle relative to the shape of the ROI. A value of (0,0) indicates the origin, whereas (1, 1) indicates the upper-right corner, regardless of the ROI’s size.
    item | The Handle instance to add. If None, a new handle will be created.
    name | The name of this handle (optional). Handles are identified by name when calling getLocalHandlePositions and getSceneHandlePositions.

  `addRotateFreeHandle`(pos, center, axes=None, item=None, name=None, index=None)

    Add a new rotation+free handle to the ROI. When dragging a handle of this type, the user can rotate the ROI around an arbitrary center point, while moving toward or away from the center point has no effect on the shape of the ROI.

    Arguments |
    pos | (length-2 sequence) The position of the handle relative to the shape of the ROI. A value of (0,0) indicates the origin, whereas (1, 1) indicates the upper-right corner, regardless of the ROI’s size.
    center | (length-2 sequence) The center point around which rotation takes place.
    item | The Handle instance to add. If None, a new handle will be created.
    name | The name of this handle (optional). Handles are identified by name when calling getLocalHandlePositions and getSceneHandlePositions.

  `addRotateHandle`(pos, center, item=None, name=None, index=None)

    Add a new rotation handle to the ROI. Dragging a rotation handle allows the user to change the angle of the ROI.

    Arguments |
    pos | (length-2 sequence) The position of the handle relative to the shape of the ROI. A value of (0,0) indicates the origin, whereas (1, 1) indicates the upper-right corner, regardless of the ROI’s size.
    center | (length-2 sequence) The center point around which rotation takes place.
    item | The Handle instance to add. If None, a new handle will be created.
    name | The name of this handle (optional). Handles are identified by name when calling getLocalHandlePositions and getSceneHandlePositions.

  `addScaleHandle`(pos, center, axes=None, item=None, name=None, lockAspect=False, index=None)

    Add a new scale handle to the ROI. Dragging a scale handle allows the user to change the height and/or width of the ROI.

    Arguments |
    pos | (length-2 sequence) The position of the handle relative to the shape of the ROI. A value of (0,0) indicates the origin, whereas (1, 1) indicates the upper-right corner, regardless of the ROI’s size.
    center | (length-2 sequence) The center point around which scaling takes place. If the center point has the same x or y value as the handle position, then scaling will be disabled for that axis.
    item | The Handle instance to add. If None, a new handle will be created.
    name | The name of this handle (optional). Handles are identified by name when calling getLocalHandlePositions and getSceneHandlePositions.

  `addScaleRotateHandle`(pos, center, item=None, name=None, index=None)

    Add a new scale+rotation handle to the ROI. When dragging a handle of this type, the user can simultaneously rotate the ROI around an arbitrary center point as well as scale the ROI by dragging the handle toward or away from the center point.

    Arguments |
    pos | (length-2 sequence) The position of the handle relative to the shape of the ROI. A value of (0,0) indicates the origin, whereas (1, 1) indicates the upper-right corner, regardless of the ROI’s size.
    center | (length-2 sequence) The center point around which scaling and rotation take place.
    item | The Handle instance to add. If None, a new handle will be created.
    name | The name of this handle (optional). Handles are identified by name when calling getLocalHandlePositions and getSceneHandlePositions.

  `addTranslateHandle`(pos, axes=None, item=None, name=None, index=None)

    Add a new translation handle to the ROI. Dragging the handle will move the entire ROI without changing its angle or shape.

    Note that, by default, ROIs may be moved by dragging anywhere inside the ROI. However, for larger ROIs it may be desirable to disable this and instead provide one or more translation handles.

    Arguments |
    pos | (length-2 sequence) The position of the handle relative to the shape of the ROI. A value of (0,0) indicates the origin, whereas (1, 1) indicates the upper-right corner, regardless of the ROI’s size.
    item | The Handle instance to add. If None, a new handle will be created.
    name | The name of this handle (optional). Handles are identified by name when calling getLocalHandlePositions and getSceneHandlePositions.

  `angle`()

    Return the angle of the ROI in degrees.

  `boundingRect`(self) → PySide2.QtCore.QRectF
  `checkPointMove`(handle, pos, modifiers)

    When handles move, they must ask the ROI if the move is acceptable. By default, this always returns True. Subclasses may wish override.

  `getAffineSliceParams`(data, img, axes=(0, 1), fromBoundingRect=False)

    Returns the parameters needed to use `affineSlice` (shape, vectors, origin) to extract a subset of data using this ROI and img to specify the subset.

    If fromBoundingRect is True, then the ROI’s bounding rectangle is used rather than the shape of the ROI.

    See `getArrayRegion` for more information.

  `getArrayRegion`(data, img, axes=(0, 1), returnMappedCoords=False, **kwds)

    Use the position and orientation of this ROI relative to an imageItem to pull a slice from an array.

    Arguments |
    data | The array to slice from. Note that this array does not have to be the same data that is represented in img.
    img | (ImageItem or other suitable QGraphicsItem) Used to determine the relationship between the ROI and the boundaries of data.
    axes | (length-2 tuple) Specifies the axes in data that correspond to the (x, y) axes of img. If the image’s axis order is set to ‘row-major’, then the axes are instead specified in (y, x) order.
    returnMappedCoords | (bool) If True, the array slice is returned along with a corresponding array of coordinates that were used to extract data from the original array.
    **kwds | All keyword arguments are passed to `affineSlice`.

    This method uses `affineSlice` to generate the slice from data and uses `getAffineSliceParams` to determine the parameters to pass to `affineSlice`.

    If returnMappedCoords is True, then the method returns a tuple (result, coords) such that coords is the set of coordinates used to interpolate values from the original data, mapped into the parent coordinate system of the image. This is useful, when slicing data from images that have been transformed, for determining the location of each value in the sliced data.

    All extra keyword arguments are passed to `affineSlice`.

  `getArraySlice`(data, img, axes=(0, 1), returnSlice=True)

    Return a tuple of slice objects that can be used to slice the region from data that is covered by the bounding rectangle of this ROI. Also returns the transform that maps the ROI into data coordinates.

    If returnSlice is set to False, the function returns a pair of tuples with the values that would have been used to generate the slice objects. ((ax0Start, ax0Stop), (ax1Start, ax1Stop))

    If the slice cannot be computed (usually because the scene/transforms are not properly constructed yet), then the method returns None.

  `getGlobalTransform`(relativeTo=None)

    Return global transformation (rotation angle+translation) required to move from relative state to current state. If relative state isn’t specified, then we use the state of the ROI when mouse is pressed.

  `getHandles`()

    Return a list of this ROI’s Handles.

  `getLocalHandlePositions`(index=None)

    Returns the position of handles in the ROI’s coordinate system.

    The format returned is a list of (name, pos) tuples.

  `getSceneHandlePositions`(index=None)

    Returns the position of handles in the scene coordinate system.

    The format returned is a list of (name, pos) tuples.

  `indexOfHandle`(handle)

    Return the index of handle in the list of this ROI’s handles.

  `paint`(self, painter: PySide2.QtGui.QPainter, option: PySide2.QtWidgets.QStyleOptionGraphicsItem, widget: typing.Union[PySide2.QtWidgets.QWidget, NoneType] = None)
  `parentBounds`()

    Return the bounding rectangle of this ROI in the coordinate system of its parent.

  `pos`()

    Return the position (x,y) of the ROI’s origin. For most ROIs, this will be the lower-left corner.

  `removeHandle`(handle)

    Remove a handle from this ROI. Argument may be either a Handle instance or the integer index of the handle.

  `renderShapeMask`(width, height)

    Return an array of 0.0-1.0 into which the shape of the item has been drawn.

    This can be used to mask array selections.

  `replaceHandle`(oldHandle, newHandle)

    Replace one handle in the ROI for another. This is useful when connecting multiple ROIs together.

    oldHandle may be a Handle instance or the index of a handle to be replaced.

  `rotate`(angle, center=None, snap=False, update=True, finish=True)

    Rotate the ROI by angle degrees.

    Arguments |
    angle | (float) The angle in degrees to rotate
    center | (None | Point) Optional center point around which the ROI is rotated, in the local coordinate system of the ROI
    snap | (bool) If True, the final ROI angle is snapped to the nearest increment (default is 15 degrees; see ROI.rotateSnapAngle)
    update | (bool) See setPos()
    finish | (bool) See setPos()

  `saveState`()

    Return the state of the widget in a format suitable for storing to disk. (Points are converted to tuple)

    Combined with setState(), this allows ROIs to be easily saved and restored.

  `scale`(s, center=None, centerLocal=None, snap=False, update=True, finish=True)

    Resize the ROI by scaling relative to center. See setPos() for an explanation of the update and finish arguments.

  `setAngle`(angle, center=None, centerLocal=None, snap=False, update=True, finish=True)

    Set the ROI’s rotation angle.

    Arguments |
    angle | (float) The final ROI angle in degrees
    center | (None | Point) Optional center point around which the ROI is rotated, expressed as [0-1, 0-1] over the size of the ROI.
    centerLocal | (None | Point) Same as center, but the position is expressed in the local coordinate system of the ROI
    snap | (bool) If True, the final ROI angle is snapped to the nearest increment (default is 15 degrees; see ROI.rotateSnapAngle)
    update | (bool) See setPos()
    finish | (bool) See setPos()

  `setPen`(*args, **kwargs)

    Set the pen to use when drawing the ROI shape. For arguments, see `mkPen`.

  `setPos`(pos, y=None, update=True, finish=True)

    Set the position of the ROI (in the parent’s coordinate system).

    Accepts either separate (x, y) arguments or a single `Point` or `QPointF` argument.

    By default, this method causes both `sigRegionChanged` and `sigRegionChangeFinished` to be emitted. If finish is False, then `sigRegionChangeFinished` will not be emitted. You can then use stateChangeFinished() to cause the signal to be emitted after a series of state changes.

    If update is False, the state change will be remembered but not processed and no signals will be emitted. You can then use stateChanged() to complete the state change. This allows multiple change functions to be called sequentially while minimizing processing overhead and repeated signals. Setting `update=False` also forces `finish=False`.

  `setSelected`(self, selected: bool)
  `setSize`(size, center=None, centerLocal=None, snap=False, update=True, finish=True)

    Set the ROI’s size.

    Arguments |
    size | (Point | QPointF | sequence) The final size of the ROI
    center | (None | Point) Optional center point around which the ROI is scaled, expressed as [0-1, 0-1] over the size of the ROI.
    centerLocal | (None | Point) Same as center, but the position is expressed in the local coordinate system of the ROI
    snap | (bool) If True, the final size is snapped to the nearest increment (see ROI.scaleSnapSize)
    update | (bool) See setPos()
    finish | (bool) See setPos()

  `setState`(state, update=True)

    Set the state of the ROI from a structure generated by saveState() or getState().

  `setZValue`(self, z: float)
  `size`()

    Return the size (w,h) of the ROI.

  `stateChanged`(finish=True)

    Process changes to the state of the ROI. If there are any changes, then the positions of handles are updated accordingly and sigRegionChanged is emitted. If finish is True, then sigRegionChangeFinished will also be emitted.

  `translate`(*args, **kargs)

    Move the ROI to a new position. Accepts either (x, y, snap) or ([x,y], snap) as arguments If the ROI is bounded and the move would exceed boundaries, then the ROI is moved to the nearest acceptable position instead.

    snap can be:

    None (default) | use self.translateSnap and self.snapSize to determine whether/how to snap
    False | do not snap
    Point(w,h) | snap to rectangular grid with spacing (w,h)
    True | snap using self.snapSize (and ignoring self.translateSnap)

    Also accepts update and finish arguments (see setPos() for a description of these).

class `pyqtgraph.` `RectROI`(pos, size, centered=False, sideScalers=False, **args)

  Rectangular ROI subclass with a single scale handle at the top-right corner.

  Arguments |
  pos | (length-2 sequence) The position of the ROI origin. See ROI().
  size | (length-2 sequence) The size of the ROI. See ROI().
  centered | (bool) If True, scale handles affect the ROI relative to its center, rather than its origin.
  sideScalers | (bool) If True, extra scale handles are added at the top and right edges.
  **args | All extra keyword arguments are passed to ROI()

class `pyqtgraph.` `EllipseROI`(pos, size, **args)

  Elliptical ROI subclass with one scale handle and one rotation handle.

  Arguments |
  pos | (length-2 sequence) The position of the ROI’s origin.
  size | (length-2 sequence) The size of the ROI’s bounding rectangle.
  **args | All extra keyword arguments are passed to ROI()

  `getArrayRegion`(arr, img=None, axes=(0, 1), **kwds)

    Return the result of ROI.getArrayRegion() masked by the elliptical shape of the ROI. Regions outside the ellipse are set to 0.

  `paint`(self, painter: PySide2.QtGui.QPainter, option: PySide2.QtWidgets.QStyleOptionGraphicsItem, widget: typing.Union[PySide2.QtWidgets.QWidget, NoneType] = None)
  `shape`(self) → PySide2.QtGui.QPainterPath

class `pyqtgraph.` `CircleROI`(pos, size=None, radius=None, **args)

  Circular ROI subclass. Behaves exactly as EllipseROI, but may only be scaled proportionally to maintain its aspect ratio.

  Arguments |
  pos | (length-2 sequence) The position of the ROI’s origin.
  size | (length-2 sequence) The size of the ROI’s bounding rectangle.
  **args | All extra keyword arguments are passed to ROI()

class `pyqtgraph.` `LineSegmentROI`(positions=(None, None), pos=None, handles=(None, None), **args)

  ROI subclass with two freely-moving handles defining a line.

  Arguments |
  positions | (list of two length-2 sequences) The endpoints of the line segment. Note that, unlike the handle positions specified in other ROIs, these positions must be expressed in the normal coordinate system of the ROI, rather than (0 to 1) relative to the size of the ROI.
  **args | All extra keyword arguments are passed to ROI()

  `boundingRect`(self) → PySide2.QtCore.QRectF
  `getArrayRegion`(data, img, axes=(0, 1), order=1, returnMappedCoords=False, **kwds)

    Use the position of this ROI relative to an imageItem to pull a slice from an array.

    Since this pulls 1D data from a 2D coordinate system, the return value will have ndim = data.ndim-1

    See ROI.getArrayRegion() for a description of the arguments.

  `paint`(self, painter: PySide2.QtGui.QPainter, option: PySide2.QtWidgets.QStyleOptionGraphicsItem, widget: typing.Union[PySide2.QtWidgets.QWidget, NoneType] = None)
  `shape`(self) → PySide2.QtGui.QPainterPath

class `pyqtgraph.` `PolyLineROI`(positions, closed=False, pos=None, **args)

  Container class for multiple connected LineSegmentROIs.

  This class allows the user to draw paths of multiple line segments.

  Arguments |
  positions | (list of length-2 sequences) The list of points in the path. Note that, unlike the handle positions specified in other ROIs, these positions must be expressed in the normal coordinate system of the ROI, rather than (0 to 1) relative to the size of the ROI.
  closed | (bool) if True, an extra LineSegmentROI is added connecting the beginning and end points.
  **args | All extra keyword arguments are passed to ROI()

  `boundingRect`(self) → PySide2.QtCore.QRectF
  `clearPoints`()

    Remove all handles and segments.

  `getArrayRegion`(data, img, axes=(0, 1), **kwds)

    Return the result of ROI.getArrayRegion(), masked by the shape of the ROI. Values outside the ROI shape are set to 0.

  `paint`(self, painter: PySide2.QtGui.QPainter, option: PySide2.QtWidgets.QStyleOptionGraphicsItem, widget: typing.Union[PySide2.QtWidgets.QWidget, NoneType] = None)
  `removeHandle`(handle, updateSegments=True)

    Remove a handle from this ROI. Argument may be either a Handle instance or the integer index of the handle.

  `saveState`()

    Return the state of the widget in a format suitable for storing to disk. (Points are converted to tuple)

    Combined with setState(), this allows ROIs to be easily saved and restored.

  `setPen`(*args, **kwds)

    Set the pen to use when drawing the ROI shape. For arguments, see `mkPen`.

  `setPoints`(points, closed=None)

    Set the complete sequence of points displayed by this ROI.

    Arguments |
    points | List of (x,y) tuples specifying handle locations to set.
    closed | If bool, then this will set whether the ROI is closed (the last point is connected to the first point). If None, then the closed mode is left unchanged.

  `setState`(state)

    Set the state of the ROI from a structure generated by saveState() or getState().

  `shape`(self) → PySide2.QtGui.QPainterPath

class `pyqtgraph.` `LineROI`(pos1, pos2, width, **args)

  Rectangular ROI subclass with scale-rotate handles on either side. This allows the ROI to be positioned as if moving the ends of a line segment. A third handle controls the width of the ROI orthogonal to its “line” axis.

  Arguments |
  pos1 | (length-2 sequence) The position of the center of the ROI’s left edge.
  pos2 | (length-2 sequence) The position of the center of the ROI’s right edge.
  width | (float) The width of the ROI.
  **args | All extra keyword arguments are passed to ROI()

class `pyqtgraph.` `MultiRectROI`(points, width, pen=None, **args)

  Chain of rectangular ROIs connected by handles.

  This is generally used to mark a curved path through an image similarly to PolyLineROI. It differs in that each segment of the chain is rectangular instead of linear and thus has width.

  Arguments |
  points | (list of length-2 sequences) The list of points in the path.
  width | (float) The width of the ROIs orthogonal to the path.
  **args | All extra keyword arguments are passed to ROI()

  `addSegment`(pos=(0, 0), scaleHandle=False, connectTo=None)

    Add a new segment to the ROI connecting from the previous endpoint to pos. (pos is specified in the parent coordinate system of the MultiRectROI)

  `boundingRect`(self) → PySide2.QtCore.QRectF
  `getHandlePositions`()

    Return the positions of all handles in local coordinates.

  `paint`(self, painter: PySide2.QtGui.QPainter, option: PySide2.QtWidgets.QStyleOptionGraphicsItem, widget: typing.Union[PySide2.QtWidgets.QWidget, NoneType] = None)
  `removeSegment`(index=-1)

    Remove a segment from the ROI.