Package qupath.lib.images.servers

Interface ImageServer<T>

Type Parameters:
T -
All Superinterfaces:
AutoCloseable
All Known Subinterfaces:
GeneratingImageServer<T>, ImageDataServer<T>
All Known Implementing Classes:
AbstractImageServer, AbstractTileableImageServer, AffineTransformImageServer, BioFormatsImageServer, ChannelDisplayTransformServer, ChannelTransformFeatureServer, CroppedImageServer, ImageJServer, LabeledImageServer, NormalizedImageServer, OpenslideImageServer, PathHierarchyImageServer, PixelClassificationImageServer, RearrangeRGBImageServer, RenderedImageServer, RotatedImageServer, SlicedImageServer, SparseImageServer, TiledTransformingImageServer, TransformingImageServer, TypeConvertImageServer, WrappedBufferedImageServer, ZConcatenatedImageServer, ZProjectedImageServer
public interface ImageServer<T> extends AutoCloseable
Generic ImageServer, able to return pixels and metadata.

The idea behind making this generic was that it could be used on various platforms and with different UIs, e.g. Swing, JavaFX, or with different kinds of image reader. In practice, the generic parameter is almost always BufferedImage.

Important! The readBufferedImage(RegionRequest) method was replaced by readRegion(RegionRequest) in v0.4.0. Implementing classes need only to worry about overriding readRegion(RegionRequest) - and legacy implementations should be updated to override the new method rather than the old one. Default implementations of both methods exist to try to ease the transition, but this may change in the future and readBufferedImage(RegionRequest) is likely to be removed.

  • Method Details

    • getPath

      String getPath()
      Get a String path that can uniquely identify this image.

      For most standard images, this should be a String representation of an absolute URI. If multiple images are stored within the same file, then this information should be encoded in the URI.

      For images that are generated some other way (e.g. created dynamically) the path may not lend itself to a URI representation, but must still be unique so that it can be used for caching tiles.

      Returns:

    • getURIs

      Collection<URI> getURIs()
      Get the URIs for images required for this server. In the simplest case, this is a singleton list returning a URI representing a local file. However, some ImageServers may not have an associated URI at all, whereas others may depend upon multiple URIs (e.g. if concatenating images).

      Note: A URI alone may not be sufficient to recreate even a simple ImageServer; see getBuilder().

      Returns:

    • getPreferredDownsamples

      double[] getPreferredDownsamples()
      Get an array of downsample factors supported by the server
      Returns:

    • nResolutions

      int nResolutions()
      Number of resolutions for the image.

      This is equivalent to getPreferredDownsamples().length.

      Returns:

    • getDownsampleForResolution

      double getDownsampleForResolution(int level)
      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.
      Parameters:
      level - Resolution level, should be 0 <= level < nResolutions().
      Returns:

    • getWidth

      int getWidth()
      Width of the full-resolution image in pixels.
      Returns:

    • getHeight

      int getHeight()
      Height of the full-resolution image in pixels.
      Returns:

    • nChannels

      int nChannels()
      Number of channels (3 for RGB).
      Returns:

    • isRGB

      boolean isRGB()
      True if the image has 8-bit red, green & blue channels (and nothing else), false otherwise.
      Returns:

    • nZSlices

      int nZSlices()
      Number of slices in a z-stack.
      Returns:

    • nTimepoints

      int nTimepoints()
      Number of time points in a time series.
      Returns:

    • getPixelCalibration

      default PixelCalibration getPixelCalibration()
      Get the PixelCalibration object from the current metadata.
      Returns:

    • getCachedTile

      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! This method should be used very cautiously, as it is permitted to return the tile stored internally in the cache for performance. This must not be modified by any code requesting the tile.

      Parameters:
      tile -
      Returns:
      the tile if it has been cached, or null if no cached tile is available for the request.
      Implementation Requirements
      because this method exists for performance, the tile may be returned directly without defensive copying. If the tile is mutable, consumers must be extremely careful to avoid modifying the tile.

    • readBufferedImage

      @Deprecated default T readBufferedImage(RegionRequest request) throws IOException
      Deprecated.
      since v0.4.0. Implementations of ImageServer should override readRegion(RegionRequest) instead. This method will be removed in a future release; it exists now only to maintain compatibility with QuPath extensions that have not yet been updated to use the newer method.
      Legacy method to request pixels for a RegionRequest, now replaced by readRegion(RegionRequest). This method is deprecated; if the generic parameter <T> represented anything other than a BufferedImage then its name became misleading.
      Parameters:
      request - the region for which pixels are requested
      Returns:
      pixels for the region being requested
      Throws:
      IOException
      Implementation Note
      The default implementation simply calls readRegion(RegionRequest)

    • readRegion

      default T readRegion(RegionRequest request) throws IOException
      Read a 2D(+C) image region for a specified RegionRequest. Coordinates and bounding box dimensions from the request are in pixel units, at the full image resolution (i.e. when downsample = 1).

      All channels are always returned.

      No specific checking is guaranteed to ensure that the request is valid, e.g. if it extends beyond the image boundary then it is likely (but not certain) that the returned image will be cropped accordingly - but some implementations may contain empty padding instead. Therefore it is up to the caller to ensure that the requests are within range.

      However, it is expected that any returnable region will be at least 1x1 pixel in size, even if via high downsampling one might otherwise expect a 0x0 image. This is consistent with the idea of pixels representing point samples rather than little squares.

      Note: One should avoid returning null, as this cannot be stored as a value in some map implementations that may be used for caching.

      Parameters:
      request - the region for which pixels are requested
      Returns:
      pixels for the region being requested
      Throws:
      IOException
      Since:
      v0.4.0
      See Also:
      Implementation Note
      Implementations of ImageServer must override this method! The default implementation exists to search for the (deprecated) readBufferedImage(RegionRequest) method, so as to maintain compatibility with older ImageServer implementations - and throws an UnsupportedOperationException if this is not found.

    • readRegion

      default T readRegion(double downsample, int x, int y, int width, int height, int z, int t) throws IOException
      Read a 2D(+C) image region for a specified z-plane and timepoint. Coordinates and bounding box dimensions are in pixel units, at the full image resolution (i.e. when downsample = 1).

      All channels are always returned.

      Parameters:
      downsample - downsample factor for the region
      x - x coordinate of the top left of the region bounding box
      y - y coordinate of the top left of the region bounding box
      width - bounding box width
      height - bounding box height
      z - index for the z-position
      t - index for the timepoint
      Returns:
      pixels for the region being requested
      Throws:
      IOException
      Since:
      v0.4.0
      See Also:

    • readRegion

      default T readRegion(double downsample, int x, int y, int width, int height) throws IOException
      Read a 2D(+C) image region from the default ImagePlane (i.e. z and t are 0). Coordinates and bounding box dimensions are in pixel units, at the full image resolution (i.e. when downsample = 1).

      All channels are always returned.

      Parameters:
      downsample - downsample factor for the region
      x - x coordinate of the top left of the region bounding box
      y - y coordinate of the top left of the region bounding box
      width - bounding box width
      height - bounding box height
      Returns:
      pixels for the region being requested
      Throws:
      IOException
      Since:
      v0.4.0
      See Also:

    • getServerType

      String getServerType()
      A string describing the type of server, for example the name of the library used (Openslide, Bioformats...)
      Returns:

    • getAssociatedImageList

      List<String> getAssociatedImageList()
      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.

      Returns:
      See Also:

    • getAssociatedImage

      T getAssociatedImage(String name)
      Get the image for a given associated image name.
      Parameters:
      name -
      Returns:
      See Also:

    • isEmptyRegion

      boolean isEmptyRegion(RegionRequest request)
      Test whether a region is empty, i.e. it contains nothing to be painted (e.g. the server paints objects but there are no objects present in the region) and readRegion(RegionRequest) would return an empty tile.

      This makes it possible to avoid a (potentially more expensive) request to readRegion(RegionRequest), or to add it to a request queue, if we know there will be nothing to show for it.

      Note: Even if the method returns false it is possible that the region is still empty - the purpose of this method is to assist performance, and it should return quickly. Therefore if the calculations needed to identify if the region is empty are too onerous, it may conservatively return false.

      Parameters:
      request -
      Returns:

    • getPixelType

      PixelType getPixelType()
      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.
      Returns:

    • getChannel

      ImageChannel getChannel(int channel)
      Request information for one channel (0-based index).
      Parameters:
      channel -
      Returns:
      See Also:

    • getMetadata

      ImageServerMetadata getMetadata()
      Get essential metadata associated with the ImageServer as a distinct object. This may be edited by the user.
      Returns:
      See Also:

    • setMetadata

      void setMetadata(ImageServerMetadata metadata) throws IllegalArgumentException
      Set the metadata to use, e.g. to change the pixel size in microns.
      Parameters:
      metadata -
      Throws:
      IllegalArgumentException - if the metadata is incompatible (e.g. different image path, different bit-depth).

    • getOriginalMetadata

      ImageServerMetadata getOriginalMetadata()
      Get the original metadata read during creation of the server. This may or may not be correct.
      Returns:
      See Also:

    • getDefaultThumbnail

      T getDefaultThumbnail(int z, int t) throws IOException
      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.

      Parameters:
      z -
      t -
      Returns:
      Throws:
      IOException

    • getTileRequestManager

      TileRequestManager getTileRequestManager()
      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.

      Returns:

    • getImageClass

      Class<T> getImageClass()
      Get the class of the image representation returned by this ImageServer.
      Returns:

    • getBuilder

      default ImageServerBuilder.ServerBuilder<T> getBuilder()
      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.

      Returns: