Package org.faceless.pdf2

Class PDFParser

  • All Implemented Interfaces:
    java.awt.print.Pageable
    public class PDFParser
extends java.lang.Object
implements java.awt.print.Pageable

    The PDFParser class can be used to parse the contents of a PDF document, for example converting it to an Image, writing to TIFF, printing it and so on. Typically you will either use PDFParser directly when working on the whole document (for instance, to save the PDF as a multi-page TIFF), or will use it to get a PagePainter object for parsing individual pages or a PageExtractor object, to extract text and images from a specific page.

    Note that this class is part of the "Viewer Extension" of the library - although it's supplied with the package an "viewer extension" license must be purchased to activate this class. While the library is unlicensed this class may be used freely, although a "DEMO" stamp will be applied to each document.

    This class implements Pageable, which means it can be printed directly using the PrinterJob.setPageable() method.
    Since:
    2.5

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.awt.image.ColorModel BLACKANDWHITE
      A ColorModel that can be passed in to writeAsTIFF() or the various PagePainter methods which represent a 1-bit black and white color model.
      static java.awt.image.ColorModel CMYK
      A ColorModel that can be passed in to writeAsTIFF() of the various PagePainter methods which represent an opaque CMYK color model.
      static java.awt.image.ColorModel GRAYSCALE
      A ColorModel that can be passed in to writeAsTIFF() of the various PagePainter methods which represent an opaque grayscale color model
      static java.awt.image.ColorModel RGB
      A ColorModel that can be passed in to writeAsTIFF() of the various PagePainter methods which represent an opaque RGB color model.
      static java.awt.image.ColorModel RGBA
      A ColorModel that can be passed in to writeAsTIFF() of the various PagePainter methods which represent a translucent RGB color model with an alpha component.
      static java.awt.image.ColorModel SEPARATIONS
      A ColorModel that can be passed to PagePainter.getImage(float).

      • Fields inherited from interface java.awt.print.Pageable

        UNKNOWN_NUMBER_OF_PAGES

    • Constructor Summary

      Constructors 
      Constructor Description
      PDFParser​(PDF pdf)
      Creates a PDFParser from the specified PDF document.

    • Field Detail

      • GRAYSCALE

        public static final java.awt.image.ColorModel GRAYSCALE
        A ColorModel that can be passed in to writeAsTIFF() of the various PagePainter methods which represent an opaque grayscale color model

      • RGB

        public static final java.awt.image.ColorModel RGB
        A ColorModel that can be passed in to writeAsTIFF() of the various PagePainter methods which represent an opaque RGB color model.

      • RGBA

        public static final java.awt.image.ColorModel RGBA
        A ColorModel that can be passed in to writeAsTIFF() of the various PagePainter methods which represent a translucent RGB color model with an alpha component. TIFFs created this way will have a transparent background.
        Since:
        2.5.2

      • CMYK

        public static final java.awt.image.ColorModel CMYK
        A ColorModel that can be passed in to writeAsTIFF() of the various PagePainter methods which represent an opaque CMYK color model.
        Since:
        2.5.2

      • SEPARATIONS

        public static final java.awt.image.ColorModel SEPARATIONS

        A ColorModel that can be passed to PagePainter.getImage(float). The returned image will be in a DeviceNColorSpace based on CMYK, but also containing a channel for any spot colors that are used in the PDF. This image can be converted to RGB for a "print preview" using the DeviceNColorSpace.getColorConvertOp method, or the image can be converted to a PDFImage for embedding into a PDF.

        This ColorModel can also be passed to writeAsTIFF(), but if the returned image contains more than four color components (i.e. it has Spot colors) then while the resulting file will be technically valid - the TIFF format allows multi-channel images - it will be unviewable, as the TIFF will not include a color-space specifying how to convert the N-channels to XYZ or RGB.

        Since:
        2.28.3
        See Also:
        DeviceNColorSpace.getColorConvertOp(java.awt.color.ColorSpace, java.lang.Object...)

    • Constructor Detail

      • PDFParser

        public PDFParser​(PDF pdf)
        Creates a PDFParser from the specified PDF document.
        Parameters:
        pdf - the PDF to parse

    • Method Detail

      • getPDF

        public final PDF getPDF()
        Return the PDF this PDFParser is built from.
        Since:
        2.11.3

      • getPagePainter

        public PagePainter getPagePainter​(PDFPage page)
        Returns a PagePainter for the specified page.
        Parameters:
        page - the PDFPage to select
        Returns:
        a PagePainter for the specified page
        Since:
        2.7.1

      • getPageExtractor

        public PageExtractor getPageExtractor​(PDFPage page)
        Returns a PageExtractor for the specified page. If the PDF does not allow extraction, throws a SecurityException
        Parameters:
        page - the page to select.
        Returns:
        a PageExtractor for the specified page
        Since:
        2.7.1
        See Also:
        isExtractable()

      • resetPageExtractor

        public void resetPageExtractor​(PDFPage page)
        Reset the previously created PageExtractor. This will only need to be done if that page has had its content altered, ie by appending to it or by changing its orientation.
        Since:
        2.11.7

      • getPageExtractors

        public java.util.List<PageExtractor> getPageExtractors()
        Get a list containining all the PageExtractors for this PDF, in order. This is not a particularly expensive operation as the extraction is not run when the extractor is created.
        Since:
        2.11.7

      • getStructureTree

        public org.w3c.dom.Document getStructureTree()

        Returns the Structure Tree for the entire document as a W3C Document. As of 2.24, this is simply an alias for the following: 

         Document doc = pdf.getStructureTree();
 doc.getDomConfig().setParameter("extract-text", true);
 return doc
        Returns:
        the document-wide Structure Tree.
        Since:
        2.19
        See Also:
        PDF.getStructureTree()

      • setFont

        public void setFont​(java.lang.String fontname,
                    java.lang.Object font)
        Specify a font substitution to use. For unembedded fonts, the library must choose a substitute font to render the glyphs. Typically the heuristics used are quite effective, but occasionally (particularly with east-asian fonts) this may need to be overridden. This method allows you to specify the mapping from a PDF font name to an AWT font, overriding the heuristics.
        Parameters:
        fontname - the name of the font used in the PDF
        font - the Font to use - either a Font or an OpenTypeFont
        Since:
        2.7.7 (since 2.11.17 the second parameter can also be an OpenTypeFont)

      • setPrintAsImageResolution

        public void setPrintAsImageResolution​(int dpi)
        When printing a PDF via this classes Pageable interface, it can sometimes be useful to force the PDF to print as an image at a specific resolution. This method can be called to set that resolution - the default value is 0 which means the file will not be printed as an image. Any other value will cause the page being printed to be converted to a bitmap to that resolution before printing. Suggested values are between 150 and 600.
        Since:
        2.16.4

      • isPrintable

        public boolean isPrintable()
        Return true if this PDF is allowed to be printed. Since 2.8.2 this method simply returns the value of EncryptionHandler.hasRight("Print")
        Returns:
        true if the document is allowed to be printed

      • isExtractable

        public boolean isExtractable()
        Return true if this PDF allows it's text and/or images to be extracted by calling the getPageExtractor(int) method. PDF's may optionally be encrypted to prevent this - see the StandardEncryptionHandler class for more information. Since 2.8.2 this method simply returns the value of EncryptionHandler.hasRight("Extract")
        Returns:
        true if the document can have its text and/or images extracted.

      • writeAsTIFF

        public void writeAsTIFF​(java.io.OutputStream out,
                        int dpi,
                        java.awt.image.ColorModel model)
                 throws java.io.IOException

        Convert the PDF to a TIFF image using the specified ColorModel and dots per inch. For example, to convert the PDF to a black and white TIFF, try: 

           PDFParser parser = new PDFParser(pdf);
   FileOutputStream out = new FileOutputStream("out.tif");
   parser.writeAsTIFF(out, 72, PDFParser.BLACKANDWHITE);
   out.close();

        The ColorModel determines what type of TIFF is created and what sort of compression is used. For instance, passing in a 2-bit black & white model will result in a black & white TIFF compressed with CCITT Group 4 compression. If the specified model returns Transparency.TRANSLUCENT from ColorModel.getTransparency() then the TIFF will be written with alpha values and created with a transparent background, otherwise the TIFF will have a white background set and will be written without alpha-values. Note that specifying a model that doesn't match the model of the PDF causes color conversions to be applied, which can be quite a slow process.

        You can create TIFF images that have less then all the pages of the PDF by manipulating the the PDF's page list before saving. Say for example you want to create 10 single-page TIFF images from your 10-page PDF document. Here's how: 

         List copy = new ArrayList(pdf.getPages());
 for (int i=0;i<copy.size();i++) {
     pdf.getPages().clear();
     pdf.getPages().add(copy.get(i));
     pdf.writeAsTIFF(out[i], dpi, model);
 }

        Parallel Operation Note: Since 2.10, this method can optionally run multiple threads in parallel to speed up writing. To enable this, set the Threads.TIFF property (typically by setting the org.faceless.pdf2.Threads.TIFF System property) to the number of threads you want to use. Note that each thread may require significant amount of memory - how much depends on the content of each page, so it's very difficult to determine in advance. Carefully tune this value yourself based on the amount of memory in your system and the type of documents you're working with in order to avoid an OutOfMemoryError.

        Parameters:
        out - The OutputStream to write the TIFF to. The stream will be left open on completion
        dpi - how many dots per inch to view the page. A value of 72 gives in 1 point per pixel. As a special hack for those creating Class F TIFF images, a DPI of -1 gives a 204x196 DPI image and -2 gives 204x96 DPI (these added in 2.6.9).
        model - the ColorModel to use to render the images.
        Throws:
        java.io.IOException - if an exception is encountered when writing the TIFF
        See Also:
        BLACKANDWHITE, RGB, CMYK, getBlackAndWhiteColorModel(int)

      • writeAsTIFF

        public void writeAsTIFF​(java.io.OutputStream out,
                        int dpi,
                        java.awt.image.ColorModel model,
                        java.awt.RenderingHints hints)
                 throws java.io.IOException
        As for writeAsTIFF(OutputStream,int,ColorModel) but allows the user to set RenderingHints to control the rendering process.
        Parameters:
        out - The OutputStream to write the TIFF to. The stream will be left open on completion
        dpi - how many dots per inch to view the page. A value of 72 gives in 1 point per pixel. As a special hack for those creating Class F TIFF images, a DPI of -1 gives a 204x196 DPI image and -2 gives 204x96 DPI (these added in 2.6.9).
        model - the ColorModel to use to render the images.
        hints - the RenderingHints to be used when rendering the image, or null to use the defaults.
        Throws:
        java.io.IOException - if an exception is encountered when writing the TIFF
        Since:
        2.6.3
        See Also:
        BLACKANDWHITE, RGB, CMYK, getBlackAndWhiteColorModel(int)

      • getWriteAsTIFFProgress

        public float getWriteAsTIFFProgress()
        Get the progress of the writeAsTIFF() method running in a different thread. The returned value will start at 0 and move towards 1 as the write progresses.
        Since:
        2.8

      • setOutputProfile

        public void setOutputProfile​(OutputProfile profile)
        Set the OutputProfile which should be updated for any extraction or rendering performed with this PDFParser. This will not give the full PDF OutputProfile (for that you should call PDF.getFullOutputProfile()) but it can be used to determine some of which features apply to particular pages.
        Since:
        2.11.25

      • getNumberOfPages

        public int getNumberOfPages()
        Return the number of pages in the document being parsed. Needed for the Pageable interface, this method just calls PDF.getNumberOfPages()
        Specified by:
        getNumberOfPages in interface java.awt.print.Pageable
        Returns:
        the number of pages in the document being parsed

      • getPageFormat

        public java.awt.print.PageFormat getPageFormat​(int pagenumber)
        Returns the PageFormat for the specified page.
        Specified by:
        getPageFormat in interface java.awt.print.Pageable
        Parameters:
        pagenumber - the page to select, from 0 to PDF.getNumberOfPages()
        Returns:
        the PageFormat for page at index pagenumber

      • getPrintable

        public java.awt.print.Printable getPrintable​(int pagenumber)
        Returns the Printable interface for a page. Needed for the Pageable interface, this method just calls getPagePainter(int)
        Specified by:
        getPrintable in interface java.awt.print.Pageable
        Parameters:
        pagenumber - the page to select, from 0 to PDF.getNumberOfPages()
        Returns:
        the Printable object for the specified page

      • getLuceneDocument

        public org.apache.lucene.document.Document getLuceneDocument​(boolean createall,
                                                             boolean createbody,
                                                             boolean createpages)

        Create a Document object for indexing the PDF with the Apache Lucene full-text indexing library. The Document is created with Field objects representing the content of the PDF, the info dictionary, the form and any annotations that may be there. The fields are called:

        bodyThe contents of all the pages in the PDF
        page.nThe contents of page n of the PDF
        info.fieldThe contents of the field field of the Info dictionary - eg. info.Title
        infoThe contents of the whole Info dictionary as one item
        form.fieldThe contents of the field field of the Form
        formThe contents of the whole Form as one item
        annotationsThe contents of all the annotations in the document as one item
        allAll the fields above concatenated into one big field - useful for searching the entire textual content of the PDF in one go

        Because creating indices for all, body and page.n is usually redundant (typically you will want only one of them), they can be turned on or off individually by setting the appropriate parameter to true or false.

        Parameters:
        createall - whether to create an all entry in the index
        createbody - whether to create an body entry in the index
        createpages - whether to create the page.n entries in the index
        Returns:
        a Document suitable for indexing with Lucene.
        Since:
        2.6.2

      • getBlackAndWhiteColorModel

        public static java.awt.image.ColorModel getBlackAndWhiteColorModel​(int threshold)

        Return a Black and White ColorModel that ensures that any colours below the specified threshold are converted to black. This method can be used to convert images that have shades of gray to black and white TIFF images - because it renders the PDF to RGB before manually converting it to Black and White it avoids some of the platform dependent behaviour that arises from using BLACKANDWHITE, and will probably run faster on many operating systems.

        Parameters:
        threshold - a number between 0 and 255 - typically around 128 or so. Higher values result in more black.

        Since 2.11.17 the value "0" can be used to automatically determine the threshold value using Otsu's algorithm. This may be appropriate for poor quality images.

        Note this ColorModel should only by used in the writeAsTIFF(java.io.OutputStream, int, java.awt.image.ColorModel) method - passing it into one of the PagePainter.getImage methods will not work

        Since:
        2.6.8
        See Also:
        BLACKANDWHITE, writeAsTIFF(java.io.OutputStream, int, java.awt.image.ColorModel)

      • getHtmlDerivation

        public HtmlDerivation getHtmlDerivation()
        Return a new HtmlDerivation based on this PDFParser
        Returns:
        the HtmlDerivation
        Since:
        2.28.4