PDImageXObject (Apache PDFBox 2.0.1 API)

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

Methods
Modifier and Type	Method and Description
`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(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.
`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.
`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. jpg/png.
`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`	`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 IOException
```
    Creates an Image XObject in the given document.
    
    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.
    
    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.
    
    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).
    
    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).
    
    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.
  - 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
  - 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
  - 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
  - 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
  - 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
  - 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 IOException
```
    Description copied from interface: PDImage
    
    Returns the image's color space.
    
    Specified by:
    
    getColorSpace in interface PDImage
    
    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(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
    
    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
  - 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 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.

Class PDImageXObject

Constructor Summary

Method Summary

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

Methods inherited from class java.lang.Object

Methods inherited from interface org.apache.pdfbox.pdmodel.common.COSObjectable

Constructor Detail

PDImageXObject

PDImageXObject

PDImageXObject

Method Detail

createThumbnail

createFromFile

createFromFileByExtension

createFromFileByContent

getMetadata

setMetadata

getStructParent

setStructParent

getImage

getStencilImage

getOpaqueImage

getMask

getColorKeyMask

getSoftMask

getBitsPerComponent

setBitsPerComponent

getColorSpace

createInputStream

createInputStream

isEmpty

setColorSpace

getHeight

setHeight

getWidth

setWidth

getInterpolate

setInterpolate

setDecode

getDecode

isStencil

setStencil

getSuffix