Package org.apache.commons.imaging

Class Imaging

  • public final class Imaging
extends java.lang.Object
    The primary application programming interface (API) to the Imaging library.

    Application Notes

    Using this class

    Almost all of the Apache Commons Imaging library's core functionality can be accessed through the methods provided by this class. The use of the Imaging class is similar to the Java API's ImageIO class, though Imaging supports formats not included in the standard Java API.

    All of methods provided by the Imaging class are declared static.

    The Apache Commons Imaging package is a pure Java implementation.

    Format support

    While the Apache Commons Imaging package handles a number of different graphics formats, support for some formats is not yet complete. For the most recent information on support for specific formats, refer to Format Support at the main project development web site.

    Optional parameters for image reading and writing

    Many of the operations provided in this class as static calls can be accessed directly using format-specific AbstractImageParser instances. These static methods are provided for convenience in simple use cases.

    Example code

    See the source of the SampleUsage class and other classes in the org.apache.commons.imaging.examples package for examples.

    See Also:
    org.apache.commons.imaging.examples.SampleUsage, Format Support

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private Imaging()  

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      private static boolean compareBytePair​(int[] a, int[] b)  
      static java.lang.String dumpImageFile​(byte[] bytes)
      Writes the ImageInfo and format-specific information for the image content of the specified byte array to a string.
      static java.lang.String dumpImageFile​(java.io.File file)
      Writes the ImageInfo and format-specific information for the image content of the specified file to a string.
      private static java.lang.String dumpImageFile​(ByteSource byteSource)  
      static java.util.List<java.awt.image.BufferedImage> getAllBufferedImages​(byte[] bytes)
      Gets all images specified by the byte array (some formats may include multiple images within a single data source).
      static java.util.List<java.awt.image.BufferedImage> getAllBufferedImages​(java.io.File file)
      Gets all images specified by the file (some formats may include multiple images within a single data source).
      static java.util.List<java.awt.image.BufferedImage> getAllBufferedImages​(java.io.InputStream is, java.lang.String fileName)
      Gets all images specified by the InputStream (some formats may include multiple images within a single data source).
      private static java.util.List<java.awt.image.BufferedImage> getAllBufferedImages​(ByteSource byteSource)  
      static java.awt.image.BufferedImage getBufferedImage​(byte[] bytes)
      Reads the first image from a byte array.
      static java.awt.image.BufferedImage getBufferedImage​(java.io.File file)
      Reads the first image from a file.
      static java.awt.image.BufferedImage getBufferedImage​(java.io.InputStream is)
      Reads the first image from an InputStream.
      static java.awt.image.BufferedImage getBufferedImage​(java.io.InputStream is, java.lang.String fileName)
      Reads the first image from an InputStream.
      private static java.awt.image.BufferedImage getBufferedImage​(ByteSource byteSource)  
      static FormatCompliance getFormatCompliance​(byte[] bytes)
      Attempts to determine the image format of the specified data and evaluates its format compliance.
      static FormatCompliance getFormatCompliance​(java.io.File file)
      Attempts to determine the image format of the specified data and evaluates its format compliance.
      private static FormatCompliance getFormatCompliance​(ByteSource byteSource)  
      static java.awt.color.ICC_Profile getIccProfile​(byte[] bytes)
      Extracts an ICC Profile (if present) from JPEG, PNG, PSD (Photoshop) and TIFF images.
      static java.awt.color.ICC_Profile getIccProfile​(java.io.File file)
      Extracts an ICC Profile (if present) from JPEG, PNG, PSD (Photoshop) and TIFF images.
      static java.awt.color.ICC_Profile getIccProfile​(java.io.InputStream is, java.lang.String fileName)
      Extracts an ICC Profile (if present) from JPEG, PNG, PSD (Photoshop) and TIFF images.
      protected static java.awt.color.ICC_Profile getIccProfile​(ByteSource byteSource)  
      static byte[] getIccProfileBytes​(byte[] bytes)
      Extracts the raw bytes of an ICC Profile (if present) from JPEG, PNG, PSD (Photoshop) and TIFF images.
      static byte[] getIccProfileBytes​(java.io.File file)
      Extracts the raw bytes of an ICC Profile (if present) from JPEG, PNG, PSD (Photoshop) and TIFF images.
      private static byte[] getIccProfileBytes​(ByteSource byteSource)  
      static ImageInfo getImageInfo​(byte[] bytes)
      Parses the "image info" of an image.
      static ImageInfo getImageInfo​(java.io.File file)
      Parses the "image info" of an image file.
      static ImageInfo getImageInfo​(java.io.InputStream is, java.lang.String fileName)
      Parses the "image info" of an image.
      static ImageInfo getImageInfo​(java.lang.String fileName, byte[] bytes)
      Parses the "image info" of an image.
      private static ImageInfo getImageInfo​(ByteSource byteSource)  
      static java.awt.Dimension getImageSize​(byte[] bytes)
      Determines the width and height of an image.
      static java.awt.Dimension getImageSize​(java.io.File file)
      Determines the width and height of an image file.
      static java.awt.Dimension getImageSize​(java.io.InputStream is, java.lang.String fileName)
      Determines the width and height of an image.
      static java.awt.Dimension getImageSize​(ByteSource byteSource)
      Determines the width and height of an image byte source.
      static ImageMetadata getMetadata​(byte[] bytes)
      Parses the metadata of an image.
      static ImageMetadata getMetadata​(java.io.File file)
      Parses the metadata of an image file.
      static ImageMetadata getMetadata​(java.io.InputStream is, java.lang.String fileName)
      Parses the metadata of an image file.
      private static ImageMetadata getMetadata​(ByteSource byteSource)  
      static java.lang.String getXmpXml​(byte[] bytes)
      Extracts the embedded XML metadata as an XML string.
      static java.lang.String getXmpXml​(java.io.File file)
      Extracts the embedded XML metadata as an XML string.
      static java.lang.String getXmpXml​(java.io.InputStream is, java.lang.String fileName)
      Extracts the embedded XML metadata as an XML string.
      static java.lang.String getXmpXml​(ByteSource byteSource)
      Extracts the embedded XML metadata as an XML string.
      static ImageFormat guessFormat​(byte[] bytes)
      Attempts to determine the image format of a file based on its "magic numbers," the first bytes of the data.
      static ImageFormat guessFormat​(java.io.File file)
      Attempts to determine the image format of a file based on its "magic numbers," the first bytes of the data.
      static ImageFormat guessFormat​(ByteSource byteSource)
      Attempts to determine the image format of a file based on its "magic numbers," the first bytes of the data.
      static boolean hasImageFileExtension​(java.io.File file)
      Attempts to determine if a file contains an image recorded in a supported graphics format based on its file-name extension (for example ".jpg", ".gif", ".png", etc.).
      static boolean hasImageFileExtension​(java.lang.String fileName)
      Attempts to determine if a file contains an image recorded in a supported graphics format based on its file-name extension (for example ".jpg", ".gif", ".png", etc.).
      static void writeImage​(java.awt.image.BufferedImage src, java.io.File file, ImageFormat format)
      Writes the content of a BufferedImage to a file using the specified image format.
      static void writeImage​(java.awt.image.BufferedImage src, java.io.OutputStream outputStream, ImageFormat format)
      Writes the content of a BufferedImage to an OutputStream using the specified image format.
      static byte[] writeImageToBytes​(java.awt.image.BufferedImage src, ImageFormat format)
      Writes the content of a BufferedImage to a byte array using the specified image format.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • MAGIC_NUMBERS_GIF

        private static final int[] MAGIC_NUMBERS_GIF

      • MAGIC_NUMBERS_PNG

        private static final int[] MAGIC_NUMBERS_PNG

      • MAGIC_NUMBERS_JPEG

        private static final int[] MAGIC_NUMBERS_JPEG

      • MAGIC_NUMBERS_BMP

        private static final int[] MAGIC_NUMBERS_BMP

      • MAGIC_NUMBERS_TIFF_MOTOROLA

        private static final int[] MAGIC_NUMBERS_TIFF_MOTOROLA

      • MAGIC_NUMBERS_TIFF_INTEL

        private static final int[] MAGIC_NUMBERS_TIFF_INTEL

      • MAGIC_NUMBERS_PAM

        private static final int[] MAGIC_NUMBERS_PAM

      • MAGIC_NUMBERS_PSD

        private static final int[] MAGIC_NUMBERS_PSD

      • MAGIC_NUMBERS_PBM_A

        private static final int[] MAGIC_NUMBERS_PBM_A

      • MAGIC_NUMBERS_PBM_B

        private static final int[] MAGIC_NUMBERS_PBM_B

      • MAGIC_NUMBERS_PGM_A

        private static final int[] MAGIC_NUMBERS_PGM_A

      • MAGIC_NUMBERS_PGM_B

        private static final int[] MAGIC_NUMBERS_PGM_B

      • MAGIC_NUMBERS_PPM_A

        private static final int[] MAGIC_NUMBERS_PPM_A

      • MAGIC_NUMBERS_PPM_B

        private static final int[] MAGIC_NUMBERS_PPM_B

      • MAGIC_NUMBERS_JBIG2_1

        private static final int[] MAGIC_NUMBERS_JBIG2_1

      • MAGIC_NUMBERS_JBIG2_2

        private static final int[] MAGIC_NUMBERS_JBIG2_2

      • MAGIC_NUMBERS_ICNS

        private static final int[] MAGIC_NUMBERS_ICNS

      • MAGIC_NUMBERS_DCX

        private static final int[] MAGIC_NUMBERS_DCX

      • MAGIC_NUMBERS_RGBE

        private static final int[] MAGIC_NUMBERS_RGBE

      • MAGIC_NUMBERS_RIFF_1

        private static final int[] MAGIC_NUMBERS_RIFF_1

      • MAGIC_NUMBERS_RIFF_2

        private static final int[] MAGIC_NUMBERS_RIFF_2

      • MAGIC_NUMBERS_WEBP

        private static final byte[] MAGIC_NUMBERS_WEBP

    • Constructor Detail

      • Imaging

        private Imaging()

    • Method Detail

      • compareBytePair

        private static boolean compareBytePair​(int[] a,
                                       int[] b)

      • dumpImageFile

        public static java.lang.String dumpImageFile​(byte[] bytes)
                                      throws ImagingException,
                                             java.io.IOException
        Writes the ImageInfo and format-specific information for the image content of the specified byte array to a string.
        Parameters:
        bytes - A valid array of bytes.
        Returns:
        A valid string.
        Throws:
        ImagingException - In the event that the specified content does not conform to the format of the specific parser implementation.
        java.io.IOException - In the event of unsuccessful read or access operation.

      • dumpImageFile

        public static java.lang.String dumpImageFile​(java.io.File file)
                                      throws ImagingException,
                                             java.io.IOException
        Writes the ImageInfo and format-specific information for the image content of the specified file to a string.
        Parameters:
        file - A valid file reference.
        Returns:
        A valid string.
        Throws:
        ImagingException - In the event that the specified content does not conform to the format of the specific parser implementation.
        java.io.IOException - In the event of unsuccessful read or access operation.

      • getAllBufferedImages

        public static java.util.List<java.awt.image.BufferedImage> getAllBufferedImages​(byte[] bytes)
                                                                         throws ImagingException,
                                                                                java.io.IOException
        Gets all images specified by the byte array (some formats may include multiple images within a single data source).
        Parameters:
        bytes - a valid array of bytes
        Returns:
        A valid (potentially empty) list of BufferedImage objects.
        Throws:
        ImagingException - In the event that the specified content does not conform to the format of the specific parser implementation.
        java.io.IOException - In the event of unsuccessful read or access operation.

      • getAllBufferedImages

        private static java.util.List<java.awt.image.BufferedImage> getAllBufferedImages​(ByteSource byteSource)
                                                                          throws ImagingException,
                                                                                 java.io.IOException
        Throws:
        ImagingException
        java.io.IOException

      • getAllBufferedImages

        public static java.util.List<java.awt.image.BufferedImage> getAllBufferedImages​(java.io.File file)
                                                                         throws ImagingException,
                                                                                java.io.IOException
        Gets all images specified by the file (some formats may include multiple images within a single data source).
        Parameters:
        file - A reference to a valid data file.
        Returns:
        A valid (potentially empty) list of BufferedImage objects.
        Throws:
        ImagingException - In the event that the specified content does not conform to the format of the specific parser implementation.
        java.io.IOException - In the event of unsuccessful read or access operation.

      • getAllBufferedImages

        public static java.util.List<java.awt.image.BufferedImage> getAllBufferedImages​(java.io.InputStream is,
                                                                                java.lang.String fileName)
                                                                         throws ImagingException,
                                                                                java.io.IOException
        Gets all images specified by the InputStream (some formats may include multiple images within a single data source).
        Parameters:
        is - A valid InputStream
        fileName - File name associated with image data (optional).
        Returns:
        A valid (potentially empty) list of BufferedImage objects.
        Throws:
        ImagingException - In the event that the specified content does not conform to the format of the specific parser implementation.
        java.io.IOException - In the event of unsuccessful read or access operation.

      • getBufferedImage

        public static java.awt.image.BufferedImage getBufferedImage​(byte[] bytes)
                                                     throws ImagingException,
                                                            java.io.IOException
        Reads the first image from a byte array.

        For the most recent information on support for specific formats, refer to Format Support at the main project development web site. While the Apache Commons Imaging package does not fully support all formats, it can read image info, metadata and ICC profiles from all image formats that provide this data.

        Parameters:
        bytes - a valid array of bytes from which to read data.
        Returns:
        if successful, a valid buffered image
        Throws:
        ImagingException - in the event of a processing error while reading an image (i.e. a format violation, etc.).
        java.io.IOException - in the event of an unrecoverable I/O exception.

      • getBufferedImage

        public static java.awt.image.BufferedImage getBufferedImage​(java.io.File file)
                                                     throws ImagingException,
                                                            java.io.IOException
        Reads the first image from a file.

        For the most recent information on support for specific formats, refer to Format Support at the main project development web site. While the Apache Commons Imaging package does not fully support all formats, it can read image info, metadata and ICC profiles from all image formats that provide this data.

        Parameters:
        file - a valid reference to a file containing image data.
        Returns:
        if successful, a valid buffered image
        Throws:
        ImagingException - in the event of a processing error while reading an image (i.e. a format violation, etc.).
        java.io.IOException - in the event of an unrecoverable I/O exception.

      • getBufferedImage

        public static java.awt.image.BufferedImage getBufferedImage​(java.io.InputStream is)
                                                     throws ImagingException,
                                                            java.io.IOException
        Reads the first image from an InputStream.

        For the most recent information on support for specific formats, refer to Format Support at the main project development web site. While the Apache Commons Imaging package does not fully support all formats, it can read image info, metadata and ICC profiles from all image formats that provide this data.

        Parameters:
        is - a valid ImageStream from which to read data.
        Returns:
        if successful, a valid buffered image
        Throws:
        ImagingException - in the event of a processing errorfileName while reading an image (i.e. a format violation, etc.).
        java.io.IOException - in the event of an unrecoverable I/O exception.

      • getBufferedImage

        public static java.awt.image.BufferedImage getBufferedImage​(java.io.InputStream is,
                                                            java.lang.String fileName)
                                                     throws ImagingException,
                                                            java.io.IOException
        Reads the first image from an InputStream.

        For the most recent information on support for specific formats, refer to Format Support at the main project development web site. While the Apache Commons Imaging package does not fully support all formats, it can read image info, metadata and ICC profiles from all image formats that provide this data.

        Parameters:
        is - a valid ImageStream from which to read data.
        fileName - the image file name.
        Returns:
        if successful, a valid buffered image
        Throws:
        ImagingException - in the event of a processing error while reading an image (i.e. a format violation, etc.).
        java.io.IOException - in the event of an unrecoverable I/O exception.

      • getFormatCompliance

        public static FormatCompliance getFormatCompliance​(byte[] bytes)
                                            throws ImagingException,
                                                   java.io.IOException
        Attempts to determine the image format of the specified data and evaluates its format compliance.

        This method returns a FormatCompliance object which includes information about the data's compliance to a specific format.

        Parameters:
        bytes - a valid array of bytes containing image data.
        Returns:
        if successful, a valid FormatCompliance object.
        Throws:
        ImagingException - in the event of unreadable data.
        java.io.IOException - in the event of an unrecoverable I/O condition.

      • getFormatCompliance

        public static FormatCompliance getFormatCompliance​(java.io.File file)
                                            throws ImagingException,
                                                   java.io.IOException
        Attempts to determine the image format of the specified data and evaluates its format compliance. This method returns a FormatCompliance object which includes information about the data's compliance to a specific format.
        Parameters:
        file - valid file containing image data
        Returns:
        if successful, a valid FormatCompliance object.
        Throws:
        ImagingException - in the event of unreadable data.
        java.io.IOException - in the event of an unrecoverable I/O condition.

      • getIccProfile

        public static java.awt.color.ICC_Profile getIccProfile​(byte[] bytes)
                                                throws ImagingException,
                                                       java.io.IOException
        Extracts an ICC Profile (if present) from JPEG, PNG, PSD (Photoshop) and TIFF images.
        Parameters:
        bytes - Byte array containing an image file.
        Returns:
        An instance of ICC_Profile or null if the image contains no ICC profile.
        Throws:
        ImagingException - if it fails to parse the image
        java.io.IOException - if it fails to read the image data

      • getIccProfile

        public static java.awt.color.ICC_Profile getIccProfile​(java.io.File file)
                                                throws ImagingException,
                                                       java.io.IOException
        Extracts an ICC Profile (if present) from JPEG, PNG, PSD (Photoshop) and TIFF images.
        Parameters:
        file - File containing image data.
        Returns:
        An instance of ICC_Profile or null if the image contains no ICC profile.
        Throws:
        ImagingException - if it fails to parse the image
        java.io.IOException - if it fails to read the image data

      • getIccProfile

        public static java.awt.color.ICC_Profile getIccProfile​(java.io.InputStream is,
                                                       java.lang.String fileName)
                                                throws ImagingException,
                                                       java.io.IOException
        Extracts an ICC Profile (if present) from JPEG, PNG, PSD (Photoshop) and TIFF images.
        Parameters:
        is - InputStream from which to read image data.
        fileName - File name associated with image data (optional).
        Returns:
        An instance of ICC_Profile or null if the image contains no ICC profile.
        Throws:
        ImagingException - if it fails to parse the image
        java.io.IOException - if it fails to read the image data

      • getIccProfileBytes

        public static byte[] getIccProfileBytes​(byte[] bytes)
                                 throws ImagingException,
                                        java.io.IOException
        Extracts the raw bytes of an ICC Profile (if present) from JPEG, PNG, PSD (Photoshop) and TIFF images.

        To parse the result use IccProfileParser or ICC_Profile.getInstance(bytes).

        Parameters:
        bytes - Byte array containing an image file.
        Returns:
        A byte array.
        Throws:
        ImagingException - if it fails to parse the image
        java.io.IOException - if it fails to read the image data
        See Also:
        IccProfileParser, ICC_Profile

      • getIccProfileBytes

        public static byte[] getIccProfileBytes​(java.io.File file)
                                 throws ImagingException,
                                        java.io.IOException
        Extracts the raw bytes of an ICC Profile (if present) from JPEG, PNG, PSD (Photoshop) and TIFF images.

        To parse the result use IccProfileParser or ICC_Profile.getInstance(bytes).

        Parameters:
        file - File containing image data.
        Returns:
        A byte array.
        Throws:
        ImagingException - if it fails to parse the image
        java.io.IOException - if it fails to read the image data
        See Also:
        IccProfileParser, ICC_Profile

      • getImageInfo

        public static ImageInfo getImageInfo​(byte[] bytes)
                              throws ImagingException,
                                     java.io.IOException
        Parses the "image info" of an image.

        "Image info" is a summary of basic information about the image such as: width, height, file format, bit depth, color type, etc.

        Not to be confused with "image metadata."

        Parameters:
        bytes - Byte array containing an image file.
        Returns:
        An instance of ImageInfo.
        Throws:
        ImagingException - if it fails to parse the image
        java.io.IOException - if it fails to read the image data
        See Also:
        ImageInfo

      • getImageInfo

        public static ImageInfo getImageInfo​(java.io.File file)
                              throws ImagingException,
                                     java.io.IOException
        Parses the "image info" of an image file.

        "Image info" is a summary of basic information about the image such as: width, height, file format, bit depth, color type, etc.

        Not to be confused with "image metadata."

        Parameters:
        file - File containing image data.
        Returns:
        An instance of ImageInfo.
        Throws:
        ImagingException - if it fails to parse the image
        java.io.IOException - if it fails to read the image data
        See Also:
        ImageInfo

      • getImageInfo

        public static ImageInfo getImageInfo​(java.io.InputStream is,
                                     java.lang.String fileName)
                              throws ImagingException,
                                     java.io.IOException
        Parses the "image info" of an image.

        "Image info" is a summary of basic information about the image such as: width, height, file format, bit depth, color type, etc.

        Not to be confused with "image metadata."

        Parameters:
        is - InputStream from which to read image data.
        fileName - File name associated with image data (optional).
        Returns:
        An instance of ImageInfo.
        Throws:
        ImagingException - if it fails to parse the image
        java.io.IOException - if it fails to read the image data
        See Also:
        ImageInfo

      • getImageInfo

        public static ImageInfo getImageInfo​(java.lang.String fileName,
                                     byte[] bytes)
                              throws ImagingException,
                                     java.io.IOException
        Parses the "image info" of an image.

        "Image info" is a summary of basic information about the image such as: width, height, file format, bit depth, color type, etc.

        Not to be confused with "image metadata."

        Parameters:
        fileName - String.
        bytes - Byte array containing an image file.
        Returns:
        An instance of ImageInfo.
        Throws:
        ImagingException - if it fails to parse the image
        java.io.IOException - if it fails to read the image data
        See Also:
        ImageInfo

      • getImageSize

        public static java.awt.Dimension getImageSize​(byte[] bytes)
                                       throws ImagingException,
                                              java.io.IOException
        Determines the width and height of an image.
        Parameters:
        bytes - Byte array containing an image file.
        Returns:
        The width and height of the image.
        Throws:
        ImagingException - if it fails to parse the image
        java.io.IOException - if it fails to read the image data

      • getImageSize

        public static java.awt.Dimension getImageSize​(ByteSource byteSource)
                                       throws ImagingException,
                                              java.io.IOException
        Determines the width and height of an image byte source.
        Parameters:
        byteSource - Byte source data.
        Returns:
        The width and height of the image.
        Throws:
        ImagingException - if it fails to parse the image
        java.io.IOException - if it fails to read the image data

      • getImageSize

        public static java.awt.Dimension getImageSize​(java.io.File file)
                                       throws ImagingException,
                                              java.io.IOException
        Determines the width and height of an image file.
        Parameters:
        file - File containing image data.
        Returns:
        The width and height of the image.
        Throws:
        ImagingException - if it fails to parse the image
        java.io.IOException - if it fails to read the image data

      • getImageSize

        public static java.awt.Dimension getImageSize​(java.io.InputStream is,
                                              java.lang.String fileName)
                                       throws ImagingException,
                                              java.io.IOException
        Determines the width and height of an image.
        Parameters:
        is - InputStream from which to read image data.
        fileName - File name associated with image data (optional).
        Returns:
        The width and height of the image.
        Throws:
        ImagingException - if it fails to parse the image
        java.io.IOException - if it fails to read the image data

      • getMetadata

        public static ImageMetadata getMetadata​(byte[] bytes)
                                 throws ImagingException,
                                        java.io.IOException
        Parses the metadata of an image. This metadata depends on the format of the image.

        JPEG/JFIF files may contain EXIF and/or IPTC metadata. PNG files may contain comments. TIFF files may contain metadata.

        The instance of IImageMetadata returned by getMetadata() should be upcast (depending on image format).

        Not to be confused with "image info."

        Parameters:
        bytes - Byte array containing an image file.
        Returns:
        An instance of ImageMetadata.
        Throws:
        ImagingException - if it fails to read the image metadata
        java.io.IOException - if it fails to read the image data
        See Also:
        ImageMetadata

      • getMetadata

        public static ImageMetadata getMetadata​(java.io.File file)
                                 throws ImagingException,
                                        java.io.IOException
        Parses the metadata of an image file. This metadata depends on the format of the image.

        JPEG/JFIF files may contain EXIF and/or IPTC metadata. PNG files may contain comments. TIFF files may contain metadata.

        The instance of IImageMetadata returned by getMetadata() should be upcast (depending on image format).

        Not to be confused with "image info."

        Parameters:
        file - File containing image data.
        Returns:
        An instance of IImageMetadata.
        Throws:
        ImagingException - if it fails to read the image metadata
        java.io.IOException - if it fails to read the image data
        See Also:
        ImageMetadata

      • getMetadata

        public static ImageMetadata getMetadata​(java.io.InputStream is,
                                        java.lang.String fileName)
                                 throws ImagingException,
                                        java.io.IOException
        Parses the metadata of an image file. This metadata depends on the format of the image.

        JPEG/JFIF files may contain EXIF and/or IPTC metadata. PNG files may contain comments. TIFF files may contain metadata.

        The instance of IImageMetadata returned by getMetadata() should be upcast (depending on image format).

        Not to be confused with "image info."

        Parameters:
        is - InputStream from which to read image data.
        fileName - File name associated with image data (optional).
        Returns:
        An instance of IImageMetadata.
        Throws:
        ImagingException - if it fails to read the image metadata
        java.io.IOException - if it fails to read the image data
        See Also:
        ImageMetadata

      • getXmpXml

        public static java.lang.String getXmpXml​(byte[] bytes)
                                  throws ImagingException,
                                         java.io.IOException
        Extracts the embedded XML metadata as an XML string.
        Parameters:
        bytes - Byte array containing an image file.
        Returns:
        Xmp Xml as String, if present. Otherwise, returns null.
        Throws:
        ImagingException - if it fails to parse the image
        java.io.IOException - if it fails to read the image data

      • getXmpXml

        public static java.lang.String getXmpXml​(ByteSource byteSource)
                                  throws ImagingException,
                                         java.io.IOException
        Extracts the embedded XML metadata as an XML string.
        Parameters:
        byteSource - File containing image data.
        Returns:
        Xmp Xml as String, if present. Otherwise, returns null.
        Throws:
        ImagingException - if it fails to parse the image
        java.io.IOException - if it fails to read the image data

      • getXmpXml

        public static java.lang.String getXmpXml​(java.io.File file)
                                  throws ImagingException,
                                         java.io.IOException
        Extracts the embedded XML metadata as an XML string.
        Parameters:
        file - File containing image data.
        Returns:
        Xmp Xml as String, if present. Otherwise, returns null.
        Throws:
        ImagingException - if it fails to parse the image
        java.io.IOException - if it fails to read the image data

      • getXmpXml

        public static java.lang.String getXmpXml​(java.io.InputStream is,
                                         java.lang.String fileName)
                                  throws ImagingException,
                                         java.io.IOException
        Extracts the embedded XML metadata as an XML string.
        Parameters:
        is - InputStream from which to read image data.
        fileName - File name associated with image data (optional).
        Returns:
        Xmp Xml as String, if present. Otherwise, returns null.
        Throws:
        ImagingException - if it fails to parse the image
        java.io.IOException - if it fails to read the image data

      • guessFormat

        public static ImageFormat guessFormat​(byte[] bytes)
                               throws java.io.IOException
        Attempts to determine the image format of a file based on its "magic numbers," the first bytes of the data.

        Many graphics format specify identifying byte values that appear at the beginning of the data file. This method checks for such identifying elements and returns a ImageFormat enumeration indicating what it detects. Note that this method can return "false positives" in cases where non-image files begin with the specified byte values.

        Parameters:
        bytes - Byte array containing an image file.
        Returns:
        An ImageFormat, such as ImageFormat.IMAGE_FORMAT_JPEG. Returns ImageFormat.IMAGE_FORMAT_UNKNOWN if the image type cannot be determined.
        Throws:
        java.io.IOException - in the event of an unrecoverable I/O condition.

      • guessFormat

        public static ImageFormat guessFormat​(ByteSource byteSource)
                               throws java.io.IOException
        Attempts to determine the image format of a file based on its "magic numbers," the first bytes of the data.

        Many graphics formats specify identifying byte values that appear at the beginning of the data file. This method checks for such identifying elements and returns a ImageFormat enumeration indicating what it detects. Note that this method can return "false positives" in cases where non-image files begin with the specified byte values.

        Parameters:
        byteSource - a valid ByteSource object potentially supplying data for an image.
        Returns:
        An ImageFormat, such as ImageFormat.IMAGE_FORMAT_JPEG. Returns ImageFormat.IMAGE_FORMAT_UNKNOWN if the image type cannot be determined.
        Throws:
        java.lang.IllegalArgumentException - in the event of an unsuccessful attempt to read the image data
        java.io.IOException - in the event of an unrecoverable I/O condition.

      • guessFormat

        public static ImageFormat guessFormat​(java.io.File file)
                               throws java.io.IOException
        Attempts to determine the image format of a file based on its "magic numbers," the first bytes of the data.

        Many graphics formats specify identifying byte values that appear at the beginning of the data file. This method checks for such identifying elements and returns a ImageFormat enumeration indicating what it detects. Note that this method can return "false positives" in cases where non-image files begin with the specified byte values.

        Parameters:
        file - File containing image data.
        Returns:
        An ImageFormat, such as ImageFormat.IMAGE_FORMAT_JPEG. Returns ImageFormat.IMAGE_FORMAT_UNKNOWN if the image type cannot be determined.
        Throws:
        java.io.IOException - in the event of an unrecoverable I/O condition.

      • hasImageFileExtension

        public static boolean hasImageFileExtension​(java.io.File file)
        Attempts to determine if a file contains an image recorded in a supported graphics format based on its file-name extension (for example ".jpg", ".gif", ".png", etc.).
        Parameters:
        file - A valid File object providing a reference to a file that may contain an image.
        Returns:
        true if the file-name includes a supported image format file extension; otherwise, false.

      • hasImageFileExtension

        public static boolean hasImageFileExtension​(java.lang.String fileName)
        Attempts to determine if a file contains an image recorded in a supported graphics format based on its file-name extension (for example ".jpg", ".gif", ".png", etc.).
        Parameters:
        fileName - A valid string representing name of file which may contain an image.
        Returns:
        true if the file name has an image format file extension.

      • writeImage

        public static void writeImage​(java.awt.image.BufferedImage src,
                              java.io.File file,
                              ImageFormat format)
                       throws ImagingException,
                              java.io.IOException
        Writes the content of a BufferedImage to a file using the specified image format.

        Image writing is not supported for all graphics formats. For the most recent information on support for specific formats, refer to Format Support at the main project development web site. While the Apache Commons Imaging package does not fully support all formats, it can read image info, metadata and ICC profiles from all image formats that provide this data.

        Parameters:
        src - a valid BufferedImage object
        file - the file to which the output image is to be written
        format - the format in which the output image is to be written
        Throws:
        ImagingException - in the event of a format violation, unsupported image format, etc.
        java.io.IOException - in the event of an unrecoverable I/O exception.
        See Also:
        ImagingConstants

      • writeImage

        public static void writeImage​(java.awt.image.BufferedImage src,
                              java.io.OutputStream outputStream,
                              ImageFormat format)
                       throws ImagingException,
                              java.io.IOException
        Writes the content of a BufferedImage to an OutputStream using the specified image format.

        Image writing is not supported for all graphics formats. For the most recent information on support for specific formats, refer to Format Support at the main project development web site. While the Apache Commons Imaging package does not fully support all formats, it can read image info, metadata and ICC profiles from all image formats that provide this data.

        Parameters:
        src - a valid BufferedImage object
        outputStream - the OutputStream to which the output image is to be written
        format - the format in which the output image is to be written
        Throws:
        ImagingException - in the event of a format violation, unsupported image format, etc.
        java.io.IOException - in the event of an unrecoverable I/O exception.
        See Also:
        ImagingConstants

      • writeImageToBytes

        public static byte[] writeImageToBytes​(java.awt.image.BufferedImage src,
                                       ImageFormat format)
                                throws ImagingException,
                                       java.io.IOException
        Writes the content of a BufferedImage to a byte array using the specified image format.

        Image writing is not supported for all graphics formats. For the most recent information on support for specific formats, refer to Format Support at the main project development web site. While the Apache Commons Imaging package does not fully support all formats, it can read image info, metadata and ICC profiles from all image formats that provide this data.

        Parameters:
        src - a valid BufferedImage object
        format - the format in which the output image is to be written
        Returns:
        if successful, a valid array of bytes.
        Throws:
        ImagingException - in the event of a format violation, unsupported image format, etc.
        java.io.IOException - in the event of an unrecoverable I/O exception.
        See Also:
        ImagingConstants