PDFLib: Images

Last time we discussed how to create textflows in order to arrange blocks of text where you would like them on a page.  Now that we can place text where we want, we are going to want to be able to place images on our PDFs.  Whether trying to place a company logo or arranging user uploaded images on a form there are many situations where we are going to want to place images both in fixed and dynamic positions. 

We are going to start with the base code from the last post so that we can set up the basic parameters for the PDF image placing program. It should look like the following.


Now we are going to want to load the image that we would like to place.  I am using a simple jpg of the number 1 in a circle that is located in my current Windows user’s “Pictures” folder.


If you remember from the previous post, the load_font method creates an integer reference to the font that is loaded internally in the pdf object.  The load_image function works in the same way.  When we want to place that image later we will do so by calling this reference.  The following lines will fit the image on the page we have created then close and save the pdf.

Now when we run the program we will get an image with its bottom left corner placed at the specified coordinates (35, 657).  Example is below.  Note that since I am not supplying anything to the optlist of the fit_image method I am not scaling or modifying the image in any way, just placing it.

One difference between a textflow reference and an image reference is that an image can be placed on a page more than once.  Below is an example where I am placing an image on the page four times.  In each call to fit_image I am specifying a different orientate parameter to the optlist.


As you can see by the x parameters of the fit_image methods it can be difficult to figure out where to place an image if you don’t already know the exact size it will be on the page. Fortunately, PDFLib gives us several options for scaling and fitting these images.

By passing the boxsize parameter to the optlist of fit_image we can specify the size of the box that we would like to fit our image in.  By specifying the box size as 50 by 50 we effectively shrink the image.  However note that it shrinks because the fitmethod is auto.  Other fitmethods have different behaviors and if we had specified nofit as the fitmethod the images would not be changed at all.

Another important option is the position option.  Up until now we have been using the default for position which is {left bottom}.  This means that the coordinate supplied to the fit_image method corresponds to the bottom left of the fitbox for the image.  The position option can be controlled with the vertical keywords "top", "center", and "bottom".  We can control horizontal position with "left", "center", and "right".  Alternatively we can control the position in the fitbox with numbers ranging 0 to 100.  The option {0 0} corresponds to bottom left and {100 100} corresponds to top right.  As an example {0 50} would be equivalent to {left center}.

 If we wanted to center an image on the top portion of the page we could do the following.

The x value of 306 is the center of a letter sized page and the y value of 757 is the letter size height of 792 minus a 35 point margin.  By setting the position option to {center top} we specify that the center and top of the image is supposed to be at that coordinate.

Things work slightly differently if we want to specify a boxsize.  If a boxsize is specified then the x and y coordinates will always refer to the bottom left coordinates of that box.  The position of the image is then based on the position of the fitbox and not the reference point.


We choose a boxsize of 150 by 150.  We subtract 75 (half of 150) from the previous x coordinate and 150 from the previous y coordinate.  This gives us a {left bottom} coordinate that will still have its {center top} coordinate in the same position as before.  We add the showborder= true option to see what the fitbox looks like.  Since we specify nothing in the fitmethod option we are using the default of nofit.

Below we can see what happens when we change the option to {center bottom}.  The fitbox does not move but the image moves within it.


We now know how to place images on a pdf.  We can orientate the image, constrain it, size it, and scale it.  Using this information we can now make almost any pdf we need.  Next time, we will discuss the final major piece: tables.