Examining a page¶
Pages are dictionaries¶
In PDFs, the main data structure is the dictionary, a key-value data
structure much like a Python dict or attrdict. The major difference is
that the keys can only be names, while values can be any type, including
other dictionaries.
PDF dictionaries are represented as pikepdf.Dictionary, and names
are of type pikepdf.Name. A page is just another dictionary, with a
few required fields that give it special status as a page.
A pikepdf.Name that is, usually, an ASCII-encoded string beginning with
“/” followed by a capital letter.
In [1]: from pikepdf import Pdf
---------------------------------------------------------------------------
ModuleNotFoundError Traceback (most recent call last)
<ipython-input-1-5d5e0079e556> in <module>()
----> 1 from pikepdf import Pdf
ModuleNotFoundError: No module named 'pikepdf'
In [2]: example = Pdf.open('../tests/resources/congress.pdf')
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-2-5533e8a6eb0a> in <module>()
----> 1 example = Pdf.open('../tests/resources/congress.pdf')
NameError: name 'Pdf' is not defined
In [3]: page1 = example.pages[0]
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-3-1efa67009061> in <module>()
----> 1 page1 = example.pages[0]
NameError: name 'example' is not defined
In [4]: page1
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-4-2932c8ee7072> in <module>()
----> 1 page1
NameError: name 'page1' is not defined
Item and attribute notation¶
Dictionary keys may be looked up using keys (page1['/MediaBox']) or
attributes (page1.MediaBox). The two conventions are equivalent.
In [5]: page1.MediaBox
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-5-7ea5a0262964> in <module>()
----> 1 page1.MediaBox
NameError: name 'page1' is not defined
In [6]: page1['/MediaBox']
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-6-e9508eb159e8> in <module>()
----> 1 page1['/MediaBox']
NameError: name 'page1' is not defined
By convention, pikepdf uses attribute notation for keys in the PDF specification and item notation for internal names within a PDF. For example
In [7]: page1.Resources.XObject['/Im0']
Here '/Im0' is an arbitrary name generated by the program that produced this
PDF, rather than a name in the specification like Resources and XObject.
Item notation here would be quite cumbersome:
['/Resources']['/XObject]['/Im0'] (not recommended).
Attribute notation is convenient, but not robust if elements are missing. For
elements that are not always present, you can use .get(), which behaves like
dict.get() in core Python. A library such as glom might help when working with complex
structured data that is not always present.
repr() output¶
Returning to the page’s output:
In [8]: page1
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-8-2932c8ee7072> in <module>()
----> 1 page1
NameError: name 'page1' is not defined
The angle brackets in the output indicate that this object cannot be
constructed with a Python expression because it contains a reference. When
angle brackets are omitted from the repr() of a pikepdf object, then the
object can be replicated with a Python expression, such as
eval(repr(x)) == x.
In Jupyter and IPython, pikepdf will instead attempt to display a preview of
the PDF page. An explicit repr(page) will show the text representation.
This page’s MediaBox is a direct object. The MediaBox describes
the size of the page in PDF coordinates (1/72 inch multiplied by the value of
the page’s /UserUnit, if present).
In [9]: import pikepdf
---------------------------------------------------------------------------
ModuleNotFoundError Traceback (most recent call last)
<ipython-input-9-7b85755da69e> in <module>()
----> 1 import pikepdf
ModuleNotFoundError: No module named 'pikepdf'
In [10]: page1.MediaBox
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-10-7ea5a0262964> in <module>()
----> 1 page1.MediaBox
NameError: name 'page1' is not defined
In [11]: pikepdf.Array([ 0, 0, 200, 304 ])
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-11-5d6adf9def9d> in <module>()
----> 1 pikepdf.Array([ 0, 0, 200, 304 ])
NameError: name 'pikepdf' is not defined
The page’s /Contents key contains instructions for drawing the page content.
Also attached to this page is a /Resources dictionary, which contains a
single XObject image. The image is compressed with the /DCTDecode filter,
meaning it is encoded with the DCT, so it is
a JPEG. [1]
| [1] | Without the JFIF header. |
Viewing images¶
pikepdf provides a helper class PdfImage for manipulating
PDF images.
In [12]: from pikepdf import PdfImage
---------------------------------------------------------------------------
ModuleNotFoundError Traceback (most recent call last)
<ipython-input-12-f8bdf5bb0790> in <module>()
----> 1 from pikepdf import PdfImage
ModuleNotFoundError: No module named 'pikepdf'
In [13]: pdfimage = PdfImage(page1.Resources.XObject['/Im0'])
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-13-bc8e4fd9df40> in <module>()
----> 1 pdfimage = PdfImage(page1.Resources.XObject['/Im0'])
NameError: name 'PdfImage' is not defined
In [14]: pdfimage
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-14-d23167302873> in <module>()
----> 1 pdfimage
NameError: name 'pdfimage' is not defined
In Jupyter (or IPython with a suitable configuration) the image will be displayed.
You can also inspect the properties of the image. The parameters are similar to Pillow’s.
In [15]: pdfimage.colorspace
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-15-b3fb3c2eee89> in <module>()
----> 1 pdfimage.colorspace
NameError: name 'pdfimage' is not defined
In [16]: pdfimage.width, pdfimage.height
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-16-c9cea2c5b1d4> in <module>()
----> 1 pdfimage.width, pdfimage.height
NameError: name 'pdfimage' is not defined
Note
.width and .height are the resolution of the image in pixels, not
the size of the image in page coordinates.
Extracting images¶
Extracting images is straightforward. extract_to() will
extract images to streams, such as an open file. Where possible, extract_to
writes compressed data directly to the stream without transcoding. The return
value is the file extension that was extracted.
In [17]: pdfimage.extract_to(stream=open('file.jpg', 'w'))
You can also retrieve the image as a Pillow image:
In [18]: pdfimage.as_pil_image()
Note
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
multiple pages.
Replacing an image¶
See test_image_access.py::test_image_replace.