PyMuPDF 1.24.4 中文文档（九）（4）https://developer.aliyun.com/article/1559628
用法
通过*shape = page.new_shape()*构造绘图对象。之后，可以跟随所需数量的 draw、finish 和 text insertions 方法。在提交绘图之前必须完成每个绘制序列。整体编码模式如下：
>>> shape = page.new_shape() >>> shape.draw1(...) >>> shape.draw2(...) >>> ... >>> shape.finish(width=..., color=..., fill=..., morph=...) >>> shape.draw3(...) >>> shape.draw4(...) >>> ... >>> shape.finish(width=..., color=..., fill=..., morph=...) >>> ... >>> shape.insert_text* >>> ... >>> shape.commit() >>> ....
注意
- 每个 finish() 将前面的绘制组合成一个逻辑形状，使其具有共同的颜色、线宽、变形等。如果指定了 closePath，它还将连接最后一个绘制的结束点与第一个绘制的起始点。
- 要成功创建复合图形，请让每个绘制方法使用前一个绘制的结束点作为其起始点。在上述伪代码中，draw2 因此应使用 draw1 的返回的 Point 作为其起始点。如果未能如此做，将自动开始一个新路径，并且 finish() 可能不会按预期工作（但它也不会报错）。
- 文本插入可以出现在提交之前的任何位置（它们既不接触
Shape.draw_cont也不接触Shape.lastPoint）。它们将直接附加到 Shape.totalcont，而绘制则将由 Shape.finish 附加。 - 每个 commit 将所有文本插入和形状放置在页面的前景或背景中，从而提供了一种控制图形层的方法。
- 只有 commit 将更新 页面的内容，其他方法基本上是字符串操作。
示例
- 创建不同颜色的饼图完整圆形：
shape = page.new_shape() # start a new shape cols = (...) # a sequence of RGB color triples pieces = len(cols) # number of pieces to draw beta = 360. / pieces # angle of each piece of pie center = pymupdf.Point(...) # center of the pie p0 = pymupdf.Point(...) # starting point for i in range(pieces): p0 = shape.draw_sector(center, p0, beta, fullSector=True) # draw piece # now fill it but do not connect ends of the arc shape.finish(fill=cols[i], closePath=False) shape.commit() # update the page
下面是 5 种颜色的示例：
- 创建常规的 n 边形（填充黄色，红色边框）。我们仅使用 draw_sector() 计算周长上的点，并在绘制多边形之前清空绘制命令缓冲区：
shape = page.new_shape() # start a new shape beta = -360.0 / n # our angle, drawn clockwise center = pymupdf.Point(...) # center of circle p0 = pymupdf.Point(...) # start here (1st edge) points = [p0] # store polygon edges for i in range(n): # calculate the edges p0 = shape.draw_sector(center, p0, beta) points.append(p0) shape.draw_cont = "" # do not draw the circle sectors shape.draw_polyline(points) # draw the polygon shape.finish(color=(1,0,0), fill=(1,1,0), closePath=False) shape.commit()
下面是 n = 7 的多边形：
## 常用参数
fontname (str)
通常有三种选项：
- 使用标准的 PDF 基本 14 字体 之一。在这种情况下，如果省略此参数，则必须不指定 fontfile，且将使用 “Helvetica”。
- 选择页面已经在使用的字体。然后指定其带斜杠“/”的引用名称，如下例所示。
- 指定系统中存在的字体文件。在这种情况下，选择一个任意的新名称用于此参数（不带“/”前缀）。
如果插入的文本应重用页面的某个字体，请使用其在
Page.get_fonts()中出现的引用名称，如下所示：假设字体列表中有项目 [1024, 0, ‘Type1’, ‘NimbusMonL-Bold’, ‘R366’]，则指定 fontname = “/R366”，fontfile = None 使用字体 NimbusMonL-Bold。
fontfile (str)
您计算机上现有的字体文件路径。如果指定了 fontfile，请确保使用上述列表中不存在的 fontname。此新字体将在 doc.save() 时嵌入 PDF。类似于新图像，每个字体文件只会被嵌入一次。使用二进制字体内容的 MD5 码表来确保这一点。
set_simple (bool)
从文件安装的字体默认安装为Type0字体。如果要仅使用 1 字节字符，请将此设置为 true。此设置无法恢复。后续更改将被忽略。
fontsize（浮点数）
文本的字体大小，请参见：
fontsize。
dashes（字符串）
导致线条绘制为虚线。一般格式为
"[n m] p"，其中（最多）3 个浮点数表示像素长度。n是虚线长度，m（可选）是随后的间隔长度，p（“相位” - 必须的，即使为 0！）指定虚线开始之前应跳过多少像素。如果省略m，则默认为n。使用
"[] 0"或None或""绘制连续线条（无虚线）。示例：
- 指定
"[3 4] 0"意味着 3 像素虚线和 4 像素间隔交替出现。"[3 3] 0"和"[3] 0"做同样的事情。有关如何实现复杂虚线效果的详细信息，请参见 Adobe PDF 参考手册，第 217 页。
color / fill（列表、元组）
描边和填充颜色可以指定为浮点数列表或元组，范围从 0 到 1。这些序列必须具有长度为 1（GRAY）、3（RGB）或 4（CMYK）。对于 GRAY 颜色空间，可以接受单个浮点数，而不是笨重的*(float,)或[float]*。接受（默认）或使用
None来不使用该参数。为了简化颜色规范，pymupdf.utils 中的 getColor() 方法可以通过名称获取预定义的 RGB 颜色三元组。它接受颜色名称的字符串，并返回相应的三元组。该方法知道超过 540 个颜色名称 - 请参阅颜色数据库部分。
请注意，当与填充颜色一起使用时，术语color通常意味着“描边”颜色。
如果将颜色参数默认为
None，则不会生成相应的颜色选择命令。如果fill和color都是None，则绘图将不包含颜色规范。但仍将“描边”，这会导致 PDF 默认颜色“黑色”被 Adobe Acrobat 和所有其他查看器使用。
width（浮点数）
形状中元素的描边（“边框”）宽度（如果适用）。默认值为 1。width、color 和 fill 有以下关系/依赖：
- 如果
fill=None，则形状元素始终会带有边框，即使color=None（此时取黑色）或width=0（此时取 1）也是如此。- 形状没有边框只能在指定了填充颜色（当然可以是白色）的情况下实现。要实现这一点，请指定
width=0。在这种情况下，color参数将被忽略。
stroke_opacity / fill_opacity（浮点数）
两个值都是在范围[0, 1]内的浮点数。负值或大于 1 的值将被忽略（在大多数情况下）。两者设置透明度，使得值 0.5 对应于 50％的透明度，0 表示不可见，1 表示不透明。例如，对于矩形，边框透明度适用于其边框，而填充透明度适用于其内部。
对于文本插入（
Shape.insert_text()和Shape.insert_textbox()），使用fill_opacity控制文本的透明度。乍一看，这似乎令人惊讶，但是当你继续查看render_mode时，它就变得明显了：fill_opacity适用于黄色，stroke_opacity适用于蓝色。
border_width（浮点数）
设置文本插入的边框宽度。在 v1.14.9 中新增。仅在使用大于零的值的渲染模式参数时相关。
render_mode（整数）
1.14.9 版本中新增：
range(8)中的整数，控制文本外观（Shape.insert_text()和Shape.insert_textbox()）。参见 Adobe PDF 参考手册第 246 页。在 v1.14.9 中新增。这些方法现在也区分填充和描边颜色。
- 对于默认值为 0，只使用文本填充颜色来绘制文本。为了向后兼容，也可以使用color参数。
- 对于渲染模式 1，只绘制每个字形（即文本字符）的边框，边框的厚度由border_width参数设置。选用color参数中的颜色，fill参数将被忽略。
- 对于渲染模式 2，字形填充并描边，同时使用颜色参数和指定的边框宽度。您可以使用此值来模拟粗体文本，而无需使用另一种字体：选择相同值的fill和color以及适当的border_width值。
- 对于渲染模式 3，字形既不描边也不填充：文本变得不可见。
以下示例使用 border_width=0.3，字体大小为 15。描边颜色为蓝色，填充颜色为一些黄色。
overlay（布尔值）
使项目出现在前景（默认）或背景中。
morph（序列）
导致“形态变化”形状或页面方法插入的文本（如 insert_textbox() / insert_text()）的“形态变化”。如果不是 None，必须是一个 (fixpoint, matrix) 对，其中 fixpoint 是一个 Point，matrix 是一个 Matrix。矩阵可以是除了平移以外的任何内容，即 matrix.e == matrix.f == 0 必须为真。点用作矩阵操作的固定点。例如，如果 matrix 是旋转或缩放，则 fixpoint 是其中心。类似地，如果 matrix 是左右或上下翻转，则镜像轴将是通过 fixpoint 的垂直或水平线等。
注意
若干方法包含检查即将插入项目是否实际适合页面的代码（如
Shape.insert_text()或Shape.draw_rect()）。但形态操作的结果则无此保证：这完全取决于程序员的责任。
lineCap (已弃用：“roundCap”) (int)
控制线段的外观。默认值 0 使每条线段正好以给定坐标处的尖角结束。值为 1 添加一个半圆到末端，其中心是端点，直径为线宽。值为 2 添加一个半正方形，边长为线宽，中心为线段的末端。
自版本 1.14.15 更改
lineJoin (int)
自版本 1.14.15 新增: 控制线连接外观的方式。可以是尖角（0）、圆形连接（1）或截断边缘（2，“butt”）。
closePath (bool)
导致绘图的终点自动与起点连接（通过直线）。
对本页有任何反馈意见吗？
本软件按原样提供，不附带任何明示或暗示的担保。本软件根据许可分发，未经许可不得复制、修改或分发。有关详细信息，请参阅 artifex.com 的许可信息或联系美国加利福尼亚州旧金山 Mesa 街 39 号 108A 单元的 Artifex Software Inc.。
此文档覆盖所有版本直至 1.24.4。
用法
绘图对象由 shape = page.new_shape() 构造。此后，可以按需使用许多绘制、完成和文本插入方法。每个绘制序列必须在提交绘图之前完成。整体编码模式如下：
>>> shape = page.new_shape() >>> shape.draw1(...) >>> shape.draw2(...) >>> ... >>> shape.finish(width=..., color=..., fill=..., morph=...) >>> shape.draw3(...) >>> shape.draw4(...) >>> ... >>> shape.finish(width=..., color=..., fill=..., morph=...) >>> ... >>> shape.insert_text* >>> ... >>> shape.commit() >>> ....
注意
- 每个 finish() 将前面的绘制组合成一个逻辑形状，赋予其共同的颜色、线宽、形态操作等。如果指定了 closePath，它还会连接最后一个绘制的终点与第一个绘制的起点。
- 为了成功创建复合图形，让每个绘制方法使用前一个绘制方法的终点作为其起点。在上述伪代码中，draw2应该使用draw1返回的 Point 作为其起点。如果未这样做，将会自动启动一个新路径，并且*finish()*可能不会按预期工作（但它也不会抱怨）。
- 文本插入可以出现在提交之前的任何地方（它们不会触及
Shape.draw_cont或者Shape.lastPoint）。它们直接附加到Shape.totalcont，而绘制将通过Shape.finish附加。 - 每次commit都会获取所有文本插入和形状，并将它们放置在页面的前景或背景上 - 因此提供了控制图形层的一种方式。
- 只有 commit 将更新 页面的内容，其他方法基本上是字符串操作。
示例
- 创建一个由不同颜色的扇形组成的完整圆：
shape = page.new_shape() # start a new shape cols = (...) # a sequence of RGB color triples pieces = len(cols) # number of pieces to draw beta = 360. / pieces # angle of each piece of pie center = pymupdf.Point(...) # center of the pie p0 = pymupdf.Point(...) # starting point for i in range(pieces): p0 = shape.draw_sector(center, p0, beta, fullSector=True) # draw piece # now fill it but do not connect ends of the arc shape.finish(fill=cols[i], closePath=False) shape.commit() # update the page
这是一个 5 种颜色的示例：
- 创建一个常规的 n 边形（填充黄色，红色边框）。我们只使用
draw_sector()来计算周长上的点，并在绘制多边形之前清空绘图命令缓冲区：
shape = page.new_shape() # start a new shape beta = -360.0 / n # our angle, drawn clockwise center = pymupdf.Point(...) # center of circle p0 = pymupdf.Point(...) # start here (1st edge) points = [p0] # store polygon edges for i in range(n): # calculate the edges p0 = shape.draw_sector(center, p0, beta) points.append(p0) shape.draw_cont = "" # do not draw the circle sectors shape.draw_polyline(points) # draw the polygon shape.finish(color=(1,0,0), fill=(1,1,0), closePath=False) shape.commit()
这是 n = 7 的多边形示例：
## 常见参数
fontname（str）
通常有三种选项：
- 使用标准的 PDF Base 14 字体之一。在这种情况下，如果未指定此参数，fontfile 不能被指定，并且使用*“Helvetica”*。
- 选择页面中已经使用的字体。然后指定其以斜杠“/”为前缀的参考名称，如下例所示。
- 指定系统上存在的字体文件。在这种情况下，选择一个任意的但是新的参数名（不带“/”前缀）。
如果插入的文本应该重复使用页面的某个字体，请使用出现在
Page.get_fonts()中的其参考名称，如下所示：假设字体列表中有项*[1024, 0, ‘Type1’, ‘NimbusMonL-Bold’, ‘R366’]，则指定fontname = “/R366”， fontfile = None来使用字体NimbusMonL-Bold*。
fontfile（str）
您计算机上存在的字体文件路径。如果指定了
fontfile，请确保使用上述列表中不存在的fontname。这个新字体将在*doc.save()*时嵌入 PDF 中。与新图像类似，字体文件只会被嵌入一次。使用二进制字体内容的 MD5 代码表来确保这一点。
set_simple（bool）
从文件安装的字体默认为Type0字体。如果只想使用 1 字节字符，请将此设置为 true。此设置无法恢复。后续更改将被忽略。
fontsize（float）
文本的字体大小，参见：
fontsize。
dashes（str）
导致绘制的线条为虚线。一般格式为
"[n m] p"，其中最多有 3 个浮点数表示像素长度。n是虚线的长度，m（可选）是随后的间隔长度，p（“相位” - 必需，即使为 0！）指定在虚线开始之前应跳过多少像素。如果省略m，则默认为n。使用
"[] 0"或None或""绘制连续线条（无虚线）。示例：
- 指定
"[3 4] 0"意味着 3 个像素长的虚线和 4 个像素长的间隔交替出现。"[] 0"和"[3] 0"做同样的事情。有关如何实现复杂的虚线效果的详细信息，请参阅 Adobe PDF 参考手册，第 217 页。
color / fill (list, tuple)
可以将描边和填充颜色指定为浮点数的元组或列表，范围从 0 到 1。这些序列必须具有长度为 1（灰度）、3（RGB）或 4（CMYK）。对于灰度色彩空间，也可以接受单个浮点数而不是笨重的*(float,)或[float]*。接受（默认）或使用
None来不使用该参数。为了简化颜色的指定，可以使用pymupdf.utils中的*getColor()*方法通过名称获取预定义的 RGB 颜色三元组。它接受一个颜色名称的字符串，并返回相应的三元组。该方法知道超过 540 个颜色名称 - 见章节颜色数据库。
请注意，术语color通常在与填充颜色一起使用时指“描边”颜色。
如果将颜色参数设为
None，则不会生成相应的颜色选择命令。如果fill和color都是None，则绘图不包含颜色规范。但仍会进行“描边”，这将导致 Adobe Acrobat 和所有其他查看器使用 PDF 的默认颜色“黑色”。
width (float)
元素形状中的描边（“边框”）宽度（如果适用）。默认值为 1。宽度、颜色和填充的关系/依赖如下：
- 如果
fill=None，则形状元素始终将带有边框 - 即使color=None（此时将使用黑色）或width=0（此时将使用 1）。- 仅通过指定填充颜色（当然可以是白色）才能实现没有边框的形状。为此，请指定
width=0。在这种情况下，将忽略color参数。
stroke_opacity / fill_opacity (floats)
两个值都是范围在[0, 1]的浮点数。负值或大于 1 的值将被忽略（在大多数情况下）。两者设置透明度，使得数值 0.5 对应 50%的透明度，0 表示不可见，1 表示不透明。例如，对于矩形，描边透明度适用于其边框，填充透明度适用于其内部。
对于文本插入（
Shape.insert_text()和Shape.insert_textbox())，使用fill_opacity来设置文本的透明度。乍一看这似乎令人惊讶，但当您进一步查看render_mode时，这变得显而易见：fill_opacity适用于黄色，stroke_opacity适用于蓝色。
border_width（浮点数）
设置文本插入的边框宽度。在 v1.14.9 中新增。仅当使用渲染模式参数值大于零时相关。
渲染模式（整数）
版本 1.14.9 中的新功能：
range(8)中的整数控制文本外观（Shape.insert_text()和Shape.insert_textbox()）。参见 Adobe PDF References 第 246 页。在 v1.14.9 中新增功能。这些方法现在还区分填充和描边颜色。
- 对于默认的 0，只使用文本填充颜色来绘制文本。为了向后兼容，也可以使用color参数。
- 对于渲染模式 1，只绘制每个字形（即文本字符）的边框，其厚度由border_width参数设置。选定的color参数的颜色用于此操作，fill参数被忽略。
- 对于渲染模式 2，字形被填充并描边，使用颜色参数和指定的边框宽度。您可以使用此值模拟粗体文本而无需使用其他字体：选择相同的值作为fill和color，并为border_width选择适当的值。
- 对于渲染模式 3，字形既不描边也不填充：文本变得不可见。
以下示例使用 border_width=0.3，以及字体大小为 15。描边颜色为蓝色，填充颜色为某种黄色。
叠加（布尔值）
导致项目出现在前景（默认）或背景中。
变形（序列）
导致了形状的“变形”，这些形状是由draw()方法创建的，或者是由页面方法insert_textbox()* / insert_text()插入的文本。如果不是None，它必须是一对*(fixpoint, matrix)，其中fixpoint是点，matrix是矩阵。矩阵可以是除了平移以外的任何东西，即matrix.e == matrix.f == 0必须为真。该点被用作矩阵操作的固定点。例如，如果matrix是旋转或缩放，则fixpoint是其中心。同样地，如果matrix是左右或上下翻转，则镜像轴将分别通过fixpoint*形成垂直或水平线等。
注意
几种方法包含检查，用于确定要插入的项目是否实际适合页面（例如
Shape.insert_text()或Shape.draw_rect()）。然而，对于变形操作的结果，没有这样的保证：这完全由程序员负责。
lineCap（已弃用：“roundCap”） (整型)
控制线端的外观。默认值 0 让每条线在给定坐标处具有尖锐的边缘。值为 1 会在端点添加一个半圆，其中心是端点，直径是线宽。值为 2 添加一个半方形，边长为线宽，中心是线端。
版本 1.14.15 中更改
lineJoin (整型)
版本 1.14.15 新特性： 控制线连接的外观方式。可以是尖锐边缘（0）、圆角连接（1）或截断边缘（2，“butt”）。
closePath (布尔型)
导致绘图的端点自动与起始点连接（通过直线）。
对此页面有任何反馈意见吗？
此软件按原样提供，不附带任何明示或暗示的担保。此软件按许可分发，并且未经授权不得复制、修改或分发。请参阅artifex.com获取许可信息，或联系美国旧金山 CA 94129 Mesa Street 39 号 Suite 108A 的 Artifex Software Inc. 以获取更多信息。
此文档涵盖了所有版本直至 1.24.4。
