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.
-
-
Field Summary
Fields Modifier and Type Field Description private java.lang.ref.SoftReference<java.awt.image.BufferedImage>
cachedImage
private int
cachedImageSubsampling
private PDColorSpace
colorSpace
private static org.apache.commons.logging.Log
LOG
Log instance.private PDResources
resources
current resource dictionary (has color spaces)
-
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
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description private java.awt.image.BufferedImage
applyMask(java.awt.image.BufferedImage image, java.awt.image.BufferedImage mask, boolean isSoft, float[] matte)
private float
clampColor(float color)
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, seecreateFromFileByExtension(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.private static COSStream
createRawStream(PDDocument document, java.io.InputStream rawInput)
Creates a COS stream from raw (encoded) data.static PDImageXObject
createThumbnail(COSStream cosStream)
Creates a thumbnail Image XObject from the given COSBase and name.private float[]
extractMatte(PDImageXObject softMask)
Extract the matte color from a softmask.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.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.private java.awt.image.BufferedImage
scaleImage(java.awt.image.BufferedImage image, int width, int height)
High-quality image scaling.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
-
-
-
-
Field Detail
-
LOG
private static final org.apache.commons.logging.Log LOG
Log instance.
-
cachedImage
private java.lang.ref.SoftReference<java.awt.image.BufferedImage> cachedImage
-
colorSpace
private PDColorSpace colorSpace
-
cachedImageSubsampling
private int cachedImageSubsampling
-
resources
private final PDResources resources
current resource dictionary (has color spaces)
-
-
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 atcreateFromFileByExtension(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 atcreateFromFileByExtension(File, PDDocument)
.- Parameters:
document
- the current documentencodedStream
- an encoded stream of image datacosFilter
- the filter or a COSArray of filterswidth
- the image widthheight
- the image heightbitsPerComponent
- the bits per componentinitColorSpace
- 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 atcreateFromFileByExtension(File, PDDocument)
.- Parameters:
stream
- the XObject stream to readresources
- 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.
-
createRawStream
private static COSStream createRawStream(PDDocument document, java.io.InputStream rawInput) throws java.io.IOException
Creates a COS stream from raw (encoded) data.- Throws:
java.io.IOException
-
createFromFile
public static PDImageXObject createFromFile(java.lang.String imagePath, PDDocument doc) throws java.io.IOException
Create a PDImageXObject from an image file, seecreateFromFileByExtension(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 callsJPEGFactory.createFromStream(org.apache.pdfbox.pdmodel.PDDocument, java.io.InputStream)
,CCITTFactory.createFromFile(org.apache.pdfbox.pdmodel.PDDocument, java.io.File)
orImageIO.read(java.io.File)
combined withLosslessFactory.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 callsJPEGFactory.createFromStream(org.apache.pdfbox.pdmodel.PDDocument, java.io.InputStream)
,CCITTFactory.createFromFile(org.apache.pdfbox.pdmodel.PDDocument, java.io.File)
orImageIO.read(java.io.File)
combined withLosslessFactory.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 callsJPEGFactory.createFromByteArray(org.apache.pdfbox.pdmodel.PDDocument, byte[])
,CCITTFactory.createFromFile(org.apache.pdfbox.pdmodel.PDDocument, java.io.File)
orImageIO.read(java.io.File)
combined withLosslessFactory.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.
-
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 unlikethe unparameterized version
, this method does not cache the resulting image.- Specified by:
getImage
in interfacePDImage
- 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 usePDImage.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 usePDImage.getRawRaster()
, if you want to access the raw data even if no matching java.awt.ColorSpace exists- Specified by:
getRawImage
in interfacePDImage
- 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 byPDImage.getColorSpace()
to know how to interpret the data in this WritableRaster. Use this if e.g. want access to the raw color information of aPDDeviceN
image.- Specified by:
getRawRaster
in interfacePDImage
- Returns:
- the raw writable raster for this image
- Throws:
java.io.IOException
-
extractMatte
private float[] extractMatte(PDImageXObject softMask) throws java.io.IOException
Extract the matte color from a softmask.- Parameters:
softMask
-- Returns:
- the matte color.
- Throws:
java.io.IOException
- if the color conversion fails.
-
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 interfacePDImage
- 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
-
applyMask
private java.awt.image.BufferedImage applyMask(java.awt.image.BufferedImage image, java.awt.image.BufferedImage mask, boolean isSoft, float[] matte)
-
clampColor
private float clampColor(float color)
-
scaleImage
private java.awt.image.BufferedImage scaleImage(java.awt.image.BufferedImage image, int width, int height)
High-quality image scaling.
-
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 interfacePDImage
-
setBitsPerComponent
public void setBitsPerComponent(int bpc)
Description copied from interface:PDImage
Set the number of bits per component.- Specified by:
setBitsPerComponent
in interfacePDImage
- 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 interfacePDImage
- 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 interfacePDImage
- 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 inDecodeOptions
.- Specified by:
createInputStream
in interfacePDImage
- 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 interfacePDImage
- 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.
-
setColorSpace
public void setColorSpace(PDColorSpace cs)
Description copied from interface:PDImage
Sets the color space for this image.- Specified by:
setColorSpace
in interfacePDImage
- 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.
-
setHeight
public void setHeight(int h)
Description copied from interface:PDImage
Sets 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.
-
setWidth
public void setWidth(int w)
Description copied from interface:PDImage
Sets 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 interfacePDImage
-
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 interfacePDImage
-
setDecode
public void setDecode(COSArray decode)
Description copied from interface:PDImage
Sets the decode array.
-
getDecode
public COSArray getDecode()
Description copied from interface:PDImage
Returns the decode array.
-
isStencil
public boolean isStencil()
Description copied from interface:PDImage
Returns true if the image is a stencil mask.
-
setStencil
public void setStencil(boolean isStencil)
Description copied from interface:PDImage
Sets whether or not the image is a stencil. This corresponds to theImageMask
entry in the image stream's dictionary.- Specified by:
setStencil
in interfacePDImage
- 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.
-
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.
-
-