Package ca.cgjennings.imageio

Class SimpleImageWriter

  • public class SimpleImageWriter
extends java.lang.Object
    A simple image writer writes images to output streams and files. It provides a simplified mechanism for configuring basic format, compression, and metadata options compared to the imageio library.

    Note:
    it is important to dispose() of instances of this class when finished with them, as many of the underlying image encoders consume significant native resources.

    Since:
    1.0
    Author:
    Chris Jennings

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String FORMAT_BMP
      Format identifier for BMP images.
      static java.lang.String FORMAT_GIF
      Format identifier for GIF89a images.
      static java.lang.String FORMAT_JPEG
      Format identifier for JPEG images.
      static java.lang.String FORMAT_JPEG2000
      Format identifier for JPEG2000 part 1 images.
      static java.lang.String FORMAT_PNG
      Format identifier for PNG images.

    • Constructor Summary

      Constructors 
      Constructor Description
      SimpleImageWriter()
      Creates an image writer for the PNG format using the default locale.
      SimpleImageWriter​(java.lang.String fileFormat)
      Creates an image writer for the requested format using the default locale.
      SimpleImageWriter​(java.lang.String fileFormat, java.util.Locale locale)
      Create a SimpleImageWriter that will produce images in the format specified by fileFormat.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      void dispose()
      Causes resources used by this writer to be released, including native resources.
      protected void finalize()
      Deprecated.
      java.lang.String getComment()
      Return the comment to be embedded in files written by this writer, if possible.
      float getCompressionQuality()
      Returns the current compression quality.
      java.lang.String[] getCompressionQualityDescriptions()
      Return an array of locale-dependent descriptions of the available compression quality settings.
      java.lang.String[] getCompressionTypes()
      Returns an array of the supported compression methods.
      float[] getCompressionValues()
      Return an array of quality values indicating the ranges of compression qualities covered by the strings returned by getCompressionValues().
      java.lang.String getFormat()
      Get the name of the file format this instance will write files in.
      static WritableImageFormat[] getImageFormats()
      Returns an array of registered image formats.
      float getPixelsPerInch()
      Return the resolution to be written with images, in pixels per inch.
      float getPixelsPerMillimetre()
      Return the resolution to be written with images, in pixels per mm.
      boolean isCompressionEnabled()
      Returns true if compression is enabled.
      boolean isCompressionOptional()
      Returns true if disabling compression has any effect.
      boolean isCompressionSupported()
      Returns true if one or more compression methods are supported.
      boolean isLossless()
      Return true if the format's compression method is lossless.
      boolean isMetadataEnabled()
      Returns true if comment and resolution metadata will be written to output files.
      boolean isProgressiveScan()
      Returns true if progressive encoding is enabled.
      boolean isProgressiveScanConfigurable()
      Returns true if the progressive scan setting can be changed.
      boolean isTransparencySupported()
      Returns true if the file format for this writer supports transparency or not.
      static void registerImageFormat​(WritableImageFormat wif)
      Registers a new image format supported for use with SimpleImageWriter.
      void setComment​(java.lang.String comment)
      Set the comment text that will be written along with files created by this writer.
      void setComment​(java.lang.String comment, java.util.Locale commentLocale)
      Set the comment text that will be written along with files created by this writer.
      void setCompressionEnabled​(boolean enable)
      Sets whether compression is enabled.
      void setCompressionQuality​(float quality)
      Control the compression quality during image writing.
      void setCompressionQuality​(java.lang.String description)
      Set image compression according to one of the strings returned by getCompressionQualityDescriptions().
      void setCompressionType​(java.lang.String type)
      Sets the compression type to use.
      void setEncodingHint​(java.lang.Object key, java.lang.Object value)
      Sets an internal encoding hint.
      void setMetadataEnabled​(boolean enable)
      Sets whether comment and resolution metadata should be written to output files, if supported by the writer and image format.
      void setPixelsPerInch​(float ppi)
      Set the pixels-per-inch resolution that will be written with the file's metadata, if possible.
      void setPixelsPerMillimetre​(float ppmm)
      Set image resolution that will be written with the file's metadata, if possible.
      void setProgressiveScan​(boolean useProgressiveScanIfPossible)
      Sets whether the writer should use progressive encoding, if possible.
      java.lang.String toString()  
      static void unregisterImageFormat​(WritableImageFormat wif)
      Unregisters a previously registered image format.
      void write​(java.awt.Image image, java.io.File output)
      Writes the image im to a file, creating the intermediate stream and closing it on completion.
      void write​(java.awt.Image image, java.io.OutputStream out)
      Writes the image im to an output stream.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • FORMAT_PNG

        public static final java.lang.String FORMAT_PNG
        Format identifier for PNG images.
        See Also:
        Constant Field Values

      • FORMAT_JPEG

        public static final java.lang.String FORMAT_JPEG
        Format identifier for JPEG images.
        See Also:
        Constant Field Values

      • FORMAT_JPEG2000

        public static final java.lang.String FORMAT_JPEG2000
        Format identifier for JPEG2000 part 1 images.
        See Also:
        Constant Field Values

      • FORMAT_GIF

        public static final java.lang.String FORMAT_GIF
        Format identifier for GIF89a images.
        See Also:
        Constant Field Values

      • FORMAT_BMP

        public static final java.lang.String FORMAT_BMP
        Format identifier for BMP images.
        See Also:
        Constant Field Values

    • Constructor Detail

      • SimpleImageWriter

        public SimpleImageWriter​(java.lang.String fileFormat)
        Creates an image writer for the requested format using the default locale.
        Parameters:
        fileFormat - the file extension or name of a supported file format
        Throws:
        java.lang.UnsupportedOperationException - if fileFormat is not a known type.
        See Also:
        SimpleImageWriter(java.lang.String, java.util.Locale)

      • SimpleImageWriter

        public SimpleImageWriter​(java.lang.String fileFormat,
                         java.util.Locale locale)
        Create a SimpleImageWriter that will produce images in the format specified by fileFormat. The fileFormat parameter must either be the name or file extension of a format registered with the imageio library.
        Parameters:
        fileFormat - name of file format to be produced by this writer
        locale - the preferred locale for labels and messages
        Throws:
        java.lang.UnsupportedOperationException - if fileFormat is not a known type.

    • Method Detail

      • getFormat

        public java.lang.String getFormat()
        Get the name of the file format this instance will write files in.
        Returns:
        the file format specified at construction

      • isTransparencySupported

        public boolean isTransparencySupported()
        Returns true if the file format for this writer supports transparency or not.
        Returns:
        true if transparency is supported

      • isCompressionSupported

        public boolean isCompressionSupported()
        Returns true if one or more compression methods are supported.
        Returns:
        true if compression is supported

      • isCompressionOptional

        public boolean isCompressionOptional()
        Returns true if disabling compression has any effect.
        Returns:
        true if compression can be disabled

      • setCompressionEnabled

        public void setCompressionEnabled​(boolean enable)
        Sets whether compression is enabled. If the compression setting cannot be changed, this will have no effect.
        Parameters:
        enable - whether to enable compression

      • isCompressionEnabled

        public boolean isCompressionEnabled()
        Returns true if compression is enabled.
        Returns:
        whether compression is enabled

      • getCompressionTypes

        public java.lang.String[] getCompressionTypes()
        Returns an array of the supported compression methods. Most formats support at most one compression method.
        Returns:
        an array of supported compression methods, or null

      • setCompressionType

        public void setCompressionType​(java.lang.String type)
        Sets the compression type to use. If the type is null, a default type is selected. Otherwise, the type must be one of the types specified by getCompressionTypes(). Changing the compression type may alter the quality descriptions and values.
        Parameters:
        type - the name of the compression type to use

      • getCompressionQualityDescriptions

        public java.lang.String[] getCompressionQualityDescriptions()
        Return an array of locale-dependent descriptions of the available compression quality settings. This method may return null, and must return null if getCompressionValues() does.
        Returns:
        an array of description Strings, or null if there are descriptions available
        See Also:
        getCompressionValues()

      • getCompressionValues

        public float[] getCompressionValues()
        Return an array of quality values indicating the ranges of compression qualities covered by the strings returned by getCompressionValues(). The quality setting getCompressionQualities()[i] covers all compression settings from getCompressionValues()[i], inclusive, to getCompressionValues()[i+1], exclusive. The only exception is for i == getCompressionQualities().length - 1, which includes the final value in the range.
        Returns:
        an array of description Strings, or null if there are descriptions available

      • isLossless

        public boolean isLossless()
        Return true if the format's compression method is lossless. A lossless format does not degrade in quality when written.
        Returns:
        true if the selected format does not lose information

      • setCompressionQuality

        public void setCompressionQuality​(java.lang.String description)
        Set image compression according to one of the strings returned by getCompressionQualityDescriptions(). The compression level will be set to the midpoint of the the description's value range.
        Parameters:
        description - the quality description string matching the desired quality level
        Throws:
        java.lang.IllegalArgumentException - if description is not a valid quality description
        See Also:
        getCompressionQualityDescriptions(), setCompressionQuality(float)

      • setCompressionQuality

        public void setCompressionQuality​(float quality)
        Control the compression quality during image writing. If quality is between 0 and 1 (inclusive), then a relative quality is requested, with a value of 0 emphasizing maximum compression and a value of 1 requesting maximum image quality. (If the format is lossless, then image quality is not affected.) If quality is less than 0, then a default compression level will be selected.
        Parameters:
        quality - the relative quality (0-1), or a negative value to request default compression

      • getCompressionQuality

        public float getCompressionQuality()
        Returns the current compression quality.
        Returns:
        the compression quality level, from 0 to 1

      • setProgressiveScan

        public void setProgressiveScan​(boolean useProgressiveScanIfPossible)
        Sets whether the writer should use progressive encoding, if possible. Progressive scan images can be displayed in multiple passes of increasing quality.
        Parameters:
        useProgressiveScanIfPossible - if true, the writer will write images in progressive scans if the format supports it

      • isProgressiveScan

        public boolean isProgressiveScan()
        Returns true if progressive encoding is enabled.
        Returns:
        true is progressive scan is enabled

      • isProgressiveScanConfigurable

        public boolean isProgressiveScanConfigurable()
        Returns true if the progressive scan setting can be changed. Some formats do not support progressive scans, while other formats support it inherently.
        Returns:
        true if the progressive scan setting is alterable

      • setPixelsPerInch

        public void setPixelsPerInch​(float ppi)
        Set the pixels-per-inch resolution that will be written with the file's metadata, if possible. The default resolution is 72 pixels per inch.
        Parameters:
        ppi - the image resolution, in pixels per inch

      • getPixelsPerInch

        public float getPixelsPerInch()
        Return the resolution to be written with images, in pixels per inch.
        Returns:
        the image resolution, in pixels per inch

      • setPixelsPerMillimetre

        public void setPixelsPerMillimetre​(float ppmm)
        Set image resolution that will be written with the file's metadata, if possible. The resolution is specified in pixels per millimetre. As a convenience, setPixelsPerInch(float) is also provided.

        The default resolution is 72 pixels per inch (approximately 2.8 pixels per mm). Images written with the writer will specify a horizontal and vertical resolution as close to this value as the file format allows.

        Parameters:
        ppmm - the intended image resolution, in pixels per mm
        See Also:
        setPixelsPerInch(float)

      • getPixelsPerMillimetre

        public float getPixelsPerMillimetre()
        Return the resolution to be written with images, in pixels per mm. As a convenience, getPixelsPerInch() is also provided. Images written with the writer will specify a horizontal and vertical resolution as close to this value as the file format allows.
        Returns:
        the current image resolution to use for writing, pixels per mm
        See Also:
        getPixelsPerInch()

      • setComment

        public void setComment​(java.lang.String comment)
        Set the comment text that will be written along with files created by this writer. If comment is null, the current comment is cleared. The comment will be assumed to be written in the language specified by this writer's locale.
        Parameters:
        comment - the comment text to be included in the file's metadata.

      • setComment

        public void setComment​(java.lang.String comment,
                       java.util.Locale commentLocale)
        Set the comment text that will be written along with files created by this writer. If comment is null, the current comment (if any) is cleared.
        Parameters:
        comment - the comment text to be included in the file's metadata.
        commentLocale - a locale describing the language the comment is written in

      • getComment

        public java.lang.String getComment()
        Return the comment to be embedded in files written by this writer, if possible. If no comment has been set, returns null.
        Returns:
        the currently set comment, or null if there is no comment

      • isMetadataEnabled

        public boolean isMetadataEnabled()
        Returns true if comment and resolution metadata will be written to output files. Metadata writing may not be supported for all file types.
        Returns:
        if metadata writing is enabled

      • setMetadataEnabled

        public void setMetadataEnabled​(boolean enable)
        Sets whether comment and resolution metadata should be written to output files, if supported by the writer and image format.
        Parameters:
        enable - if true, metadata will be written if supported

      • write

        public void write​(java.awt.Image image,
                  java.io.File output)
           throws java.io.IOException
        Writes the image im to a file, creating the intermediate stream and closing it on completion. If the file exists, it will be overwritten.
        Parameters:
        image - an Image to be written
        output - the File which contains the destination file to be written
        Throws:
        java.io.IOException - if I/O errors occur during the write operation

      • write

        public void write​(java.awt.Image image,
                  java.io.OutputStream out)
           throws java.io.IOException
        Writes the image im to an output stream. The stream is left open after writing.
        Parameters:
        image - the Image to be written
        out - the OutputStream to writeBufferedImage to
        Throws:
        java.io.IOException - if I/O errors occur during the write operation

      • dispose

        public void dispose()
        Causes resources used by this writer to be released, including native resources. The result of calling any method of this writer after calling dispose() is undefined (although the typical result would be a NullPointerException).

      • finalize

        @Deprecated
protected void finalize()
                 throws java.lang.Throwable
        Deprecated.
        Overrides:
        finalize in class java.lang.Object
        Throws:
        java.lang.Throwable

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • setEncodingHint

        public void setEncodingHint​(java.lang.Object key,
                            java.lang.Object value)
        Sets an internal encoding hint. These hints are typically used to work around bugs with specific image format encoders.
        Parameters:
        key - the hint key
        value - the hint value

      • registerImageFormat

        public static void registerImageFormat​(WritableImageFormat wif)
        Registers a new image format supported for use with SimpleImageWriter.
        Parameters:
        wif - a descriptor for the image format
        Throws:
        java.lang.NullPointerException - if the format is null

      • unregisterImageFormat

        public static void unregisterImageFormat​(WritableImageFormat wif)
        Unregisters a previously registered image format.
        Parameters:
        wif - the format to remove

      • getImageFormats

        public static WritableImageFormat[] getImageFormats()
        Returns an array of registered image formats.
        Returns:
        a new array of the supported image formats