API 参考文档
命令行界面
- 版本 1.16.8 中的新功能
PyMuPDF 也可以从命令行使用以执行实用功能。此功能应使一些最基本的脚本编写过时。
不可否认，MuPDF CLI mutool 存在一些功能重叠。另一方面，MuPDF 不再支持 PDF 嵌入文件，因此 PyMuPDF 在这里提供了一些独特的东西。
调用
命令行界面可以通过两种方式调用。
-
使用已安装的
pymupdf命令：pymupdf <command and parameters> -
或者使用 Python 的
-m开关和 PyMuPDF 的fitz模块：python -m fitz <command and parameters>
一般备注：
-
通过
"-h"请求帮助，或通过"command -h"请求特定命令的帮助。 -
在不引入歧义的情况下可以缩写参数。
-
几个命令支持参数
-pages和-xrefs。它们用于向下选择。请注意：- 此实用程序的 页码 必须是 基于 1 的。
- 有效的
xref编号从 1 开始。 - 指定逗号分隔的 单个 整数或整数 范围 的列表。范围 是由一个连字符“-”分隔的整数对。整数不能超过最大页数或
xref编号。为了指定最大值，可以使用符号变量“N”。整数或范围可以多次出现，顺序任意且可以重叠。如果范围中的第一个数字大于第二个数字，则将以相反顺序处理相应项目。
-
如何在您的脚本中使用该模块：
>>> import pymupdf.__main__ >>> cmd = "clean input.pdf output.pdf -pages 1,N".split() # prepare command line >>> saved_parms = sys.argv[1:] # save original command line >>> sys.argv[1:] = cmd # store new command line >>> pymupdf.__main__.() # execute module >>> sys.argv[1:] = saved_parms # restore original command line -
使用以下 2 行代码，并使用Nuitka进行独立模式编译。这将为您提供一个带有所有模块功能的 CLI 可执行文件，可以在所有兼容平台上使用，而无需安装 Python、PyMuPDF 或 MuPDF。
from pymupdf.__main__ import main
main()
清理和复制
此命令将优化 PDF 并将结果存储在新文件中。您还可以将其用于加密、解密和创建子文档。它与 MuPDF 命令行实用程序 “mutool clean” 大多相似：
pymupdf clean -h
usage: fitz clean [-h] [-password PASSWORD]
[-encryption {keep,none,rc4-40,rc4-128,aes-128,aes-256}]
[-owner OWNER] [-user USER] [-garbage {0,1,2,3,4}]
[-compress] [-ascii] [-linear] [-permission PERMISSION]
[-sanitize] [-pretty] [-pages PAGES]
input output
-------------- optimize PDF or create sub-PDF if pages given --------------
positional arguments:
input PDF filename
output output PDF filename
optional arguments:
-h, --help show this help message and exit
-password PASSWORD password
-encryption {keep,none,rc4-40,rc4-128,aes-128,aes-256}
encryption method
-owner OWNER owner password
-user USER user password
-garbage {0,1,2,3,4} garbage collection level
-compress compress (deflate) output
-ascii ASCII encode binary data
-linear format for fast web display
-permission PERMISSION
integer with permission levels
-sanitize sanitize / clean contents
-pretty prettify PDF structure
-pages PAGES output selected pages, format: 1,5-7,50-N
如果指定了“-pages”，请注意只复制与页面相关的对象，不包括文档级项目，例如嵌入的文件等。
有关参数含义，请参阅Document.save()。
提取字体和图像
从所选 PDF 页面中提取字体或图像到指定目录：
pymupdf extract -h
usage: fitz extract [-h] [-images] [-fonts] [-output OUTPUT] [-password PASSWORD]
[-pages PAGES]
input
--------------------- extract images and fonts to disk --------------------
positional arguments:
input PDF filename
optional arguments:
-h, --help show this help message and exit
-images extract images
-fonts extract fonts
-output OUTPUT output directory, defaults to current
-password PASSWORD password
-pages PAGES only consider these pages, format: 1,5-7,50-N
图像文件名根据命名方案构建：“img-xref.ext”，其中“ext”是与图像关联的扩展名，xref是图像 PDF 对象的xref。
字体文件名由字体名称和相关扩展名组成。字体名称中的任何空格都将替换为连字符“-”。
输出目录必须已经存在。
注意
除了输出目录创建之外，此功能在功能上等同于并且已过时 此脚本。
连接 PDF 文档
要连接几个 PDF 文件，请指定：
pymupdf join -h
usage: fitz join [-h] -output OUTPUT [input [input ...]]
---------------------------- join PDF documents ---------------------------
positional arguments:
input input filenames
optional arguments:
-h, --help show this help message and exit
-output OUTPUT output filename
specify each input as 'filename[,password[,pages]]'
注意
-
每个输入必须输入为**“文件名，密码，页面”**。密码和页面是可选的。
-
如果使用“pages”条目，则需要密码输入。如果 PDF 不需要密码，请指定两个逗号。
-
**“页面”**格式与本节顶部解释的相同。
-
每个输入文件在使用后立即关闭。因此，您可以使用其中一个作为输出文件名，从而覆盖它。
示例：要连接以下文件
-
file1.pdf: 所有页面，从后往前，无密码
-
file2.pdf: 最后一页，第一页，密码：“secret”
-
file3.pdf: 从第 5 页到最后一页，无密码
并将结果存储为output.pdf，输入此命令：
pymupdf join -o output.pdf file1.pdf,N-1 file2.pdf,secret,N,1 file3.pdf,5-N
低级信息
显示 PDF 内部信息。同样，与*“mutool show”*有相似之处：
pymupdf show -h
usage: fitz show [-h] [-password PASSWORD] [-catalog] [-trailer] [-metadata]
[-xrefs XREFS] [-pages PAGES]
input
------------------------- display PDF information -------------------------
positional arguments:
input PDF filename
optional arguments:
-h, --help show this help message and exit
-password PASSWORD password
-catalog show PDF catalog
-trailer show PDF trailer
-metadata show PDF metadata
-xrefs XREFS show selected objects, format: 1,5-7,N
-pages PAGES show selected pages, format: 1,5-7,50-N
示例：
pymupdf show x.pdf
PDF is password protected
pymupdf show x.pdf -pass hugo
authentication unsuccessful
pymupdf show x.pdf -pass jorjmckie
authenticated as owner
file 'x.pdf', pages: 1, objects: 19, 58 MB, PDF 1.4, encryption: Standard V5 R6 256-bit AES
Document contains 15 embedded files.
pymupdf show FDA-1572_508_R6_FINAL.pdf -tr -m
'FDA-1572_508_R6_FINAL.pdf', pages: 2, objects: 1645, 1.4 MB, PDF 1.6, encryption: Standard V4 R4 128-bit AES
document contains 740 root form fields and is signed
------------------------------- PDF metadata ------------------------------
format: PDF 1.6
title: FORM FDA 1572
author: PSC Publishing Services
subject: Statement of Investigator
keywords: None
creator: PScript5.dll Version 5.2.2
producer: Acrobat Distiller 9.0.0 (Windows)
creationDate: D:20130522104413-04'00'
modDate: D:20190718154905-07'00'
encryption: Standard V4 R4 128-bit AES
------------------------------- PDF trailer -------------------------------
<<
/DecodeParms <<
/Columns 5
/Predictor 12
>>
/Encrypt 1389 0 R
/Filter /FlateDecode
/ID [ <9252E9E39183F2A0B0C51BE557B8A8FC> <85227BE9B84B724E8F678E1529BA8351> ]
/Index [ 1388 258 ]
/Info 1387 0 R
/Length 253
/Prev 1510559
/Root 1390 0 R
/Size 1646
/Type /XRef
/W [ 1 3 1 ]
>>
嵌入文件命令
以下命令处理嵌入文件 - 这是 MuPDF 在 v1.14 之后完全删除的功能，因此从所有其命令行工具中删除。
信息
显示嵌入文件名（长格式或短格式）：
pymupdf embed-info -h
usage: fitz embed-info [-h] [-name NAME] [-detail] [-password PASSWORD] input
--------------------------- list embedded files ---------------------------
positional arguments:
input PDF filename
optional arguments:
-h, --help show this help message and exit
-name NAME if given, report only this one
-detail show detail information
-password PASSWORD password
示例：
pymupdf embed-info some.pdf
'some.pdf' contains the following 15 embedded files.
20110813_180956_0002.jpg
20110813_181009_0003.jpg
20110813_181012_0004.jpg
20110813_181131_0005.jpg
20110813_181144_0006.jpg
20110813_181306_0007.jpg
20110813_181307_0008.jpg
20110813_181314_0009.jpg
20110813_181315_0010.jpg
20110813_181324_0011.jpg
20110813_181339_0012.jpg
20110813_181913_0013.jpg
insta-20110813_180944_0001.jpg
markiert-20110813_180944_0001.jpg
neue.datei
每个条目的详细输出如下所示：
name: neue.datei
filename: text-tester.pdf
ufilename: text-tester.pdf
desc: nur zum Testen!
size: 4639
length: 1566
提取
像这样提取嵌入文件：
pymupdf embed-extract -h
usage: fitz embed-extract [-h] -name NAME [-password PASSWORD] [-output OUTPUT]
input
---------------------- extract embedded file to disk ----------------------
positional arguments:
input PDF filename
optional arguments:
-h, --help show this help message and exit
-name NAME name of entry
-password PASSWORD password
-output OUTPUT output filename, default is stored name
有关详细信息，请参阅Document.embfile_get()。示例（参考上一节）：
pymupdf embed-extract some.pdf -name neue.datei
Saved entry 'neue.datei' as 'text-tester.pdf'
删除
像这样删除嵌入文件：
pymupdf embed-del -h
usage: fitz embed-del [-h] [-password PASSWORD] [-output OUTPUT] -name NAME input
--------------------------- delete embedded file --------------------------
positional arguments:
input PDF filename
optional arguments:
-h, --help show this help message and exit
-password PASSWORD password
-output OUTPUT output PDF filename, incremental save if none
-name NAME name of entry to delete
有关详细信息，请参阅Document.embfile_del()。
插入
使用此命令添加新的嵌入文件：
pymupdf embed-add -h
usage: fitz embed-add [-h] [-password PASSWORD] [-output OUTPUT] -name NAME -path
PATH [-desc DESC]
input
---------------------------- add embedded file ----------------------------
positional arguments:
input PDF filename
optional arguments:
-h, --help show this help message and exit
-password PASSWORD password
-output OUTPUT output PDF filename, incremental save if none
-name NAME name of new entry
-path PATH path to data for new entry
-desc DESC description of new entry
“名称” 绝对不应该已经存在于 PDF 中。有关详细信息，请参阅Document.embfile_add()。
更新
使用此命令更新现有的嵌入文件：
pymupdf embed-upd -h
usage: fitz embed-upd [-h] -name NAME [-password PASSWORD] [-output OUTPUT]
[-path PATH] [-filename FILENAME] [-ufilename UFILENAME]
[-desc DESC]
input
--------------------------- update embedded file --------------------------
positional arguments:
input PDF filename
optional arguments:
-h, --help show this help message and exit
-name NAME name of entry
-password PASSWORD password
-output OUTPUT Output PDF filename, incremental save if none
-path PATH path to new data for entry
-filename FILENAME new filename to store in entry
-ufilename UFILENAME new unicode filename to store in entry
-desc DESC new description to store in entry
except '-name' all parameters are optional
使用此方法更改文件的元信息 - 只需省略*“路径”*。有关详细信息，请参阅Document.embfile_upd()。
复制
在 PDF 之间复制嵌入的文件：
pymupdf embed-copy -h
usage: fitz embed-copy [-h] [-password PASSWORD] [-output OUTPUT] -source
SOURCE [-pwdsource PWDSOURCE]
[-name [NAME [NAME ...]]]
input
--------------------- copy embedded files between PDFs --------------------
positional arguments:
input PDF to receive embedded files
optional arguments:
-h, --help show this help message and exit
-password PASSWORD password of input
-output OUTPUT output PDF, incremental save to 'input' if omitted
-source SOURCE copy embedded files from here
-pwdsource PWDSOURCE password of 'source' PDF
-name [NAME [NAME ...]]
restrict copy to these entries
文本提取
- v1.18.16 中的新功能
从任意支持的文档中提取文本到文本文件。目前，有三种输出格式模式可用：简单，块排序和复制物理布局。
-
简单文本提取会将所有文本复制到文档页面中 - 不会进行任何特定的阅读顺序重新排列。
-
块排序按升序垂直，然后水平坐标对文本块（由 MuPDF 标识）进行排序。这应足以建立基本文本页的“自然”阅读顺序。
-
布局 力求复制输入页面的原始外观。你可以期待如下结果（由命令
pymupdf gettext -pages 1 demo1.pdf生成）：
注意
“gettext” 命令提供了一种类似于 XPDF 软件的 CLI 工具 pdftotext 的功能，www.foolabs.com/xpdf/ — 这对于“布局”模式尤其如此，该模式结合了该工具的 -layout 和 -table 选项。
在输出文件的每一页之后，都会写入一个换页符，hex(12) — 即使输入页面根本没有文本。此行为可以通过选项进行控制。
注意
对于“布局”模式，仅支持水平、从左到右、从上到下的文本，其他文本将被忽略。在此模式下，如果文本的fontsize太小，则也将被忽略。
“Simple” 和 “blocks” 模式在对比输出中会显示所有文本，无论文本大小或方向如何。
命令：
pymupdf gettext -h
usage: fitz gettext [-h] [-password PASSWORD] [-mode {simple,blocks,layout}] [-pages PAGES] [-noligatures]
[-convert-white] [-extra-spaces] [-noformfeed] [-skip-empty] [-output OUTPUT] [-grid GRID]
[-fontsize FONTSIZE]
input
----------------- extract text in various formatting modes ----------------
positional arguments:
input input document filename
optional arguments:
-h, --help show this help message and exit
-password PASSWORD password for input document
-mode {simple,blocks,layout}
mode: simple, block sort, or layout (default)
-pages PAGES select pages, format: 1,5-7,50-N
-noligatures expand ligature characters (default False)
-convert-white convert whitespace characters to space (default False)
-extra-spaces fill gaps with spaces (default False)
-noformfeed write linefeeds, no formfeeds (default False)
-skip-empty suppress pages with no text (default False)
-output OUTPUT store text in this file (default inputfilename.txt)
-grid GRID merge lines if closer than this (default 2)
-fontsize FONTSIZE only include text with a larger :data:`fontsize` (default 3)
注意
只要不引入歧义，命令选项可以缩写。因此，以下命令执行相同的操作：
... -output text.txt -noligatures -noformfeed -convert-white -grid 3 -extra-spaces ...... -o text.txt -nol -nof -c -g 3 -e ...
输出文件名默认为输入文件名，其扩展名替换为 .txt。与其他命令一样，你可以按照上面所示的 mutool 格式选择页面范围**（注意：基于 1）**。
-
模式：（str）选择格式模式 — 默认为“布局”。
-
去连字：（bool）对应于非
TEXT_PRESERVE_LIGATURES。如果指定，连字（在高级字体中存在的字形，如“fi”组合多个字符的字形）将被分割成它们的组件（即“f”，“i”）。默认为传递它们。 -
转换白色：对应于非
TEXT_PRESERVE_WHITESPACE。如果指定，所有空白字符（如制表符）将替换为一个或多个空格。默认为传递它们。 -
额外空格：（bool）对应于非
TEXT_INHIBIT_SPACES。如果指定，相邻字符之间的大间隙将用一个或多个空格填充。默认为关闭。 -
无换页符：（bool）在输出页面末尾写入换行符
n，而不是hex(12)（换页符）。 -
跳过空白页：（bool）跳过没有文本的页面。
-
grid：垂直坐标差异不超过此值（以点为单位）的线将合并到同一输出行中。仅适用于“layout”模式。慎用：在大多数情况下，3 或默认的 2 应该足够。如果太大，原始中意图不同的线可能会被合并，导致输出混乱和/或不完整。如果太低，则可能会为输入行中的某些跨度生成单独的输出行，仅因为它们以稍微不同的字体编码并具有略微偏离的属性。
-
**fontsize：**仅包括文本大于此值的
fontsize（默认为 3）。仅适用于“layout”选项。
对本页有任何反馈吗？
此软件按原样提供，不带任何明示或暗示的担保。此软件在许可下分发，未经明确授权不得复制、修改或分发。有关详细信息，请参阅artifex.com上的许可信息或联系 Artifex Software Inc.，39 Mesa Street，Suite 108A，San Francisco CA 94129，美国。
本文档覆盖了所有版本直至 1.24.4。
调用
命令行界面可以通过两种方式调用。
-
使用已安装的
pymupdf命令：pymupdf <command and parameters> -
或者使用 Python 的
-m开关与 PyMuPDF 的fitz模块：python -m fitz <command and parameters>
一般备注：
-
通过
"-h"请求帮助，或通过"command -h"请求特定命令的帮助。 -
在不引入歧义的情况下，参数可以缩写。
-
几个命令支持参数
-pages和-xrefs。它们用于下拉选择。请注意：- 此实用程序的页面编号必须以基于 1 的方式给出。
- 有效的
xref编号从 1 开始。 - 指定一个以逗号分隔的单个整数或整数范围的列表。范围是由一个连字符“-”分隔的两个整数对。整数不得超过最大页面或 xref 编号。为了指定最大值，可以使用符号变量“N”。整数或范围可以多次出现，顺序任意，并且可以重叠。如果在范围内第一个数字大于第二个数字，则将按相反顺序处理相应项。
-
如何在您的脚本内使用该模块：
>>> import pymupdf.__main__ >>> cmd = "clean input.pdf output.pdf -pages 1,N".split() # prepare command line >>> saved_parms = sys.argv[1:] # save original command line >>> sys.argv[1:] = cmd # store new command line >>> pymupdf.__main__.() # execute module >>> sys.argv[1:] = saved_parms # restore original command line -
使用以下 2 行代码并以独立模式编译它，可以使用Nuitka。这将为您提供一个带有所有模块功能的 CLI 可执行文件，可在所有兼容的平台上使用，无需安装 Python、PyMuPDF 或 MuPDF。
from pymupdf.__main__ import main
main()
清理和复制
此命令将优化 PDF 并将结果存储在新文件中。您也可以将其用于加密、解密和创建子文档。它与 MuPDF 命令行实用程序*“mutool clean”*大致相似：
pymupdf clean -h
usage: fitz clean [-h] [-password PASSWORD]
[-encryption {keep,none,rc4-40,rc4-128,aes-128,aes-256}]
[-owner OWNER] [-user USER] [-garbage {0,1,2,3,4}]
[-compress] [-ascii] [-linear] [-permission PERMISSION]
[-sanitize] [-pretty] [-pages PAGES]
input output
-------------- optimize PDF or create sub-PDF if pages given --------------
positional arguments:
input PDF filename
output output PDF filename
optional arguments:
-h, --help show this help message and exit
-password PASSWORD password
-encryption {keep,none,rc4-40,rc4-128,aes-128,aes-256}
encryption method
-owner OWNER owner password
-user USER user password
-garbage {0,1,2,3,4} garbage collection level
-compress compress (deflate) output
-ascii ASCII encode binary data
-linear format for fast web display
-permission PERMISSION
integer with permission levels
-sanitize sanitize / clean contents
-pretty prettify PDF structure
-pages PAGES output selected pages, format: 1,5-7,50-N
如果指定了“-pages”，请注意仅复制与页面相关的对象，不包括文档级项目，例如嵌入文件。
请参阅 Document.save() 以了解参数含义。
提取字体和图像
从选定的 PDF 页面提取字体或图像到指定目录：
pymupdf extract -h
usage: fitz extract [-h] [-images] [-fonts] [-output OUTPUT] [-password PASSWORD]
[-pages PAGES]
input
--------------------- extract images and fonts to disk --------------------
positional arguments:
input PDF filename
optional arguments:
-h, --help show this help message and exit
-images extract images
-fonts extract fonts
-output OUTPUT output directory, defaults to current
-password PASSWORD password
-pages PAGES only consider these pages, format: 1,5-7,50-N
图像文件名 根据命名方案构建：“img-xref.ext”，其中“ext”是与图像关联的扩展名，xref是图像 PDF 对象的 xref。
字体文件名 由字体名称和相关扩展名组成。字体名称中的任何空格都将替换为连字符“-”。
输出目录必须已经存在。
注意
除了输出目录的创建外，此功能在功能上等同于并淘汰了 此脚本。
合并 PDF 文档
要合并多个 PDF 文件，请指定：
pymupdf join -h
usage: fitz join [-h] -output OUTPUT [input [input ...]]
---------------------------- join PDF documents ---------------------------
positional arguments:
input input filenames
optional arguments:
-h, --help show this help message and exit
-output OUTPUT output filename
specify each input as 'filename[,password[,pages]]'
注意
-
每个输入必须输入为 “filename,password,pages”。密码和页面是可选的。
-
如果使用“pages”条目，则需要密码输入。如果 PDF 不需要密码，请指定两个逗号。
-
“pages” 的格式与本节顶部解释的相同。
-
每个输入文件在使用后立即关闭。因此，您可以使用其中一个作为输出文件名，并覆盖它。
示例：要合并以下文件
-
file1.pdf： 所有页面，从后往前，无密码
-
file2.pdf： 最后一页，第一页，密码：“secret”
-
file3.pdf： 从第 5 页到最后一页，无密码
并将结果存储为 output.pdf，请输入此命令：
pymupdf join -o output.pdf file1.pdf,N-1 file2.pdf,secret,N,1 file3.pdf,5-N
低级信息
显示 PDF 的内部信息。同样，与 “mutool show” 有相似之处：
pymupdf show -h
usage: fitz show [-h] [-password PASSWORD] [-catalog] [-trailer] [-metadata]
[-xrefs XREFS] [-pages PAGES]
input
------------------------- display PDF information -------------------------
positional arguments:
input PDF filename
optional arguments:
-h, --help show this help message and exit
-password PASSWORD password
-catalog show PDF catalog
-trailer show PDF trailer
-metadata show PDF metadata
-xrefs XREFS show selected objects, format: 1,5-7,N
-pages PAGES show selected pages, format: 1,5-7,50-N
示例：
pymupdf show x.pdf
PDF is password protected
pymupdf show x.pdf -pass hugo
authentication unsuccessful
pymupdf show x.pdf -pass jorjmckie
authenticated as owner
file 'x.pdf', pages: 1, objects: 19, 58 MB, PDF 1.4, encryption: Standard V5 R6 256-bit AES
Document contains 15 embedded files.
pymupdf show FDA-1572_508_R6_FINAL.pdf -tr -m
'FDA-1572_508_R6_FINAL.pdf', pages: 2, objects: 1645, 1.4 MB, PDF 1.6, encryption: Standard V4 R4 128-bit AES
document contains 740 root form fields and is signed
------------------------------- PDF metadata ------------------------------
format: PDF 1.6
title: FORM FDA 1572
author: PSC Publishing Services
subject: Statement of Investigator
keywords: None
creator: PScript5.dll Version 5.2.2
producer: Acrobat Distiller 9.0.0 (Windows)
creationDate: D:20130522104413-04'00'
modDate: D:20190718154905-07'00'
encryption: Standard V4 R4 128-bit AES
------------------------------- PDF trailer -------------------------------
<<
/DecodeParms <<
/Columns 5
/Predictor 12
>>
/Encrypt 1389 0 R
/Filter /FlateDecode
/ID [ <9252E9E39183F2A0B0C51BE557B8A8FC> <85227BE9B84B724E8F678E1529BA8351> ]
/Index [ 1388 258 ]
/Info 1387 0 R
/Length 253
/Prev 1510559
/Root 1390 0 R
/Size 1646
/Type /XRef
/W [ 1 3 1 ]
>>
嵌入文件命令
以下命令处理嵌入文件 - 这是自 MuPDF v1.14 后完全从 MuPDF 及其所有命令行工具中移除的功能。
信息
显示嵌入文件名（长格式或短格式）：
pymupdf embed-info -h
usage: fitz embed-info [-h] [-name NAME] [-detail] [-password PASSWORD] input
--------------------------- list embedded files ---------------------------
positional arguments:
input PDF filename
optional arguments:
-h, --help show this help message and exit
-name NAME if given, report only this one
-detail show detail information
-password PASSWORD password
示例：
pymupdf embed-info some.pdf
'some.pdf' contains the following 15 embedded files.
20110813_180956_0002.jpg
20110813_181009_0003.jpg
20110813_181012_0004.jpg
20110813_181131_0005.jpg
20110813_181144_0006.jpg
20110813_181306_0007.jpg
20110813_181307_0008.jpg
20110813_181314_0009.jpg
20110813_181315_0010.jpg
20110813_181324_0011.jpg
20110813_181339_0012.jpg
20110813_181913_0013.jpg
insta-20110813_180944_0001.jpg
markiert-20110813_180944_0001.jpg
neue.datei
每个条目的详细输出如下所示：
name: neue.datei
filename: text-tester.pdf
ufilename: text-tester.pdf
desc: nur zum Testen!
size: 4639
length: 1566
提取
像这样提取嵌入文件：
pymupdf embed-extract -h
usage: fitz embed-extract [-h] -name NAME [-password PASSWORD] [-output OUTPUT]
input
---------------------- extract embedded file to disk ----------------------
positional arguments:
input PDF filename
optional arguments:
-h, --help show this help message and exit
-name NAME name of entry
-password PASSWORD password
-output OUTPUT output filename, default is stored name
有关详细信息，请参阅 Document.embfile_get()。示例（参见前一节）：
pymupdf embed-extract some.pdf -name neue.datei
Saved entry 'neue.datei' as 'text-tester.pdf'
删除
像这样删除嵌入文件：
pymupdf embed-del -h
usage: fitz embed-del [-h] [-password PASSWORD] [-output OUTPUT] -name NAME input
--------------------------- delete embedded file --------------------------
positional arguments:
input PDF filename
optional arguments:
-h, --help show this help message and exit
-password PASSWORD password
-output OUTPUT output PDF filename, incremental save if none
-name NAME name of entry to delete
有关详细信息，请参阅 Document.embfile_del()。
插入
使用以下命令添加新的嵌入文件：
pymupdf embed-add -h
usage: fitz embed-add [-h] [-password PASSWORD] [-output OUTPUT] -name NAME -path
PATH [-desc DESC]
input
---------------------------- add embedded file ----------------------------
positional arguments:
input PDF filename
optional arguments:
-h, --help show this help message and exit
-password PASSWORD password
-output OUTPUT output PDF filename, incremental save if none
-name NAME name of new entry
-path PATH path to data for new entry
-desc DESC description of new entry
“NAME” 绝不能已存在于 PDF 中。有关详细信息，请参阅 Document.embfile_add()。
更新
使用以下命令更新现有的嵌入文件：
pymupdf embed-upd -h
usage: fitz embed-upd [-h] -name NAME [-password PASSWORD] [-output OUTPUT]
[-path PATH] [-filename FILENAME] [-ufilename UFILENAME]
[-desc DESC]
input
--------------------------- update embedded file --------------------------
positional arguments:
input PDF filename
optional arguments:
-h, --help show this help message and exit
-name NAME name of entry
-password PASSWORD password
-output OUTPUT Output PDF filename, incremental save if none
-path PATH path to new data for entry
-filename FILENAME new filename to store in entry
-ufilename UFILENAME new unicode filename to store in entry
-desc DESC new description to store in entry
except '-name' all parameters are optional
使用此方法更改文件的元信息 - 只需省略 “PATH”。有关详细信息，请参阅 Document.embfile_upd()。
复制
在 PDF 之间复制嵌入的文件：
pymupdf embed-copy -h
usage: fitz embed-copy [-h] [-password PASSWORD] [-output OUTPUT] -source
SOURCE [-pwdsource PWDSOURCE]
[-name [NAME [NAME ...]]]
input
--------------------- copy embedded files between PDFs --------------------
positional arguments:
input PDF to receive embedded files
optional arguments:
-h, --help show this help message and exit
-password PASSWORD password of input
-output OUTPUT output PDF, incremental save to 'input' if omitted
-source SOURCE copy embedded files from here
-pwdsource PWDSOURCE password of 'source' PDF
-name [NAME [NAME ...]]
restrict copy to these entries
信息
显示嵌入文件的名称（长格式或短格式）：
pymupdf embed-info -h
usage: fitz embed-info [-h] [-name NAME] [-detail] [-password PASSWORD] input
--------------------------- list embedded files ---------------------------
positional arguments:
input PDF filename
optional arguments:
-h, --help show this help message and exit
-name NAME if given, report only this one
-detail show detail information
-password PASSWORD password
示例：
pymupdf embed-info some.pdf
'some.pdf' contains the following 15 embedded files.
20110813_180956_0002.jpg
20110813_181009_0003.jpg
20110813_181012_0004.jpg
20110813_181131_0005.jpg
20110813_181144_0006.jpg
20110813_181306_0007.jpg
20110813_181307_0008.jpg
20110813_181314_0009.jpg
20110813_181315_0010.jpg
20110813_181324_0011.jpg
20110813_181339_0012.jpg
20110813_181913_0013.jpg
insta-20110813_180944_0001.jpg
markiert-20110813_180944_0001.jpg
neue.datei
每个条目的详细输出如下：
name: neue.datei
filename: text-tester.pdf
ufilename: text-tester.pdf
desc: nur zum Testen!
size: 4639
length: 1566
提取
这样提取嵌入文件：
pymupdf embed-extract -h
usage: fitz embed-extract [-h] -name NAME [-password PASSWORD] [-output OUTPUT]
input
---------------------- extract embedded file to disk ----------------------
positional arguments:
input PDF filename
optional arguments:
-h, --help show this help message and exit
-name NAME name of entry
-password PASSWORD password
-output OUTPUT output filename, default is stored name
有关详细信息，请参阅Document.embfile_get()。示例（参见前一节）：
pymupdf embed-extract some.pdf -name neue.datei
Saved entry 'neue.datei' as 'text-tester.pdf'
删除
这样删除嵌入文件：
pymupdf embed-del -h
usage: fitz embed-del [-h] [-password PASSWORD] [-output OUTPUT] -name NAME input
--------------------------- delete embedded file --------------------------
positional arguments:
input PDF filename
optional arguments:
-h, --help show this help message and exit
-password PASSWORD password
-output OUTPUT output PDF filename, incremental save if none
-name NAME name of entry to delete
有关详细信息，请参阅Document.embfile_del()。
插入
使用此命令添加新的嵌入文件：
pymupdf embed-add -h
usage: fitz embed-add [-h] [-password PASSWORD] [-output OUTPUT] -name NAME -path
PATH [-desc DESC]
input
---------------------------- add embedded file ----------------------------
positional arguments:
input PDF filename
optional arguments:
-h, --help show this help message and exit
-password PASSWORD password
-output OUTPUT output PDF filename, incremental save if none
-name NAME name of new entry
-path PATH path to data for new entry
-desc DESC description of new entry
“名称” 不能已经存在于 PDF 中。有关详细信息，请参阅Document.embfile_add()。
更新
使用此命令更新现有的嵌入文件：
pymupdf embed-upd -h
usage: fitz embed-upd [-h] -name NAME [-password PASSWORD] [-output OUTPUT]
[-path PATH] [-filename FILENAME] [-ufilename UFILENAME]
[-desc DESC]
input
--------------------------- update embedded file --------------------------
positional arguments:
input PDF filename
optional arguments:
-h, --help show this help message and exit
-name NAME name of entry
-password PASSWORD password
-output OUTPUT Output PDF filename, incremental save if none
-path PATH path to new data for entry
-filename FILENAME new filename to store in entry
-ufilename UFILENAME new unicode filename to store in entry
-desc DESC new description to store in entry
except '-name' all parameters are optional
使用这种方法来更改文件的元信息 - 只需省略*“路径”*。有关详细信息，请参阅Document.embfile_upd()。
复制
在 PDF 之间复制嵌入的文件：
pymupdf embed-copy -h
usage: fitz embed-copy [-h] [-password PASSWORD] [-output OUTPUT] -source
SOURCE [-pwdsource PWDSOURCE]
[-name [NAME [NAME ...]]]
input
--------------------- copy embedded files between PDFs --------------------
positional arguments:
input PDF to receive embedded files
optional arguments:
-h, --help show this help message and exit
-password PASSWORD password of input
-output OUTPUT output PDF, incremental save to 'input' if omitted
-source SOURCE copy embedded files from here
-pwdsource PWDSOURCE password of 'source' PDF
-name [NAME [NAME ...]]
restrict copy to these entries
文本提取
- 在 v1.18.16 中新增
从任意支持的文档中提取文本到文本文件。目前，有三种输出格式模式可用：简单、块排序和复制物理布局。
-
简单文本提取会复制文档页面中显示的所有文本 - 不会做任何特定阅读顺序的重新排列。
-
块排序按升序垂直，然后水平坐标对文本块（由 MuPDF 标识）进行排序。这应足以为基本文本页建立“自然”的阅读顺序。
-
布局致力于复制输入页面的原始外观。您可以期待像这样的结果（由命令
pymupdf gettext -pages 1 demo1.pdf生成）：
注意
“gettext”命令提供了类似于 XPDF 软件的 CLI 工具pdftotext的功能，www.foolabs.com/xpdf/ - 对于“布局”模式，这是特别真实的，该模式结合了该工具的-layout和-table选项。
在输出文件的每个页面之后，都会写入一个换页符，hex(12) - 即使输入页面根本没有文本。此行为可以通过选项进行控制。
注意
对于“布局”模式，只支持水平、从左到右、从上到下的文本，其他文本将被忽略。在此模式下，如果文本的fontsize太小，也会被忽略。
与之相反，“简单”和“块”模式输出所有文本，无论文本大小或方向如何。
命令：
pymupdf gettext -h
usage: fitz gettext [-h] [-password PASSWORD] [-mode {simple,blocks,layout}] [-pages PAGES] [-noligatures]
[-convert-white] [-extra-spaces] [-noformfeed] [-skip-empty] [-output OUTPUT] [-grid GRID]
[-fontsize FONTSIZE]
input
----------------- extract text in various formatting modes ----------------
positional arguments:
input input document filename
optional arguments:
-h, --help show this help message and exit
-password PASSWORD password for input document
-mode {simple,blocks,layout}
mode: simple, block sort, or layout (default)
-pages PAGES select pages, format: 1,5-7,50-N
-noligatures expand ligature characters (default False)
-convert-white convert whitespace characters to space (default False)
-extra-spaces fill gaps with spaces (default False)
-noformfeed write linefeeds, no formfeeds (default False)
-skip-empty suppress pages with no text (default False)
-output OUTPUT store text in this file (default inputfilename.txt)
-grid GRID merge lines if closer than this (default 2)
-fontsize FONTSIZE only include text with a larger :data:`fontsize` (default 3)
注意
命令选项可以缩写，只要不会引入歧义。所以以下做同样的事情：
... -output text.txt -noligatures -noformfeed -convert-white -grid 3 -extra-spaces ...... -o text.txt -nol -nof -c -g 3 -e ...
输出文件名默认为输入文件名，并将其扩展名替换为.txt。与其他命令一样，您可以选择页面范围（注意：基于 1 的索引！）以mutool格式选择，如上所示。
-
mode: （字符串）选择格式模式，默认为“布局”模式。
-
noligatures: （布尔值）对应于不
TEXT_PRESERVE_LIGATURES。如果指定，连字（存在于高级字体中：将多个字符组合成一个字形，如“fi”）将被拆分为其组成部分（即“f”，“i”）。默认为保留它们。 -
convert-white: 对应于不
TEXT_PRESERVE_WHITESPACE。如果指定，所有空白字符（如制表符）将被替换为一个或多个空格。默认为保留它们。 -
extra-spaces: （布尔值）对应于不
TEXT_INHIBIT_SPACES。如果指定，邻近字符之间的大间隙将填充为一个或多个空格。默认为关闭。 -
noformfeed: （布尔值）而不是
hex(12)（进纸符），在输出页面的末尾写入换行符n。 -
skip-empty: （布尔值）跳过没有文本的页面。
-
grid: 竖直坐标差值不超过此数值（以点为单位）的线将合并为同一输出行。仅适用于“布局”模式。使用时请注意： 大多数情况下，3 或默认值 2 应该足够。如果过大，原本意图不同的行可能被合并，导致输出混乱或不完整。如果过小，输入行中某些跨度使用稍有偏差属性的不同字体可能会生成单独的输出行。
-
fontsize: 仅包括
fontsize大于此值的文本（默认为 3）。仅适用于“布局”选项。
对本页有任何反馈吗？
此软件按原样提供，不带任何明示或暗示的保证。此软件按许可分发，未经许可明确授权，不得复制、修改或分发。请参阅artifex.com上的许可信息或联系 Artifex Software Inc.，39 Mesa Street，Suite 108A，San Francisco CA 94129，美国获取更多信息。
此文档覆盖所有版本直至 1.24.4。
类
-
注释
-
注释 -
MuPDF 中的注释图标
-
示例
-
-
存档
Archive
-
颜色空间
颜色空间
-
显示列表
显示列表
-
文档
-
文档 -
set_metadata()示例 -
set_toc()演示 -
insert_pdf()示例 -
其他示例
-
-
文档编写器
文档编写器
-
字体
字体
-
身份
-
整数矩形
IRect
-
链接
链接
-
链接目标
链接目标
-
矩阵
-
矩阵 -
示例
-
-
大纲
大纲
-
页面
-
修改页面
-
get_links() 条目的描述
-
关于支持链接的说明
-
文档和页面的同源方法
-
-
像素图
-
像素图 -
支持的输入图像格式
-
支持的输出图像格式
-
-
点
点
-
四边形
-
四边形 -
备注
-
代数和包含检查
-
-
矩形
矩形
-
形状
-
形状 -
用法
-
示例
-
常见参数
-
-
故事
-
故事 -
元素定位回调函数
-
-
文本页
-
文本页 -
字典输出的结构
-
-
文本编写器
文本编写器
-
工具
-
工具 -
示例会话
-
-
小部件
-
小部件 -
小部件的标准字体
-
支持的小部件类型
-
-
XML
-
XML -
设置文本属性
-
XML 类的上下文管理器支持
-
你对这个页面有任何反馈意见吗？
此软件按原样提供，不提供任何明示或暗示的保证。此软件根据许可分发，未经授权不得复制、修改或分发。请参阅许可信息，网址为 artifex.com，或联系美国旧金山 CA 94129 Mesa Street 39 号 108A 室的 Artifex Software Inc. 了解更多信息。
此文档涵盖了所有版本直至 1.24.4。
Annot
此类仅适用于 PDF 文档。
引用自 Adobe PDF 参考手册：“注释将诸如注释、声音或电影等对象与 PDF 文档页面上的位置相关联，或者通过鼠标和键盘与用户进行交互的方式。”
每一个注释对象都与其页面存在父子关系。如果页面对象变得不可用（关闭文档、任何文档结构更改等），则其所有现有的注释对象也将不可用——每当访问注释属性或方法时，都会引发异常，指示对象“被遗弃”。
| 属性 | 简短描述 |
|---|---|
Annot.delete_responses() | 删除所有响应注释 |
Annot.get_file() | 获取附加文件内容 |
Annot.get_oc() | 获取OCG / OCMD的xref |
Annot.get_pixmap() | 注释的图像作为位图 |
Annot.get_sound() | 获取音频注释的声音 |
Annot.get_text() | 提取注释文本 |
Annot.get_textbox() | 提取注释文本 |
Annot.set_border() | 设置注释的边框属性 |
Annot.set_blendmode() | 设置注释的混合模式 |
Annot.set_colors() | 设置注释的颜色 |
Annot.set_flags() | 设置注释的标志字段 |
Annot.set_irt_xref() | 定义注释为“响应于” |
Annot.set_name() | 设置注释的名称字段 |
Annot.set_oc() | 设置OCG / OCMD的xref |
Annot.set_opacity() | 更改透明度 |
Annot.set_open() | 打开/关闭注释或其弹出窗口 |
Annot.set_popup() | 为注释创建弹出窗口 |
Annot.set_rect() | 更改注释矩形 |
Annot.set_rotation() | 更改旋转角度 |
Annot.update_file() | 更新附加文件内容 |
Annot.update() | 应用累积的注释更改 |
Annot.blendmode | 注释的混合模式 |
Annot.border | 边框详细信息 |
Annot.colors | 边框 / 背景和填充颜色 |
Annot.file_info | 获取附加文件信息 |
Annot.flags | 注释标志 |
Annot.has_popup | 注释是否有弹出窗口 |
Annot.irt_xref | 此注释所回应的注释 |
Annot.info | 各种信息 |
Annot.is_open | 注释或其弹出窗口是否已打开 |
Annot.line_ends | 线型注释的起始 / 终止外观 |
Annot.next | 指向下一个注释的链接 |
Annot.opacity | 注释的透明度 |
Annot.parent | 注释的页面对象 |
Annot.popup_rect | 注释弹出窗口的矩形 |
Annot.popup_xref | 注释的弹出窗口的 PDF xref 号码 |
Annot.rect | 包含注释的矩形 |
Annot.type | 注释的类型 |
Annot.vertices | 多边形、折线等的点坐标。 |
Annot.xref | PDF xref 号码 |
类 API
class Annot
get_pixmap(matrix=pymupdf.Identity, dpi=None, colorspace=pymupdf.csRGB, alpha=False)
- v1.19.2 中的变更：增加了对 dpi 参数的支持。
从页面中未经转换的坐标创建注释的像素图像。像素图像的 IRect 等于Annot.rect.irect（见下文）。所有参数都是关键字参数。
参数：
-
matrix (matrix_like) – 用于图像创建的矩阵。默认值为 Identity。
-
dpi (int) –（v1.19.2 中新增）每英寸的点数。如果不是
None，则忽略矩阵参数。 -
colorspace (Colorspace) – 用于图像创建的颜色空间。默认值为pymupdf.csRGB。
-
alpha (bool) – 是否包含透明信息。默认值为False。
返回类型：
Pixmap
注意
-
如果刚刚创建或修改了注释，则应该先通过
page = doc.reload_page(page)重新加载页面。 -
当
alpha=True时，像素图像的像素将具有*“预乘”*的特性。要了解一些背景知识，例如查看“预乘阿尔法”这里。
get_text(opt, clip=None, flags=None)
- 1.18.0 新增
检索以各种格式提取注释的内容 - 类似于 Page 的相同方法。目前仅对注释类型 ‘FreeText’ 和 ‘Stamp’ 提供相关数据。其他类型返回空字符串（或等效对象）。
参数：
-
opt (str) –
(仅限位置) 所需格式 - 下列值之一。请注意，此方法的工作方式与 Page 的同名方法完全相同。
-
”text” –
TextPage.extractTEXT()，默认值 -
”blocks” –
TextPage.extractBLOCKS() -
”words” –
TextPage.extractWORDS() -
”html” –
TextPage.extractHTML() -
”xhtml” –
TextPage.extractXHTML() -
”xml” –
TextPage.extractXML() -
”dict” –
TextPage.extractDICT() -
”json” –
TextPage.extractJSON() -
”rawdict” –
TextPage.extractRAWDICT()
-
-
clip (rect-like) – (仅限关键字) 限制提取到此区域。几乎不应该需要，默认为
Annot.rect。 -
flags (int) – (仅限关键字) 控制返回的数据量。默认为简单文本提取。
get_textbox(rect)
- 新功能 1.18.0
返回注释文本。与Annot.get_text()的“text”选项基本相同（除了换行符）。
参数：
rect (rect-like) – 要考虑的区域，默认为Annot.rect。
set_info(info=None, content=None, title=None, creationDate=None, modDate=None, subject=None)
- 1.16.10 版更改
更改注释属性。这些属性包括日期、内容、主题和作者 (标题)。对于 name 和 id 的更改将被忽略。更新是有选择性的：要保持属性不变，将其设置为 None。要删除现有数据，使用空字符串。
参数：
-
info (dict) – 与 info 属性兼容的字典（参见下文）。所有条目都必须是字符串。如果此参数不是字典，则使用其他参数 - 否则将忽略它们。
-
content (str) – (v1.16.10 新增) 参见
info中的描述。 -
title (str) – (v1.16.10 新增) 参见
info中的描述。 -
creationDate (str) – (v1.16.10 新增) 注释创建日期。如果提供，应该符合 PDF 日期时间格式。
-
modDate (str) – (v1.16.10 新增) 最后修改日期。如果提供，应该符合 PDF 日期时间格式。
-
subject (str) – (v1.16.10 新增) 参见
info中的描述。
set_line_ends(start, end)
设置注释的线端样式。每种注释类型由一系列点定义，这些点由线连接。被标识为 start 的符号附加在第一个点上，end 附加在此列表的最后一个点上。对于不支持的注释类型，将产生一个带有警告消息的无操作。
注意
-
虽然“自由文本”、“线条”、“折线”和“多边形”注释可以具有这些属性，但是（Py-）MuPDF 不支持“自由文本”的线端，因为不支持其呼出变体。
-
（在 v1.16.16 中更改）某些符号具有内部区域（如菱形、圆圈、正方形等）。默认情况下，这些区域用注释的填充颜色填充。如果为 None，则选择白色。现在可以使用
Annot.update()的 fill_color 参数来覆盖此设置，并为线端符号指定自己的填充颜色。
参数：
-
start（int） - 第一个点的符号编号。
-
end（int） - 最后一个点的符号编号。
set_oc(xref)
使用 PDF 可选内容机制设置注释的可见性。此可见性由支持 PDF 查看器的用户界面控制。它独立于其他属性（如 Annot.flags）。
参数：
xref（int） - 可选内容组（OCG 或 OCMD）的 xref。任何先前的 xref 将被覆盖。如果为零，则将删除先前的条目。如果 xref 不为零且不指向有效的 PDF 对象，则会发生异常。
注意
这不需要执行 Annot.update() 就能生效。
get_oc()
返回一个可选内容对象的 xref，如果没有则返回零。
返回：
零或 OCG（或 OCMD）的 xref。
set_irt_xref(xref)
- 新功能在 v1.19.3 版本中引入
设置注释以“响应于”另一个注释。
参数：
xref（int） -
另一个注释的 xref。
注意
必须引用此页面上的现有注释。设置此属性不需要后续的 update()。
set_open(value)
- 新功能在 v1.18.4 版本中引入
设置注释的弹出注释打开或关闭 - 或 注释本身，如果其类型是“文本”（“便笺”）。
参数：
value（bool） - 所需的打开状态。
set_popup(rect)
- 新功能在 v1.18.4 版本中引入
为注释创建一个弹出注释，并指定其矩形。如果弹出窗口已存在，则仅更新其矩形。
参数：
rect（rect_like） - 所需的矩形。
set_opacity(value)
设置注释的透明度。不透明度也可以在 Annot.update() 中设置。
参数：
value（float） - 范围为 [0, 1] 的浮点数。假设值超出范围则假定为 1。例如，值为 0.5 将透明度设置为 50%。
三个重叠的“圆”注释，每个透明度设置为 0.5：
blendmode
- 新功能在 v1.18.4 版本中引入
注释的混合模式。参见 Adobe PDF 参考手册，第 324 页有详细说明。
返回类型：
字符串
返回：
混合模式或None。
set_blendmode(blendmode)
- 新版本 v1.16.14 中新增功能
设置注释的混合模式。参见 Adobe PDF 参考手册，第 324 页有详细说明。混合模式也可以在Annot.update()中设置。
参数：
blendmode（str） – 设置混合模式。使用Annot.update()来在视觉外观中反映这一点。有关预定义值，请参见 PDF 标准混合模式。使用PDF_BM_Normal可以删除混合模式。
set_name(name)
- 新版本 1.16.0 中新增功能
更改任何注释类型的名称字段。对于‘FileAttachment’和‘Text’注释，这是图标名称；对于‘Stamp’注释，这是印章中的文本。视觉结果（如果有的话）取决于您的 PDF 查看器。另请参见 MuPDF 中的注释图标。
参数：
name（str） – 新名称。
注意
如果您设置了“Stamp”注释的名称，则不会更改矩形，也不会对文本进行布局。如果您从 Stamp Annotation Icons 选择了标准文本（在"STAMP_"后的确切名称部分），则应收到原始布局。任意文本不会变成大写，而是按照字体“Times-Bold”水平居中显示在一行中，并缩短以适应。为了完全显示您的文本，其使用fontsize 20 计算的长度不得超过 190 点。因此，请确保以下不等式成立：pymupdf.get_text_length(text, fontname="tibo", fontsize=20) <= 190。
set_rect(rect)
更改注释的矩形。注释可以移动，并且矩形的两侧可以分别进行缩放。但是，注释外观永远不会旋转、翻转或倾斜。此方法仅影响特定的注释类型[2]，并将在其他情况下导致 Python 的sys.stderr上的消息。不会引发异常，但将返回False。
参数：
rect（rect_like） – 注释的新矩形（有限且非空）。例如，使用值 annot.rect + (5, 5, 5, 5) 将使 annot 位置向右和向下移动 5 个像素。
注意
为了激活效果，您不需要调用Annot.update()。
set_rotation(angle)
设置注释的旋转。这会使注释矩形围绕其中心点旋转。然后根据生成的四边形计算一个新的注释矩形。
参数：
angle（int） – 角度旋转角度。可能存在任意值，但将被限制在区间0, 360)内。
注意
-
您必须调用[
Annot.update()来激活效果。 -
对于 PDF_ANNOT_FREE_TEXT，只有 0、90、180 和 270 中的一个值是可能的，并且会旋转当前矩形内的文本（保持不变）。其他值将被静默忽略并替换为 0。
-
否则，只能旋转以下注释类型之一：‘Square’、‘Circle’、‘Caret’、‘Text’、‘FileAttachment’、‘Ink’、‘Line’、‘Polyline’、‘Polygon’和‘Stamp’。对于所有其他类型，该方法是一个无操作。
set_border(border=None, width=None, style=None, dashes=None, clouds=None)
-
自 1.16.9 版更改：允许不使用字典来指定。如果border不是字典，则使用直接参数。
-
从 1.22.5 版更改：支持“多云”边框效果。
仅适用于 PDF：更改边框宽度、虚线、样式和云效果。有关更多详细信息，请参见Annot.border属性。
参数：
-
border（dict）– 由
border属性返回的字典，其键为*“width”（float）、“style”（str）、“dashes”（sequence）和clouds*（int）。省略的键将保持相应的属性不变。将 border 参数设置为None（默认值）以使用其他参数。 -
width（float）– 非负值将更改边框线宽度。
-
style（str）– 除
None之外的值将更改此边框属性。 -
dashes（sequence）– 序列的所有项必须是整数，否则参数将被忽略。要移除虚线，请使用：
dashes=[]。如果虚线是非空序列，则“style”将自动设置为“D”（虚线）。 -
clouds（int）– 大于等于 0 的值将更改此属性。使用
clouds=0完全删除云状外观。仅支持“Square”、“Circle”和“Polygon”注释类型。
set_flags(flags)
更改注释标志。使用|运算符来组合几个。
参数：
flags（int）– 一个指定所需标志的整数。
set_colors(colors=None, stroke=None, fill=None)
- 自 1.16.9 版更改：允许直接设置颜色。如果colors不是字典，则使用这些参数。
更改支持的注释类型的“描边”和“填充”颜色-并非所有注释都接受两者。
参数：
-
colors（dict）– 包含颜色规范的字典。有关接受的字典键和值，请参见下文。最实用的方法应该是首先复制colors属性，然后根据需要修改此字典。
-
stroke（sequence）– 见上文。
-
fill（sequence）– 见上文。
*v1.18.5 中更改：*要完全删除颜色规范，请使用空序列，如[]。如果指定None，则不会更改现有规范。
delete_responses()
- 1.16.12 版新功能
删除引用此注释的注释。这包括任何“Popup”注释和所有响应它的注释。
update(opacity=None, blend_mode=None, fontsize=0, text_color=None, border_color=None, fill_color=None, cross_out=True, rotate=-1)
在相关更改后同步注释的外观与其属性。
仅对以下更改可以安全地省略此方法：
Annot.set_rect()Annot.set_flags()Annot.set_oc()Annot.update_file()Annot.set_info()（除了对*“content”*的任何更改）
所有参数均为可选。(从 v1.16.14 起更改) 混合模式和不透明度适用于 所有注释类型。其他参数大多数是特殊用途，如下所述。
可以使用 PuMuPDF 中通常格式的颜色规范，作为从 0.0 到 1.0 的浮点数序列（包括两者）。序列长度必须为 1、3 或 4（支持 GRAY、RGB 和 CMYK 颜色空间）。对于 GRAY，只需一个浮点数也可以接受。
参数：
-
不透明度 (float) – (自 v1.16.14 新增) 适用于所有注释类型： 更改或设置注释的透明度。有效值为 0 <= opacity < 1。
-
混合模式 (str) – (自 v1.16.14 新增) 适用于所有注释类型： 更改或设置注释的混合模式。有效值参见 PDF 标准混合模式。
-
字体大小 (float) – 更改
字体大小。仅适用于“自由文本”注释。 -
文本颜色 (sequence*,*float) – 更改文本颜色。仅适用于“自由文本”注释。
-
边框颜色 (sequence*,*float) – 更改边框颜色。仅适用于“自由文本”注释。
-
填充颜色 (sequence*,*float) –
填充颜色。
- ’直线‘，’折线‘，’多边形‘ 注释：用于给适用的线条末端符号填充不同于注释的颜色 (从 v1.16.16 起变更)。
-
划掉 (bool) – (自 v1.17.2 新增) 向注释矩形添加两条对角线。仅适用于“遮挡”注释。如果不需要，则必须指定 False，即使注释创建时为 False。
-
旋转 (int) – 新的旋转值。默认值 (-1) 表示无变化。支持“自由文本”和其他几种注释类型（参见
Annot.set_rotation())，[1]。对于“自由文本”，只能选择 0、90、180 或 270 度。其他整数均可接受。
返回类型：
布尔
注意
在Page.annots()循环内使用此方法 不推荐！ 这是因为大多数注释更新需要重新加载拥有页面 - 这不能在此循环内完成。请使用文档中提供的示例编码模式。
file_info
附件注释类型的基本信息。
返回类型：
字典
返回：
一个字典，具有键 “filename”、“ufilename”、“desc”（描述）、“size”（未压缩文件大小）、“length”（压缩长度），适用于 FileAttachment 注释类型，否则为 None。
get_file()
返回附加文件内容。
返回类型：
字节
返回：
附加文件的内容。
update_file(buffer=None, filename=None, ufilename=None, desc=None)
更新附加文件的内容。所有参数均为可选。如果没有参数，则无操作。
参数：
-
缓冲区 (bytes*|bytearray|*BytesIO) –
新文件内容。省略以仅更改元信息。
(在 1.14.13 版中更改) io.BytesIO 现在也受支持。
-
文件名 (str) – 关联文件的新文件名。
-
ufilename (str) – 关联文件的新 Unicode 文件名。
-
描述 (str) – 文件内容的新描述。
get_sound()
返回嵌入音频注释的音频内容。
返回类型：
字典
返回：
声音音频文件和相关属性。这些是可能的字典键，其中“rate”和“stream”始终存在。
| 键 | 描述 |
|---|---|
| 率 | (float, 必需) 每秒样本数 |
| 通道 | (int, 可选) 声音通道数 |
| bps | (int, 可选) 每个通道的每样本位数值 |
| 编码 | (str, 可选) 编码格式：原始，有符号，muLaw，ALaw |
| 压缩 | (str, 可选) 压缩过滤器的名称 |
| 流 | (bytes, 必需) 音频文件内容 |
opacity
注释的透明度。如果设置，则其值范围为 [0, 1]。PDF 的默认值为 1。然而，为了区别，如果未设置，我们返回 -1.0。
返回类型：
浮点数
parent
注释的拥有页面对象。
返回类型：
页面
rotation
注释旋转。
返回类型：
整数
返回：
值范围为 [-1, 359]。如果根本没有旋转，则返回 -1（并暗示旋转角度为 0）。其他可能的值被规范化为某个值 0 <= 角度 < 360。
rect
包含注释的矩形。
返回类型：
矩形
next
此页面上的下一个注释或无。
返回类型：
Annot
type
一个数字和一到两个描述注释类型的字符串，如 [2, ‘FreeText’, ‘FreeTextCallout’]。第二个字符串条目是可选的，可能为空。请参见附录 注释类型 查看可能值及其含义列表。
返回类型：
列表
info
包含各种信息的字典。所有字段都是可选字符串。对于未提供的信息项，返回空字符串。
-
名称 – 例如，“Stamp”注释将包含如“售出”或“实验性”的印章文本，对于其他注释类型，您将在此处看到注释图标的名称（例如“PushPin”适用于文件附件）。
-
内容 – 包含 Text 和 FreeText 注释类型文本的字符串。常用于填充注释弹出窗口的文本字段。
-
标题 – 包含注释弹出窗口标题的字符串。按照惯例，这用于注释作者。
-
creationDate – 创建时间戳。
-
modDate – 最后修改时间戳。
-
主题 – 主题。
-
id – (自 1.16.10 版起新增) 注释的唯一标识。这是从 PDF 键 /NM 获取的。PyMuPDF 添加的注释将有一个唯一的名称，显示在此处。
返回类型：
字典
flags
一个整数，其低位包含注释应如何呈现的标志。
返回类型：
整数
line_ends
指定注释类型‘FreeText’、‘Line’、‘PolyLine’和‘Polygon’的起始和结束符号的一对整数。如果不适用，则为 None。有关此列表中可能值和描述，请参见 Adobe PDF 参考手册，第 400 页的表 1.76。
返回类型：
元组
vertices
包含各种类型注释的变量数量的点（“顶点”）坐标的列表（每个由一对浮点数给出）：
-
‘Line’ – 起始和结束坐标（2 个浮点对）。
-
‘FreeText’ – 指定起始、（可选的）膝点和结束坐标的 2 或 3 个浮点对。
-
‘PolyLine’ / ‘Polygon’ – 由线段连接的边的坐标（n 个点的 n 个浮点对）。
-
文本标记注释 – 指定标记文本跨度的 QuadPoints 的 4 个浮点对（请参见 Adobe PDF 参考手册，第 403 页）。
-
‘Ink’ – 一到多个子列表的顶点坐标。每个这样的子列表代表绘图中的一条分开的线。
返回类型：
列表
colors
两个浮点数列表的字典，范围为 0 <= float <= 1，指定“描边”和内部（“填充”）颜色。“描边”颜色用于边框和所有活动绘制或书写的内容（“描边”）。“填充”颜色用于对象的内部，如线段端点、圆形和正方形的内部。这些列表的长度隐式确定了所使用的颜色空间：1 = GRAY，3 = RGB，4 = CMYK。因此，“[1.0, 0.0, 0.0]”代表 RGB 颜色红色。如果未指定颜色，则这两个列表都可以为空。
返回类型：
字典
xref
PDF xref。
返回类型：
整数
irt_xref
PDF xref，这个注释所回应的注释。如果没有回应注释，则返回零。
返回类型：
整数
popup_xref
关联弹出式注释的 PDF xref。如果不存在则为零。
返回类型：
整数
has_popup
注释是否具有弹出式注释。
返回类型：
布尔值
is_open
注释的弹出式是否已打开 – 或 注释本身（仅适用于‘Text’注释）。
返回类型：
布尔值
popup_rect
关联弹出式注释的矩形。如果不存在，则为无限矩形。
返回类型：
矩形
rect_delta
代表注释的/RD条目的四个浮点数的元组。这四个数字描述了两个矩形之间的数值差异（左、上、-右、-底）：注释的rect和包含在该矩形内的矩形。如果缺少条目，则此属性为(0, 0, 0, 0)。如果注释边框是一条普通的直线，则这些数字通常是边框宽度除以 2。如果注释具有“多云”边框，则您将在此处看到云半圆的宽度。一般来说，这些数字不一定相同。要计算内部矩形，请执行 a.rect + a.rect_delta。
border
包含边框特征的字典。如果没有边框信息，则为空。可能存在以下键：
-
width – 指定的边框粗细，单位为点。如果未指定宽度，则值为 -1.0。
-
dashes – 一系列整数，指定了线条虚线图案。[] 表示无虚线，[n] 表示等长的n点的开关长度，更长的列表将被解释为指定交替的开关长度值。详见 Adobe PDF References 第 126 页获取更多详细信息。
-
style – 1 字节边框样式：“S”（实线）= 环绕注释的实线，“D”（虚线）= 环绕注释的虚线，虚线图案由 dashes 条目指定，“B”（斜角）= 模拟凸起的矩形，看起来高于页面表面，“I”（内凹）= 模拟凹陷的矩形，看起来低于页面表面，“U”（下划线）= 注释矩形底部的单线。
-
clouds – 表示“多云”边框的整数，其中
n是一个整数，满足-1 <= n <= 2。当n = 0时表示直线（无云），1 表示小半圆，2 表示大半圆，模拟云朵外观。如果是 -1，则没有指定。
返回类型：
字典
MuPDF 中的注释图标
这是可通过名称引用的图标列表，用于注释类型“文本”和“文件附件”。您可以在添加注释时使用icon参数，或在Annot.set_name()中使用 as 参数。在选择项目时，您可以自行决定是否使用例如“演讲者”图标作为“文件附件”的图标。
示例
更改注释的图形图像。同时更新“作者”和在弹出窗口中显示的文本：
doc = pymupdf.open("circle-in.pdf")
page = doc[0] # page 0
annot = page.first_annot # get the annotation
annot.set_border(dashes=[3]) # set dashes to "3 on, 3 off ..."
# set stroke and fill color to some blue
annot.set_colors({"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.set_info(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.set_rect(r) # update rectangle
annot.update() # update the annot's appearance
doc.save("circle-out.pdf") # save
这是修改前后圆形注释的外观（使用 Nitro PDF 查看器显示的弹出窗口）：
脚注
您对本页面有任何反馈吗？
本软件按原样提供，不提供任何明示或暗示的保证。此软件受许可证约束，未经许可不得复制、修改或分发。请参阅许可信息，请访问artifex.com，或联系美国旧金山 CA 94129 Mesa Street 39 号 108A 套房的 Artifex Software Inc.了解更多信息。
本文档涵盖了所有版本直至 1.24.4。
## MuPDF 中的注释图标
这是可通过名称引用的图标列表，用于“文本”和“文件附件”注释类型。您可以通过icon参数在添加注释时使用它们，或在Annot.set_name()中作为参数使用。您可以自行决定在何时选择哪个项目 - 没有任何机制会阻止您例如将“扬声器”图标用于“文件附件”。
示例
更改注释的图形图像。还要更新“作者”和在弹出窗口中显示的文本：
doc = pymupdf.open("circle-in.pdf")
page = doc[0] # page 0
annot = page.first_annot # get the annotation
annot.set_border(dashes=[3]) # set dashes to "3 on, 3 off ..."
# set stroke and fill color to some blue
annot.set_colors({"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.set_info(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.set_rect(r) # update rectangle
annot.update() # update the annot's appearance
doc.save("circle-out.pdf") # save
这是更改前后圆形注释的外观（使用 Nitro PDF 查看器显示弹出窗口）：
脚注
您对此页面有何反馈？
此软件按“原样”提供，不附带任何明示或暗示的担保。此软件在许可下分发，未经明确授权，不得复制、修改或分发。有关详细信息，请参阅artifex.com，或联系 Artifex Software Inc.，39 Mesa Street，Suite 108A，San Francisco CA 94129，美国。
此文档覆盖所有 1.24.4 版本及更早版本。
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
