How to Insert new PDF Pages, Images and Text

Inserting new Pages

Beginning with v1.11.0 PyMuPDF allows to insert new pages into (existing or new) PDFs. This works like so:

    doc = fitz.open("some.pdf")            # or a new PDF by fitz.open()
    doc.insertPage(n, text="some text")  # insert a new page in front of page n
    doc.save(...)                          # save what we did

Insertion page number n is 0-based and means "insertion in front of this page". Insertion at end is achieved by n = -1. Several parameters and options are available: fontsize, color, standard Base14 fonts or other fonts from your system, page dimension, etc. If text is a string containing line breaks (\n) or a Python sequence, then several text lines are generated.

We have included a new demo program text2pdf.py that converts a text file to a new PDF using this feature. As usual with PyMuPDF: a very fast alternative to similar solutions.

Inserting new Images

You may want to look at this new example GUI script: It allows inserting, deleting and re-positioning images on PDF pages. It requires PyMuPDF version 1.17.5 and a Phoenix version of wxPython.

New images can be put on PDF pages. Here is a basic code snippet:

    doc = fitz.open("some.pdf")            # some existing PDF
    page = doc[n]                          # load page (0-based)
    rect = fitz.Rect(0, 0, 100, 100)       # where we want to put the image
    pix = fitz.Pixmap("some.image")        # any supported image file
    page.insertImage(rect, pixmap=pix, overlay=True)   # insert image
    doc.save(...)                          # save our deeds

The image will overlay (default) what currently is there in the rectangle. Transparent images are supported and thus can be used for some kind of "watermarking" your PDF. With overlay = False, the image will become background.

In order to put an identical thumbnail on each page, do this:

for page in doc:
    page.insertImage(rect, pixmap=pix)

Potentially except for the first page, this is a very fast process. On my machine it took 6 seconds to stamp all the 1'310 pages of Adobe's PDF Reference Manual with a (relatively small) image.

The method is more flexible than shown here:

• Instead of a fitz.Pixmap you can also directly use the filename of the image - replace parameter pixmap= with filename=. Or use an image in memory (as a bytes or io.BytesIO object) and use parameter stream= instead.
• Rotate the image using rotate=deg specifying an integer multiple of 90 degrees.
• The image will be inserted centered, normally fully using at least one of width or height of the rectangle but keeping its aspect ratio. If you specify keep-proportion=False, then the image will fully cover the rectangle area and thus may appear somehow distorted.

How to "censor" a PDF

I am not (quite) serious here ... but using this technique you can overlay certain text pieces with images as well:

    doc = fitz.open(...)
    for page in doc:
        rl = page.searchFor("nasty word", hit_max=nnn)
        for r in rl:
            page.insertImage(r, "black.jpg")
    doc.save("censored.pdf")

File "censored.pdf" will now have every (up to nnn per page) occurrence of "nasty word" overlaid with picture "black.jpg".

But note: the overlaid text is physically still there, and can be accessed e.g. via page.getText().

You can also use this approach to emphasize text in a textmarker style:

Create a small image file that only contains pixels of one color to be used for textmarking, say "yellow.jpg". Then use it in a variation of the above:

    pix = fitz.Pixmap("yellow.jpg")          # arbitrary size
    for page in doc:
        rl = page.searchFor("interesting stuff", hit_max=...)
        for r in rl:                         # every rectangle containing this text
            page.insertImage(r, pixmap=pix, overlay=False)
    doc.save(...)

All "interesting stuff" will now be textmarked yellow, i.e. shown with a yellow background.

If you don't want to use an image file, but just a general color as background, use this script instead:

    from fitz.utils import getColor          # function delivers RGB triple for a color name
    pink = getColor("pink")                  # one of the 540+ pre-installed colors ...
    for page in doc:
        rl = page.searchFor("interesting stuff", hit_max=...)
        for r in rl:                         # every rectangle containing this text
            page.drawRect(r, color=pink, fill=pink, overlay=False)
    doc.save(...)

Please note, that all these changes permanently modify the PDF. They can not be reverted, in contrast to using annotations, which can be deleted again.

Inserting new Text

You can insert new text on existing pages. This works similar to creating a new page together with text, but adds more flexibility. You can freely position your text pieces, choose different fonts / text sizes / colors for each piece, rotate it (multiples of 90 degrees), etc.

    page = doc[n]
    text = "some text containing line breaks and\na prettier mono-spaced font."
    fname = "F0"
    ffile = "c:/windows/fonts/dejavusansmono.ttf"
    where = fitz.Point(50, 100)    # text starts here
    # this inserts 2 lines of text using font `DejaVu Sans Mono`
    page.insert_text(where, text,
                    fontname=fname,    # arbitrary if fontfile given
                    fontfile=ffile,    # any file containing a font
                    fontsize=11,       # default
                    rotate=0,          # rotate text
                    color=(0, 0, 1),   # some color (blue)
                    overlay=True)      # text in foreground

Inserting Textboxes

This method is similar to the previous one (and in fact ultimately uses it).

You provide a rectangle and text that should be put into it - and nowhere else. Text is broken down to single words respecting tabulators and multiple spaces. Alignment is possible: left, center, right or justified.

The method returns a non-negative float result if successful.

    rc = page.insert_textbox(rect, text,
                    align=fitz.TEXT_ALIGN_JUSTIFY,  # justify the text
                    # ... more parameters like in insertText()
                    )
    if rc < 0:
        # take action if not enough space

The value rc indicates how much unused space is left in the rectangle area. If negative, no action has been taken, and you could increase the rectangle, reduce fontsize or amount of text or whatever.