jPDFImages Developer Guide
jPDFImages Developer Guide
jPDFImages is a Java library that integrates seamlessly into your application or applet to allow you to convert PDF documents into images as well as to create or update PDF documents with images. jPDFImages provides the following functions:
- Export PDF document pages as JPEG, TIFF, or PNG images.
- Import images into new or existing documents.
- Export pages to BufferedImage objects for further processing.
- Save to the file system or to Java output streams.
The starting point for using jPDFImages is the com.qoppa.pdfImages.PDFDocument class. This class is used to load PDF documents or to create new documents and then provides methods to import and export images to and from the document.
The class provides three constructors to load PDF files from the file system, a URL or an InputStream. All constructors take an additional parameter, an object that implements IPasswordHandler, that will be queried if the PDF file requires a password to open (called Open or User password). For PDF files that are not currently encrypted, this second parameter can be null:
PDFDocument pdfDoc = new PDFDocument (new URL("http://www.mysite.com/content.pdf"), null);
Once a PDF document has been loaded by instantiating the PDFDocument class, the pages in the document can be exported as images in JPEG, TIFF or binary formats.
//Export the first page in all three formats pdfDopdfDoc.savePagesAsJPEG(0, "c:\\somefile.jpg",150,0.80f); pdfDoc.savePagesAsTIFF(0, "c:\\somefile.jpg",150,TIFFCompression.TIFF_FAX_GROUP4)); pdfDoc.savePagesAsPNG(0, "c:\\somefile.jpg",150f);
Notice that there is a third parameter in all method calls (set to 150 in the sample above). This parameter is the DPI to use when rendering the image. As PDF is a resolution independent format, it can render at any DPI, so this parameter has to be passed into the library. The DPI value will directly affect the width and height of the image.
There is also a fourth parameter when saving a JPEG or a TIFF file. When saving a JPEG file, the fourth parameter is the quality level at which to compress the JPEG image and can range between 0.10 and 1.00. When saving a TIFF file, the fourth parameter determines the TIFF compression to use and it has to be one of the predefined values in the TIFFCompression class.
Additionally, the library can return the image of a page as a BufferedImage object. The method call is as follows:
BufferedImage pageImage = pdfDoc.getPageImage (0, 150);
jPDFImages is also able to import images into new pages in a document. The document can be an existing document or a new document according to the constructor used when creating the PDFDocument object. Once a PDFDocument object has been instantiated, the following code would import images in JPEG, TIFF and PNG formats:
// Create new pages and import the images into them pdfDoc.appendJPEGAsPage ("c:\\somefile.jpg"); pdfDoc.appendTIFFAsPages ("c:\\somefile.tif"); pdfDoc.appendPNGAsPage ("c:\\somefile.png");
When the methods are called, the library will create new pages and size them to the image size, and then import the image into the new pages. The library looks at the DPI value in the image files to determine the size of the page in inches.
Getting / Setting Information about the PDF Document
To get basic information about the loaded PDF document, you need to get the DocumentInfo class accessible through PDFDocument.getDocumentInfo. From this class, you can get and set nformation about the document such as title, author, subject, keywords, etc…
System.out.println(pdfDoc.getDocumentInfo().getTitle()); System.out.println(pdfDoc.getDocumentInfo().getAuthor()); System.out.println(pdfDoc.getDocumentInfo().getKeywords());
Distribution and JAR Files
Only the jPDFImages.jar file is always required for deployment, the remaining jar files are used to work with specific features in some PDF documents:
jPDFImages.jar – This is the main jar file for the component, it is always required.
cmykProfile.jar – No longer needed as of v2091R1. This jar file contains a CMYK profile used to accurately convert CMYK colors to RGB for display. If the file is not present, jPDFImages will revert to a mathematical conversion that is less accurate. This file is necessary if the PDF documents viewed have CMYK content and accurate color conversion is desired.
cmaps.jar – This jar file contains CMaps, used to read and display character encodings used with CJK (Chinese, Japanese, Korean) content.
jai_imageio.jar – This jar file contains Java’s ImageIO image decoders, including a decoder for JPEG 2000 images. This is only used when a document contains JPEG 2000 images.
jai_codec.jar – This jar file contains additional image encoders / decoders for ImageIO, it is necessary when opening and saving TIFF files.