PDFlib 8 Windows COM/.NET Tutorial

7 Importing Images and PDF Pages
PDFlib offers a variety of features for importing raster images and pages from existing
PDF documents, and placing them on the page. This chapter covers the details of dealing
with raster images and importing pages from existing PDF documents. Placing images
and PDF pages on an output page is discussed in Section 7.3, »Placing Images and
imported PDF Pages«, page 192.
Cookbook Code samples regarding image issues can be found in the images category of the PDFlib Cookbook.
7.1 Importing Raster Images
7.1.1 Basic Image Handling
Embedding raster images with PDFlib is easy to accomplish. First, the image file has to
be opened with a PDFlib function which does a brief analysis of the image parameters.
The load_image( ) function returns a handle which serves as an image descriptor. This
handle can be used in a call to fit_image( ), along with positioning and scaling parameters:
image = p.load_image("auto", "image.jpg", "");
if (image == -1)
throw new Exception("Error: " + p.get_errmsg());
p.fit_image(image, 0.0, 0.0, "");
p.close_image(image);
The last parameter of fit_image( ) function is an option list which supports a variety of
options for positioning, scaling, and rotating the image. Details regarding these options
are discussed in Section 7.3, »Placing Images and imported PDF Pages«, page 192.
Cookbook A full code sample can be found in the Cookbook topic images/starter_image.
Re-using image data. PDFlib supports an important PDF optimization technique for
using repeated raster images. Consider a layout with a constant logo or background on
multiple pages. In this situation it is possible to include the actual image data only once
in the PDF, and generate only a reference on each of the pages where the image is used.
Simply load the image file once, and call fit_image( ) every time you want to place the
logo or background on a particular page. You can place the image on multiple pages, or
use different scaling factors for different occurrences of the same image (as long as the
image hasn’t been closed). Depending on the image’s size and the number of occurrences,
this technique can result in enormous space savings.
Scaling and dpi calculations. PDFlib never changes the number of pixels in an imported
image. Scaling either blows up or shrinks image pixels, but doesn’t do any downsampling
(the number of pixels in an image will always remain the same). A scaling factor of
1 results in a pixel size of 1 unit in user coordinates. In other words, the image will be imported
with its native resolution (or 72 dpi if it doesn’t contain any resolution informa-
7.1 Importing Raster Images 179