Chapter 17: PDF to Image Conversion

Starting with Version 2.0, AspPDF is capable of converting a PDF page to an image via the method PdfPage.ToImage.

The ToImage method returns an instance of the PdfPreview object which performs the PDF-to-image conversion and generates the page image. The image can then be saved to disk, memory or an HTTP stream. The ToImage method accepts an optional PdfParam object or parameter string argument.

PdfPreview generates images in PNG format. This versatile image format is ideal for the task since it supports true colors and uses artifact-free lossless compression. PNG format is fully supported by all major browsers.

The following code sample generates a PDF document from a URL, saves/reopens it, and converts page 1 of the document to an image. The saving/reopening step is necessary because the PdfPage.ToImage method can only be used on existing, not new, documents.

Click on the links below to run this code sample:

http://localhost/asppdf/manual_17/17_pdftoimage.asp http://localhost/asppdf/manual_17/17_pdftoimage.aspx

By default, the resultant image's width and height in pixels match the page's width and height in user units. For example, a standard US Letter page (8.5 x 11 inches or 612 x 792 user units) becomes a 612 x 792 pixel image (in case of a landscape-oriented page, the width and height of the image matches the height and width of the page, respectively.)

To set the page image to a desired size, the ResolutionX and ResolutionY parameters to the ToImage method should be used. These parameters are 72 (dpi) by default. Note that in the code sample above, these parameters are both set to 36 which makes the image dimensions half of what they would be by default. Setting these parameters to a number larger (smaller) than 72 makes the resultant image proportionally larger (smaller). The ResolutionX and ResolutionY values usually equal each other to avoid a distortion in the image's aspect ratio.

To obtain the pixel dimensions of the resultant image, use the PdfPreview object's properties Width and Height.

Page images generated by the ToImage method are always in the RGB color space, but the original PDF being converted to an image may contain images and graphics in the CMYK color space, in which case they have to be converted to RGB.

To achieve reasonably good color reproduction, the ToImage method performs a series of complex non-linear color transformations based on profiles, the standard color space definitions established by the International Color Consortium (ICC). Profile-based CMYK-to-RGB conversion is a fairly slow process. If your PDF document contains large high-resolution CMYK images and performance is of essence, use the parameter FastCMYK=True which invokes a simple linear formula for CMYK-to-RGB conversion and offers some performance improvement at the expense of color-reproduction quality.

The following images demonstrate the effect of the FastCMYK parameter:

Original Document:

FastCMYK=False (default):

FastCMYK=True:

The majority of PDF documents are self-sufficient since they embed all the fonts they use. Documents like that make it easy and straightforward for PDF viewers such as Acrobat Reader and PDF-to-image converters such as AspPDF to do their jobs.

Some PDF documents, however, only reference font names and do not embed the fonts themselves. While large applications such as Acrobat have the luxury of being deployed with a whole library of fonts they can use, AspPDF only contains the 14 required standard PDF fonts in it and must rely on the fonts already installed on the system in case the PDF document does not embed a certain font. Therefore, not every document can be rendered properly.

To help diagnose such issues, the PdfPreview object provides the property Log that returns a string of errors encountered during the PDF-to-image conversion process. Most of these errors are usually font-related. Error entries are separated by a pair of CRLFs. To enable error logging, the parameter Debug=True must be used:

A typical log string may look as follows:

A PDF page may contain a /Rotate attribute set to 90, 180 or 270 (degrees), which makes this page appear in the landscape mode or upside-down. By default, the ToImage method takes the Rotate value into account to orient the image appropriately. If, for whatever reason, the Rotate value needs to be ignored, the parameter IgnoreRotate should be set to True.

Also, some PDF pages contain /MediaBox and /CropBox attributes which are different from each other. By default, the ToImage method uses the CropBox attribute to calculate the dimensions of the resultant image, which is consistent with the behavior of all major PDF viewers. If, for whatever reason, the MediaBox attribute needs to be used instead (which usually covers a larger area than the CropBox), the parameter IgnoreCropBox should be set to True. This may cause the image to include areas of the page that are normally invisible when viewed in a PDF viewer.

As an additional bonus, the PdfPreview object is capable of extracting images from a PDF page. The method PdfPreview.ExtractImage returns a new instance of the PdfPreview object representing an image specified by a 1-based index. This image can then be saved the regular way, via the methods Save, SaveToMemory or SaveHttp. If the specified index exceeds the number of images on the page, ExtractImage returns Nothing (or null in C#.)

The images are always saved as PNGs as this is PdfPreview's format of choice.

The following code snippet opens a PDF documents and saves all of the images from page 1 to disk:

As of Version 3.6, AspPDF is capable of replacing images in an existing PDF document with other images or graphics. The image extraction and image replacement features can be used jointly to shrink the overall size of a PDF document by substituting its high-resolution images with their lower-resolution versions. Image replacement is covered in detail in Section 17.8 below.

As of Version 2.1, the PdfPreview object offers automatic printing functionality via the method SendToPrinter. This method sends the image of a page contained in this PdfPreview object to a printer.

The SendToPrinter method accepts two arguments: the local or network name of the printer and, optionally, a parameter list adjusting the appearance of the printout. As of Version 2.6.0.3, if the printer name is set to an empty string, the default printer name for the current machine is used.

The print quality is determined by the resolution of the image being printed. It is therefore recommended that the ResolutionX and ResolutionY parameters to the ToImage method be set to at least 300 or, better yet, 600.

By default, the SendToPrinter method prints the image as it is, without stretching it. If the parameter Stretch is set to True, the image is stretched to cover the entire print area. Additionaly, you can use the parameters ScaleX and ScaleY to scale the image up or down. For example, the values "ScaleX = 0.5; ScaleY= 0.5" scales the image down by 50%.

The following code sample sends page 2 of c:\path\document.pdf to the printer. The image is stretched to cover the entire print area.

You may encounter the error "Access is denied" when attempting to send the image to a network printer. To avoid the error, you need to impersonate an interactive user account with the LogonUser method of the PdfManager object, as follows:

The LogonUser method was added in Version 2.1 as well. The first argument is a Windows domain and can be an empty string. The 2nd and 3rd arguments are the username and password of the account to be impersonated. The 4th argument is the login type and usually omitted.

17.6.2 Document Printing

As of Version 2.7, the page printing functionality described in the previous sub-section has been expanded to support the printing of an entire document or any portion thereof, in both simplex (one-sided) and duplex (double-sided) modes.

In AspPDF 2.7+, the PdfDocument object has been given its own SendToPrinter method which sends the entire document (or an arbitrary set of pages) to the printer as opposed to just an individual page. Internally, the PdfDocument.SendToPrinter method iterates through the pages of the document, creates PdfPreview objects for each of them and sends the page images to the printer one by one. If your printer supports duplex printing, this method can optionally print double-sided documents in both long-edge and short-edge binding modes.

The PdfDocument.SendToPrinter method expects the same arguments as its PdfPreview.SendToPrinter counterpart: the printer name (local or network) and a list of parameters. In addition to the parameters described above, this method also accepts parameters controlling the duplex mode, as well as the page ranges to be printed.

The Duplex parameter controls duplex printing. Duplex=1 enables duplex printing in the regular long-edge-binding mode, and Duplex=2 in the short-edge binding mode. If this parameter is set to 0 or omitted, the regular simplex (one-sided) printing is used.

The From1/To1, From2/To2, ..., FromN/ToN pairs of parameters specify the ranges of pages to be printed. Page indices are 1-based. If the specified ranges overlap, the overlapping pages will be printed multiple times. By default, the entire document is printed.

The following code prints pages 2, 5, and 7-10 of a document in a duplex long-edge-binding mode:

As of Version 2.9, the PdfDocument.SendToPrinter method also supports printer tray (or bin) selection via the Tray parameter. The Microsoft documentation defines the following values for this parameter:

First (1), upper (1), only one (1), lower (2), middle (3), manual (4), envelope (5), envelope manual (6), auto (7), tractor (8), small format (9), large format (10), large capacity (11), cassette (14), form source (15), last (15).

However, many printers use driver-specific tray values that start at 256 and up. The correct Tray values for such printers should be determined by trial and error.

As of Version 3.2.0.2, the PdfDocument.SendToPrinter method also supports printing multiple copies via the Copies parameter (1 by default.)

As of Version 3.4.0.3, the Collate parameter (False by default) is supported, which enable collation if set to True. For example, if you print two copies of a three-page document and you choose not to collate them, the pages print in this order: 1, 1, 2, 2, 3, 3. If you choose to collate, the pages print in this order: 1, 2, 3, 1, 2, 3.

Also, Version 3.4.0.3 adds two more parameters to support label printers: PaperWidth and PaperHeight. These parameters specify the paper width and height in tenths of a millimeter. For example, if your label printer uses 2 ⁵/₁₆" x 4" labels, the PaperWidth and PaperHeight parameters should be set to 590 and 1020, respectively. If these parameters are not used, a document may come out shrunk when printed on a label printer.

As of version 2.8, the PdfPreview object has been expanded to perform yet another useful task: extracting text strings from the document along with their respective coordinates. This feature enables you to know exactly where on the page a particular text item is. Regular (coordinate-less) text extraction is described in Section 9.4 - Content Extraction.

PdfPreview's TextItems property returns a collection of objects, each encapsulating the text fragment and its respective coordinates and dimensions. To avoid adding a new object to AspPDF's already populous object diagram, we have retrofitted the PdfRect for the task by adding a new Text property to this object which returns the actual fragment of text in Unicode format. The existing PdfRect properties, Left, Bottom, Width and Height, return the coordinates of the lower-left corner and horizontal and vertical dimensions of the fragment, respectively.

To populate the TextItems collection, the PdfPage.ToImage method must be called with the parameter ExtractText set to a non-zero value. ExtractText can be a combination (sum) of the following flags:

• Bit 1 (1): Enables text extraction. If this flag is not set, text extraction is not performed and the TextItems collection is empty.
• Bit 2 (2): Sorts text fragments in the order from top to bottom, and from left to right. If this flag is not set, the text fragments in the TextItems collection appear in an arbitrary order.
• Bit 3 (4): Glues adjacent text fragments together. If this flag is not set, a single text fragment may contain a single word, a part of the word or even a single character. Setting this flag usually combines all or most text fragments of a paragraph line into a single long string. For this flag to work, bit 2 must also be set.
• Bit 4 (8): Does not glue adjacent text fragments if there is a space character separating them. For this flag to work, flags 2 and 3 must also be set.

The following code sample draws red outlines around all text fragments it finds on a page, as well as the order in which each fragment is encountered in the collection (as shown on the image below.)

Click on the links below to run this code sample:

http://localhost/asppdf/manual_17/17_extracttext.asp http://localhost/asppdf/manual_17/17_extracttext.aspx

17.8.1 Feature Overview

As of Version 3.6, AspPDF is capable of replacing images in an existing PDF documents with other images or graphics. This feature is useful, among other things, for reducing the overall size of a PDF document by replacing its high-resolution images with their lower-resolution versions.

The image replacement feature is built on top of the document stitching functionality described in Section 14.1. Consider the following code:

This code creates an empty new document, Doc1, and appends Doc2 to it, thus creating a document almost completely identical to Doc2. All items comprising Doc2 are copied to Doc1 during the appending operation, including images.

If a certain image in Doc2 needs to be replaced with another image, the new image needs to be opened via the Doc1 object's OpenImage method, and a mapping between the new and old images needs to be added with the method AddImageReplacement (introduced in Version 3.6):

This code copies all items from Doc2 to Doc1 except the image item specified by imageID. That item is not copied and the Image object is used in its place.

The 1st argument to the AddImageReplacement method specifies the internal ID of the image item to be replaced within Doc2, and the 2nd argument is an instance of the PdfImage object to replace it with. The 2nd argument can also be an instance of the PdfGraphics object if the image needs to be replaced with a graphics as opposed to another image. The method AddImageReplacement can be called multiple times if multiple images need to be replaced.

An image ID is a string containing two numbers separated by an underscore, such as "123_0". The 2nd number is usually 0. Image IDs can be obtained via the Log property of the object representing an extracted image, or via the PdfPreview.ImageItems collection, as described below.

17.8.2 Combining Image Extraction and Image Replacement

The following code sample replaces all images in a PDF document with their resized versions. Image resizing is performed with the help of AspJpeg, another Persits component which can be downloaded from www.aspjpeg.com.

First, the code sample extracts all images from the document using the procedure described in Section 17.5 earlier in this chapter. The extracted images are then resized by 50%. Their names and image IDs are recorded in arrays. The image ID of an extracted image is returned by the Log property of the PdfPreview representing this extracted image.

Lastly, the AddImageReplacement method is called for every resized image in the array, followed by a call to AppendDocument and Save to complete the image replacement operation.

Click on the links below to run this code sample:

http://localhost/asppdf/manual_17/17_imagereplacement.asp http://localhost/asppdf/manual_17/17_imagereplacement.aspx

This code sample reduces the size of the PDF document twoimages.pdf (included in the installation) from 117 KB to 30 KB.

17.8.3 Obtaining Image Information

In addition to the AddImageReplacement method, AspPDF 3.6 also offers a way to obtain a list of images in a PDF document, including information about each image's pixel size, displacement, scaling, rotation, image ID and coordinate transformation matrix, without actually performing image extraction. This information is obtained via the PdfPreview object's ImageItems property which returns a collection of PdfRect objects, each representing an image within the PDF document. This collection is similar to that returned by the TextItems property described above.

To populate the ImageItems collection, the PdfPage.ToImage method must be called with the parameter ImageInfo set to True.

The width and height of the image are returned by the PdfRect properties Right and Top, respectively. The image ID is returned by the PdfRect property Text.

The displacement, scaling, rotation and coordinate transformation matrix values are encapsulated in a PdfParam object returned by the PdfRect property ImageInfo (introduced in Version 3.6). For example, the following code snippet displays the object ID, width, height and scaling factors for all images of a document:

The full list of values encapsulated in the PdfParam object returned by the Rect.ImageInfo property is as follows:

Access to this information can be quite useful when an image needs to be replaced with a graphics, as discussed below.

17.8.4 Replacing Images with Graphics

As shown in the Section 17.8.2 code sample, replacing images with other images with the same aspect ratio is very straightforward. However, if the aspect ratio of the replacement image is different from that of the original image, a vertical or horizontal distortion will occur as the new image will be stretched to fill the area occupied by the old image. To avoid distortions, an image can be replaced with a graphics as opposed to another image. The graphics may have arbitrary content, including other images, drawings, text, etc.

The following code sample replaces all images in a PDF document with a red image with the caption "Image Removed" on a yellow background filling the entire area of the original image. The red image is not stretched in any way and centered inside the yellow area.

Click on the links below to run this code sample:

http://localhost/asppdf/manual_17/17_image2graphics.asp http://localhost/asppdf/manual_17/17_image2graphics.aspx