Inspecting the Links of a Page

Here is how to get all links and their types:

>>> # get all links on a page
>>> links = page.getLinks()

links is a Python list of dictionaries. For details see Page.getLinks().

Rendering a Page

This example creates an image out of a page’s content:

>>> pix = page.getPixmap()

Now pix is a Pixmap object that contains an RGBA image of the page, ready to be used. This method offers lots of variations for controlling the image: resolution, colorspace, transparency, rotation, mirroring, shifting, shearing, etc.

Saving the Page Image in a File

We can simply store the image in a PNG file:

>>> pix.writePNG("test.png")

Displaying the Image in Dialog Managers

We can also use it in GUI dialog managers. Pixmap.samples represents the area of bytes of all the pixels as a Python bytes object. Here are two examples, find more here.

wxPython:

>>> bitmap = wx.BitmapFromBufferRGBA(pix.width, pix.height, pix.samples)

Tkinter:

>>> # the following requires: "from PIL import Image, ImageTk"
>>> img = Image.frombytes("RGBA", [pix.width, pix.height], pix.samples)
>>> photo = ImageTk.PhotoImage(img)

Now, photo can be used as an image in TK.

Extracting Text

We can also extract all text of a page in one chunk of string:

>>> text = page.getText(type)

Use one of the following strings for type:

• "text": (default) plain text with line breaks. No formatting, no text position details.
• "html": creates a full visual version of the page including any images, which can be displayed in browsers.
• "json": same information level as HTML. Use a JSON module to interpret.
• "xhtml": text information level as the TEXT version, but includes images and can also be displayed in browsers.
• "xml": contains no images, but full position and font information about each single text character. Use an XML module to interpret.

To give you an idea about the output of these alternatives, we did text example extracts. See Appendix 2: Details on Text Extraction.

Searching Text

You can find out, exactly where on a page a certain string appears:

>>> areas = page.searchFor("mupdf", hit_max = 16)

The variable areas will contain a list of up to 16 Rectangles, each of which surrounds one occurrence of the string “mupdf” (case insensitive). You could use this information to e.g. highlight those areas or create a cross reference of the document.

Please also do have a look at chapter Working together: DisplayList and TextPage and at demo program demo.py. Among other things they contain details on how the TextPage, Device and DisplayList classes can be used for a more direct control, e.g. when performance considerations suggest it.

Modifying, Creating, Re-arranging and Deleting Pages

There are several ways to manipulate the page tree of a PDF:

Methods Document.deletePage() and Document.deletePageRange() delete pages.

Methods Document.copyPage() and Document.movePage() copy or move a page to another location within the document.

Document.insertPage() and Document.newPage() insert pages.

Method Document.select() shrinks a document down to selected pages. It accepts a sequence of integers as argument. These integers must be in range 0 <= i < pageCount. When executed, all pages missing in this list will be deleted. Only pages that do occur will remain - in the sequence specified and as many times (!) as specified.

So you can easily create new PDFs with the first or last 10 pages, only the odd or only the even pages (for doing double-sided printing), pages that do or don’t contain a certain text, reverse their sequence, … whatever you may think of.

The saved new document will contain all still valid links, annotations and bookmarks.

Pages themselves can moreover be modified by a range of methods (e.g. page rotation, annotation and link maintenance, text and image insertion).

Joining and Splitting PDF Documents

Method Document.insertPDF() inserts pages from another PDF at a specified place of the current one. Here is a simple joiner example (doc1 and doc2 being openend PDFs):

>>> # append complete doc2 to the end of doc1
>>> doc1.insertPDF(doc2)

Here is how to split doc1. This creates a new document of its first and last 10 pages (could also be done using Document.select()):

>>> doc2 = fitz.open()                 # new empty PDF
>>> doc2.insertPDF(doc1, to_page = 9)
>>> doc2.insertPDF(doc1, from_page = len(doc1) - 10)
>>> doc2.save(...)

More can be found in the Document chapter. Also have a look at PDFjoiner.py.

Saving

As mentioned above, Document.save() will always save the document in its current state.

Since MuPDF 1.9, you can write changes back to the original PDF by specifying incremental = True. This process is (usually) extremely fast, since changes are appended to the original file without rewriting it.

Document.save() supports all options of MuPDF’s command line utility mutool clean, see the following table (corresponding mutool clean option is indicated as “mco”).

For example, mutool clean -ggggz file.pdf yields excellent compression results. It corresponds to doc.save(filename, garbage=4, deflate=1).