Annot

Quote from the Adobe PDF Reference 1.7: “An annotation associates an object such as a note, sound, or movie with a location on a page of a PDF document, or provides a way to interact with the user by means of the mouse and keyboard.”

This class supports accessing such annotations - not only for PDF files, but for all MuPDF supported document types. However, only a few methods and properties apply to non-PDF documents.

There is a parent-child relationship between an annotation and its page. If the page object becomes unusable (closed document, any document structure change, etc.), then so does every of its existing annotation objects - an exception is raised saying that the object is “orphaned”, whenever an annotation property or method is accessed.

Class API

class Annot

getPixmap(matrix = fitz.Ientity, colorspace = fitz.csRGB, alpha = False)

Creates a pixmap from the annotation as it appears on the page in untransformed coordinates. The pixmap’s IRect equals Annot.rect.irect (see below).

Parameters:	matrix (Matrix) – a matrix to be used for image creation. Default is the fitz.Identity matrix. colorspace (Colorspace) – a colorspace to be used for image creation. Default is fitz.csRGB. alpha (bool) – whether to include transparency information. Default is False.
Return type:	Pixmap

setInfo(d)

Changes the info dictionary. This is includes dates, contents, subject and author (title). Changes for name will be ignored.

Parameters:	d (dict) – a dictionary compatible with the info property (see below). All entries must be unicode, bytes, or strings. If bytes values in Python 3 they will be treated as being UTF8 encoded.

setRect(rect)

Changes the rectangle of an annotation. The annotation can be moved around and both sides of the rectangle can be independently scaled. However, the annotation appearance will never get rotated, flipped or sheared.

Parameters:	rect (Rect) – the new rectangle of the annotation. This could e.g. be a rectangle rect = Annot.rect * M with a suitable Matrix M (only scaling and translating will yield the expected effect).

setBorder(value)

PDF only: Change border width and dashing properties. Any other border properties will be deleted.

Parameters:

value (float or dict) – a number or a dictionary specifying the desired border properties. If a dictionary, its width and dashes keys are used (see property annot.border). If a number is specified or a dictionary like {"width": w}, only the border width will be changed and any dashes will remain unchanged. Conversely, with a dictionary {"dashes": [...]}, only line dashing will be changed. To remove dashing and get a contiguous line, specify {"dashes": []}.

setFlags(flags)

Changes the flags of the annotation. See Annotation Flags for possible values and use the | operator to combine several.

Parameters:	flags (int) – an integer specifying the required flags.

setColors(d)

Changes the colors associated with the annotation.

Parameters:	d (dict) – a dictionary containing color specifications. For accepted dictionary keys and values see below. The most practical way should be to first make a copy of the colors property and then modify this dictionary as required.

updateImage()

Attempts to modify the displayed graphical image such that it coincides with the values currently contained in the border and colors properties. This is achieved by modifying the contents stream of the associated appearance XObject. Not all possible formats of content streams are currently supported: if the stream contains invocations of yet other XObject objects, a ValueError is raised.

fileInfo()

Returns basic information of an attached file (file attachment annotations only).

Return type:	dict
Returns:	a dictionary with keys filename, size (uncompressed file size), length (compressed length).

fileGet()

Returns the uncompressed content of the attached file.

Return type:	bytes or str (Py2)
Returns:	the content of the attached file.

fileUpd(buffer, filename=None)

Updates the content of an attached file with new data. Optionally, the filename can be changed, too.

Parameters:	buffer (bytes or bytearray) – the new file content. filename (str) – new filename to associate with the file.
Return type:	int
Returns:	zero

parent

The owning page object of the annotation.

Return type:	Page

rect

The rectangle containing the annotation in untransformed coordinates.

Return type:	Rect

next

The next annotation on this page or None.

Return type:	Annot

type

Meaningful for PDF only: A number and one or two strings describing the annotation type, like [2, 'FreeText', 'FreeTextCallout']. The second string entry is optional and may be empty. [] if not PDF. See the appendix Annotation Types for a list of possible values and their meanings.

Return type:	list

info

Meaningful for PDF only: A dictionary containing various information. All fields are unicode or strings (Python 2 or Python 3 respectively).

• name - e.g. for [12, 'Stamp'] type annotations it will contain the stamp text like Sold or Experimental.
• content - a string containing the text for type Text and FreeText annotations. Commonly used for filling the text field of annotation pop-up windows. For FileAttachment it should be used as description for the attached file. Initially just contains the filename.
• title - a string containing the title of the annotation pop-up window. By convention, this is used for the annotation author.
• creationDate - creation timestamp.
• modDate - last modified timestamp.
• subject - subject, an optional string.

Return type:	dict

flags

Meaningful for PDF only: An integer whose low order bits contain flags for how the annotation should be presented. See section Annotation Flags for details.

Return type:	int

lineEnds

Meaningful for PDF only: A dictionary specifying the starting and the ending appearance of annotations of types Line, PolyLine, among others. An example would be {'start': 'None', 'end': 'OpenArrow'}. {} if not specified or not applicable. For possible values and descriptions in this list, see the Adobe PDF Reference 1.7, table 8.27 on page 630.

Return type:	dict

vertices

Meaningful for PDF only: A list containing point (“vertices”) coordinates (each given by 2 floats specifying the x and y coordinate respectively) for various types of annotations:

• Line - the starting and ending coordinates (4 floats).
• [2, 'FreeText', 'FreeTextCallout'] - 4 or 6 floats designating the starting, the (optional) knee point, and the ending coordinates.
• PolyLine / Polygon - the coordinates of the edges connected by line pieces ( 2 * n floats for n points).
• text markup annotations - 8 * n floats specifying the QuadPoints of the n marked text spans (see Adobe PDF Reference 1.7, page 634).
• Ink - list of one to many sublists of vertex coordinates. Each such sublist represents a separate line in the drawing.

Return type:	list

colors

Meaningful for PDF only: A dictionary of two lists of floats in range 0 <= float <= 1 specifying the common (common) or stroke and the interior (fill) non-stroke colors. The common color is used for borders and everything that is actively painted or written (“stroked”). The fill color is used for the interior of objects like line ends, circles and squares. The lengths of these lists implicitely determine the colorspaces used: 1 = GRAY, 3 = RGB, 4 = CMYK. So [1.0, 0.0, 0.0] stands for RGB and color red. Both lists can be [] if not specified. The dictionary will be empty {} if no PDF. The value of each float is mapped to integer values from 0 (<=> 0.0) to 255 (<=> 1.0).

Return type:	dict

border

Meaningful for PDF only: A dictionary containing border characteristics. It will be empty {} if not PDF or when no border information is provided. Technically, the PDF entries /Border, /BS and /BE will be checked to build this information. The following keys can occur:

• width - a float indicating the border thickness in points.
• effect - a list specifying a border line effect like [1, 'C']. The first entry “intensity” is an integer (from 0 to 2 for maximum intensity). The second is either ‘S’ for “no effect” or ‘C’ for a “cloudy” line.
• dashes - a list of integers (arbitrarily limited to 10) specifying a line dash pattern in user units (usually points). [] means no dashes, [n] means equal on-off lengths of n points, longer lists will be interpreted as specifying alternating on-off length values. See the Adobe PDF Reference 1.7 page 217 for more details.
• style - 1-byte border style: S (Solid) = solid rectangle surrounding the annotation, D (Dashed) = dashed rectangle surrounding the annotation, the dash pattern is specified by the dashes entry, B (Beveled) = a simulated embossed rectangle that appears to be raised above the surface of the page, I (Inset) = a simulated engraved rectangle that appears to be recessed below the surface of the page, U (Underline) = a single line along the bottom of the annotation rectangle.

Return type:	dict

doc = fitz.open("circle-in.pdf")
page = doc[0]                          # page 0
annot = page.firstAnnot                # get the annotation
annot.setBorder({"dashes": [3]})       # set dashes to "3 on, 3 off ..."

# set border / popup color to blue and fill color to some light blue
annot.setColors({"common":[0, 0, 1], "fill":[0.75, 0.8, 0.95]})
info = annot.info                      # get info dict
info["title"] = "Jorj X. McKie"        # author name in popup title

# text in popup window ...
info["content"] = "I changed border and colors and enlarged the image by 20%."
info["subject"] = "Demonstration of PyMuPDF"     # some readers also show this
annot.setInfo(info)                    # update info dict
r = annot.rect                         # take annot rect
r.x1 = r.x0 + r.width  * 1.2           # new location has same top-left
r.y1 = r.y0 + r.height * 1.2           # but 20% longer sides
annot.setRect(r)                       # update rectangle
annot.updateImage()                    # update appearance
doc.save("circle-out.pdf", garbage=4)  # save