org.apache.pdfbox.pdmodel.graphics.image

## Class PDImageXObject

- java.lang.Object
- - org.apache.pdfbox.pdmodel.graphics.PDXObject
  - - org.apache.pdfbox.pdmodel.graphics.image.PDImageXObject

All Implemented Interfaces:
  COSObjectable, PDImage

    public final class PDImageXObject
    extends PDXObject
    implements PDImage

An Image XObject.

Author:
  John Hewson, Ben Litchfield

### Constructor Summary

Constructors
Constructor and Description
`PDImageXObject(PDDocument document)` Creates an Image XObject in the given document.
`PDImageXObject(PDDocument document, InputStream encodedStream, COSBase cosFilter, int width, int height, int bitsPerComponent, PDColorSpace initColorSpace)` Creates an Image XObject in the given document using the given filtered stream.
`PDImageXObject(PDStream stream, PDResources resources)` Creates an Image XObject with the given stream as its contents and current color spaces.

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`static PDImageXObject` `createFromByteArray(PDDocument document, byte[] byteArray, String name)` Create a PDImageXObject from bytes of an image file.
`static PDImageXObject` `createFromByteArray(PDDocument document, byte[] byteArray, String name, CustomFactory customFactory)` Create a PDImageXObject from an image byte array.
`static PDImageXObject` `createFromFile(String imagePath, PDDocument doc)` Create a PDImageXObject from an image file, see `createFromFileByExtension(File, PDDocument)` for more details.
`static PDImageXObject` `createFromFileByContent(File file, PDDocument doc)` Create a PDImageXObject from an image file.
`static PDImageXObject` `createFromFileByExtension(File file, PDDocument doc)` Create a PDImageXObject from an image file.
`InputStream` `createInputStream()` Returns an InputStream containing the image data, irrespective of whether this is an inline image or an image XObject.
`InputStream` `createInputStream(DecodeOptions options)` Returns an InputStream, passing additional options to each filter.
`InputStream` `createInputStream(List<String> stopFilters)` Returns an InputStream containing the image data, irrespective of whether this is an inline image or an image XObject.
`static PDImageXObject` `createThumbnail(COSStream cosStream)` Creates a thumbnail Image XObject from the given COSBase and name.
`int` `getBitsPerComponent()` Returns bits per component of this image, or -1 if one has not been set.
`COSArray` `getColorKeyMask()` Returns the color key mask array associated with this image, or null if there is none.
`PDColorSpace` `getColorSpace()` Returns the image's color space.
`COSArray` `getDecode()` Returns the decode array.
`int` `getHeight()` Returns height of this image, or -1 if one has not been set.
`BufferedImage` `getImage()` Returns the content of this image as an AWT buffered image with an (A)RGB color space.
`BufferedImage` `getImage(Rectangle region, int subsampling)` Returns the content of this image as an AWT buffered image with an (A)RGB colored space.
`boolean` `getInterpolate()` Returns true if the image should be interpolated when rendered.
`PDImageXObject` `getMask()` Returns the Mask Image XObject associated with this image, or null if there is none.
`PDMetadata` `getMetadata()` Returns the metadata associated with this XObject, or null if there is none.
`BufferedImage` `getOpaqueImage()` Returns an RGB buffered image containing the opaque image stream without any masks applied.
`BufferedImage` `getOpaqueImage(Rectangle region, int subsampling)` Returns an RGB buffered image containing the opaque image stream without any masks applied.
`PDPropertyList` `getOptionalContent()` This will get the optional content group or optional content membership dictionary.
`BufferedImage` `getRawImage()` Try to get the raw image as AWT buffered image with it's original colorspace.
`WritableRaster` `getRawRaster()` Return the image data as WritableRaster.
`PDImageXObject` `getSoftMask()` Returns the Soft Mask Image XObject associated with this image, or null if there is none.
`BufferedImage` `getStencilImage(Paint paint)` Returns an ARGB image filled with the given paint and using this image as a mask.
`int` `getStructParent()` Returns the key of this XObject in the structural parent tree.
`String` `getSuffix()` This will get the suffix for this image type, e.g.
`int` `getWidth()` Returns the width of this image, or -1 if one has not been set.
`boolean` `isEmpty()` Returns true if the image has no data.
`boolean` `isStencil()` Returns true if the image is a stencil mask.
`void` `setBitsPerComponent(int bpc)` Set the number of bits per component.
`void` `setColorSpace(PDColorSpace cs)` Sets the color space for this image.
`void` `setDecode(COSArray decode)` Sets the decode array.
`void` `setHeight(int h)` Sets the height of the image.
`void` `setInterpolate(boolean value)` Sets the Interpolate flag, true for high-quality image scaling.
`void` `setMetadata(PDMetadata meta)` Sets the metadata associated with this XObject, or null if there is none.
`void` `setOptionalContent(PDPropertyList oc)` Sets the optional content group or optional content membership dictionary.
`void` `setStencil(boolean isStencil)` Sets whether the image is a stencil.
`void` `setStructParent(int key)` Sets the key of this XObject in the structural parent tree.
`void` `setWidth(int w)` Sets the width of the image.

### Methods inherited from class org.apache.pdfbox.pdmodel.graphics.PDXObject

`createXObject, getCOSObject, getStream`

### Methods inherited from class java.lang.Object

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

### Methods inherited from interface org.apache.pdfbox.pdmodel.graphics.image.PDImage

`getCOSObject`

### Constructor Detail

#### PDImageXObject

    public PDImageXObject(PDDocument document)
                   throws IOException

Creates an Image XObject in the given document. This constructor is for internal PDFBox use and is not for PDF generation. Users who want to create images should look at `createFromFileByExtension(File, PDDocument)`.

Parameters:
  `document` - the current document
Throws:
  `IOException` - if there is an error creating the XObject.

#### PDImageXObject

    public PDImageXObject(PDDocument document,
                          InputStream encodedStream,
                          COSBase cosFilter,
                          int width,
                          int height,
                          int bitsPerComponent,
                          PDColorSpace initColorSpace)
                   throws IOException

Creates an Image XObject in the given document using the given filtered stream. This constructor is for internal PDFBox use and is not for PDF generation. Users who want to create images should look at `createFromFileByExtension(File, PDDocument)`.

Parameters:
  `document` - the current document
  `encodedStream` - an encoded stream of image data
  `cosFilter` - the filter or a COSArray of filters
  `width` - the image width
  `height` - the image height
  `bitsPerComponent` - the bits per component
  `initColorSpace` - the color space
Throws:
  `IOException` - if there is an error creating the XObject.

#### PDImageXObject

    public PDImageXObject(PDStream stream,
                          PDResources resources)
                   throws IOException

Creates an Image XObject with the given stream as its contents and current color spaces. This constructor is for internal PDFBox use and is not for PDF generation. Users who want to create images should look at `createFromFileByExtension(File, PDDocument)`.

Parameters:
  `stream` - the XObject stream to read
  `resources` - the current resources
Throws:
  `IOException` - if there is an error creating the XObject.

### Method Detail

#### createThumbnail

    public static PDImageXObject createThumbnail(COSStream cosStream)
                                          throws IOException

Creates a thumbnail Image XObject from the given COSBase and name.

Parameters:
  `cosStream` - the COS stream
Returns:
  an XObject
Throws:
  `IOException` - if there is an error creating the XObject.

#### createFromFile

    public static PDImageXObject createFromFile(String imagePath,
                                                PDDocument doc)
                                         throws IOException

Create a PDImageXObject from an image file, see `createFromFileByExtension(File, PDDocument)` for more details.

Parameters:
  `imagePath` - the image file path.
  `doc` - the document that shall use this PDImageXObject.
Returns:
  a PDImageXObject.
Throws:
  `IOException` - if there is an error when reading the file or creating the PDImageXObject, or if the image type is not supported.

#### createFromFileByExtension

    public static PDImageXObject createFromFileByExtension(File file,
                                                           PDDocument doc)
                                                    throws IOException

Create a PDImageXObject from an image file. The file format is determined by the file name suffix. The following suffixes are supported: JPG, JPEG, TIF, TIFF, GIF, BMP and PNG. This is a convenience method that calls `JPEGFactory.createFromStream(org.apache.pdfbox.pdmodel.PDDocument, java.io.InputStream)`, `CCITTFactory.createFromFile(org.apache.pdfbox.pdmodel.PDDocument, java.io.File)` or `ImageIO.read(java.io.File)` combined with `LosslessFactory.createFromImage(org.apache.pdfbox.pdmodel.PDDocument, java.awt.image.BufferedImage)`. (The later can also be used to create a PDImageXObject from a BufferedImage). Starting with 2.0.18, this call will create an image directly from a PNG file without decoding it (when possible), which is faster. However the result size depends on the compression skill of the software that created the PNG file. If file size or bandwidth are important to you or to your clients, then create your PNG files with a tool that has implemented the Zopfli algorithm, or use the two-step process mentioned above.

Parameters:
  `file` - the image file.
  `doc` - the document that shall use this PDImageXObject.
Returns:
  a PDImageXObject.
Throws:
  `IOException` - if there is an error when reading the file or creating the PDImageXObject.
  `IllegalArgumentException` - if the image type is not supported.

#### createFromFileByContent

    public static PDImageXObject createFromFileByContent(File file,
                                                         PDDocument doc)
                                                  throws IOException

Create a PDImageXObject from an image file. The file format is determined by the file content. The following file types are supported: JPG, JPEG, TIF, TIFF, GIF, BMP and PNG. This is a convenience method that calls `JPEGFactory.createFromStream(org.apache.pdfbox.pdmodel.PDDocument, java.io.InputStream)`, `CCITTFactory.createFromFile(org.apache.pdfbox.pdmodel.PDDocument, java.io.File)` or `ImageIO.read(java.io.File)` combined with `LosslessFactory.createFromImage(org.apache.pdfbox.pdmodel.PDDocument, java.awt.image.BufferedImage)`. (The later can also be used to create a PDImageXObject from a BufferedImage). Starting with 2.0.18, this call will create an image directly from a PNG file without decoding it (when possible), which is faster. However the result size depends on the compression skill of the software that created the PNG file. If file size or bandwidth are important to you or to your clients, then create your PNG files with a tool that has implemented the Zopfli algorithm, or use the two-step process mentioned above.

Parameters:
  `file` - the image file.
  `doc` - the document that shall use this PDImageXObject.
Returns:
  a PDImageXObject.
Throws:
  `IOException` - if there is an error when reading the file or creating the PDImageXObject.
  `IllegalArgumentException` - if the image type is not supported.

#### createFromByteArray

    public static PDImageXObject createFromByteArray(PDDocument document,
                                                     byte[] byteArray,
                                                     String name)
                                              throws IOException

Create a PDImageXObject from bytes of an image file. The file format is determined by the file content. The following file types are supported: JPG, JPEG, TIF, TIFF, GIF, BMP and PNG. This is a convenience method that calls `JPEGFactory.createFromByteArray(org.apache.pdfbox.pdmodel.PDDocument, byte[])`, `CCITTFactory.createFromFile(org.apache.pdfbox.pdmodel.PDDocument, java.io.File)` or `ImageIO.read(java.io.File)` combined with `LosslessFactory.createFromImage(org.apache.pdfbox.pdmodel.PDDocument, java.awt.image.BufferedImage)`. (The later can also be used to create a PDImageXObject from a BufferedImage). Starting with 2.0.18, this call will create an image directly from a PNG file without decoding it (when possible), which is faster. However the result size depends on the compression skill of the software that created the PNG file. If file size or bandwidth are important to you or to your clients, then create your PNG files with a tool that has implemented the Zopfli algorithm, or use the two-step process mentioned above.

Parameters:
  `byteArray` - bytes from an image file.
  `document` - the document that shall use this PDImageXObject.
  `name` - name of image file for exception messages, can be null.
Returns:
  a PDImageXObject.
Throws:
  `IOException` - if there is an error when reading the file or creating the PDImageXObject.
  `IllegalArgumentException` - if the image type is not supported.

#### createFromByteArray

    public static PDImageXObject createFromByteArray(PDDocument document,
                                                     byte[] byteArray,
                                                     String name,
                                                     CustomFactory customFactory)
                                              throws IOException

Create a PDImageXObject from an image byte array. This overloaded version allows providing a custom factory to handle specific image formats, such as BMP and GIF, or to act as a fallback strategy when the default converters (e.g., for PNG or TIFF) fail.

Parameters:
  `document` - the document that shall use this PDImageXObject.
  `byteArray` - bytes from an image file.
  `name` - name of image file for exception messages, can be null.
  `customFactory` - optional factory used to handle BMP, GIF, or fallback cases (e.g., for PNG or TIFF). If `null`, this method delegates to `createFromByteArray(PDDocument, byte[], String)`.
Returns:
  a PDImageXObject.
Throws:
  `IOException` - if there is an error when reading the file or creating the PDImageXObject.
  `IllegalArgumentException` - if the image type is not supported.

#### getMetadata

    public PDMetadata getMetadata()

Returns the metadata associated with this XObject, or null if there is none.

Returns:
  the metadata associated with this object.

#### setMetadata

    public void setMetadata(PDMetadata meta)

Sets the metadata associated with this XObject, or null if there is none.

Parameters:
  `meta` - the metadata associated with this object

#### getStructParent

    public int getStructParent()

Returns the key of this XObject in the structural parent tree.

Returns:
  this object's key the structural parent tree or -1 if there isn't any.

#### setStructParent

    public void setStructParent(int key)

Sets the key of this XObject in the structural parent tree.

Parameters:
  `key` - the new key for this XObject

#### getImage

    public BufferedImage getImage()
                           throws IOException

Returns the content of this image as an AWT buffered image with an (A)RGB color space. The size of the returned image is the larger of the size of the image itself or its mask. The returned images are cached via a SoftReference.

Specified by:
  `getImage` in interface `PDImage`
Returns:
  content of this image as a buffered image.
Throws:
  `IOException` - if the buffered image could not be created

#### getImage

    public BufferedImage getImage(Rectangle region,
                                  int subsampling)
                           throws IOException

Returns the content of this image as an AWT buffered image with an (A)RGB colored space. Only the subregion specified is rendered, and is subsampled by advancing the specified amount of rows and columns in the source image for every resulting pixel. Note that unlike `the unparameterized version`, this method does not cache the resulting image.

Specified by:
  `getImage` in interface `PDImage`
Parameters:
  `region` - The region of the source image to get, or null if the entire image is needed. The actual region will be clipped to the dimensions of the source image.
  `subsampling` - The amount of rows and columns to advance for every output pixel, a value of 1 meaning every pixel will be read
Returns:
  subsampled content of the requested subregion as a buffered image.
Throws:
  `IOException` - if the buffered image could not be created

#### getRawImage

    public BufferedImage getRawImage()
                              throws IOException

Description copied from interface: `PDImage`
Try to get the raw image as AWT buffered image with it's original colorspace. No color conversion is performed. You could use the returned BufferedImage for draw operations. But this would be very slow as the color conversion would happen on demand. You rather should use `PDImage.getImage()` for that. This method returns null if it is not possible to map the underlying colorspace into a java.awt.ColorSpace. Use this method if you want to extract the image without loosing any color information, as no color conversion will be performed. You can always use `PDImage.getRawRaster()`, if you want to access the raw data even if no matching java.awt.ColorSpace exists

Specified by:
  `getRawImage` in interface `PDImage`
Returns:
  the raw image with a java.awt.ColorSpace or null
Throws:
  `IOException` - if the raw image could not be created

#### getRawRaster

    public WritableRaster getRawRaster()
                                throws IOException

Description copied from interface: `PDImage`
Return the image data as WritableRaster. You should consult the PDColorSpace returned by `PDImage.getColorSpace()` to know how to interpret the data in this WritableRaster. Use this if e.g. want access to the raw color information of a `PDDeviceN` image.

Specified by:
  `getRawRaster` in interface `PDImage`
Returns:
  the raw writable raster for this image
Throws:
  `IOException` - if the buffered raw writable raster could not be created

#### getStencilImage

    public BufferedImage getStencilImage(Paint paint)
                                  throws IOException

Returns an ARGB image filled with the given paint and using this image as a mask. The returned images are not cached.

Specified by:
  `getStencilImage` in interface `PDImage`
Parameters:
  `paint` - the paint to fill the visible portions of the image with
Returns:
  a masked image filled with the given paint
Throws:
  `IOException` - if the image cannot be read

#### getOpaqueImage

    public BufferedImage getOpaqueImage()
                                 throws IOException

Returns an RGB buffered image containing the opaque image stream without any masks applied. If this Image XObject is a mask then the buffered image will contain the raw mask.

Returns:
  the image without any masks applied
Throws:
  `IOException` - if the image cannot be read

#### getOpaqueImage

    public BufferedImage getOpaqueImage(Rectangle region,
                                        int subsampling)
                                 throws IOException

Returns an RGB buffered image containing the opaque image stream without any masks applied. If this Image XObject is a mask then the buffered image will contain the raw mask.

Parameters:
  `region` - The region of the source image to get, or null if the entire image is needed. The actual region will be clipped to the dimensions of the source image.
  `subsampling` - The amount of rows and columns to advance for every output pixel, a value of 1 meaning every pixel will be read. It must not be larger than the image width or height.
Returns:
  the image without any masks applied
Throws:
  `IOException` - if the image cannot be read

#### getMask

    public PDImageXObject getMask()
                           throws IOException

Returns the Mask Image XObject associated with this image, or null if there is none.

Returns:
  Mask Image XObject
Throws:
  `IOException` - if the mask data could not be read

#### getColorKeyMask

    public COSArray getColorKeyMask()

Returns the color key mask array associated with this image, or null if there is none.

Returns:
  Mask Image XObject

#### getSoftMask

    public PDImageXObject getSoftMask()
                               throws IOException

Returns the Soft Mask Image XObject associated with this image, or null if there is none.

Returns:
  the SMask Image XObject, or null.
Throws:
  `IOException` - if the soft mask data could not be read

#### getBitsPerComponent

    public int getBitsPerComponent()

Description copied from interface: `PDImage`
Returns bits per component of this image, or -1 if one has not been set.

Specified by:
  `getBitsPerComponent` in interface `PDImage`
Returns:
  bits per component of this image or -1

#### setBitsPerComponent

    public void setBitsPerComponent(int bpc)

Description copied from interface: `PDImage`
Set the number of bits per component.

Specified by:
  `setBitsPerComponent` in interface `PDImage`
Parameters:
  `bpc` - The number of bits per component.

#### getColorSpace

    public PDColorSpace getColorSpace()
                               throws IOException

Description copied from interface: `PDImage`
Returns the image's color space.

Specified by:
  `getColorSpace` in interface `PDImage`
Returns:
  the image's color space
Throws:
  `IOException` - If there is an error getting the color space.

#### createInputStream

    public InputStream createInputStream()
                                  throws IOException

Description copied from interface: `PDImage`
Returns an InputStream containing the image data, irrespective of whether this is an inline image or an image XObject.

Specified by:
  `createInputStream` in interface `PDImage`
Returns:
  Decoded stream
Throws:
  `IOException` - if the data could not be read.

#### createInputStream

    public InputStream createInputStream(DecodeOptions options)
                                  throws IOException

Description copied from interface: `PDImage`
Returns an InputStream, passing additional options to each filter. As a side effect, the filterSubsampled flag is set in `DecodeOptions`.

Specified by:
  `createInputStream` in interface `PDImage`
Parameters:
  `options` - Additional decoding options passed to the filters used
Returns:
  Decoded stream
Throws:
  `IOException` - if the data could not be read

#### createInputStream

    public InputStream createInputStream(List<String> stopFilters)
                                  throws IOException

Description copied from interface: `PDImage`
Returns an InputStream containing the image data, irrespective of whether this is an inline image or an image XObject. The given filters will not be decoded.

Specified by:
  `createInputStream` in interface `PDImage`
Parameters:
  `stopFilters` - A list of filters to stop decoding at.
Returns:
  Decoded stream
Throws:
  `IOException` - if the data could not be read.

#### isEmpty

    public boolean isEmpty()

Description copied from interface: `PDImage`
Returns true if the image has no data.

Specified by:
  `isEmpty` in interface `PDImage`
Returns:
  true if the image has no data

#### setColorSpace

    public void setColorSpace(PDColorSpace cs)

Description copied from interface: `PDImage`
Sets the color space for this image.

Specified by:
  `setColorSpace` in interface `PDImage`
Parameters:
  `cs` - The color space for this image.

#### getHeight

    public int getHeight()

Description copied from interface: `PDImage`
Returns height of this image, or -1 if one has not been set.

Specified by:
  `getHeight` in interface `PDImage`
Returns:
  height of this image or -1

#### setHeight

    public void setHeight(int h)

Description copied from interface: `PDImage`
Sets the height of the image. This is for internal PDFBox usage and not to set the size of the image on the page.

Specified by:
  `setHeight` in interface `PDImage`
Parameters:
  `h` - The height of the image.

#### getWidth

    public int getWidth()

Description copied from interface: `PDImage`
Returns the width of this image, or -1 if one has not been set.

Specified by:
  `getWidth` in interface `PDImage`
Returns:
  width of this image or -1

#### setWidth

    public void setWidth(int w)

Description copied from interface: `PDImage`
Sets the width of the image. This is for internal PDFBox usage and not to set the size of the image on the page.

Specified by:
  `setWidth` in interface `PDImage`
Parameters:
  `w` - The width of the image.

#### getInterpolate

    public boolean getInterpolate()

Description copied from interface: `PDImage`
Returns true if the image should be interpolated when rendered.

Specified by:
  `getInterpolate` in interface `PDImage`
Returns:
  true if the image should be interpolated when rendered

#### setInterpolate

    public void setInterpolate(boolean value)

Description copied from interface: `PDImage`
Sets the Interpolate flag, true for high-quality image scaling.

Specified by:
  `setInterpolate` in interface `PDImage`
Parameters:
  `value` - true for high-quality image scaling

#### setDecode

    public void setDecode(COSArray decode)

Description copied from interface: `PDImage`
Sets the decode array.

Specified by:
  `setDecode` in interface `PDImage`
Parameters:
  `decode` - the new decode array.

#### getDecode

    public COSArray getDecode()

Description copied from interface: `PDImage`
Returns the decode array.

Specified by:
  `getDecode` in interface `PDImage`
Returns:
  the decode array

#### isStencil

    public boolean isStencil()

Description copied from interface: `PDImage`
Returns true if the image is a stencil mask.

Specified by:
  `isStencil` in interface `PDImage`
Returns:
  true if the image is a stencil mask

#### setStencil

    public void setStencil(boolean isStencil)

Description copied from interface: `PDImage`
Sets whether the image is a stencil. This corresponds to the `ImageMask` entry in the image stream's dictionary.

Specified by:
  `setStencil` in interface `PDImage`
Parameters:
  `isStencil` - True to make the image a stencil.

#### getSuffix

    public String getSuffix()

This will get the suffix for this image type, e.g. jpg/png.

Specified by:
  `getSuffix` in interface `PDImage`
Returns:
  The image suffix or null if not available.

#### getOptionalContent

    public PDPropertyList getOptionalContent()

This will get the optional content group or optional content membership dictionary.

Returns:
  The optional content group or optional content membership dictionary or null if there is none.

#### setOptionalContent

    public void setOptionalContent(PDPropertyList oc)

Sets the optional content group or optional content membership dictionary.

Parameters:
  `oc` - The optional content group or optional content membership dictionary.