JPG Images Support

JPG Images support is provided via the PDF DCT Decode filter.
No transcoding is done, only a direct pass-through of the image information to an images stream. This means that the implementation is quick, and running time is quick. It also means whatever implementation requirements that the DCT filter has, apply here as well.

Usage

To use the JPG Image support call either one of the following methods:

• PDFImageXObject* PDFWriter::CreateImageXObjectFromJPGFile(const string& inJPGFilePath)

This method writes the JPG Image as an xobject image to the PDF stream. it returns a reference object you can use for adding an image reference (and usage) to a content stream, and content resources. The reference object hold both the image Object ID and JPG header information on physical measurements of the JPG image. Note that the input file path is encoded using UTF8.

Note that when using the Do Command (of the content stream) to draw the image there is no native scale. so the image will be drawn to a 1X1 box. to set it to the right dimensions use whatever algorithm your application uses for determine which header information to use with the JPG header information given by the returned reference object. Note that a lot of applications have different decisions on what is the physical size of an image…especially if no such information exists (a caveat in the creation of digital cameras).

Make sure to use this method before writing your content stream, or pause writing to it before creating the image object. otherwise the object will be written in the context of the content stream and the PDF will be invalid.

• PDFFormXObject* PDFWriter::CreateFormXObnjectFromJPGFile(const string& inJPGFilePath)

This method writes the JPG image as a form XObject, sizing the image in accordance to it’s JFIF,Exif or Photoshop BIM physical information. The sizing algorithm first looks for JFIF header and uses its physcial dimensions information, otherwise EXIF is looked for with the same purpose in mind, and if not found Photoshop header is looked for. If none exists or holds physical information the image is sized according to pixel width and height.

See JPGImageTest.cpp for a usage sample

Note that both image and form creation methods have overrides receiving ObjectIDType as input. These variants are to be used when forward referencing is sought after (first usage of image/form, then creation of them). consult Forward Referencing for information.

Advanced usage

most of the work is done in the JPGImageHandler class. you can access the working instances via DocumentConext::GetJPEGImageHandler method. it offers one interesting service (on top of image/form xobject creation) which is to provide Image physical information.

BoolAndJPEGImageInformation RetrieveImageInformation(const string& inJPGFilePath)
Retrieve image information about the JPG file as specified by the input path. the information provided is about physical information, sample width and height, and the number of image components (which determines the color space to use). You can use it to provide size scaling to the image.
This method is also used by the image creation methods, and it has a repository for previous calls on the same image path. hence – if the call is used on an images previously parsed, there will be no extra-parsing. similarly, if this method is called by the user, later calls on the same image will use the information already parsed.

A bit about implementation

The implementation is fairly trivial, as most of the “real” work is done by the native DCT filter of PDF. The code parses the image for the minimum required information to create an Image XObject, and some physical size information. The Form variant of the method uses
a simple algorithm to determine the size, preferring JFIF information over Exif. Exif is preferred over Photoshop BIM information. if neither is found the samples are used for determining the physical width, using 1 pixel = 1/72 inch as measure.

Note that image input can come from any stream, and not just files. For a discussion of custom stream input see Custom input and output