Page

Class representing a document page. A page object is created by Document.loadPage() or, equivalently, via indexing the document like doc[n] - it has no independent constructor.

There is a parent-child relationship between a document and its pages. If the document is closed or deleted, all page objects (and their respective children, too) in existence will become unusable (“orphaned”): If a page property or method is being used, an exception is raised.

Several page methods have a Document counterpart for convenience. At the end of this chapter you will find a synopsis.

Adding Page Content

This is available for PDF documents only. There are basically two groups of methods:

  1. Methods making permanent changes. This group contains insertText(), insertTextbox() and all draw*() methods. They provide “stand-alone”, shortcut versions for the same-named methods of the Shape class. For detailed descriptions have a look in that chapter. Some remarks on the relationship between the Page and Shape methods:

  • In contrast to Shape, the results of page methods are not interconnected: they do not share properties like colors, line width / dashing, morphing, etc.

  • Each page draw*() method invokes a Shape.finish() and then a Shape.commit() and consequently accepts the combined arguments of both these methods.

  • Text insertion methods (insertText() and insertTextbox()) do not need Shape.finish() and therefore only invoke Shape.commit().

  1. Methods adding annotations. Annotations can be added, modified and deleted without necessarily having full document permissions. Their effect is not permanent in the sense, that manipulating them does not require to rebuild the document. Adding and deleting annotations are page methods. Changing existing annotations is possible via methods of the Annot class.

Method / Attribute

Short Description

Page.addCaretAnnot()

PDF only: add a caret annotation

Page.addCircleAnnot()

PDF only: add a circle annotation

Page.addFileAnnot()

PDF only: add a file attachment annotation

Page.addFreetextAnnot()

PDF only: add a text annotation

Page.addHighlightAnnot()

PDF only: add a “highlight” annotation

Page.addInkAnnot()

PDF only: add an ink annotation

Page.addLineAnnot()

PDF only: add a line annotation

Page.addPolygonAnnot()

PDF only: add a polygon annotation

Page.addPolylineAnnot()

PDF only: add a multi-line annotation

Page.addRectAnnot()

PDF only: add a rectangle annotation

Page.addRedactAnnot()

PDF only: add a redation annotation

Page.addSquigglyAnnot()

PDF only: add a “squiggly” annotation

Page.addStampAnnot()

PDF only: add a “rubber stamp” annotation

Page.addStrikeoutAnnot()

PDF only: add a “strike-out” annotation

Page.addTextAnnot()

PDF only: add a comment

Page.addUnderlineAnnot()

PDF only: add an “underline” annotation

Page.addWidget()

PDF only: add a PDF Form field

Page.annot_names()

PDF only: a list of annotation and widget names

Page.annots()

return a generator over the annots on the page

Page.apply_redactions()

PDF olny: process redaction annots on the page

Page.bound()

rectangle of the page

Page.deleteAnnot()

PDF only: delete an annotation

Page.deleteLink()

PDF only: delete a link

Page.drawBezier()

PDF only: draw a cubic Bezier curve

Page.drawCircle()

PDF only: draw a circle

Page.drawCurve()

PDF only: draw a special Bezier curve

Page.drawLine()

PDF only: draw a line

Page.drawOval()

PDF only: draw an oval / ellipse

Page.drawPolyline()

PDF only: connect a point sequence

Page.drawRect()

PDF only: draw a rectangle

Page.drawSector()

PDF only: draw a circular sector

Page.drawSquiggle()

PDF only: draw a squiggly line

Page.drawZigzag()

PDF only: draw a zig-zagged line

Page.getFontList()

PDF only: get list of used fonts

Page.getImageBbox()

PDF only: get bbox of inserted image

Page.getImageList()

PDF only: get list of used images

Page.getLinks()

get all links

Page.getPixmap()

create a Pixmap

Page.getSVGimage()

create a page image in SVG format

Page.getText()

extract the page’s text

Page.getTextPage()

create a TextPage for the page

Page.insertFont()

PDF only: insert a font for use by the page

Page.insertImage()

PDF only: insert an image

Page.insertLink()

PDF only: insert a link

Page.insertText()

PDF only: insert text

Page.insertTextbox()

PDF only: insert a text box

Page.links()

return a generator of the links on the page

Page.load_annot()

PDF only: load an annotation identified by its name

Page.loadLinks()

return the first link on a page

Page.newShape()

PDF only: create a new Shape

Page.searchFor()

search for a string

Page.setCropBox()

PDF only: modify the visible page

Page.setMediaBox()

PDF only: modify the mediabox

Page.setRotation()

PDF only: set page rotation

Page.showPDFpage()

PDF only: display PDF page image

Page.updateLink()

PDF only: modify a link

Page.widgets()

return a generator over the fields on the page

Page.writeText()

write one or more TextWriter objects

Page.CropBox

the page’s CropBox

Page.CropBoxPosition

displacement of the CropBox

Page.firstAnnot

first Annot on the page

Page.firstLink

first Link on the page

Page.firstWidget

first widget (form field) on the page

Page.MediaBox

the page’s MediaBox

Page.MediaBoxSize

bottom-right point of MediaBox

Page.number

page number

Page.parent

owning document object

Page.rect

rectangle (mediabox) of the page

Page.rotation

PDF only: page rotation

Page.xref

PDF xref

Class API

class Page
bound()

Determine the rectangle of the page. Same as property Page.rect below. For PDF documents this usually also coincides with objects MediaBox and CropBox, but not always. For example, if the page is rotated, then this is reflected by this method – the Page.CropBox however will not change.

Return type

Rect

addCaretAnnot(point)

(New in version 1.16.0)

PDF only: Add a caret icon. A caret annotation is a visual symbol that indicates the presence of text edits.

Parameters

point (point_like) – the top left point of a 20 x 20 rectangle containing the MuPDF-provided icon.

Return type

Annot

Returns

the created annotation.

_images/img-caret-annot.jpg
addTextAnnot(point, text, icon="Note")

PDF only: Add a comment icon (“sticky note”) with accompanying text.

Parameters
  • point (point_like) – the top left point of a 20 x 20 rectangle containing the MuPDF-provided “note” icon.

  • text (str) – the commentary text. This will be shown on double clicking or hovering over the icon. May contain any Latin characters.

  • icon (str) – (new in version 1.16.0) choose one of “Note” (default), “Comment”, “Help”, “Insert”, “Key”, “NewParagraph”, “Paragraph” as the visual symbol for the embodied text 4.

Return type

Annot

Returns

the created annotation.

addFreetextAnnot(rect, text, fontsize=12, fontname="helv", text_color=0, fill_color=1, rotate=0)

PDF only: Add text in a given rectangle.

Parameters
  • rect (rect_like) – the rectangle into which the text should be inserted. Text is automatically wrapped to a new line at box width. Lines not fitting into the box will be invisible.

  • text (str) – the text. May contain any Latin characters.

  • fontsize (float) – the font size. Default is 12.

  • fontname (str) – the font name. Default is “Helv”. Accepted alternatives are “Cour”, “TiRo”, “ZaDb” and “Symb”. The name may be abbreviated to the first two characters, like “Co” for “Cour”. Lower case is also accepted. Since MuPDF v1.16, bold or italic variants of the fonts are no longer accepted. A user-contributed script provides a circumvention for this restriction – see section Using Buttons and JavaScript in chapter Collection of Recipes.

  • text_color (sequence,float) – (new in version 1.16.0) the text color. Default is black.

  • fill_color (sequence,float) – (new in version 1.16.0) the fill color. Default is white.

  • rotate (int) – the text orientation. Accepted values are 0, 90, 270, invalid entries are set to zero.

Return type

Annot

Returns

the created annotation. Color properties can only be changed using special parameters of Annot.update(). There, you can also set a border color different from the text color.

addFileAnnot(pos, buffer, filename, ufilename=None, desc=None, icon="PushPin")

PDF only: Add a file attachment annotation with a “PushPin” icon at the specified location.

Parameters
  • pos (point_like) – the top-left point of a 18x18 rectangle containing the MuPDF-provided “PushPin” icon.

  • buffer (bytes,bytearray,BytesIO) –

    the data to be stored (actual file content, any data, etc.).

    Changed in version 1.14.13 io.BytesIO is now also supported.

  • filename (str) – the filename to associate with the data.

  • ufilename (str) – the optional PDF unicode version of filename. Defaults to filename.

  • desc (str) – an optional description of the file. Defaults to filename.

  • icon (str) – (new in version 1.16.0) choose one of “PushPin” (default), “Graph”, “Paperclip”, “Tag” as the visual symbol for the attached data 4.

Return type

Annot

Returns

the created annotation. Use methods of Annot to make any changes.

addInkAnnot(list)

PDF only: Add a “freehand” scribble annotation.

Parameters

list (sequence) – a list of one or more lists, each containing point_like items. Each item in these sublists is interpreted as a Point through which a connecting line is drawn. Separate sublists thus represent separate drawing lines.

Return type

Annot

Returns

the created annotation in default appearance (black line of width 1). Use annotation methods with a subsequent Annot.update() to modify.

addLineAnnot(p1, p2)

PDF only: Add a line annotation.

Parameters
  • p1 (point_like) – the starting point of the line.

  • p2 (point_like) – the end point of the line.

Return type

Annot

Returns

the created annotation. It is drawn with line color black and line width 1. To change, or attach other information (like author, creation date, line properties, colors, line ends, etc.) use methods of Annot. The rectangle is automatically created to contain both points, each one surrounded by a circle of radius 3 (= 3 * line width) to make room for any line end symbols. Use methods of Annot to make any changes.

addRectAnnot(rect)
addCircleAnnot(rect)

PDF only: Add a rectangle, resp. circle annotation.

Parameters

rect (rect_like) – the rectangle in which the circle or rectangle is drawn, must be finite and not empty. If the rectangle is not equal-sided, an ellipse is drawn.

Return type

Annot

Returns

the created annotation. It is drawn with line color black, no fill color and line width 1. Use methods of Annot to make any changes.

addRedactAnnot(quad, text=None, fontname=None, fontsize=11, align=TEXT_ALIGN_LEFT, fill=(1, 1, 1), text_color=(0, 0, 0))

PDF only: (new in version 1.16.11) Add a redaction annotation. A redaction annotation identifies content that is intended to be removed from the document. Adding such an annotation is the first of two steps. It makes visible what will be removed in the subsequent step, Page.apply_redactions().

Parameters
  • quad (quad_like,rect_like) – specifies the (rectangular) area to be removed which is always equal to the annotation rectangle. This may be a rect_like or quad_like object. If a quad is specified, then the envelopping rectangle is taken.

  • text (str) – (New in v1.16.12) text to be placed in the rectangle after applying the redaction (and thus removing old content).

  • fontname (str) – (New in v1.16.12) the font to use when text is given, otherwise ignored. This must be one of the Base14_Fonts or a CJK fonts.

  • fontsize (float) – (New in v1.16.12) the fontsize to use for the replacing text. If the text is too large to fit, several insertion attempts will be made, gradually reducing this value down to 4. If then the text will still not fit, no text insertion will take place at all.

  • align (int) – (New in v1.16.12) the horizontal alignment for the replacing text. See insertTextbox() for available values. The vertical alignment is always centered (approximately).

  • fill (sequence) – (New in v1.16.12) the fill color of the rectangle after applying the redaction. The default is white = (1, 1, 1), which is also taken if None is specified. (Changed in v1.16.13) To suppress any fill color, specify False. In this cases the rectangle remains transparent.

  • text_color (sequence) – (New in v1.16.12) the color of the replacing text. Default is black = (0, 0, 0).

Return type

Annot

Returns

the created annotation. The appearance of a redaction annotation cannot be changed (except for its rectangle). A redaction is displayed as a crossed-out transparent rectangle with red lines.

_images/img-redact.jpg
addPolylineAnnot(points)
addPolygonAnnot(points)

PDF only: Add an annotation consisting of lines which connect the given points. A Polygon’s first and last points are automatically connected, which does not happen for a PolyLine. The rectangle is automatically created as the smallest rectangle containing the points, each one surrounded by a circle of radius 3 (= 3 * line width). The following shows a ‘PolyLine’ that has been modified with colors and line ends.

Parameters

points (list) – a list of point_like objects.

Return type

Annot

Returns

the created annotation. It is drawn with line color black, no fill color and line width 1. Use methods of Annot to make any changes to achieve something like this:

_images/img-polyline.png
addUnderlineAnnot(quads=None, start=None, stop=None, clip=None)
addStrikeoutAnnot(quads=None, start=None, stop=None, clip=None)
addSquigglyAnnot(quads=None, start=None, stop=None, clip=None)
addHighlightAnnot(quads=None, start=None, stop=None, clip=None)

PDF only: These annotations are normally used for marking text which has previously been somehow located (for example via searchFor()). But this is not required: you are free to “mark” just anything.

Standard colors are chosen per annotation type: yellow for highlighting, red for strike out, green for underlining, and magenta for wavy underlining.

The methods convert the arguments into a list of Quad objects. The annotation rectangle is then calculated to envelop all these quadrilaterals.

Note

searchFor() delivers a list of either rectangles or quadrilaterals. Such a list can be directly used as parameter for these annotation types and will deliver one common annotation for all occurrences of the search string:

>>> quads = page.searchFor("pymupdf", hit_max=100, quads=True)
>>> page.addHighlightAnnot(quads)
Parameters
  • quads (rect_like,quad_like,list,tuple) – (Changed in v1.14.20) the rectangles or quads containing the to-be-marked text (locations). A list or tuple must consist of rect_like or quad_like items (or even a mixture of either). You should prefer using quads, because this will automatically support non-horizontal text and avoid rectangle-to-quad conversion effort. (Changed in v1.16.14) Set this parameter to None if you want to use the following arguments.

  • start (point_like) – (New in v1.16.14) start text marking at this point. Defaults to the top-left point of clip.

  • stop (point_like) – (New in v1.16.14) stop text marking at this point. Defaults to the bottom-right point of clip.

  • clip (rect_like) – (New in v1.16.14) only consider text lines intersecting this area. Defaults to the page rectangle.

Return type

Annot or (changed in v1.16.14) None

Returns

the created annotation. (Changed in v1.16.14) If quads is an empty list, no annotation is created. To change colors, set the “stroke” color accordingly (Annot.setColors()) and then perform an Annot.update().

Note

Starting with v1.16.14 you can use parameters start, stop and clip to highlight consecutive lines between the points start and stop. Make use of clip to further reduce the selected line bboxes and thus deal with e.g. multi-column pages. The following multi-line highlight was created specifying the two red points and setting clip accordingly.

_images/img-markers.jpg
addStampAnnot(rect, stamp=0)

PDF only: Add a “rubber stamp” like annotation to e.g. indicate the document’s intended use (“DRAFT”, “CONFIDENTIAL”, etc.).

Parameters
  • rect (rect_like) – rectangle where to place the annotation.

  • stamp (int) – id number of the stamp text. For available stamps see Stamp Annotation Icons.

Note

  • The stamp’s text and its border line will automatically be sized and be put horizontally and vertically centered in the given rectangle. Annot.rect is automatically calculated to fit the given width and will usually be smaller than this parameter.

  • The font chosen is “Times Bold” and the text will be upper case.

  • The appearance can be changed using Annot.setOpacity() and by setting the “stroke” color (no “fill” color supported).

  • This can be used to create watermark images: on a temporary PDF page create a stamp annotation with a low opacity value, make a pixmap from it with alpha=True (and potentially also rotate it), discard the temporary PDF page and use the pixmap with insertImage() for your target PDF.

_images/img-stampannot.jpg
addWidget(widget)

PDF only: Add a PDF Form field (“widget”) to a page. This also turns the PDF into a Form PDF. Because of the large amount of different options available for widgets, we have developed a new class Widget, which contains the possible PDF field attributes. It must be used for both, form field creation and updates.

Parameters

widget (Widget) – a Widget object which must have been created upfront.

Returns

a widget annotation.

deleteAnnot(annot)

PDF only: Delete the specified annotation from the page and return the next one.

Changed in version 1.16.6 The removal will now include any bound ‘Popup’ or response annotations and related objects.

Parameters

annot (Annot) – the annotation to be deleted.

Return type

Annot

Returns

the annotation following the deleted one. Please remember that physical removal will take place only with saving to a new file with a positive garbage collection option.

apply_redactions()

PDF only: (New in version 1.16.11) Remove all text content contained in any redaction rectangle.

(Changed in v1.16.12) The previous mark parameter is gone. Instead, the respective rectangles are filled with the individual fill color of each redaction annotation. If a text was given in the annotation, then insertTextbox() is invoked to insert it, using parameters provided with the redaction.

This method applies and then deletes all redaction annotations from the page.

Returns

True if at least one redaction annotation has been processed, False otherwise.

Note

Text contained in a redaction rectangle will be physically removed from the page and will no longer appear in e.g. text extractions. Other annotations are unaffected.

Images and XObjects (embedded PDF pages, e.g. via showPDFpage()) will also physically be removed from the page if they are completely contained in a redation rectangle. Partial overlaps however will only be overlaid with the redaction background color, and no removal will take place.

Decision to remove text is made on a by-character level: A character will be removed if and only if the bottom-left corner of its boundary box is contained in some redaction rectangle. Hence it may happen, that a character is removed even if the better part of it is outside the redaction or – vice versa – not removed, even if most of its bbox is inside the rect.

Redactions are an easy way to replace single words in a PDF, or to physically render them unreadable: locate the word “secret” using some text extraction or search method and insert a redaction using “xxxxxx” as replacement text for each occurrence. Just be wary if the replacement is much longer than the original – this may lead to an awkward appearance or no new text at all. Also, for a number of reasons, the new text is often not exactly positioned on the same line like the old one.

PDF only: Delete the specified link from the page. The parameter must be an original item of getLinks() (see below). The reason for this is the dictionary’s “xref” key, which identifies the PDF object to be deleted.

Parameters

linkdict (dict) – the link to be deleted.

PDF only: Insert a new link on this page. The parameter must be a dictionary of format as provided by getLinks() (see below).

Parameters

linkdict (dict) – the link to be inserted.

PDF only: Modify the specified link. The parameter must be a (modified) original item of getLinks() (see below). The reason for this is the dictionary’s “xref” key, which identifies the PDF object to be changed.

Parameters

linkdict (dict) – the link to be modified.

Retrieves all links of a page.

Return type

list

Returns

A list of dictionaries. For a description of the dictionary entries see below. Always use this or the Page.links() method if you intend to make changes to the links of a page.

(New in version 1.16.4)

Return a generator over the page’s links. The results equal the entries of Page.getLinks().

Parameters

kinds (sequence) – a sequence of integers to down-select to one or more link kinds. Default is all links. Example: kinds=(fitz.LINK_GOTO,) will only return internal links.

Return type

generator

Returns

an entry of Page.getLinks() for each iteration.

annots(types=None)

(New in version 1.16.4)

Return a generator over the page’s annotations.

Parameters

types (sequence) – a sequence of integers to down-select to one or annotation types. Default is all annotations. Example: types=(fitz.PDF_ANNOT_FREETEXT, fitz.PDF_ANNOT_TEXT) will only return ‘FreeText’ and ‘Text’ annotations.

Return type

generator

Returns

an Annot for each iteration.

widgets(types=None)

(New in version 1.16.4)

Return a generator over the page’s form fields.

Parameters

types (sequence) – a sequence of integers to down-select to one or more widget types. Default is all form fields. Example: types=(fitz.PDF_WIDGET_TYPE_TEXT,) will only return ‘Text’ fields.

Return type

generator

Returns

a Widget for each iteration.

writeText(rect=None, writers=None, overlay=True, color=None, opacity=None, keep_proportion=True, rotate=0)

(New in version 1.16.18)

PDF only: Write the text of one or more TextWriter ojects to the page.

Parameters
  • rect (rect_like) – where to place the text. If omitted, the rectangle union of the text writers is used.

  • writers (sequence) – a non-empty tuple / list of TextWriter objects or a single TextWriter.

  • opacity (float) – set transparency, overwrites resp. value in the text writers.

  • color (sequ) – set the text color, overwrites resp. value in the text writers.

  • overlay (bool) – put the text in foreground or background.

  • keep_proportion (bool) – maintain the aspect ratio.

  • rotate (float) – rotate the text by an arbitrary angle.

Note

Parameters overlay, keep_proportion and rotate have the same meaning as in showPDFpage.

insertText(point, text, fontsize=11, fontname="helv", fontfile=None, idx=0, color=None, fill=None, render_mode=0, border_width=1, encoding=TEXT_ENCODING_LATIN, rotate=0, morph=None, overlay=True)

PDF only: Insert text starting at point_like point. See Shape.insertText().

insertTextbox(rect, buffer, fontsize=11, fontname="helv", fontfile=None, idx=0, color=None, fill=None, render_mode=0, border_width=1, encoding=TEXT_ENCODING_LATIN, expandtabs=8, align=TEXT_ALIGN_LEFT, charwidths=None, rotate=0, morph=None, overlay=True)

PDF only: Insert text into the specified rect_like rect. See Shape.insertTextbox().

drawLine(p1, p2, color=None, width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, morph=None)

PDF only: Draw a line from p1 to p2 (point_like s). See Shape.drawLine().

drawZigzag(p1, p2, breadth=2, color=None, width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, morph=None)

PDF only: Draw a zigzag line from p1 to p2 (point_like s). See Shape.drawZigzag().

drawSquiggle(p1, p2, breadth=2, color=None, width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, morph=None)

PDF only: Draw a squiggly (wavy, undulated) line from p1 to p2 (point_like s). See Shape.drawSquiggle().

drawCircle(center, radius, color=None, fill=None, width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, morph=None)

PDF only: Draw a circle around center (point_like) with a radius of radius. See Shape.drawCircle().

drawOval(quad, color=None, fill=None, width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, morph=None)

PDF only: Draw an oval (ellipse) within the given rect_like or quad_like. See Shape.drawOval().

drawSector(center, point, angle, color=None, fill=None, width=1, dashes=None, lineCap=0, lineJoin=0, fullSector=True, overlay=True, closePath=False, morph=None)

PDF only: Draw a circular sector, optionally connecting the arc to the circle’s center (like a piece of pie). See Shape.drawSector().

drawPolyline(points, color=None, fill=None, width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, closePath=False, morph=None)

PDF only: Draw several connected lines defined by a sequence of point_like s. See Shape.drawPolyline().

drawBezier(p1, p2, p3, p4, color=None, fill=None, width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, closePath=False, morph=None)

PDF only: Draw a cubic Bézier curve from p1 to p4 with the control points p2 and p3 (all are :data`point_like` s). See Shape.drawBezier().

drawCurve(p1, p2, p3, color=None, fill=None, width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, closePath=False, morph=None)

PDF only: This is a special case of drawBezier(). See Shape.drawCurve().

drawRect(rect, color=None, fill=None, width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, morph=None)

PDF only: Draw a rectangle. See Shape.drawRect().

Note

An efficient way to background-color a PDF page with the old Python paper color is

>>> col = fitz.utils.getColor("py_color")
>>> page.drawRect(page.rect, color=col, fill=col, overlay=False)
insertFont(fontname="helv", fontfile=None, fontbuffer=None, set_simple=False, encoding=TEXT_ENCODING_LATIN)

PDF only: Add a new font to be used by text output methods and return its xref. If not already present in the file, the font definition will be added. Supported are the built-in Base14_Fonts and the CJK fonts via “reserved” fontnames. Fonts can also be provided as a file path or a memory area containing the image of a font file.

Parameters

fontname (str) – The name by which this font shall be referenced when outputting text on this page. In general, you have a “free” choice here (but consult the Adobe PDF References, page 56, section 3.2.4 for a formal description of building legal PDF names). However, if it matches one of the Base14_Fonts or one of the CJK fonts, fontfile and fontbuffer are ignored.

In other words, you cannot insert a font via fontfile / fontbuffer and also give it a reserved fontname.

Note

A reserved fontname can be specified in any mixture of upper or lower case and still match the right built-in font definition: fontnames “helv”, “Helv”, “HELV”, “Helvetica”, etc. all lead to the same font definition “Helvetica”. But from a Page perspective, these are different references. You can exploit this fact when using different encoding variants (Latin, Greek, Cyrillic) of the same font on a page.

Parameters
  • fontfile (str) – a path to a font file. If used, fontname must be different from all reserved names.

  • fontbuffer (bytes/bytearray) – the memory image of a font file. If used, fontname must be different from all reserved names. This parameter would typically be used to transfer fonts between different pages of the same or different PDFs.

  • set_simple (int) – applicable for fontfile / fontbuffer cases only: enforce treatment as a “simple” font, i.e. one that only uses character codes up to 255.

  • encoding (int) – applicable for the “Helvetica”, “Courier” and “Times” sets of Base14_Fonts only. Select one of the available encodings Latin (0), Cyrillic (2) or Greek (1). Only use the default (0 = Latin) for “Symbol” and “ZapfDingBats”.

Rytpe

int

Returns

the xref of the installed font.

Note

Built-in fonts will not lead to the inclusion of a font file. So the resulting PDF file will remain small. However, your PDF viewer software is responsible for generating an appropriate appearance – and there exist differences on whether or how each one of them does this. This is especially true for the CJK fonts. But also Symbol and ZapfDingbats are incorrectly handled in some cases. Following are the Font Names and their correspondingly installed Base Font names:

Base-14 Fonts 1

Font Name

Installed Base Font

Comments

helv

Helvetica

normal

heit

Helvetica-Oblique

italic

hebo

Helvetica-Bold

bold

hebi

Helvetica-BoldOblique

bold-italic

cour

Courier

normal

coit

Courier-Oblique

italic

cobo

Courier-Bold

bold

cobi

Courier-BoldOblique

bold-italic

tiro

Times-Roman

normal

tiit

Times-Italic

italic

tibo

Times-Bold

bold

tibi

Times-BoldItalic

bold-italic

symb

Symbol

3

zadb

ZapfDingbats

3

CJK Fonts 2 (China, Japan, Korea)

Font Name

Installed Base Font

Comments

china-s

Heiti

simplified Chinese

china-ss

Song

simplified Chinese (serif)

china-t

Fangti

traditional Chinese

china-ts

Ming

traditional Chinese (serif)

japan

Gothic

Japanese

japan-s

Mincho

Japanese (serif)

korea

Dotum

Korean

korea-s

Batang

Korean (serif)

insertImage(rect, filename=None, pixmap=None, stream=None, rotate=0, keep_proportion=True, overlay=True)

PDF only: Put an image inside the given rectangle. The image can be taken from a pixmap, a file or a memory area - of these parameters exactly one must be specified.

Changed in version 1.14.11 By default, the image keeps its aspect ratio.

Parameters
  • rect (rect_like) –

    where to put the image on the page. Only the rectangle part which is inside the page is used. This intersection must be finite and not empty.

    Changed in version 1.14.13 The image is now always placed centered in the rectangle, i.e. the center of the image and the rectangle coincide.

  • filename (str) – name of an image file (all formats supported by MuPDF – see Supported Input Image Formats). If the same image is to be inserted multiple times, choose one of the other two options to avoid some overhead.

  • stream (bytes,bytearray,io.BytesIO) –

    image in memory (all formats supported by MuPDF – see Supported Input Image Formats). This is the most efficient option.

    Changed in version 1.14.13 io.BytesIO is now also supported.

  • pixmap (Pixmap) – a pixmap containing the image.

  • rotate (int) – (new in version v1.14.11) rotate the image. Must be an integer multiple of 90 degrees. If you need a rotation by an arbitrary angle, consider converting the image to a PDF (Document.convertToPDF()) first and then use Page.showPDFpage() instead.

  • keep_proportion (bool) – (new in version v1.14.11) maintain the aspect ratio of the image.

For a description of overlay see Common Parameters.

This example puts the same image on every page of a document:

>>> doc = fitz.open(...)
>>> rect = fitz.Rect(0, 0, 50, 50)       # put thumbnail in upper left corner
>>> img = open("some.jpg", "rb").read()  # an image file
>>> for page in doc:
      page.insertImage(rect, stream = img)
>>> doc.save(...)

Note

  1. If that same image had already been present in the PDF, then only a reference to it will be inserted. This of course considerably saves disk space and processing time. But to detect this fact, existing PDF images need to be compared with the new one. This is achieved by storing an MD5 code for each image in a table and only compare the new image’s MD5 code against the table entries. Generating this MD5 table, however, is done when the first image is inserted - which therefore may have an extended response time.

  2. You can use this method to provide a background or foreground image for the page, like a copyright, a watermark. Please remember, that watermarks require a transparent image …

  3. The image may be inserted uncompressed, e.g. if a Pixmap is used or if the image has an alpha channel. Therefore, consider using deflate=True when saving the file.

  4. The image is stored in the PDF in its original quality. This may be much better than you ever need for your display. In this case consider decreasing the image size before inserting it – e.g. by using the pixmap option and then shrinking it or scaling it down (see Pixmap chapter). The PIL method Image.thumbnail() can also be used for that purpose. The file size savings can be very significant.

  5. The most efficient way to display the same image on multiple pages is another method: showPDFpage(). Consult Document.convertToPDF() for how to obtain intermediary PDFs usable for that method. Demo script fitz-logo.py implements a fairly complete approach.

getText(opt="text", flags=None)

Retrieves the content of a page in a variety of formats. This is a wrapper for TextPage methods by choosing the output option as follows:

Parameters
  • opt (str) –

    A string indicating the requested format, one of the above. A mixture of upper and lower case is supported.

    Changed in version 1.16.3 Values “words” and “blocks” are now also accepted.

  • flags (int) – (new in version 1.16.2) indicator bits to control whether to include images or how text should be handled with respect to white spaces and ligatures. See Preserve Text Flags for available indicators and Text Extraction Flags Defaults for default settings.

Return type

str, list, dict

Returns

The page’s content as a string, list or as a dictionary. Refer to the corresponding TextPage method for details.

Note

You can use this method as a document conversion tool from any supported document type (not only PDF!) to one of TEXT, HTML, XHTML or XML documents.

getTextPage(flags=3)

(New in version 1.16.5)

Create a TextPage for the page. This method avoids using an intermediate DisplayList.

Parameters

flags (in) – indicator bits controlling the content available for subsequent extraction – see the parameter of Page.getText().

Returns

TextPage

getFontList(full=False)

PDF only: Return a list of fonts referenced by the page. Wrapper for Document.getPageFontList().

getImageList(full=False)

PDF only: Return a list of images referenced by the page. Wrapper for Document.getPageImageList().

getImageBbox(item)

(New in version 1.16.0)

PDF only: Return the boundary box of an image.

Parameters

item (list) – an item of the list Page.getImageList() with full=True specified.

Return type

Rect

Returns

the boundary box of the image. Changed in version 1.16.7 If the page in fact does not display this image, an infinite rectangle is returned now. In previous versions, an exception was raised.

Warning

The method internally cleans the page’s /Contents object(s) using Page._cleanContents(). Please consult its description for implications.

Note

  • Be aware that Page.getImageList() may contain “dead” entries, i.e. there may be image references which – although present in the PDF – are not displayed by this page. In this case an exception is raised.

  • This function is still somewhat experimental: it does not yet cover all possibilities of how an image location might have been coded, but instead makes some simplifying assumptions. As a result you occasionally may find the bbox incorrectly calculated. In contrast, image blocks returned by Page.getText() (“dict” or “rawdict” options) do contain a correct bbox on the one hand, but on the other hand do not allow an (easy) identification of the image as a PDF object. There are however ways to match these information pieces – please consult the recipes chapter.

getSVGimage(matrix=fitz.Identity)

Create an SVG image from the page. Only full page images are currently supported.

Parameters

matrix (matrix_like) – a matrix, default is Identity.

Returns

a UTF-8 encoded string that contains the image. Because SVG has XML syntax it can be saved in a text file with extension .svg.

getPixmap(matrix=fitz.Identity, colorspace=fitz.csRGB, clip=None, alpha=False, annots=True)

Create a pixmap from the page. This is probably the most often used method to create a pixmap.

Parameters
  • matrix (matrix_like) – default is Identity.

  • colorspace (str or Colorspace) – Defines the required colorspace, one of “GRAY”, “RGB” or “CMYK” (case insensitive). Or specify a Colorspace, ie. one of the predefined ones: csGRAY, csRGB or csCMYK.

  • clip (irect_like) – restrict rendering to this area.

  • alpha (bool) –

    whether to add an alpha channel. Always accept the default False if you do not really need transparency. This will save a lot of memory (25% in case of RGB … and pixmaps are typically large!), and also processing time. Also note an important difference in how the image will be rendered: with True the pixmap’s samples area will be pre-cleared with 0x00. This results in transparent areas where the page is empty. With False the pixmap’s samples will be pre-cleared with 0xff. This results in white where the page has nothing to show.

    Changed in version 1.14.17

    The default alpha value is now False.

    • Generated with alpha=True

    _images/img-alpha-1.png
    • Generated with alpha=False

    _images/img-alpha-0.png

  • annots (bool) – (new in vrsion 1.16.0) whether to also render any annotations on the page. You can create pixmaps for annotations separately.

Return type

Pixmap

Returns

Pixmap of the page.

annot_names()

(New in version 1.16.10)

PDF only: return a list of the names of annotations or widgets.

Return type

list

load_annot(annot_id)

(New in version 1.16.10)

PDF only: return the annotation identified by annot_id – its unique name (/NM).

Parameters

annot_id (str) – the annotation name.

Return type

Annot

Returns

the annotation or None.

Return the first link on a page. Synonym of property firstLink.

Return type

Link

Returns

first link on the page (or None).

setRotation(rotate)

PDF only: Sets the rotation of the page.

Parameters

rotate (int) – An integer specifying the required rotation in degrees. Must be an integer multiple of 90.

showPDFpage(rect, docsrc, pno=0, keep_proportion=True, overlay=True, rotate=0, clip=None)

PDF only: Display a page of another PDF as a vector image (otherwise similar to Page.insertImage()). This is a multi-purpose method. For example, you can use it to

  • create “n-up” versions of existing PDF files, combining several input pages into one output page (see example 4-up.py),

  • create “posterized” PDF files, i.e. every input page is split up in parts which each create a separate output page (see posterize.py),

  • include PDF-based vector images like company logos, watermarks, etc., see svg-logo.py, which puts an SVG-based logo on each page (requires additional packages to deal with SVG-to-PDF conversions).

Changed in version 1.14.11

Parameter reuse_xref has been deprecated.

Parameters
  • rect (rect_like) –

    where to place the image on current page. Must be finite and its intersection with the page must not be empty.

    Changed in version 1.14.11

    Position the source rectangle centered in this rectangle.

  • docsrc (Document) – source PDF document containing the page. Must be a different document object, but may be the same file.

  • pno (int) – page number (0-based, in -inf < pno < docsrc.pageCount) to be shown.

  • keep_proportion (bool) – whether to maintain the width-height-ratio (default). If false, all 4 corners are always positioned on the border of the target rectangle – whatever the rotation value. In general, this will deliver distorted and /or non-rectangular images.

  • overlay (bool) – put image in foreground (default) or background.

  • rotate (float) – (new in version 1.14.10) show the source rectangle rotated by some angle. Changed in version 1.14.11: Any angle is now supported.

  • clip (rect_like) – choose which part of the source page to show. Default is the full page, else must be finite and its intersection with the source page must not be empty.

Note

In contrast to method Document.insertPDF(), this method does not copy annotations or links, so they are not shown. But all its other resources (text, images, fonts, etc.) will be imported into the current PDF. They will therefore appear in text extractions and in getFontList() and getImageList() lists – even if they are not contained in the visible area given by clip.

Example: Show the same source page, rotated by 90 and by -90 degrees:

>>> doc = fitz.open()  # new empty PDF
>>> page=doc.newPage()  # new page in A4 format
>>>
>>> # upper half page
>>> r1 = fitz.Rect(0, 0, page.rect.width, page.rect.height/2)
>>>
>>> # lower half page
>>> r2 = r1 + (0, page.rect.height/2, 0, page.rect.height/2)
>>>
>>> src = fitz.open("PyMuPDF.pdf")  # show page 0 of this
>>>
>>> page.showPDFpage(r1, src, 0, rotate=90)
>>> page.showPDFpage(r2, src, 0, rotate=-90)
>>> doc.save("show.pdf")
_images/img-showpdfpage.jpg
newShape()

PDF only: Create a new Shape object for the page.

Return type

Shape

Returns

a new Shape to use for compound drawings. See description there.

searchFor(text, hit_max=16, quads=False, flags=None)

Searches for text on a page. Wrapper for TextPage.search().

Parameters
  • text (str) – Text to search for. Upper / lower case is ignored. The string may contain spaces.

  • hit_max (int) – Maximum number of occurrences accepted.

  • quads (bool) – Return Quad instead of Rect objects.

  • flags (int) – Control the data extracted by the underlying TextPage. Default is 0 (ligatures are dissolved, white space is replaced with space and excessive spaces are not suppressed).

Return type

list

Returns

A list of Rect s (resp. Quad s) each of which – normally! – surrounds one occurrence of text. However: if the search string spreads across more than one line, then a separate item is recorded in the list for each part of the string per line. So, if you are looking for “search string” and the two words happen to be located on separate lines, two entries will be recorded in the list: one for “search” and one for “string”.

Note

In this way, the effect supports multi-line text marker annotations.

setMediaBox(r)

PDF only: (New in v1.16.13) Change the physical page dimension by setting MediaBox in the page’s object definition.

Parameters

r (rect-like) – the new MediaBox value.

Note

This method also sets the page’s CropBox to the same value – to prevent mismatches caused by values further up in the parent hierarchy.

Caution

For existing pages this may have unexpected effects, if painting commands depend on a certain setting, and may lead to an empty or distorted appearance.

setCropBox(r)

PDF only: change the visible part of the page.

Parameters

r (rect_like) – the new visible area of the page. Note that this must be specified in unrotated coordinates.

After execution if the page is not rotated, Page.rect will equal this rectangle, shifted to the top-left position (0, 0). Example session:

>>> page = doc.newPage()
>>> page.rect
fitz.Rect(0.0, 0.0, 595.0, 842.0)
>>>
>>> page.CropBox                   # CropBox and MediaBox still equal
fitz.Rect(0.0, 0.0, 595.0, 842.0)
>>>
>>> # now set CropBox to a part of the page
>>> page.setCropBox(fitz.Rect(100, 100, 400, 400))
>>> # this will also change the "rect" property:
>>> page.rect
fitz.Rect(0.0, 0.0, 300.0, 300.0)
>>>
>>> # but MediaBox remains unaffected
>>> page.MediaBox
fitz.Rect(0.0, 0.0, 595.0, 842.0)
>>>
>>> # revert everything we did
>>> page.setCropBox(page.MediaBox)
>>> page.rect
fitz.Rect(0.0, 0.0, 595.0, 842.0)
rotation

PDF only: contains the rotation of the page in degrees and -1 for other document types.

Type

int

CropBoxPosition

Contains the top-left point of the page’s /CropBox for a PDF, otherwise Point(0, 0).

Type

Point

CropBox

The page’s /CropBox for a PDF. Always the unrotated page rectangle is returned. For a non-PDF this will always equal the page rectangle.

Type

Rect

MediaBoxSize

Contains the width and height of the page’s Page.MediaBox for a PDF, otherwise the bottom-right coordinates of Page.rect.

Type

Point

MediaBox

The page’s MediaBox for a PDF, otherwise Page.rect.

Type

Rect

Note

For most PDF documents and for all other types, page.rect == page.CropBox == page.MediaBox is true. However, for some PDFs the visible page is a true subset of MediaBox. Also, if the page is rotated, its Page.rect may not equal Page.CropBox. In these cases the above attributes help to correctly locate page elements.

Contains the first Link of a page (or None).

Type

Link

firstAnnot

Contains the first Annot of a page (or None).

Type

Annot

firstWidget

Contains the first Widget of a page (or None).

Type

Widget

number

The page number.

Type

int

parent

The owning document object.

Type

Document

rect

Contains the rectangle of the page. Same as result of Page.bound().

Type

Rect

xref

The page’s PDF xref. Zero if not a PDF.

Type

Rect


Homologous Methods of Document and Page

This is an overview of homologous methods on the Document and on the Page level.

Document Level

Page Level

Document.getPageFontlist(pno)

Page.getFontList()

Document.getPageImageList(pno)

Page.getImageList()

Document.getPagePixmap(pno, …)

Page.getPixmap()

Document.getPageText(pno, …)

Page.getText()

Document.searchPageFor(pno, …)

Page.searchFor()

The page number “pno”` is a 0-based integer -inf < pno < pageCount.

Note

Most document methods (left column) exist for convenience reasons, and are just wrappers for: Document[pno].<page method>. So they load and discard the page on each execution.

However, the first two methods work differently. They only need a page’s object definition statement - the page itself will not be loaded. So e.g. Page.getFontList() is a wrapper the other way round and defined as follows: page.getFontList == page.parent.getPageFontList(page.number).

Footnotes

1

If your existing code already uses the installed base name as a font reference (as it was supported by PyMuPDF versions earlier than 1.14), this will continue to work.

2

Not all PDF reader software (including internet browsers and office software) display all of these fonts. And if they do, the difference between the serifed and the non-serifed version may hardly be noticable. But serifed and non-serifed versions lead to different installed base fonts, thus providing an option to be displayable with your specific PDF viewer.

3(1,2)

Not all PDF readers display these fonts at all. Some others do, but use a wrong character spacing, etc.

4(1,2)

You are generally free to choose any of the Annotation Icons in MuPDF you consider adequate.