Class PDImageXObject

    • 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.
      • 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
      • 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
      • 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.