Images Support

The PDFWriter library supports embedding TIFF, PNG and JPG Images as well as PDF pages. There are high level methods, that are generic for any image type. In addition there are lower level methods, allow more advanced usages of the images (or PDF document). In this section we will look into the high level method

The method of using the embedding capability is by generating either an Image or Form XObject with the PDFWriter object, and later place it in a content stream, either of a page or a Form XObject, by using the content stream Do command. It is also possible to first use the image, and only later embed its content with Forward Referencing capability.

Usage Example

The basic placement of images is done by using the ContentContext (of either page of form) DrawImage method. The following shows an example:

The following is a typical usage of the image embedding infrastracture (status checks removed for faster reading):

pdfWriter.StartPDF("HighLevelImages.PDF",ePDFVersion13);
PDFPage* page = new PDFPage();
page->SetMediaBox(PDFRectangle(0,0,595,842));
PageContentContext* cxt = pdfWriter.StartPageContentContext(page);
cxt->DrawImage(10,10,"soundcloud_logo.jpg"));
pdfWriter.EndPageContentContext(cxt);
pdfWriter.WritePageAndRelease(page);
pdfWriter.EndPDF();

The DrawImage method is called to place the image at soundcloud_logo.jpg at 10,10. The same can be done with tiff images and pdf pages.

h1. Image placement options

The DrawImage method has an optional 4th parameter. This parameter is a struct of type ImageOptions. The following code shows some usages of this struct:

//usage 1
AbstractContentContext::ImageOptions opt1;
opt1.imageIndex = 2;
cxt->DrawImage(10,10,"multipage.tif",opt1);
//usage 2
AbstractContentContext::ImageOptions opt2;
opt2.transformationMethod = AbstractContentContext::eMatrix;
opt2.matrix[0] = opt2.matrix[3] = 0.25;
cxt->DrawImage(10,10,"soundcloud_logo.jpg",opt2);
//usage 3
AbstractContentContext::ImageOptions opt3;
opt3.transformationMethod = AbstractContentContext::eFit;
opt3.boundingBoxHeight = 100;
opt3.boundingBoxWidth = 100;
cxt->DrawImage(0,0,"XObjectContent.PDF",opt3);
//usage 4
opt3.fitProportional = true;
cxt->DrawImage(100,100,"XObjectContent.PDF",opt3);

The first usage places the 3rd image in the multipage.tiff file at 10,10. It does so by setting the imageIndex property of the options structure.
The second usage places soundcloud_logo.jpg at 10,10, but at quarter of its size. It does so by setting a transfromation on the image, using a matrix that is [0.25,0,0,0.25,0,0]. It achieves that by setting the transformationMethod property to eMatrix, and setting the matrix property to the desired matrix. The third usage shows the constraining abilities of DrawImage. This time the options structure is instructed to constrain the image to a 100X100 rectangle. It does so by setting the transformationMethod to eFit, and setting the boundingBoxHeight and boundingBoxWidth to the desired measurements. The fourth usage shows how the constraining ability may be used while respecting the image aspect ratio. To fit the image propertionally simply set the fitProportional property to true.

You can see more sample code using this method here.

Getting images measurements

Sometimes you may require the image measurements. For images supported by the library you can use the GetImageDimensions method of PDFWriter. For example:

DoubleAndDoublePair jpgDimensions = pdfWriter.GetImageDimensions("soundcloud_logo.jpg");

jpgDimensions will now have a pair. The first of the pair is the width, the second is the height.

You can see more sample code using this method here.

Further Reading

in TIFF Images Support, PNG Images Support and JPG Images Support you can find details on how to use the more advanced options around image embedding. for PDF embedded look in here - PDF Embedding