Interface Decoder

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
BMPDecoder, GIFDecoder, JPEGDecoder, PNGDecoder, TIFFDecoder
public interface Decoder extends AutoCloseable

Image decoder.

Decoders are instantiated per request and need not be thread-safe. But any library they call into does need to support simultaneous usage from multiple threads.

Notes

Initialization and disposal

Instances should not use constructors to initialize themselves. Instead they may implement Plugin.initializePlugin(), or they may defer initialization until first use.

Likewise, for class-level initialization, implementations should use Plugin.onApplicationStart() instead of a static initializer.

Instances should release all necessary resources using close().

Image indexes

Several methods accept an imageIndex argument, which is meant to enable access to multiple images contained within the same file, as in the case of e.g. a client "page" query. How this works is:

  • For basic still images, there is only the main image at index 0.
  • For formats like JPEG2000 that support different resolution levels of the same image, there is still only the main image at index 0.
  • For formats like TIFF and PDF that support multiple sibling images or pages, these are accessible by their index. Some special considerations for TIFF:
    • TIFF also supports subimages of subimages, which this interface does not.)
    • The sibling images in a TIFF may be different resolution levels, as in a pyramidal TIFF. In this case, they will not be accessible by their index.
  • For formats like HEIF that support unordered subimages, each subimage will have an unpredictable index assigned by the codec library. (The primary image will generally be at index 0.)
  • For animated image formats like GIF, each frame has its own index.
  • For video formats, the index refers to each second of the video.

The value passed to an imageIndex argument must never be greater than the return value of {@link #getNumImages()} - 1—otherwise an IndexOutOfBoundsException is thrown.

Default implementations

Some methods have default implementations. These correspond with features that may be nice to have in some circumstances but are nevertheless nonessential.

  • Method Details

    • setArena

      default void setArena(Arena arena)

      Implementations that make use of the Foreign Function & Memory API should do their native work in this instance. They should not close it.

      The default implementation does nothing.

      Parameters:
      arena - Arena in which to allocate foreign memory.

    • setSource

      void setSource(Path imageFile)
      Sets the source to a file.
      Parameters:
      imageFile - File to read from.

    • setSource

      void setSource(ImageInputStream inputStream)
      Sets the source to a stream.
      Parameters:
      inputStream - Stream to read from, which will not be closed.

    • detectFormat

      Format detectFormat() throws IOException

      Called after a source has been set.

      If reading from a setSource(ImageInputStream) stream}, the stream position is reset to 0 before returning.

      Unlike many of the other interface methods, implementations should not throw a SourceFormatException, and instead just return Format.UNKNOWN.

      Returns:
      Format of the image to decode, if supported by the instance; otherwise Format.UNKNOWN. The implementation must create the instance from scratch and not obtain it from the format registry, which may be empty at the time this method is invoked.
      Throws:
      NoSuchFileException - if the source file does not exist.
      IOException - if there is some other error reading the image.

    • getNumImages

      int getNumImages() throws IOException
      Note that for many video formats, a duration is not encoded in the beginning of the file and may need to be found by some other (expensive) means. In this case it's better to return Integer.MAX_VALUE than to find the exact duration.
      Returns:
      Number of images available in the image container. See the class documentation and the note above.
      Throws:
      NoSuchFileException - if the source file does not exist.
      SourceFormatException - if the image format is not supported.
      IOException - if there is some other error reading the number of images.

    • getNumResolutions

      int getNumResolutions() throws IOException

      Returns the number of resolutions available in the image.

      • For conventional formats, this is 1.
      • For pyramidal TIFF, this is the number of embedded images, equal to getNumImages().
      • For JPEG2000, it is (number of decomposition) levels + 1.
      Returns:
      Number of resolutions available in the image.
      Throws:
      NoSuchFileException - if the source file does not exist.
      SourceFormatException - if the image format is not supported.
      IOException - if there is some other error reading the number of resolutions.

    • getNumThumbnails

      default int getNumThumbnails(int imageIndex) throws IOException
      The default implementation returns 0.
      Returns:
      Number of thumbnail images available for the image at the given index. (See class documentation.)
      Throws:
      IndexOutOfBoundsException - if the given index is out of bounds.
      NoSuchFileException - if the source file does not exist.
      SourceFormatException - if the image format is not supported.
      IOException - if there is some other error reading the number of thumbnails.

    • getSize

      Size getSize(int imageIndex) throws IOException
      Parameters:
      imageIndex - See the class documentation..
      Returns:
      Dimensions of the image at the given index.
      Throws:
      IndexOutOfBoundsException - if the given index is out of bounds.
      NoSuchFileException - if the source file does not exist.
      SourceFormatException - if the image format is not supported.
      IOException - if there is an error reading the size.

    • getSupportedFormats

      Set<Format> getSupportedFormats()
      Returns:
      All formats supported by the implementation. The instances must be created from scratch and not obtained from the format registry, which may be empty at the time this method is invoked.

    • getThumbnailSize

      default Size getThumbnailSize(int imageIndex, int thumbnailIndex) throws IOException

      The default implementation throws an UnsupportedOperationException.

      Parameters:
      imageIndex - See the class documentation..
      thumbnailIndex - Value between 0 and getNumThumbnails(int) - 1.
      Returns:
      Dimensions of the thumbnail image at the given index.
      Throws:
      UnsupportedOperationException - if the implementation does not support thumbnails.
      IndexOutOfBoundsException - if either of the given indices are out of bounds.
      NoSuchFileException - if the source file does not exist.
      SourceFormatException - if the image format is not supported.
      IOException - if there is an error reading the size.

    • getTileSize

      Size getTileSize(int imageIndex) throws IOException
      Parameters:
      imageIndex - See the class documentation.
      Returns:
      Size of the tiles in the image at the given index, or the full image dimensions if the image is not tiled.
      Throws:
      IndexOutOfBoundsException - if the given index is out of bounds.
      NoSuchFileException - if the source file does not exist.
      SourceFormatException - if the image format is not supported.
      IOException - if there is some other error reading the size.

    • decode

      default BufferedImage decode(int imageIndex) throws IOException

      Decodes an entire image into memory.

      This implementation wraps decode(int, Region, double[], ReductionFactor, double[], Set).

      Throws:
      IOException

    • decode

      BufferedImage decode(int imageIndex, Region region, double[] scales, ReductionFactor reductionFactor, double[] diffScales, Set<DecoderHint> decoderHints) throws IOException

      Decodes the region of the image corresponding to the given arguments. The image has ≤ 8-bit RGB(A) color.

      For image formats that support an embedded TIFF/EXIF orientation, implementations must reorient any related arguments (in particular, region). However, they need not rotate the resulting image. If they are able to efficiently render an oriented image without rotating in a later step, they should add DecoderHint.ALREADY_ORIENTED to the decoderHints.

      Implementations are encouraged to return an instance whose Raster is backed by a DataBufferByte. (This is the case for the standard BufferedImage types BufferedImage.TYPE_4BYTE_ABGR, BufferedImage.TYPE_3BYTE_BGR, and BufferedImage.TYPE_BYTE_GRAY. Also, Java2DUtils.newImage(int, int, byte[], ComponentOrder) can be used to create such an instance.) This will enable more efficient copying to/from native memory (if necessary).

      Parameters:
      imageIndex - See the class documentation. Also note that for pyramidal images, this is not used to choose a pyramid level. Instead, the scales argument is.
      region -

      Region to read relative to the full-sized oriented source image. Region.oriented(Size, Orientation) can be used to translate this to physical source image coordinates.

      If the region exceeds the image bounds, it is silently clipped to the image bounds.

      If an implementation is not able to utilize this argument efficiently, it should add DecoderHint.IGNORED_REGION to the decoderHints.

      scales -

      Two-element array of X and Y axis scales. Never null. Applied after crop.

      If an implementation is not able to utilize this argument efficiently, it should add DecoderHint.IGNORED_SCALE to the decoderHints.

      reductionFactor - The ReductionFactor.factor property will be modified to reflect the reduction factor of the returned image, i.e. the number of times its dimensions have been halved relative to the full-sized image when a ≤ 0.5 scale has been requested.
      diffScales -

      Two-element array that will be populated with the X and Y axis differential scales computed during reading.

      Differential scales here are scales relative to the reduced image (see reductionFactor). For example, if a client has requested a scale of 45%, and the implementation is reading an image at a reduction factor of 1 (50%), the differential scale is the amount that the returned image will need to be downscaled further, e.g. 0.45 / 0.5.

      Implementations that don't support reading at arbitrary scales (probably most of them) should simply set these two elements to 1.

      decoderHints - Hints provided to and/or returned from the method.
      Throws:
      IndexOutOfBoundsException - if the given index is out of bounds.
      NoSuchFileException - if the source file does not exist.
      SourceFormatException - if the image format is not supported.
      IOException - if there is some other error reading the image.

    • decodeSequence

      default BufferedImageSequence decodeSequence() throws IOException

      Decodes a sequence of images into memory

      This method is meant to support short animations (e.g. animated GIF). It is not meant to support video formats, which could fill up all available memory and then some. These should simply throw an UnsupportedOperationException, which is what this default implementation does.

      Throws:
      UnsupportedOperationException - if the implementation does not support sequences.
      NoSuchFileException - if the source file does not exist.
      SourceFormatException - if the image format is not supported.
      IOException - if there is some other error reading the sequence.

    • readMetadata

      Metadata readMetadata(int imageIndex) throws IOException
      Reads metadata pertaining to the image at the given index.
      Returns:
      Metadata for the image at the given index. If there is none, an EmptyMetadata can be returned.
      Throws:
      IndexOutOfBoundsException - if the given index is out of bounds.
      NoSuchFileException - if the source file does not exist.
      SourceFormatException - if the image format is not supported.
      IOException - if there is some other error reading the metadata.

    • readThumbnail

      default BufferedImage readThumbnail(int imageIndex, int thumbnailIndex) throws IOException

      Reads a thumbnail image into memory.

      Implementations are encouraged to return an instance whose Raster is backed by a DataBufferByte. See the documentation of decode(int, Region, double[], ReductionFactor, double[], Set) for more information.

      The default implementation throws an UnsupportedOperationException.

      Parameters:
      imageIndex - See the class documentation.
      thumbnailIndex - Value between 0 and getNumThumbnails(int) - 1.
      Throws:
      UnsupportedOperationException - if the implementation does not support thumbnails.
      IndexOutOfBoundsException - if either of the given indices are out of bounds.
      NoSuchFileException - if the source file does not exist.
      SourceFormatException - if the image format is not supported.
      IOException - if there is some other error reading the image.

    • close

      void close()
      Releases all resources when an instance is no longer needed, but does not close the stream supplied to setSource(ImageInputStream).
      Specified by:
      close in interface AutoCloseable