Package qupath.lib.roi

Class RoiEditor

java.lang.Object
qupath.lib.roi.RoiEditor
public class RoiEditor extends Object
Helper class for interactively modifying existing ROIs.

Modification of ROIs has been made intentionally quite awkward to help ensure they are fairly consistent (i.e. limited mutability), but this can be a bit infuriating when the user wishes to make annotations interactively.

Also, currently PathObjects have their ROIs set at creation time - adding further annoyance to the lack of easy ROI editability.

RoiEditors provide GUIs with a mechanism for controlled ROI manipulation, when the natural alternative (creating new ROIs) might be too computationally expensive. By consciously having to make changes via a RoiEditor, it is hoped that programmers will remember inform the PathObjectHierarchy whenever an object has been changed (note that this does not happen automatically - the RoiEditor knows nothing of PathObjects and hierarchies... only ROIs of various flavors).

Where any other ROI processing is required, the 'correct' approach is to create a new PathObject as required.

Author:
Pete Bankhead

  • Method Summary

    Modifier and Type
    Method
    Description
    static RoiEditor
    createInstance()
    Create a new RoiEditor.
    void
    ensureHandlesUpdated()
    In the event that the current ROI has been modified elsewhere (which generally it shouldn't be) request the handles to be recomputed to avoid inconsistency.
    boolean
    finishTranslation()
    Notify the editor that translation should end.
    List<Point2>
    getHandles()
    Get all the handles for the current ROI being edited, or an empty list if no handles are available.
    ROI
    getROI()
    Retrieve the ROI currently being edited (may be null).
    boolean
    grabHandle(double x, double y, double maxDist, boolean shiftDown)
    Try to grab a ROI handle.
    boolean
    hasActiveHandle()
    Returns true if a handle is currently active, for example being reposition.
    boolean
    hasROI()
    Returns true if this editor currently has a ROI.
    boolean
    isTranslating()
    Query if a ROI is currently being translated through this editor.
    ROI
    requestNewHandle(double x, double y)
    Request an updated ROI with a new handle inserted - useful e.g.
    void
    resetActiveHandle()
    Ensure that no handle is active.
    ROI
    setActiveHandlePosition(double x, double y, double minDisplacement, boolean shiftDown)
    If a handle has been grabbed, update its displacement.
    void
    setROI(ROI roi)
    Set the active ROI, stopping any ROI translation currently in progress.
    void
    setROI(ROI roi, boolean stopTranslating)
    Set the active ROI, optionally stopping any ROI translation currently in progress.
    boolean
    startTranslation(double x, double y, boolean snapToPixel)
    Returns true if the current ROI is translatable, and at the end of this call the translation has started.
    ROI
    updateTranslation(double x, double y, ImageRegion constrainRegion)
    Update a ROI by translation, optionally constraining its movement within a specified boundary.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • createInstance

      public static RoiEditor createInstance()
      Create a new RoiEditor.
      Returns:

    • setROI

      public void setROI(ROI roi)
      Set the active ROI, stopping any ROI translation currently in progress.
      Parameters:
      roi -

    • setROI

      public void setROI(ROI roi, boolean stopTranslating)
      Set the active ROI, optionally stopping any ROI translation currently in progress.
      Parameters:
      roi -
      stopTranslating - if true, then any ROI currently being translated will have its translation completed. Normally this should be true, but it may be false if the new ROI being set is part of the same translation event.

    • startTranslation

      public boolean startTranslation(double x, double y, boolean snapToPixel)
      Returns true if the current ROI is translatable, and at the end of this call the translation has started.
      Parameters:
      x -
      y -
      snapToPixel - if true, request that translations snap to pixel coordinates
      Returns:

    • updateTranslation

      public ROI updateTranslation(double x, double y, ImageRegion constrainRegion)
      Update a ROI by translation, optionally constraining its movement within a specified boundary.

      Returns the same ROI if translation was not possible, or the translation resulted in no movement, of if isTranslating() returns false. Otherwise returns a translated version of the ROI;

      Parameters:
      x -
      y -
      constrainRegion -
      Returns:

    • finishTranslation

      public boolean finishTranslation()
      Notify the editor that translation should end.
      Returns:
      true if there is any displacement between the current and starting translation points, false otherwise.

    • isTranslating

      public boolean isTranslating()
      Query if a ROI is currently being translated through this editor.
      Returns:

    • ensureHandlesUpdated

      public void ensureHandlesUpdated()
      In the event that the current ROI has been modified elsewhere (which generally it shouldn't be) request the handles to be recomputed to avoid inconsistency.

    • getHandles

      public List<Point2> getHandles()
      Get all the handles for the current ROI being edited, or an empty list if no handles are available.
      Returns:

    • hasROI

      public boolean hasROI()
      Returns true if this editor currently has a ROI.
      Returns:

    • getROI

      public ROI getROI()
      Retrieve the ROI currently being edited (may be null).
      Returns:

    • hasActiveHandle

      public boolean hasActiveHandle()
      Returns true if a handle is currently active, for example being reposition.
      Returns:
      See Also:

    • resetActiveHandle

      public void resetActiveHandle()
      Ensure that no handle is active.

    • requestNewHandle

      public ROI requestNewHandle(double x, double y)
      Request an updated ROI with a new handle inserted - useful e.g. when drawing a polygon.
      Parameters:
      x -
      y -
      Returns:

    • grabHandle

      public boolean grabHandle(double x, double y, double maxDist, boolean shiftDown)
      Try to grab a ROI handle. This will fail (return false, with an error logged) if isTranslating() returns true.
      Parameters:
      x -
      y -
      maxDist - define the distance to search for the nearest handle
      shiftDown - determined from a MouseEvent, this may optionally be used to control how the handle is modified (e.g. to enforce a square bounding box for a rectangle or ellipse).
      Returns:

    • setActiveHandlePosition

      public ROI setActiveHandlePosition(double x, double y, double minDisplacement, boolean shiftDown)
      If a handle has been grabbed, update its displacement.
      Parameters:
      x -
      y -
      minDisplacement - if > 0, smaller movements will be discarded to avoid unnecessary work.
      shiftDown - determined from a MouseEvent, this may optionally be used to control how the handle is modified (e.g. to enforce a square bounding box for a rectangle or ellipse).
      Returns: