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.
Attribute |
Short Description |
---|---|
PDF only: returns attached file content |
|
PDF only: returns attached file information |
|
PDF only: sets attached file new content |
|
image of the annotation as a pixmap |
|
PDF only: changes the border of an annotation |
|
PDF only: changes the colors of an annotation |
|
PDF only: changes the flags of an annotation |
|
PDF only: change metadata of an annotation |
|
PDF only: sets the line ending styles |
|
PDF only: changes the annot’s transparency |
|
PDF only: changes the rectangle of an annotation |
|
PDF only: applies accumulated annot changes |
|
PDF only: change an existing form field |
|
PDF only: border details |
|
PDF only: border / background and fill colors |
|
PDF only: annotation flags |
|
PDF only: various information |
|
PDF only: start / end appearance of line-type annotations |
|
link to the next annotation |
|
the annot’s transparency |
|
page object of the annotation |
|
rectangle containing the annotation |
|
PDF only: type of the annotation |
|
PDF only: point coordinates of Polygons, PolyLines, etc. |
|
PDF only: Widget object for form fields |
|
PDF only: possible values for “Widget” list / combo boxes |
|
PDF only: “Widget” field name |
|
PDF only: “Widget” field type |
|
PDF only: “Widget” field value |
|
the PDF |
Class API
-
class
Annot
¶ -
getPixmap
(matrix=fitz.Identity, 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
-
setInfo
(d)¶ Changes the info dictionary. This 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 strings.
-
setLineEnds
(start, end)¶ PDF only: Sets an annotation’s line ending styles. Only ‘FreeText’, ‘Line’, ‘PolyLine’, and ‘Polygon’ annotations can have these properties. Each of these annotation types is defined by a list of points which are connected by lines. The symbol identified by
start
is attached to the first point, andend
to the last point of this list. For unsupported annotation types, a no-operation with a warning message results. See Annotation Line End Styles for details.- Parameters
start (int) – The symbol number for the first point.
end (int) – The symbol number for the last point.
-
setOpacity
(value)¶ PDF only: Change an annotation’s transparency.
- Parameters
value (float) – a float in range
[0, 1]
. Any value outside is assumed to be 1. E.g. a value of 0.5 sets the transparency to 50%.
Three overlapping ‘Circle’ annotations with each opacity set to 0.5:
-
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 (finite and not empty). E.g. using a value of
annot.rect + (5, 5, 5, 5)
will shift the annot position 5 pixels to the right and downwards.
-
setBorder
(border)¶ PDF only: Change border width and dashing properties.
- Parameters
border (dict) – a dictionary with keys
"width"
(float),"style"
(str) and"dashes"
(sequence). Omitted keys will leave the resp. property unchanged. To e.g. remove dashing use:"dashes": []
. If dashes is not an empty sequence, “style” will automatically set to “D” (dashed).
-
setFlags
(flags)¶ Changes the annotation flags. See Annotation Flags for possible values and use the
|
operator to combine several.- Parameters
flags (int) – an integer specifying the required flags.
-
setColors
(d)¶ PDF only: Changes the “stroke” and “fill” colors for supported annotation types.
- 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.
Note
This method does not work for widget annotations, and results in a no-op with a warning message. Use
updateWidget()
instead. Certain annotation types have no fill colors. In these cases this value is ignored and a warning is issued. FreeText annotations also require a special handling – seeupdate()
.
-
update
(fontsize=0, text_color=None, border_color=None, fill_color=None, rotate=-1)¶ PDF only: Modify the displayed annotation image such that it coincides with the values contained in the
width
,border
,colors
and other properties, after they have been modified by the respective methods (like.setBorder()
,setColors()
, etc.).It is ignored for widget annotations (use
updateWidget()
instead).Without invoking this method, changes to any of these will be lost. All arguments are optional and only work for FreeText annotations – because of the peculiarities of how this annotation type is implemented by MuPDF. For other types they are ignored. Color specifications may be made in the usual format used in PuMuPDF as sequences of floats ranging from 0.0 to 1.0 (including both). The sequence length must be 1, 3 or 4 (supporting GRAY, RGB and CMYK colorspaces respectively).
- Parameters
fontsize (float) – change font size of the text.
text_color (sequence) – change the text color.
border_color (sequence) – change the border color.
fill_color (sequence) – the fill color. If you set (or leave) this to
None
, then no rectangle at all will be drawn around the text, and the border color will be ignored. This will leave anything “under” the text visible.rotate (int) – new rotation value. Default (-1) means no change.
- Return type
bool
- Returns
True
on success, elseFalse
(orNone
for non-PDFs).
-
updateWidget
(widget)¶ Modifies an existing form field. The existing and the changed widget attributes must all be provided by way of a Widget object. This is because the method will update the field with all properties of the Widget object.
- Parameters
widget (Widget) – a widget object containing the complete (old and new) properties of the widget. Create this object by copying the
Annot.widget
attribute and applying your changes to it and then passing it to this method.
-
fileInfo
()¶ Basic information of the annot’s attached file.
- Return type
dict
- Returns
a dictionary with keys
filename
,ufilename
,desc
(description),size
(uncompressed file size),length
(compressed length) for FileAttachment annot types, elseNone
.
-
fileGet
()¶ Returns attached file content.
- Return type
bytes
- Returns
the content of the attached file.
-
fileUpd
(buffer=None, filename=None, ufilename=None, desc=None)¶ Updates the content of an attached file.
- Parameters
buffer (bytes|bytearray|BytesIO) –
the new file content. May be omitted to only change meta-information.
Changed in version 1.14.13:
io.BytesIO
is now also supported.filename (str) – new filename to associate with the file.
ufilename (str) – new unicode filename to associate with the file.
desc (str) – new description of the file content.
-
opacity
¶ The annotation’s transparency. If set, it is a value in range
[0, 1]
. The PDF default is1.0
. However, in an effort to tell the difference, we return-1.0
if not set (as well as for non-PDFs).- Return type
float
-
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) strings.
name
– e.g. for ‘Stamp’ annotations it will contain the stamp text like “Sold” or “Experimental”, for other annot types you will see the name of the annot’s icon here (“PushPin” for FileAttachment).content
– a string containing the text for typeText
andFreeText
annotations. Commonly used for filling the text field of annotation pop-up windows.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 pair of integers specifying start and end symbol of annotations types ‘FreeText’, ‘Line’, ‘PolyLine’, and ‘Polygon’.
None
if not applicable. For possible values and descriptions in this list, see Annotation Line End Styles and the Adobe PDF Reference 1.7, table 8.27 on page 630.- Return type
tuple
-
vertices
¶ PDF only: A list containing a variable number of point (“vertices”) coordinates (each given by a pair of floats) for various types of annotations:
Line
– the starting and ending coordinates (2 float pairs).[2, 'FreeText', 'FreeTextCallout']
– 2 or 3 float pairs designating the starting, the (optional) knee point, and the ending coordinates.PolyLine
/Polygon
– the coordinates of the edges connected by line pieces (n float pairs for n points).text markup annotations – 4 float pairs specifying the
QuadPoints
of the marked text span (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
-
widget
¶ PDF only: A class containing all properties of a form field – including the following three attributes.
None
for other annotation types.- Return type
-
widget_name
¶ PDF only: The field name for an annotation of type
ANNOT_WIDGET
,None
otherwise. EqualsWidget.field_name
.- Return type
str
-
widget_value
¶ PDF only: The field content for an annotation of type
ANNOT_WIDGET
. IsNone
for non-PDFs, other annotation types, or if no value has been entered. For button types the value will beTrue
orFalse
. Push button states have no permanent reflection in the file and are therefore always reported asFalse
. For text, list boxes and combo boxes, a string is returned for single values. If multiple selections have been made (may happen for list boxes and combo boxes), a list of strings is returned. For list boxes and combo boxes, the selectable values are contained inwidget_choices
below. EqualsWidget.field_value
.- Return type
bool, str or list
-
widget_choices
¶ PDF only: Contains a list of selectable values for list boxes and combo boxes (annotation type
ANNOT_WIDGET
), elseNone
. EqualsWidget.choice_values
.- Return type
list
-
widget_type
¶ PDF only: The field type for an annotation of type
ANNOT_WIDGET
, elseNone
.- Return type
tuple
- Returns
a tuple
(int, str)
. E.g. for a text field(3, 'Text')
is returned. For a complete list see Annotation Types. The first item equalsWidget.field_type
, and the second isWidget.field_type_string
.
-
colors
¶ Meaningful for PDF only: A dictionary of two lists of floats in range
0 <= float <= 1
specifying thestroke
and the interior (fill
) colors. If not a PDF,None
is returned. The stroke 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 color red. Both lists can be[]
if no color is specified. The value of each floatf
is mapped to the integer valuei
in range 0 to 255 via the computationf = i / 255
.- Return type
dict
-
border
¶ Meaningful for PDF only: A dictionary containing border characteristics. It will be
None
for non-PDFs and an empty dictionary if no border information exists. The following keys can occur:width
– a float indicating the border thickness in points. The value is -1.0 if no width is specified.dashes
– a sequence of integers specifying a line dash pattern.[]
means no dashes,[n]
means equal on-off lengths ofn
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 thedashes
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
-
Example¶
Change the graphical image of an annotation. Also update the “author” and the text to be shown in the popup window:
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 stroke and fill color to some blue
annot.setColors({"stroke":(0, 0, 1), "fill":(0.75, 0.8, 0.95)})
info = annot.info # get info dict
info["title"] = "Jorj X. McKie" # set author
# text in popup window ...
info["content"] = "I changed border and colors and enlarged the image by 20%."
info["subject"] = "Demonstration of PyMuPDF" # some PDF viewers 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.update() # update the annot's appearance
doc.save("circle-out.pdf") # save
This is how the circle annotation looks like before and after the change (pop-up windows displayed using Nitro PDF viewer):