Functions

The following are miscellaneous functions and attributes on a fairly low-level technical detail.

Some functions provide detail access to PDF structures. Others are stripped-down, high performance versions of other functions which provide more information.

Yet others are handy, general-purpose utilities.

Function

Short Description

Annot.clean_contents()

PDF only: clean the annot’s contents object

Annot.set_apn_matrix()

PDF only: set the matrix of the appearance object

Annot.set_apn_bbox()

PDF only: set the bbox of the appearance object

Annot.apn_matrix

PDF only: the matrix of the appearance object

Annot.apn_bbox

PDF only: bbox of the appearance object

ConversionHeader()

return header string for getText methods

ConversionTrailer()

return trailer string for getText methods

Document.del_xml_metadata()

PDF only: remove XML metadata

Document.set_xml_metadata()

PDF only: remove XML metadata

Document.delete_object()

PDF only: delete an object

Document.get_new_xref()

PDF only: create and return a new xref entry

Document._getOLRootNumber()

PDF only: return / create xref of /Outline

Document.pdf_catalog()

PDF only: return the xref of the catalog

Document.page_xref()

PDF only: get xref of page object by page number

Document.pdf_trailer()

PDF only: return the PDF file trailer string

Document.xml_metadata_xref()

PDF only: return XML metadata xref number

Document.xref_length()

PDF only: return length of xref table

Document.xref_object()

PDF only: return object definition “source”

Document._make_page_map()

PDF only: create a fast-access array of page numbers

Document.extractFont()

PDF only: extract embedded font

Document.extractImage()

PDF only: extract embedded image

Document.getCharWidths()

PDF only: return a list of glyph widths of a font

Document.isStream()

PDF only: check whether an xref is a stream object

Document.FontInfos

PDF only: information on inserted fonts

ImageProperties()

return a dictionary of basic image properties

getPDFnow()

return the current timestamp in PDF format

getPDFstr()

return PDF-compatible string

getTextlength()

return string length for a given font & fontsize

Page.clean_contents()

PDF only: clean the page’s contents objects

Page.get_contents()

PDF only: return a list of content xref numbers

Page.set_contents()

PDF only: set page’s contents to some xref

Page.getDisplayList()

create the page’s display list

Page.getTextBlocks()

extract text blocks as a Python list

Page.getTextWords()

extract text words as a Python list

Page.run()

run a page through a device

Page.read_contents()

PDF only: get complete, concatenated /Contents source

Page.wrap_contents()

wrap contents with stacking commands

Page.is_wrapped

check whether contents wrapping is present

planishLine()

matrix to map a line to the x-axis

PaperSize()

return width, height for a known paper format

PaperRect()

return rectangle for a known paper format

sRGB_to_pdf()

return PDF RGB color tuple from a sRGB integer

sRGB_to_rgb()

return (R, G, B) color tuple from a sRGB integer

glyph_name_to_unicode()

return unicode from a glyph name

unicode_to_glyph_name()

return glyph name from a unicode

make_table()

split rectangle in sub-rectangles

adobe_glyph_names()

list of glyph names defined in Adobe Glyph List

adobe_glyph_unicodes()

list of unicodes defined in Adobe Glyph List

paperSizes

dictionary of pre-defined paper formats

fitz_fontdescriptors

dictionary of available supplement fonts

PaperSize(s)

Convenience function to return width and height of a known paper format code. These values are given in pixels for the standard resolution 72 pixels = 1 inch.

Currently defined formats include ‘A0’ through ‘A10’, ‘B0’ through ‘B10’, ‘C0’ through ‘C10’, ‘Card-4x6’, ‘Card-5x7’, ‘Commercial’, ‘Executive’, ‘Invoice’, ‘Ledger’, ‘Legal’, ‘Legal-13’, ‘Letter’, ‘Monarch’ and ‘Tabloid-Extra’, each in either portrait or landscape format.

A format name must be supplied as a string (case in sensitive), optionally suffixed with “-L” (landscape) or “-P” (portrait). No suffix defaults to portrait.

Parameters

s (str) – any format name from above (upper or lower case), like “A4” or “letter-l”.

Return type

tuple

Returns

(width, height) of the paper format. For an unknown format (-1, -1) is returned. Esamples: fitz.PaperSize(“A4”) returns (595, 842) and fitz.PaperSize(“letter-l”) delivers (792, 612).


PaperRect(s)

Convenience function to return a Rect for a known paper format.

Parameters

s (str) – any format name supported by PaperSize().

Return type

Rect

Returns

fitz.Rect(0, 0, width, height) with width, height=fitz.PaperSize(s).

>>> import fitz
>>> fitz.PaperRect("letter-l")
fitz.Rect(0.0, 0.0, 792.0, 612.0)
>>>

sRGB_to_pdf(srgb)

New in v1.17.4

Convenience function returning a PDF color triple (red, green, blue) for a given sRGB color integer as it occurs in Page.getText() dictionaries “dict” and “rawdict”.

Parameters

srgb (int) – an integer of format RRGGBB, where each color component is an integer in range(255).

Returns

a tuple (red, green, blue) with float items in intervall 0 <= item <= 1 representing the same color.


glyph_name_to_unicode(name)

New in v1.18.0

Return the unicode number of a glyph name based on the Adobe Glyph List.

Parameters

name (str) – the name of some glyph. The function is based on the Adobe Glyph List.

Return type

int

Returns

the unicode. Invalid name entries return 0xfffd (65533).

Note

A similar functionality is provided by package fontTools in its agl sub-package.


unicode_to_glyph_name(ch)

New in v1.18.0

Return the glyph name of a unicode number, based on the Adobe Glyph List.

Parameters

che (int) –

the unicode given by e.g. ord("ß"). The function is based on the Adobe Glyph List.

Return type

str

Returns

the glyph name. E.g. fitz.unicode_to_glyph_name(ord("Ä")) returns 'Adieresis'.

Note

A similar functionality is provided by package fontTools: in its agl sub-package.


adobe_glyph_names()

New in v1.18.0

Return a list of glyph names defined in the Adobe Glyph List.

Return type

list

Returns

list of strings.

Note

A similar functionality is provided by package fontTools in its agl sub-package.


adobe_glyph_unicodes()

New in v1.18.0

Return a list of unicodes for there exists a glyph name in the Adobe Glyph List.

Return type

list

Returns

list of integers.

Note

A similar functionality is provided by package fontTools in its agl sub-package.


sRGB_to_rgb(srgb)

New in v1.17.4

Convenience function returning a color (red, green, blue) for a given sRGB color integer .

Parameters

srgb (int) – an integer of format RRGGBB, where each color component is an integer in range(255).

Returns

a tuple (red, green, blue) with integer items in intervall 0 <= item <= 255 representing the same color.


make_table(rect, cols=1, rows=1)

New in v1.17.4

Convenience function to split a rectangle into sub-rectangles. Returns a list of rows lists, each containing cols Rect items. Each sub-rectangle can then be addressed by its row and column index.

Parameters
  • rect (rect_like) – the rectangle to split.

  • cols (int) – the desired number of columns.

  • rows (int) – the desired number of rows.

Returns

a list of Rect objects of equal size, whose union equals rect. Here is the layout of a 3x4 table created by cell = fitz.make_table(rect, cols=4, rows=3):

_images/img-make-table.jpg

planishLine(p1, p2)

(New in version 1.16.2)

Return a matrix which maps the line from p1 to p2 to the x-axis such that p1 will become (0,0) and p2 a point with the same distance to (0,0).

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

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

Return type

Matrix

Returns

a matrix which combines a rotation and a translation:

p1 = fitz.Point(1, 1)
p2 = fitz.Point(4, 5)
abs(p2 - p1)  # distance of points
5.0
m = fitz.planishLine(p1, p2)
p1 * m
Point(0.0, 0.0)
p2 * m
Point(5.0, -5.960464477539063e-08)
# distance of the resulting points
abs(p2 * m - p1 * m)
5.0
_images/img-planish.png


paperSizes

A dictionary of pre-defines paper formats. Used as basis for PaperSize().


fitz_fontdescriptors

(New in v1.17.5)

A dictionary of usable fonts from repository pymupdf-fonts. Items are keyed by their reserved fontname and provide information like this:

In [2]: fitz.fitz_fontdescriptors.keys()
Out[2]: dict_keys(['figbo', 'figo', 'figbi', 'figit', 'fimbo', 'fimo',
'spacembo', 'spacembi', 'spacemit', 'spacemo', 'math', 'music', 'symbol1',
'symbol2'])
In [3]: fitz.fitz_fontdescriptors["fimo"]
Out[3]:
{'name': 'Fira Mono Regular',
'size': 125712,
'mono': True,
'bold': False,
'italic': False,
'serif': True,
'glyphs': 1485}

getPDFnow()

Convenience function to return the current local timestamp in PDF compatible format, e.g. D:20170501121525-04’00’ for local datetime May 1, 2017, 12:15:25 in a timezone 4 hours westward of the UTC meridian.

Return type

str

Returns

current local PDF timestamp.


getTextlength(text, fontname='helv', fontsize=11, encoding=TEXT_ENCODING_LATIN)

(New in version 1.14.7)

Calculate the length of text on output with a given builtin font, fontsize and encoding.

Parameters
  • text (str) – the text string.

  • fontname (str) – the fontname. Must be one of either the PDF Base 14 Fonts or the CJK fonts, identified by their “reserved” fontnames (see table in :meth.`Page.insertFont`).

  • fontsize (float) – size of the font.

  • encoding (int) – the encoding to use. Besides 0 = Latin, 1 = Greek and 2 = Cyrillic (Russian) are available. Relevant for Base-14 fonts “Helvetica”, “Courier” and “Times” and their variants only. Make sure to use the same value as in the corresponding text insertion.

Return type

float

Returns

the length in points the string will have (e.g. when used in Page.insertText()).

Note

This function will only do the calculation – it won’t insert font or text.

Warning

If you use this function to determine the required rectangle width for the (Page or Shape) insertTextbox methods, be aware that they calculate on a by-character level. Because of rounding effects, this will mostly lead to a slightly larger number: sum([fitz.getTextlength(c) for c in text]) > fitz.getTextlength(text). So either (1) do the same, or (2) use something like fitz.getTextlength(text + “’”) for your calculation.


getPDFstr(text)

Make a PDF-compatible string: if the text contains code points ord(c) > 255, then it will be converted to UTF-16BE with BOM as a hexadecimal character string enclosed in “<>” brackets like <feff…>. Otherwise, it will return the string enclosed in (round) brackets, replacing any characters outside the ASCII range with some special code. Also, every “(“, “)” or backslash is escaped with an additional backslash.

Parameters

text (str) – the object to convert

Return type

str

Returns

PDF-compatible string enclosed in either () or <>.


ImageProperties(stream)

(New in version 1.14.14)

Return a number of basic properties for an image.

Parameters

stream (bytes|bytearray|BytesIO|file) – an image either in memory or an opened file. A memory resident image maybe any of the formats bytes, bytearray or io.BytesIO.

Returns

a dictionary with the following keys (an empty dictionary for any error):

Key

Value

width

(int) width in pixels

height

(int) height in pixels

colorspace

(int) colorspace.n (e.g. 3 = RGB)

bpc

(int) bits per component (usually 8)

format

(int) image format in range(15)

ext

(str) image file extension indicating the format

size

(int) length of the image in bytes

Example:

>>> fitz.ImageProperties(open("img-clip.jpg","rb"))
{'bpc': 8, 'format': 9, 'colorspace': 3, 'height': 325, 'width': 244, 'ext': 'jpeg', 'size': 14161}
>>>

ConversionHeader("text", filename="UNKNOWN")

Return the header string required to make a valid document out of page text outputs.

Parameters
  • output (str) – type of document. Use the same as the output parameter of getText().

  • filename (str) – optional arbitrary name to use in output types “json” and “xml”.

Return type

str


ConversionTrailer(output)

Return the trailer string required to make a valid document out of page text outputs. See Page.getText() for an example.

Parameters

output (str) – type of document. Use the same as the output parameter of getText().

Return type

str


Document.delete_object(xref)

PDF only: Delete an object given by its cross reference number.

Parameters

xref (int) – the cross reference number. Must be within the document’s valid xref range.

Warning

Only use with extreme care: this may make the PDF unreadable.


Document.del_xml_metadata()

Delete an object containing XML-based metadata from the PDF. (Py-) MuPDF does not support XML-based metadata. Use this if you want to make sure that the conventional metadata dictionary will be used exclusively. Many thirdparty PDF programs insert their own metadata in XML format and thus may override what you store in the conventional dictionary. This method deletes any such reference, and the corresponding PDF object will be deleted during next garbage collection of the file.


Document.set_xml_metadata(xml)

Store data as the document’s XML Metadata. Correct format is up to the programmer – there is no checking. Any previous such data are overwritten.

Parameters

xml (str) – The data to store


Document.pdf_trailer(compressed=False)

(New in version 1.14.9)

Return the trailer of the PDF (UTF-8), which is usually located at the PDF file’s end. If not a PDF or the PDF has no trailer (because of irrecoverable errors), None is returned.

Parameters

compressed (bool) – (ew in version 1.14.14) whether to generate a compressed output or one with nice indentations to ease reading (default).

Returns

a string with the PDF trailer information. This is the analogous method to Document.xref_object() except that the trailer has no identifying xref number. As can be seen here, the trailer object points to other important objects:

>>> doc=fitz.open("adobe.pdf")
>>> # compressed output
>>> print(doc.pdf_trailer(True))
<</Size 334093/Prev 25807185/XRefStm 186352/Root 333277 0 R/Info 109959 0 R
/ID[(\\227\\366/gx\\016ds\\244\\207\\326\\261\\\\\\305\\376u)
(H\\323\\177\\346\\371pkF\\243\\262\\375\\346\\325\\002)]>>
>>> # non-compressed otput:
>>> print(doc.pdf_trailer(False))
<<
   /Size 334093
   /Prev 25807185
   /XRefStm 186352
   /Root 333277 0 R
   /Info 109959 0 R
   /ID [ (\227\366/gx\016ds\244\207\326\261\\\305\376u) (H\323\177\346\371pkF\243\262\375\346\325\002) ]
>>

Note

MuPDF is capable of recovering from a number of damages a PDF may have. This includes re-generating a trailer, where the end of a file has been lost (e.g. because of incomplete downloads). If however None is returned for a PDF, then the recovery mechanisms did not work and you should check for any error messages: print(fitz.TOOLS.mupdf_warnings().


Document._make_page_map()

Create an internal array of page numbers, which significantly speeds up page lookup (Document.loadPage()). If this array exists, finding a page object will be up to two times faster. Functions which change the PDF’s page layout (copy, delete, move, select pages) will destroy this array again.


Document.xml_metadata_xref()

Return the XML-based metadata xref of the PDF if present – also refer to Document._delXmlMetadata(). You can use it to retrieve the content via Document.xrefStream() and then work with it using some XML software.

Return type

int

Returns

xref of PDF file level XML metadata – or 0 if none exists.


Document._getPageObjNumber(pno)

or

Document.page_xref(pno)

Return the xref and generation number for a given page.

Parameters

pno (int) – Page number (zero-based).

Return type

list

Returns

xref and generation number of page pno as a list [xref, gen].


Document.pdf_catalog()

Return the xref of the PDF catalog.

Return type

int

Returns

xref of the PDF catalog – a central dictionary pointing to many other PDF information.


Page.run(dev, transform)

Run a page through a device.

Parameters
  • dev (Device) – Device, obtained from one of the Device constructors.

  • transform (Matrix) – Transformation to apply to the page. Set it to Identity if no transformation is desired.


Page.wrap_contents()

Put string pair “q” / “Q” before, resp. after a page’s /Contents object(s) to ensure that any “geometry” changes are local only.

Use this method as an alternative, minimalistic version of Page.clean_contents(). Its advantage is a small footprint in terms of processing time and impact on the data size of incremental saves.


Page.is_wrapped

Indicate whether Page.wrap_contents() may be required for object insertions in standard PDF geometry. Please note that this is a quick, basic check only: a value of False may still be a false alarm.


Page.getTextBlocks(flags=None)

Deprecated wrapper for TextPage.extractBLOCKS().


Page.getTextWords(flags=None)

Deprecated wrapper for TextPage.extractWORDS().


Page.getDisplayList()

Run a page through a list device and return its display list.

Return type

DisplayList

Returns

the display list of the page.


Page._getContents()

Return a list of xref numbers of contents objects belonging to the page.

Return type

list

Returns

a list of xref integers.

Each page may have zero to many associated contents objects (stream s) which contain some operator syntax describing what appears where and how on the page (like text or images, etc. See the Adobe PDF References, chapter “Operator Summary”, page 985). This function only enumerates the number(s) of such objects. To get the actual stream source, use function Document.xrefStream() with one of the numbers in this list. Use Document.updateStream() to replace the content.


Page._setContents(xref)

PDF only: Set a given object (identified by its xref) as the page’s one and only contents object. Useful for joining mutiple contents objects as in the following snippet:

>>> c = b""
>>> xreflist = page._getContents()
>>> for xref in xreflist:
        c += doc.xrefStream(xref)
>>> doc.updateStream(xreflist[0], c)
>>> page._setContents(xreflist[0])
>>> # doc.save(..., garbage=1) will remove the unused objects
Parameters

xref (int) – the cross reference number of a contents object. An exception is raised if outside the valid xref range or not a stream object.


Page.clean_contents(sanitize=True)

(Changed in v1.17.6)

PDF only: Clean and concatenate all contents objects associated with this page. “Cleaning” includes syntactical corrections, standardizations and “pretty printing” of the contents stream. Discrepancies between contents and resources objects will also be corrected if sanitize is true. See Page.getContents() for more details.

Changed in version 1.16.0 Annotations are no longer implicitely cleaned by this method. Use Annot._cleanContents() separately.

Parameters

sanitize (bool) – (new in v1.17.6) if true, synchronization between resources and their actual use in the contents object is snychronized. For example, if a font is not actually used for any text of the page, then it will be deleted from the /Resources/Font object.

Warning

This is a complex function which may generate large amounts of new data and render old data unused. It is not recommended using it together with the incremental save option. Also note that the resulting singleton new /Contents object is uncompressed. So you should save to a new file using options “deflate=True, garbage=3”.


Page.readContents()

New in version 1.17.0. Return the concatenation of all contents objects associated with the page – without cleaning or otherwise modifying them. Use this method whenever you need to parse this source in its entirety whithout having to bother how many separate contents objects exist.


Annot.clean_contents(sanitize=True)

Clean the contents streams associated with the annotation. This is the same type of action which Page.clean_contents() performs – just restricted to this annotation.


Document.getCharWidths(xref=0, limit=256)

Return a list of character glyphs and their widths for a font that is present in the document. A font must be specified by its PDF cross reference number xref. This function is called automatically from Page.insertText() and Page.insertTextbox(). So you should rarely need to do this yourself.

Parameters
  • xref (int) – cross reference number of a font embedded in the PDF. To find a font xref, use e.g. doc.getPageFontList(pno) of page number pno and take the first entry of one of the returned list entries.

  • limit (int) – limits the number of returned entries. The default of 256 is enforced for all fonts that only support 1-byte characters, so-called “simple fonts” (checked by this method). All PDF Base 14 Fonts are simple fonts.

Return type

list

Returns

a list of limit tuples. Each character c has an entry (g, w) in this list with an index of ord(c). Entry g (integer) of the tuple is the glyph id of the character, and float w is its normalized width. The actual width for some fontsize can be calculated as w * fontsize. For simple fonts, the g entry can always be safely ignored. In all other cases g is the basis for graphically representing c.

This function calculates the pixel width of a string called text:

def pixlen(text, widthlist, fontsize):
try:
    return sum([widthlist[ord(c)] for c in text]) * fontsize
except IndexError:
    m = max([ord(c) for c in text])
    raise ValueError:("max. code point found: %i, increase limit" % m)

Document.xref_object(xref, compressed=False)

Return the string (“source code”) representing an arbitrary object. For stream objects, only the non-stream part is returned. To get the stream data, use Document.xrefStream().

Parameters
  • xref (int) – xref number.

  • compressed (bool) – (new in version 1.14.14) whether to generate a compressed output or one with nice indentations to ease reading or parsing (default).

Return type

string

Returns

the string defining the object identified by xref. Example:

>>> doc = fitz.open("Adobe PDF Reference 1-7.pdf")  # the PDF
>>> page = doc[100]  # some page in it
>>> print(doc.xref_object(page.xref, compressed=True))
<</CropBox[0 0 531 666]/Annots[4795 0 R 4794 0 R 4793 0 R 4792 0 R 4797 0 R 4796 0 R]
/Parent 109820 0 R/StructParents 941/Contents 229 0 R/Rotate 0/MediaBox[0 0 531 666]
/Resources<</Font<</T1_0 3914 0 R/T1_1 3912 0 R/T1_2 3957 0 R/T1_3 3913 0 R/T1_4 4576 0 R
/T1_5 3931 0 R/T1_6 3944 0 R>>/ProcSet[/PDF/Text]/ExtGState<</GS0 333283 0 R>>>>
/Type/Page>>
>>> print(doc.xref_object(page.xref, compressed=False))
<<
   /CropBox [ 0 0 531 666 ]
   /Annots [ 4795 0 R 4794 0 R 4793 0 R 4792 0 R 4797 0 R 4796 0 R ]
   /Parent 109820 0 R
   /StructParents 941
   /Contents 229 0 R
   /Rotate 0
   /MediaBox [ 0 0 531 666 ]
   /Resources <<
      /Font <<
         /T1_0 3914 0 R
         /T1_1 3912 0 R
         /T1_2 3957 0 R
         /T1_3 3913 0 R
         /T1_4 4576 0 R
         /T1_5 3931 0 R
         /T1_6 3944 0 R
      >>
      /ProcSet [ /PDF /Text ]
      /ExtGState <<
         /GS0 333283 0 R
      >>
   >>
   /Type /Page
>>

Document.isStream(xref)

(New in version 1.14.14)

PDF only: Check whether the object represented by xref is a stream type. Return is False if not a PDF or if the number is outside the valid xref range.

Parameters

xref (int) – xref number.

Returns

True if the object definition is followed by data wrapped in keyword pair stream, endstream.


Document.get_new_xref()

Increase the xref by one entry and return that number. This can then be used to insert a new object.

Return type

int

Returns

the number of the new xref entry.


Document.xref_length()

Return length of xref table.

Return type

int

Returns

the number of entries in the xref table.


Document._getOLRootNumber()

Return xref number of the /Outlines root object (this is not the first outline entry!). If this object does not exist, a new one will be created.

Return type

int

Returns

xref number of the /Outlines root object.

Document.extractImage(xref)

PDF Only: Extract data and meta information of an image stored in the document. The output can directly be used to be stored as an image file, as input for PIL, Pixmap creation, etc. This method avoids using pixmaps wherever possible to present the image in its original format (e.g. as JPEG).

Parameters

xref (int) – xref of an image object. If this is not in range(1, doc.xrefLength()), or the object is no image or other errors occur, None is returned and no exception is raised.

Return type

dict

Returns

a dictionary with the following keys

  • ext (str) image type (e.g. ‘jpeg’), usable as image file extension

  • smask (int) xref number of a stencil (/SMask) image or zero

  • width (int) image width

  • height (int) image height

  • colorspace (int) the image’s colorspace.n number.

  • cs-name (str) the image’s colorspace.name.

  • xres (int) resolution in x direction. Please also see resolution.

  • yres (int) resolution in y direction. Please also see resolution.

  • image (bytes) image data, usable as image file content

>>> d = doc.extractImage(1373)
>>> d
{'ext': 'png', 'smask': 2934, 'width': 5, 'height': 629, 'colorspace': 3, 'xres': 96,
'yres': 96, 'cs-name': 'DeviceRGB',
'image': b'\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x05\ ...'}
>>> imgout = open("image." + d["ext"], "wb")
>>> imgout.write(d["image"])
102
>>> imgout.close()

Note

There is a functional overlap with pix = fitz.Pixmap(doc, xref), followed by a pix.getPNGData(). Main differences are that extractImage, (1) does not always deliver PNG image formats, (2) is very much faster with non-PNG images, (3) usually results in much less disk storage for extracted images, (4) returns None in error cases (generates no exception). Look at the following example images within the same PDF.

  • xref 1268 is a PNG – Comparable execution time and identical output:

    In [23]: %timeit pix = fitz.Pixmap(doc, 1268);pix.getPNGData()
    10.8 ms ± 52.4 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)
    In [24]: len(pix.getPNGData())
    Out[24]: 21462
    
    In [25]: %timeit img = doc.extractImage(1268)
    10.8 ms ± 86 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)
    In [26]: len(img["image"])
    Out[26]: 21462
    
  • xref 1186 is a JPEG – Document.extractImage() is many times faster and produces a much smaller output (2.48 MB vs. 0.35 MB):

    In [27]: %timeit pix = fitz.Pixmap(doc, 1186);pix.getPNGData()
    341 ms ± 2.86 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)
    In [28]: len(pix.getPNGData())
    Out[28]: 2599433
    
    In [29]: %timeit img = doc.extractImage(1186)
    15.7 µs ± 116 ns per loop (mean ± std. dev. of 7 runs, 100000 loops each)
    In [30]: len(img["image"])
    Out[30]: 371177
    
Document.extractFont(xref, info_only=False)

PDF Only: Return an embedded font file’s data and appropriate file extension. This can be used to store the font as an external file. The method does not throw exceptions (other than via checking for PDF and valid xref).

Parameters
  • xref (int) – PDF object number of the font to extract.

  • info_only (bool) – only return font information, not the buffer. To be used for information-only purposes, avoids allocation of large buffer areas.

Return type

tuple

Returns

a tuple (basename, ext, subtype, buffer), where ext is a 3-byte suggested file extension (str), basename is the font’s name (str), subtype is the font’s type (e.g. “Type1”) and buffer is a bytes object containing the font file’s content (or b””). For possible extension values and their meaning see Font File Extensions. Return details on error:

  • (“”, “”, “”, b””) – invalid xref or xref is not a (valid) font object.

  • (basename, “n/a”, “Type1”, b””)basename is one of the PDF Base 14 Fonts, which cannot be extracted.

Example:

>>> # store font as an external file
>>> name, ext, buffer = doc.extractFont(4711)
>>> # assuming buffer is not None:
>>> ofile = open(name + "." + ext, "wb")
>>> ofile.write(buffer)
>>> ofile.close()

Warning

The basename is returned unchanged from the PDF. So it may contain characters (such as blanks) which may disqualify it as a filename for your operating system. Take appropriate action.

Document.FontInfos

Contains following information for any font inserted via Page.insertFont() in this session of PyMuPDF:

  • xref (int) – XREF number of the /Type/Font object.

  • info (dict) – detail font information with the following keys:

    • name (str) – name of the basefont

    • idx (int) – index number for multi-font files

    • type (str) – font type (like “TrueType”, “Type0”, etc.)

    • ext (str) – extension to be used, when font is extracted to a file (see Font File Extensions).

    • glyphs (list) – list of glyph numbers and widths (filled by textinsertion methods).

Return type

list