Package 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	Description
PDImageXObject(PDStream stream, PDResources resources)	Creates an Image XObject with the given stream as its contents and current color spaces.
PDImageXObject(PDDocument document)	Creates an Image XObject in the given document.
PDImageXObject(PDDocument document, java.io.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.

Method Summary

Modifier and Type	Method	Description
static PDImageXObject	createFromByteArray(PDDocument document, byte[] byteArray, java.lang.String name)	Create a PDImageXObject from bytes of an image file.
static PDImageXObject	createFromFile(java.lang.String imagePath, PDDocument doc)	Create a PDImageXObject from an image file, see createFromFileByExtension(File, PDDocument) for more details.
static PDImageXObject	createFromFileByContent(java.io.File file, PDDocument doc)	Create a PDImageXObject from an image file.
static PDImageXObject	createFromFileByExtension(java.io.File file, PDDocument doc)	Create a PDImageXObject from an image file.
java.io.InputStream	createInputStream()	Returns an InputStream containing the image data, irrespective of whether this is an inline image or an image XObject.
java.io.InputStream	createInputStream(java.util.List<java.lang.String> stopFilters)	Returns an InputStream containing the image data, irrespective of whether this is an inline image or an image XObject.
java.io.InputStream	createInputStream(DecodeOptions options)	Returns an InputStream, passing additional options to each filter.
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.
java.awt.image.BufferedImage	getImage()	Returns the content of this image as an AWT buffered image with an (A)RGB color space.
java.awt.image.BufferedImage	getImage(java.awt.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.
java.awt.image.BufferedImage	getOpaqueImage()	Returns an RGB buffered image containing the opaque image stream without any masks applied.
java.awt.image.BufferedImage	getOpaqueImage(java.awt.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.
java.awt.image.BufferedImage	getRawImage()	Try to get the raw image as AWT buffered image with it's original colorspace.
java.awt.image.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.
java.awt.image.BufferedImage	getStencilImage(java.awt.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.
java.lang.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 or not 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, getCOSStream, getPDStream, 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.common.COSObjectable

getCOSObject

Constructor Detail

PDImageXObject

public PDImageXObject(PDDocument document)
               throws java.io.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:

java.io.IOException - if there is an error creating the XObject.

PDImageXObject

public PDImageXObject(PDDocument document,
                      java.io.InputStream encodedStream,
                      COSBase cosFilter,
                      int width,
                      int height,
                      int bitsPerComponent,
                      PDColorSpace initColorSpace)
               throws java.io.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:

java.io.IOException - if there is an error creating the XObject.

PDImageXObject

public PDImageXObject(PDStream stream,
                      PDResources resources)
               throws java.io.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:

java.io.IOException - if there is an error creating the XObject.

Method Detail

createThumbnail

public static PDImageXObject createThumbnail(COSStream cosStream)
                                      throws java.io.IOException

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

Parameters:

cosStream - the COS stream

Returns:

an XObject

Throws:

java.io.IOException - if there is an error creating the XObject.

createFromFile

public static PDImageXObject createFromFile(java.lang.String imagePath,
                                            PDDocument doc)
                                     throws java.io.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:

java.io.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(java.io.File file,
                                                       PDDocument doc)
                                                throws java.io.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:

java.io.IOException - if there is an error when reading the file or creating the PDImageXObject.

java.lang.IllegalArgumentException - if the image type is not supported.

createFromFileByContent

public static PDImageXObject createFromFileByContent(java.io.File file,
                                                     PDDocument doc)
                                              throws java.io.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:

java.io.IOException - if there is an error when reading the file or creating the PDImageXObject.

java.lang.IllegalArgumentException - if the image type is not supported.

createFromByteArray

public static PDImageXObject createFromByteArray(PDDocument document,
                                                 byte[] byteArray,
                                                 java.lang.String name)
                                          throws java.io.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:

java.io.IOException - if there is an error when reading the file or creating the PDImageXObject.

java.lang.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 java.awt.image.BufferedImage getImage()
                                      throws java.io.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:

java.io.IOException

getImage

public java.awt.image.BufferedImage getImage(java.awt.Rectangle region,
                                             int subsampling)
                                      throws java.io.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:

java.io.IOException

getRawImage

public java.awt.image.BufferedImage getRawImage()
                                         throws java.io.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 alwoys 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:

java.io.IOException

getRawRaster

public java.awt.image.WritableRaster getRawRaster()
                                           throws java.io.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:

java.io.IOException

getStencilImage

public java.awt.image.BufferedImage getStencilImage(java.awt.Paint paint)
                                             throws java.io.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:

java.io.IOException - if the image cannot be read

getOpaqueImage

public java.awt.image.BufferedImage getOpaqueImage()
                                            throws java.io.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:

java.io.IOException - if the image cannot be read

getOpaqueImage

public java.awt.image.BufferedImage getOpaqueImage(java.awt.Rectangle region,
                                                   int subsampling)
                                            throws java.io.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:

java.io.IOException - if the image cannot be read

getMask

public PDImageXObject getMask()
                       throws java.io.IOException

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

Returns:

Mask Image XObject

Throws:

java.io.IOException

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 java.io.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:

java.io.IOException

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

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 java.io.IOException

Description copied from interface: PDImage

Returns the image's color space.

Specified by:

getColorSpace in interface PDImage

Throws:

java.io.IOException - If there is an error getting the color space.

createInputStream

public java.io.InputStream createInputStream()
                                      throws java.io.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:

java.io.IOException - if the data could not be read.

createInputStream

public java.io.InputStream createInputStream(DecodeOptions options)
                                      throws java.io.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:

java.io.IOException - if the data could not be read

createInputStream

public java.io.InputStream createInputStream(java.util.List<java.lang.String> stopFilters)
                                      throws java.io.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:

java.io.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

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

setHeight

public void setHeight(int h)

Description copied from interface: PDImage

Sets the height of the image.

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

setWidth

public void setWidth(int w)

Description copied from interface: PDImage

Sets the width of the image.

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

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

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

isStencil

public boolean isStencil()

Description copied from interface: PDImage

Returns true if the image is a stencil mask.

Specified by:

isStencil in interface PDImage

setStencil

public void setStencil(boolean isStencil)

Description copied from interface: PDImage

Sets whether or not 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 java.lang.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.