Working with images¶
PDFs embed images as binary stream objects within the PDF’s data stream. The stream object’s dictionary describes properties of the image such as its dimensions and color space. The same image may be drawn multiple times on multiple pages, at different scales and positions.
In some cases such as JPEG2000, the standard file format of the image is used verbatim, even when the file format contains headers and information that is repeated in the stream dictionary. In other cases such as for PNG-style encoding, the image file format is not used directly.
pikepdf currently has no facility to embed new images into PDFs. We recommend img2pdf instead, because it does the job so well. pikepdf instead allows for image inspection and lossless/transcode free (where possible) “pdf2img”.
pikepdf also cannot extract vector images, that is images produced through a combination of PDF drawing commands. These are produced by a content stream, or sometimes a Form XObject. Unfortunately there may not be anything in the PDF that indicates a particular sequence of operations produces an image, and that sequence is not necessarily all in the same place. To extract a vector image, use a PDF viewer/editor to crop to that image.
Playing with images¶
pikepdf provides a helper class
PdfImage for manipulating
images in a PDF. The helper class helps manage the complexity of the image
In : from pikepdf import Pdf, PdfImage, Name In : example = Pdf.open('../tests/resources/congress.pdf') In : page1 = example.pages In : list(page1.images.keys()) Out: ['/Im0'] In : rawimage = page1.images['/Im0'] # The raw object/dictionary In : pdfimage = PdfImage(rawimage) In : type(pdfimage) Out: pikepdf.models.image.PdfImage
In Jupyter (or IPython with a suitable backend) the image will be displayed.
You can also inspect the properties of the image. The parameters are similar to Pillow’s.
In : pdfimage.colorspace Out: '/DeviceRGB' In : pdfimage.width, pdfimage.height Out: (1000, 1520)
.height are the resolution of the image in pixels, not
the size of the image in page coordinates. The size of the image in page
coordinates is determined by the content stream.
Extracting images is straightforward.
extract images to a specified file prefix. The extension is determined while
extracting and appended to the filename. Where possible,
writes compressed data directly to the stream without transcoding. (Transcoding
lossy formats like JPEG can reduce their quality.)
In : pdfimage.extract_to(fileprefix='image') Out: 'image.jpg'
It also possible to extract to a writable Python stream using
You can also retrieve the image as a Pillow image (this will transcode):
In : type(pdfimage.as_pil_image()) Out: PIL.JpegImagePlugin.JpegImageFile
Another way to view the image is using Pillow’s
Not all image types can be extracted. Also, some PDFs describe an image with a mask, with transparency effects. pikepdf can only extract the images themselves, not rasterize them exactly as they would appear in a PDF viewer. In the vast majority of cases, however, the image can be extracted as it appears.
This simple example PDF displays a single full page image. Some PDF creators
will paint a page using multiple images, and features such as layers,
transparency and image masks. Accessing the first image on a page is like an
HTML parser that scans for the first
<img src=""> tag it finds. A lot
more could be happening. There can be multiple images drawn multiple times
on a page, vector art, overdrawing, masking, and transparency. A set of
resources can be grouped together in a “Form XObject” (not to be confused
with a PDF Form), and drawn at all once. Images can be referenced by
Replacing an image¶
In this example we extract an image and replace it with a grayscale equivalent.
In : import zlib In : rawimage = pdfimage.obj In : pillowimage = pdfimage.as_pil_image() In : grayscale = pillowimage.convert('L') In : grayscale = grayscale.resize((32, 32)) In : rawimage.write(zlib.compress(grayscale.tobytes()), filter=Name("/FlateDecode")) In : rawimage.ColorSpace = Name("/DeviceGray") In : rawimage.Width, rawimage.Height = 32, 32
Notes on this example:
It is generally possible to use
zlib.compress()to generate compressed image data, although this is not as efficient as using a program that knows it is preparing a PDF.
In general we can resize an image to any scale. The PDF content stream specifies where to draw an image and at what scale.
This example would replace all occurrences of the image if it were used multiple times in a PDF.
Removing an image¶
The easy way to remove an image is to replace it with a 1x1 pixel transparent image.
A transparent image can be created by setting the
/ImageMask to true.
Note that, if an image is referenced on multiple pages, this procedure only updates the occurrence on one page. If all references to the image are deleted, it should not be included in the output file.
In : pdf = pikepdf.open('../tests/resources/sandwich.pdf') In : page = pdf.pages In : image_name, image = next(iter(page.images.items())) In : new_image = pdf.make_stream(b'\xff') In : new_image.Width, new_image.Height = 1, 1 In : new_image.BitsPerComponent = 1 In : new_image.ImageMask = True In : new_image.Decode = [0, 1] In : page.Resources.XObject[image_name] = new_image