Package qupath.lib.images.servers

Class AbstractImageServer<T>

java.lang.Object
qupath.lib.images.servers.AbstractImageServer<T>
Type Parameters:
T -
All Implemented Interfaces:
AutoCloseable, ImageServer<T>
Direct Known Subclasses:
AbstractTileableImageServer, ImageJServer, TransformingImageServer
public abstract class AbstractImageServer<T> extends Object implements ImageServer<T>
Abstract implementation of ImageServer providing some common functionality.
Author:
Pete Bankhead

  • Constructor Details

    • AbstractImageServer

      protected AbstractImageServer(Class<T> imageClass)

  • Method Details

    • getImageClass

      public Class<T> getImageClass()
      Description copied from interface: ImageServer
      Get the class of the image representation returned by this ImageServer.
      Specified by:
      getImageClass in interface ImageServer<T>
      Returns:

    • getCache

      protected Map<RegionRequest,T> getCache()
      Get the internal cache. This may be useful to check for the existence of a cached tile any time when speed is of the essence, and if no cached tile is available a request will not be made.
      Returns:

    • getThumbnailDownsampleFactor

      protected double getThumbnailDownsampleFactor(int maxWidth, int maxHeight)

    • createServerBuilder

      protected abstract ImageServerBuilder.ServerBuilder<T> createServerBuilder()
      Create a ServerBuilder, which can be used to construct an identical ImageServer. This should also include the current metadata. It is permissible to return null for an ImageServer that cannot be recreated via a ImageServerBuilder.ServerBuilder.
      Returns:

    • getBuilder

      public ImageServerBuilder.ServerBuilder<T> getBuilder()
      Description copied from interface: ImageServer
      Get a ServerBuilder capable of building a server the same as this one.

      The purpose of this is to aid serialization of servers by switching to a simpler representation.

      The default implementation returns null, indicating that rebuilding the server is not supported.

      Specified by:
      getBuilder in interface ImageServer<T>
      Returns:

    • getDownsampleForResolution

      public double getDownsampleForResolution(int level)
      Description copied from interface: ImageServer
      Get the downsample factor for a specified resolution level, where level 0 is the full resolution image and nResolutions() - 1 is the lowest resolution available.
      Specified by:
      getDownsampleForResolution in interface ImageServer<T>
      Parameters:
      level - Resolution level, should be 0 <= level < nResolutions().
      Returns:

    • close

      public void close() throws Exception
      Specified by:
      close in interface AutoCloseable
      Throws:
      Exception

    • nResolutions

      public int nResolutions()
      Description copied from interface: ImageServer
      Number of resolutions for the image.

      This is equivalent to getPreferredDownsamples().length.

      Specified by:
      nResolutions in interface ImageServer<T>
      Returns:

    • getPreferredDownsamples

      public double[] getPreferredDownsamples()
      Request the preferred downsamples from the image metadata.

      Note that this makes a defensive copy of the array, so it is generally preferable to use #getDownsampleForResolution(int) where possible.

      Specified by:
      getPreferredDownsamples in interface ImageServer<T>
      Returns:
      See Also:

    • isRGB

      public boolean isRGB()
      Description copied from interface: ImageServer
      True if the image has 8-bit red, green & blue channels (and nothing else), false otherwise.
      Specified by:
      isRGB in interface ImageServer<T>
      Returns:

    • getPixelType

      public PixelType getPixelType()
      Description copied from interface: ImageServer
      The bit-depth and type of the image. This refers to a single channel, e.g. an 8-bit RGB image will have a type of PixelType.UINT8.
      Specified by:
      getPixelType in interface ImageServer<T>
      Returns:

    • finalize

      protected void finalize() throws Throwable
      Attempt to close the server. While not at all a good idea to rely on this, it may help clean up after some forgotten servers.
      Overrides:
      finalize in class Object
      Throws:
      Throwable

    • isEmptyRegion

      public boolean isEmptyRegion(RegionRequest request)
      Always returns false.
      Specified by:
      isEmptyRegion in interface ImageServer<T>
      Parameters:
      request -
      Returns:

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getCachedTile

      public T getCachedTile(TileRequest tile)
      Get a cached tile, or null if the tile has not been cached.

      This is useful whenever it is important to return quickly rather than wait for a tile to be fetched or generated.

      Warning! The cached tile is returned directly (with no defensive copying) for performance. This means that it must not be modified by the code that requests it. If there is any chance the tile may be modified (or passed to untrusted code), then make sure to make a defensive copy, e.g. using BufferedImageTools.duplicate(java.awt.image.BufferedImage) if using a buffered image.

      Specified by:
      getCachedTile in interface ImageServer<T>
      Parameters:
      tile -
      Returns:
      the tile if it has been cached, or null if no cached tile is available for the request.

    • createID

      protected abstract String createID()
      Create a unique ID for the server, which can be returned as the default value of getPath(). A suggested implementation is 

        getClass().getName() + ": " + URI + parameters
      This will be called on demand whenever getPath() is first required.
      Returns:

    • getPath

      public String getPath()
      Default implementation lazily calls createID() on demand.
      Specified by:
      getPath in interface ImageServer<T>
      Returns:
      See Also:

    • getWidth

      public int getWidth()
      Description copied from interface: ImageServer
      Width of the full-resolution image in pixels.
      Specified by:
      getWidth in interface ImageServer<T>
      Returns:

    • getHeight

      public int getHeight()
      Description copied from interface: ImageServer
      Height of the full-resolution image in pixels.
      Specified by:
      getHeight in interface ImageServer<T>
      Returns:

    • nChannels

      public int nChannels()
      Description copied from interface: ImageServer
      Number of channels (3 for RGB).
      Specified by:
      nChannels in interface ImageServer<T>
      Returns:

    • nZSlices

      public int nZSlices()
      Description copied from interface: ImageServer
      Number of slices in a z-stack.
      Specified by:
      nZSlices in interface ImageServer<T>
      Returns:

    • nTimepoints

      public int nTimepoints()
      Description copied from interface: ImageServer
      Number of time points in a time series.
      Specified by:
      nTimepoints in interface ImageServer<T>
      Returns:

    • getMetadata

      public ImageServerMetadata getMetadata()
      Description copied from interface: ImageServer
      Get essential metadata associated with the ImageServer as a distinct object. This may be edited by the user.
      Specified by:
      getMetadata in interface ImageServer<T>
      Returns:
      See Also:

    • setMetadata

      public void setMetadata(ImageServerMetadata metadata)
      Description copied from interface: ImageServer
      Set the metadata to use, e.g. to change the pixel size in microns.
      Specified by:
      setMetadata in interface ImageServer<T>
      Parameters:
      metadata -

    • getAssociatedImageList

      public List<String> getAssociatedImageList()
      Description copied from interface: ImageServer
      Get a list of 'associated images', e.g. thumbnails or slide overview images.

      Each associated image is simply a T that does not warrant (or require) a full ImageServer, and most likely would never be analyzed.

      Specified by:
      getAssociatedImageList in interface ImageServer<T>
      Returns:
      See Also:

    • getAssociatedImage

      public T getAssociatedImage(String name)
      Description copied from interface: ImageServer
      Get the image for a given associated image name.
      Specified by:
      getAssociatedImage in interface ImageServer<T>
      Parameters:
      name -
      Returns:
      See Also:

    • getChannel

      public ImageChannel getChannel(int channel)
      Description copied from interface: ImageServer
      Request information for one channel (0-based index).
      Specified by:
      getChannel in interface ImageServer<T>
      Parameters:
      channel -
      Returns:
      See Also:

    • getDefaultThumbnail

      public T getDefaultThumbnail(int z, int t) throws IOException
      Description copied from interface: ImageServer
      Get the default thumbnail for a specified z-slice and timepoint.

      This should be the lowest resolution image that is available in the case of the multiresolution image, or else the full image. For large datasets, it may be used to determine basic statistics or histograms without requiring every pixel to be visited in the full resolution image.

      Specified by:
      getDefaultThumbnail in interface ImageServer<T>
      Parameters:
      z -
      t -
      Returns:
      Throws:
      IOException

    • getTileRequestManager

      public TileRequestManager getTileRequestManager()
      Description copied from interface: ImageServer
      Get a TileRequestManager that can be used to identify image tiles that may be efficiently requested from this ImageServer.

      This is useful because managing arbitrary RegionRequests can result in inefficiencies if a request straddles multiple tiles unnecessarily. Also, it can be used to help ensure consistency whenever requesting regions at different resolutions, where rounding errors might otherwise occur.

      Note that the TileRequestManager is not guaranteed to remain the same for the lifecycle of the server. For example, if the image metadata is changed then a new manager may be constructed.

      Specified by:
      getTileRequestManager in interface ImageServer<T>
      Returns: