Package qupath.lib.gui.viewer

Class QuPathViewer

java.lang.Object
qupath.lib.gui.viewer.QuPathViewer
All Implemented Interfaces:
EventListener, TileListener<BufferedImage>, PathObjectHierarchyListener, PathObjectSelectionListener
Direct Known Subclasses:
QuPathViewerPlus
public class QuPathViewer extends Object implements TileListener<BufferedImage>, PathObjectHierarchyListener, PathObjectSelectionListener
JavaFX component for viewing a (possibly large) image, along with overlays.
Author:
Pete Bankhead

  • Property Details

  • Field Details

    • imageUpdated

      protected boolean imageUpdated
      Flag used to indicate that the image was updated for a repaint (otherwise it's assumed only the overlay may have changed)

    • locationUpdated

      protected boolean locationUpdated
      Flag used to indicate that the visible region in the viewer has changed

  • Constructor Details

    • QuPathViewer

      public QuPathViewer(DefaultImageRegionStore regionStore, OverlayOptions overlayOptions)
      Create a new viewer.
      Parameters:
      regionStore - store used to tile caching
      overlayOptions - overlay options to control the viewer display

  • Method Details

    • getView

      public Pane getView()
      Get the main JavaFX component representing this viewer. This is what should be added to a scene.
      Returns:

    • setMinimumRepaintSpacingMillis

      public void setMinimumRepaintSpacingMillis(long repaintSpacingMillis)
      Prevent frequent repaints (temporarily) by setting a minimum time that must have elapsed after the previous repaint for a new one to be triggered. (Repaint requests that come in between are simply disregarded for performance.)

      When finished, it's necessary to call resetMinimumRepaintSpacingMillis() to make sure that normal service is resumed.

      Parameters:
      repaintSpacingMillis -
      See Also:

    • resetMinimumRepaintSpacingMillis

      public void resetMinimumRepaintSpacingMillis()
      Return to processing all repainting requests.

      Note: calling this command triggers a repaint itself.

    • setBorderColor

      public void setBorderColor(Color color)
      Set the border color for this viewer. This can be used to indicate (for example) that a particular viewer is active.
      Parameters:
      color -

    • getBorderColor

      public Color getBorderColor()
      Get the border color set for this viewer.
      Returns:

    • repaint

      public void repaint()
      Request that the viewer is repainted. The repaint is not triggered immediately, but rather enqueued for future processing.

      Note that this can be used for changes in the field of view or overlay, but not for large changes that require any cached thumbnail to also be updated (e.g. changing the brightness/contrast or lookup table). In such cases repaintEntireImage() is required.

      See Also:

    • getMinDownsample

      public double getMinDownsample()
      Get the minimum downsample value supported by this viewer. This prevents zooming in by an unreasonably large amount.
      Returns:

    • getMaxDownsample

      public double getMaxDownsample()
      Get the maximum downsample value supported by this viewer. This prevents zooming out by an unreasonably large amount.
      Returns:

    • zoomOut

      public void zoomOut(int nSteps)
      Zoom out by a specified number of steps, where one 'step' indicates a minimal zoom increment.
      Parameters:
      nSteps -

    • zoomIn

      public void zoomIn(int nSteps)
      Zoom in by a specified number of steps, where one 'step' indicates a minimal zoom increment.
      Parameters:
      nSteps -

    • getDefaultZoomFactor

      public double getDefaultZoomFactor()
      The amount by which the downsample factor is scaled for one increment of zoomIn() or zoomOut(). Controls zoom speed.
      Returns:

    • zoomOut

      public void zoomOut()
      Zoom out by one step.
      See Also:

    • zoomIn

      public void zoomIn()
      Zoom in by one step.
      See Also:

    • imageDataProperty

      public ReadOnlyObjectProperty<ImageData<BufferedImage>> imageDataProperty()
      Property for the image data currently being displayed within this viewer.
      Returns:
      See Also:

    • getImageData

      public ImageData<BufferedImage> getImageData()
      Get the image data currently being displayed within thie viewer.
      Returns:

    • getOverlayOptions

      public OverlayOptions getOverlayOptions()
      Get the overlay options that control the viewer display.
      Returns:

    • getImageRegionStore

      public DefaultImageRegionStore getImageRegionStore()
      Get the region store used by this viewer for tile caching and painting.
      Returns:

    • setDoFasterRepaint

      public void setDoFasterRepaint(boolean fasterRepaint)
      Set flag to indicate that repaints should prefer speed over accuracy. This is useful when scrolling quickly, or rapidly changing the image zoom.

      Note: Previously, this would drop the downsample level - but this produced visual artifacts too often. Currently it only impacts interpolation used.

      Parameters:
      fasterRepaint -

    • getMousePosition

      public Point2D getMousePosition()
      Get the current cursor position within this viewer, or null if the cursor is outside the viewer. This is provided in the component space.
      Returns:

    • isShowing

      public boolean isShowing()
      Returns true if the viewer is visible, and attached to a scene.
      Returns:

    • initializeForServer

      protected void initializeForServer(ImageServer<BufferedImage> server)

    • isSpaceDown

      public boolean isSpaceDown()
      Returns true if the spacebar was pressed when this component was focussed, and is still being held down.
      Returns:

    • setSpaceDown

      public void setSpaceDown(boolean spaceDown)
      Notify this viewer that the isSpaceDown status should be changed.

      This is useful whenever another component might have received the event, but the viewer needs to 'know' when it receives the focus.

      Parameters:
      spaceDown -

    • getCenterPixelX

      public double getCenterPixelX()
      Get the x-coordinate of the pixel currently centered in the viewer, in the full size image space.
      Returns:

    • getCenterPixelY

      public double getCenterPixelY()
      Get the y-coordinate of the pixel currently centered in the viewer, in the full size image space.
      Returns:

    • setActiveTool

      public void setActiveTool(PathTool tool)
      Set the active PathTool for input to this viewer.
      Parameters:
      tool -

    • getActiveTool

      public PathTool getActiveTool()
      Get the active PathTool for this viewer. Note that this is not necessarily identical to the result of the last call to setActiveTool(PathTool), because it may be modified by other behavior (e.g. pressing the spacebar to temporarily activate the Move tool).
      Returns:

    • updateCursor

      protected void updateCursor()

    • getCursor

      public Cursor getCursor()
      Get the current cursor for this viewer
      Returns:

    • setCursor

      public void setCursor(Cursor cursor)
      Set the requested cursor to display in this viewer
      Parameters:
      cursor -

    • getSelectedObject

      public PathObject getSelectedObject()
      Get the currently-selected object from the hierarchy.
      Returns:

    • getAllSelectedObjects

      public Collection<PathObject> getAllSelectedObjects()
      Get all currently-selected objects from the hierarchy.
      Returns:

    • setCustomPixelLayerOverlay

      public void setCustomPixelLayerOverlay(PathOverlay pathOverlay)
      Optionally set a custom overlay to use for the pixel layer.

      This is useful to support live prediction based on a specific field of view, for example.

      Parameters:
      pathOverlay -

    • resetCustomPixelLayerOverlay

      public void resetCustomPixelLayerOverlay()
      Reset the custom pixel layer overlay to null.

    • getCustomPixelLayerOverlay

      public PathOverlay getCustomPixelLayerOverlay()
      Get the custom pixel layer overlay, or null if it has not be set.
      Returns:

    • getCurrentROI

      public ROI getCurrentROI()
      Get the current ROI, i.e. the ROI belonging to the currently-selected object - or null, if there is no object or if the selected object has no ROI.
      Returns:

    • setSelectedObject

      public void setSelectedObject(PathObject pathObject)
      Set selected object in the current hierarchy, without centering the viewer.
      Parameters:
      pathObject -

    • setSelectedObject

      public void setSelectedObject(PathObject pathObject, boolean addToSelected)
      Set selected object in the current hierarchy, without centering the viewer.
      Parameters:
      pathObject -
      addToSelected -

    • getRenderer

      protected ImageRenderer getRenderer()
      Request a renderer that converts image tiles into RGB images.

      By default, this returns getImageDisplay.

      Subclasses might override this, e.g. to use custom image viewers that select transforms some other way.

      Returns:

    • getDisplayedRegionShape

      public Shape getDisplayedRegionShape()
      Get a shape corresponding to the region of the image currently visible in this viewer. Coordinates are in the image space. If no rotation is applied, the result will be an instance of java.awt.Rectangle. Otherwise it will be a Path2D with the rotated rectangle vertices.
      Returns:

    • getDisplayedClipShape

      protected Shape getDisplayedClipShape(Shape clip)
      Transform a clip shape into image coordinates for this viewer. The resulting shape coordinates are in the image space.
      Parameters:
      clip - The clip shape, or null if the entire width & height of the component should be used.
      Returns:

    • zoomToFit

      public void zoomToFit()
      Request that the downsample is set to contain the entire image, and the image is centered in the viewer.

    • getServer

      public ImageServer<BufferedImage> getServer()
      Get the ImageServer for the current image displayed within the viewer, or null if no image is displayed.
      Returns:

    • hasServer

      public boolean hasServer()
      Returns true if there is currently an ImageServer being displayed in this viewer.
      Returns:

    • setZPosition

      public void setZPosition(int zPos)
      Set the requested z-slice to be visible.
      Parameters:
      zPos -

    • getTPosition

      public int getTPosition()
      Get the currently-visible time point.
      Returns:

    • setTPosition

      public void setTPosition(int tPosition)
      Set the requested time point to be visible.
      Parameters:
      tPosition -

    • getZPosition

      public int getZPosition()
      Get the currently-visible z-slice.
      Returns:

    • getImagePlane

      public ImagePlane getImagePlane()
      Get the ImagePlane currently being displayed, including z and t positions. Channels are ignored.
      Returns:

    • isImageDataChanging

      public boolean isImageDataChanging()
      Returns true between the time setImageData has been called, and before the first repaint has been completed.

      This is useful to distinguish between view changes triggered by setting the ImageData, and those triggered by panning/zooming.

      Returns:

    • setImageData

      public void setImageData(ImageData<BufferedImage> imageDataNew) throws IOException
      Set the current image for this viewer.
      Parameters:
      imageDataNew -
      Throws:
      IOException

    • resetImageData

      public void resetImageData()
      Reset the image data to null.

    • fireImageDataChanged

      protected void fireImageDataChanged(ImageData<BufferedImage> imageDataPrevious, ImageData<BufferedImage> imageDataNew)

    • fireVisibleRegionChangedEvent

      protected void fireVisibleRegionChangedEvent(Shape shape)

    • repaintEntireImage

      public void repaintEntireImage()
      Request that the entire image is repainted, including the thumbnail. This should be called whenever a major change in display is triggered, such as changing the brightness/contrast or lookup table. Otherwise, repaint() is preferable.
      See Also:

    • getMagnification

      public double getMagnification()
      Get the magnification for the image within this viewer, or Double.NaN if no image is present. This is mostly for display; getDownsampleFactor() is more meaningful. The actual value of the magnification depends upon whether any magnification value is available within the image metadata.
      Returns:

    • getFullMagnification

      public double getFullMagnification()
      Get the full magnification for the image. This is either the magnification value stored within the current image metadata, or 1.0 if no suitable image or metadata is available.
      Returns:

    • setMagnification

      public void setMagnification(double magnification)
      Set the downsample factor based upon magnification values. In general, setDownsampleFactor(double) should be used directly in preference to this method.
      Parameters:
      magnification -

    • closeViewer

      public void closeViewer()
      Request that this viewer is closed. This unbinds the viewer from any properties it may be observing, and also triggers QuPathViewerListener.viewerClosed(QuPathViewer) calls for any viewer listeners.

    • paintComponent

      protected void paintComponent(Graphics g)

    • paintViewer

      protected void paintViewer(Graphics g, int w, int h)

    • getMaxROIHandleSize

      public double getMaxROIHandleSize()
      Get the maximum size for which ROI handles may be drawn.
      Returns:

    • repaintTimestamp

      public ReadOnlyLongProperty repaintTimestamp()
      Get the timestamp referring to the last time this viewer was repainted.
      Returns:

    • getOverlayLayers

      public List<PathOverlay> getOverlayLayers()
      Get an unmodifiable list containing the overlay layers, in order.
      Returns:

    • getCustomOverlayLayers

      public ObservableList<PathOverlay> getCustomOverlayLayers()
      Get direct access to the custom overlay list.
      Returns:

    • getGammaOp

      public LookupOp getGammaOp()
      Get a LookupOp that can perform any requested gamma correction in this viewer. Note that the gamma is applied to the RGB image (not the original data).
      Returns:
      a gamma op if specified, or null if no gamma adjustment is required (gamma is 1.0, or invalid)

    • getGamma

      public double getGamma()
      Get the gamma value used for this viewer.
      Returns:

    • setGamma

      public void setGamma(double gamma)
      Set the gamma value for this viewer. Note that if the property is bound (as it is by default, the method does not change the gamma value but rather logs a warning that viewer.gammaProperty().unbind() should be called first.
      Parameters:
      gamma -

    • gammaProperty

      public DoubleProperty gammaProperty()
      Get the gamma property for this viewer. By default, this is bound to PathPrefs.viewerGammaProperty().
      Returns:
      See Also:

    • getROIEditor

      public RoiEditor getROIEditor()
      Get the RoiEditor used by this viewer.
      Returns:

    • getImageDisplay

      public ImageDisplay getImageDisplay()
      Get the ImageDisplay object used to determine how the image is converted to RGB for display.
      Returns:

    • componentContains

      protected boolean componentContains(double x, double y)

    • setDownsampleFactor

      public void setDownsampleFactor(double downsampleFactor)
      Set the downsample factor for this viewer.
      Parameters:
      downsampleFactor -

    • getThumbnail

      public BufferedImage getThumbnail()
      Get a thumbnail representing the image as displayed by this viewer.
      Returns:

    • getAllThumbnails

      public List<BufferedImage> getAllThumbnails()
      Get thumbnails for all z-slices & time points
      Returns:

    • getRGBThumbnail

      public BufferedImage getRGBThumbnail()
      Get a thumbnail representing the image as displayed by this viewer. Note: This will be a color (aRGB) image, with any color transforms applied - therefore should not be used to extract 'original' pixel values
      Returns:

    • setDownsampleFactor

      public void setDownsampleFactor(double downsampleFactor, double cx, double cy)
      Set downsample factor, so that the specified coordinate in the image space is not shifted in the viewer afterwards. The purpose is to make it possible to zoom in/out while keeping the cursor focussed on a particular location. The specified downsample factor will automatically be clipped to the range getMinDownsample to getMaxDownsample.
      Parameters:
      downsampleFactor -
      cx -
      cy -

    • setDownsampleFactor

      public void setDownsampleFactor(double downsampleFactor, double cx, double cy, boolean clipToMinMax)
      Set downsample factor, so that the specified coordinate in the image space is not shifted in the viewer afterwards. The purpose is to make it possible to zoom in/out while keeping the cursor focused on a particular location.
      Parameters:
      downsampleFactor -
      cx -
      cy -
      clipToMinMax - If true, the specified downsample factor will be clipped to the range getMinDownsample to getMaxDownsample.

    • getZoomToFitDownsampleFactor

      protected double getZoomToFitDownsampleFactor()

    • getServerWidth

      public int getServerWidth()
      Get the width in pixels of the full resolution of the current image, or 0 if no image is currently open.
      Returns:

    • getServerHeight

      public int getServerHeight()
      Get the height in pixels of the full resolution of the current image, or 0 if no image is currently open.
      Returns:

    • getServerBounds

      public ImageRegion getServerBounds()
      Get an ImageRegion representing the full width and height of the current image. The ImagePlane is set according to the z and t position of the viewer.
      Returns:

    • getDownsampleFactor

      public double getDownsampleFactor()
      Get the current downsample factor.
      Returns:

    • componentPointToImagePoint

      public Point2D componentPointToImagePoint(Point2D point, Point2D pointDest, boolean constrainToBounds)
      Convert a coordinate from the viewer into the corresponding pixel coordinate in the full-resolution image - optionally constraining it to any server bounds. A point object can optionally be provided into which the location is written (may be the same as the component point object).
      Parameters:
      point -
      pointDest -
      constrainToBounds -
      Returns:

    • componentPointToImagePoint

      public Point2D componentPointToImagePoint(double x, double y, Point2D pointDest, boolean constrainToBounds)
      Convert x and y coordinates from the component space to the image space.
      Parameters:
      x - x coordinate, related to getView()
      y - y coordinate, related to getView()
      pointDest - object in which to store the corresponding image point (will be set and returned if non-null)
      constrainToBounds - if true, clip the image coordinate computed from x and y to fit within the image bounds
      Returns:
      a Point2D referring to the pixel coordinate corresponding to the component coordinate defined by x and y;

    • imagePointToComponentPoint

      public Point2D imagePointToComponentPoint(Point2D point, Point2D pointDest, boolean constrainToBounds)
      Convert a coordinate from the the full-resolution image into the corresponding pixel coordinate in the viewer - optionally constraining it to any viewer component bounds. A point object can optionally be provided into which the location is written (may be the same as the image point object).
      Parameters:
      point -
      pointDest -
      constrainToBounds -
      Returns:

    • centerImage

      public void centerImage()
      Center the current image in the viewer, while keeping the same downsample factor. This does nothing if no image is currently open.

    • getObjectClassificationString

      public String getObjectClassificationString(double x, double y)
      Get a string representing the object classification x & y location in the viewer component, or an empty String if no object is found.
      Parameters:
      x - x-coordinate in the component space (not image space)
      y - y-coordinate in the component space (not image space)
      Returns:
      a String to display representing the object classification

    • getImageObjectClassificationString

      public String getImageObjectClassificationString(double x, double y)
      Get a string representing the object classification x & y location in the viewer component, or an empty String if no object is found.
      Parameters:
      x - x-coordinate in the image space (not the component/viewer space)
      y - y-coordinate in the image space (not the component/viewer space)
      Returns:
      a String to display representing the object classification

    • getFullLocationString

      protected String getFullLocationString(boolean useCalibratedUnits)
      Get a string to summarize the pixel found below the most recent known mouse location, or "" if the mouse is outside this viewer.
      Parameters:
      useCalibratedUnits - If true, microns will be used rather than pixels (if known).
      Returns:

    • getHierarchy

      public PathObjectHierarchy getHierarchy()
      Get the object hierarchy for the current image data, or null if no image data is available.
      Returns:

    • addViewerListener

      public void addViewerListener(QuPathViewerListener listener)
      Add a viewer listener.
      Parameters:
      listener -

    • removeViewerListener

      public void removeViewerListener(QuPathViewerListener listener)
      Remove a viewer listener.
      Parameters:
      listener -

    • setCenterPixelLocation

      public void setCenterPixelLocation(double x, double y)
      Set the image pixel to display in the center of the viewer (using image pixel coordinates at the full-resolution)
      Parameters:
      x -
      y -

    • centerROI

      public void centerROI(ROI roi)
      Center the specified ROI in the viewer
      Parameters:
      roi -

    • updateAffineTransform

      protected void updateAffineTransform()

    • setRotation

      public void setRotation(double theta)
      Set the rotation; angle in radians.
      Parameters:
      theta -

    • isRotated

      public boolean isRotated()
      Returns true if viewer.getRotation() != 0.
      Returns:
      isRotated

    • getRotation

      public double getRotation()
      Get the current rotation; angle in radians.
      Returns:
      rotation in radians

    • rotationProperty

      public DoubleProperty rotationProperty()
      Return the rotation property of this viewer.
      Returns:
      rotation property
      See Also:

    • tileAvailable

      public void tileAvailable(String serverPath, ImageRegion region, BufferedImage tile)
      Description copied from interface: TileListener
      Notify a listener that an image tile has been received read & is available.
      Specified by:
      tileAvailable in interface TileListener<BufferedImage>
      Parameters:
      serverPath -
      region -
      tile -

    • forceOverlayUpdate

      public void forceOverlayUpdate()
      Force the overlay displaying detections and annotations to be repainted. Any cached versions will be thrown away, so this is useful when some aspect of the display has changed, e.g. objects colors or fill/outline status. Due to the usefulness of caching for performance, it should not be called too often.

    • hierarchyChanged

      public void hierarchyChanged(PathObjectHierarchyEvent event)
      Description copied from interface: PathObjectHierarchyListener
      Notify listeners of a change in the hierarchy or its objects.
      Specified by:
      hierarchyChanged in interface PathObjectHierarchyListener
      Parameters:
      event -

    • selectedPathObjectChanged

      public void selectedPathObjectChanged(PathObject pathObjectSelected, PathObject previousObject, Collection<PathObject> allSelected)
      Description copied from interface: PathObjectSelectionListener
      Fired when the selected objects have changed.
      Specified by:
      selectedPathObjectChanged in interface PathObjectSelectionListener
      Parameters:
      pathObjectSelected - the primary selected object
      previousObject - the previous primary selected object
      allSelected - all currently selected objects (including the primary)

    • requiresTileRegion

      public boolean requiresTileRegion(String serverPath, ImageRegion region)
      Description copied from interface: TileListener
      Check if the listener requires a particular tile. This is primarily designed to deal with asynchronous tile requests; by the time the server is ready to process the the request, it might be out of date (e.g. if the user has panned to a different part of the image). A server *may* make use of this function to do a last minute poll of all listeners to check if the region is required. Any implementation should return quickly (erring conservatively on the side of 'true' if the calculations would be prohibitively expensive), since otherwise it doesn't save time in seeking the tile itself.
      Specified by:
      requiresTileRegion in interface TileListener<BufferedImage>
      Parameters:
      serverPath -
      region -
      Returns:

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • zPositionProperty

      public IntegerProperty zPositionProperty()
      Current z-position for the z-slice currently visible in the viewer.
      Returns:
      See Also:

    • tPositionProperty

      public IntegerProperty tPositionProperty()
      Current t-position for the timepoint currently visible in the viewer.
      Returns:
      See Also:

    • requestStopMoving

      public void requestStopMoving()
      Request that the viewer stop any panning immediately.
      See Also:

    • requestDecelerate

      public void requestDecelerate()
      Request that a viewer decelerate any existing panning smoothly.
      See Also:

    • requestStartMoving

      public void requestStartMoving(double dx, double dy)
      Request that the viewer start panning with a velocity determined by dx and dy.

      This can be used in combination with requestDecelerate to end a panning event more smoothly.

      Parameters:
      dx -
      dy -
      See Also:

    • requestCancelDirection

      public void requestCancelDirection(boolean xAxis)
      Requests that the viewer cancels either the x- or y-axis direction.
      Parameters:
      xAxis -