PyMuPDF 1.24.4 中文文档（九）（4）

PyMuPDF 1.24.4 中文文档（九）（3）https://developer.aliyun.com/article/1559626

形状

原文：pymupdf.readthedocs.io/en/latest/shape.html

此类仅适用于 PDF。

此类允许在 PDF 页面上创建互连的图形元素。其方法的含义和名称与对应的 Page 方法相同。

实际上，每个 Page 绘制方法只是一个便利的包装器，包括（1）一个形状绘制方法，（2）Shape.finish()方法，和（3）Shape.commit()方法。对于页面文本插入，只调用了Shape.commit()方法。如果为页面执行了许多绘制和文本操作，则应始终考虑使用 Shape 对象。

可以连续执行几种绘制方法，每一种方法都将为一个绘制做出贡献。完成绘制后，必须调用Shape.finish()方法来应用颜色、虚线、宽度、变形和其他属性。

此类的绘制方法（以及Shape.insert_textbox()）记录它们覆盖的区域在一个矩形内（Shape.rect）。例如，此属性可用于设置Page.cropbox_position。

粗体（Text insertions）Shape.insert_text()和Shape.insert_textbox()隐式执行“完成”，因此只需要Shape.commit()生效。因此，两者都包括控制属性如颜色等的参数。

类 API

class Shape

__init__(self, page)

创建一个新的图形。在导入 PyMuPDF 时，pymupdf.Page对象被赋予构造Shape对象的便利方法new_shape()。在实例化期间，将检查我们是否有 PDF 页面。否则会引发异常。

参数：

page (页面) – PDF 文档的现有页面。

draw_line(p1, p2)

从point_like对象p1到p2绘制线条。

参数：

• p1 (类似点) – 起始点
  
• p2 (类似点) – 终点
  

返回类型：

点

返回：

终点，p2。

draw_squiggle(p1, p2, breadth=2)

从point_like对象p1到p2绘制波浪线。始终会绘制整数个完整波浪周期，其中一个周期的长度为4 * breadth。根据需要调整breath参数以满足此条件。绘制的线条在离开p1时总是向“左”转向，并且总是从“右”连接到p2。

参数：

• p1 (类似点) – 起始点
  
• p2 (类似点) – 终点
  
• breadth (浮点数) – 每个波浪的振幅。条件*2 * breadth < abs(p2 - p1)*必须为真，以适配至少一个波浪。参见以下图片，显示由一个完整周期连接的两个点。
  

返回类型：

点

返回：

终点，p2。

这是一个三条相连的线的示例，形成一个封闭的、填充的三角形。小箭头表示描边方向。

>>> import pymupdf
>>> doc=pymupdf.open()
>>> page=doc.new_page()
>>> r = pymupdf.Rect(100, 100, 300, 200)
>>> shape=page.new_shape()
>>> shape.draw_squiggle(r.tl, r.tr)
>>> shape.draw_squiggle(r.tr, r.br)
>>> shape.draw_squiggle(r.br, r.tl)
>>> shape.finish(color=(0, 0, 1), fill=(1, 1, 0))
>>> shape.commit()
>>> doc.save("x.pdf") 

注意

绘制的波浪线不是三角函数（正弦/余弦）。如果需要，请查看draw.py。

draw_zigzag(p1, p2, breadth=2)

从point_like对象p1到p2绘制一条锯齿线。否则，与Shape.draw_squiggle()完全相同。

参数：

• p1（point_like） – 起点
  
• p2（point_like） – 终点
  
• breadth（float） – 运动的幅度。条件*2 * breadth < abs(p2 - p1)*必须为真，以至少适合一个周期。
  

返回类型：

点

返回：

终点，p2。

draw_polyline(points)

在序列points中的点之间绘制多个连接线。通过将最后一个项目设置为第一个项目，可以用于创建任意多边形。

参数：

points（sequence） – 一系列point_like对象。其长度必须至少为 2（在这种情况下等效于draw_line()）。

返回类型：

点

返回：

points[-1] – 参数序列中的最后一个点。

draw_bezier(p1, p2, p3, p4)

从p1到p4绘制标准的立方贝塞尔曲线，使用p2和p3作为控制点。

所有参数都是point_like s。

返回类型：

点

返回：

终点，p4。

注意

点不需要不同 – 尝试一些相等的情况！

示例：

draw_oval(tetra)

在给定的四边形（四边形）内绘制一个“椭圆”。如果是正方形，则绘制正规圆，一般矩形将导致椭圆。如果使用四边形，则可以得到大量的形状。

绘图从底部左 -> 左上角线的中点开始并结束，以逆时针方向进行。

参数：

tetra（rect_like*,*quad_like） –

rect_like或quad_like。

版本 1.14.5 中的更改： 现在还支持四边形。

返回类型：

点

返回：

线段rect.bl -> rect.tl或quad.ll -> quad.ul的中间点。这里仅仅看几个例子，或者在 PyMuPDF-Utilities 仓库的quad-show?.py脚本中查看。

draw_circle(center, radius)

给定其中心和半径，绘制一个圆。绘图从点center - (radius, 0)开始并结束，以逆时针方向进行。此点是包围正方形左侧边中点。

这是一个快捷方式，用于draw_sector(center, start, 360, fullSector=False)。要以顺时针方向绘制相同的圆，请使用-360作为角度。

参数：

• center（point_like） – 圆的中心。
  
• radius（float） – 圆的半径。必须为正。
  

返回类型：

点

返回：

Point(center.x - radius, center.y)。

draw_curve(p1, p2, p3)

draw_bezier() 的特例：从 p1 到 p3 绘制三次贝塞尔曲线。在线段 p1 -> p2 和 p3 -> p2 上生成一个控制点。因此，两个控制点都位于线段 p1 -> p3 的同一侧。这保证了曲线的曲率不会改变其符号。如果到达 p2 的线段成 90 度角，则生成的曲线是一个四分之一椭圆（或同样长度的四分之一圆）。

所有参数都是point_like。

返回类型：

点

返回：

端点 p3。以下是一个填充的四分之一椭圆段。黄色区域的方向为顺时针：

draw_sector(center, point, angle, fullSector=True)

绘制一个圆形扇区，可选地将弧连接到圆的中心（就像一个饼图片段）。

参数：

• center（point_like） – 圆的中心。
  
• point（point_like） – 饼图弧段的两个端点之一。另一个端点由 angle 计算得出。
  
• angle（float） – 扇形的角度（以度为单位）。用于计算弧的另一个端点。根据其符号，弧可能逆时针绘制（正）或顺时针绘制。
  
• fullSector（bool） – 是否从弧的两端绘制连接线到圆心。如果指定了填充颜色，则整个“饼图”会被着色，否则只有扇区被着色。
  

返回类型：

点

返回：

弧的另一个端点。可以用作创建逻辑连接的饼图的后续调用的起点。示例：

draw_rect(rect, *, radius=None)

• 自 v1.22.0 更改：添加参数 radius。

绘制一个矩形。绘制从左上角开始并以逆时针方向结束的图形。

参数：

• rect（rect_like） – 矩形在页面上的位置。
  
• radius（multiple） – 绘制圆角矩形的圆角。如果不是 None，则指定圆角的曲率半径，作为矩形边长的百分比。必须是一个或两个浮点数 0 < radius <= 0.5，其中 0.5 对应于相应边长的 50%。如果是一个浮点数，则曲率的半径计算为 radius * min(width, height)，绘制角的周长作为四分之一圆。如果给出一个元组 (rx, ry)，则曲率是关于水平和垂直方向不对称的。radius=(0.5, 0.5) 绘制一个椭圆。
  

返回类型：

点

返回：

矩形的左上角。

draw_quad(quad)

绘制一个四边形。绘制从左上角（Quad.ul）开始并以逆时针方向结束的图形。这是使用参数 (ul, ll, lr, ur, ul) 调用 Shape.draw_polyline() 的快捷方式。

参数：

quad (quad_like) – 在页面上放置四边形的位置。

返回类型：

Point

返回：

Quad.ul。

finish(width=1, color=(0,), fill=None, lineCap=0, lineJoin=0, dashes=None, closePath=True, even_odd=False, morph=(fixpoint, matrix), stroke_opacity=1, fill_opacity=1, oc=0)

通过将 Common Parameters 应用于所有draw()方法来完成一组绘制draw*()*方法。

Shape.insert_text()和Shape.insert_textbox()对此没有影响。

该方法还支持使用 Point fixpoint和 Matrix matrix对复合图形进行变形。

参数：

• morph (sequence) – 在某个任意的 Point fixpoint周围对文本或复合图形进行变形，方法是将 Matrix matrix应用于它。这意味着fixpoint是此操作的固定点：它不会改变其位置。默认值为无变形（None）。矩阵的前 4 个组件可以包含任何值，但matrix.e == matrix.f == 0必须为真。这意味着可以进行任意组合的缩放、倾斜、旋转、翻转等操作，但不能进行平移。
  
• stroke_opacity (float) – (new in v1.18.1) 设置笔触颜色的透明度。值小于 0 或大于 1 将被忽略。默认值为 1（不透明）。
  
• fill_opacity (float) – (new in v1.18.1) 设置填充颜色的透明度。默认值为 1（不透明）。
  
• even_odd (bool) – 请求使用**“even-odd 规则”进行填充操作。默认值为False，因此使用“nonzero  winding number  规则”**。这些规则是在区域重叠时应用填充颜色的备选方法。只有在相当复杂的形状中，才会使用这些规则产生不同的行为。有关详细解释，请参阅  Adobe PDF References，第 137 页及以后。以下是一个示例，演示了差异。
  
• oc (int) – (new in v1.18.4) xref的数字，表示可以有条件地显示此绘图的OCG或OCMD。
  

注

对于形状中的每个像素，将发生以下情况：

1. 规则 “even-odd” 计算像素包含的区域数。如果此计数为奇数，则像素被视为内部形状；如果为偶数，则像素被视为外部形状。
   
2. 默认规则 “nonzero winding” 还会查看包含像素的每个区域的“方向”：如果区域逆时针绘制，则加 1；如果顺时针，则减 1。如果结果为零，则像素被视为外部，具有非零计数的像素被视为内部形状。
   

在上图的四个形状中，上两个形状分别显示了以标准方式绘制的三个圆（逆时针，查看箭头）。下面的两个形状包含一个（左上角）按顺时针方向绘制的圆。可以看出，面积方向对右侧列（奇偶规则）无关紧要。

insert_text(point, text, fontsize=11, fontname='helv', fontfile=None, set_simple=False, encoding=TEXT_ENCODING_LATIN, color=None, lineheight=None, fill=None, render_mode=0, border_width=1, rotate=0, morph=None, stroke_opacity=1, fill_opacity=1, oc=0)

插入文本行从 point 处开始。

参数：

• point (point_like) –
  text 的左下角第一个字符的像素位置。了解它如何与 rotate 参数结合使用很重要。请参考下图。小红点表示 point 在四种可能情况下的位置。
  
  
• text (str/sequence) – 要插入的文本。可以指定为字符串类型或序列类型。对于包含换行符 n 的序列或字符串，将插入多行。不会处理行太宽的问题，但插入的行数将受页面上的“垂直”空间限制（根据 rotate 参数所建立的阅读方向）。任何文本的剩余部分将被丢弃 – 但是返回代码包含插入行的数量。
  
• lineheight (float) – 一个因子，用于覆盖从字体属性计算的行高。如果不是 None，将使用 fontsize * lineheight 的行高。
  
• stroke_opacity (float) – (v1.18.1 新增) 设置描边颜色（字符的边框线）的透明度。只有 0 <= value <= 1 的值会被考虑。默认为 1（不透明）。
  
• fill_opacity (float) – (v1.18.1 新增) 设置填充颜色的透明度。默认为 1（不透明）。使用此值来控制文本颜色的透明度。描边透明度仅影响字符的边框线。
  
• rotate (int) – 决定是否旋转文本。可接受的值为 90 度的倍数。默认为 0（无旋转），意味着从左到右的水平文本行。180 表示从右到左倒置显示文本。90 表示逆时针旋转，文本向上运行。270（或-90）表示顺时针旋转，文本向下运行。在任何情况下，point 指定第一个字符矩形的左下角坐标。如果存在多行，则始终按照此参数建立的阅读方向进行排列。因此，在 rotate = 180 的情况下，第二行位于第一行上方，依此类推。
  
• oc (int) – (v1.18.4 新增) 表示一个 Xref 的编号，用于使此文本在特定条件下显示。
  

返回类型：

int

返回：

插入的行数。

其他参数的描述请参见 Common Parameters。

insert_textbox(rect, buffer, fontsize=11, fontname='helv', fontfile=None, set_simple=False, encoding=TEXT_ENCODING_LATIN, color=None, fill=None, render_mode=0, border_width=1, expandtabs=8, align=TEXT_ALIGN_LEFT, rotate=0, lineheight=None, morph=None, stroke_opacity=1, fill_opacity=1, oc=0)

仅适用于 PDF：将文本插入指定的矩形区域。文本将被分割成行和单词，然后填充到可用空间中，从四个矩形角之一开始，这取决于 rotate。将尊重换行符和多个空格。

参数：

• rect (rect_like) – 要使用的区域。必须是有限且非空的。
  
• buffer（str/sequence）– 要插入的文本。必须指定为字符串或字符串序列。即使在序列条目中也会尊重换行。
  
• align（int）– 对齐每一行文本。默认为 0（左对齐）。居中、右对齐和两端对齐是其他支持的选项，请参阅 文本对齐。请注意，参数值 TEXT_ALIGN_JUSTIFY 的效果仅可通过“简单”（单字节）字体（包括 PDF 基本 14 字体）实现。
  
• lineheight（float）–
  一个因子，用于覆盖从字体属性计算出的行高。如果不是 None，则将使用行高 fontsize * lineheight。
  arg int expandtabs:
  使用 string.expandtabs() 方法逐行控制制表符 \t 的处理。
  
• stroke_opacity（float）– （在 v1.18.1 中新增）设置描边颜色的透明度。负值和大于 1 的值将被忽略。默认为 1（不透明）。
  
• fill_opacity（float）– （在 v1.18.1 中新增）设置填充颜色的透明度。默认为 1（不透明）。使用此值控制文本颜色的透明度。描边不透明度仅影响字符的边框线。
  
• rotate（int）– 请求文本在矩形中旋转。该值必须是 90 度的倍数。默认为 0（不旋转）。实际上，处理四个值 0、90、180 和 270（= -90），每个值导致文本从不同的矩形角开始。左下角是 90，右下角是 180，-90 / 270 是右上角。请参阅示例，了解文本如何填充到矩形中。此参数优先于变形。请参阅第二个示例，其中文本首先向左旋转了 90 度，然后整个矩形围绕其左下角顺时针旋转。
  
• oc（int）– （在 v1.18.4 中新增）xref编号，用于使此文本有条件地显示为 OCG 或 OCMD。
  

返回类型：

浮点

返回：

如果为正数或零：执行成功。返回的值是像素中未使用的矩形线空间。这可以安全地忽略 – 或用于优化矩形，定位后续项目等。

如果为负数：不执行。返回的值是存储文本行的空间不足。扩大矩形，减小 fontsize，减少文本数量等。

有关其他参数的描述，请参阅 常见参数。

commit(overlay=True)

更新页面的 contents，其中包含累积的绘图，然后是任何文本插入。如果文本重叠绘图，则将在绘图的顶部写入。

警告

不要忘记执行此方法：

如果形状未提交，它将被忽略，并且页面不会更改！

方法将重置属性Shape.rect，lastPoint，draw_cont，text_cont和totalcont。之后，形状对象可以在同一页中重新使用。

参数：

overlay（bool）– 确定是否将内容放置在前景（默认）或背景中。仅当页面已经具有非空contents对象时才相关。

———- 属性 ———-

doc

仅供参考：页面的文档。

类型：

文档

page

仅供参考：拥有的页面。

类型：

页面

height

页面的高度副本

类型：

浮点

width

页面的宽度副本。

类型：

浮点数

draw_cont

自上次完成以来的draw 方法累积的命令缓冲区。每个完成方法将其命令附加到Shape.totalcont。

类型：

str

text_cont

累积的文本缓冲区。所有文本插入都在这里进行。此缓冲区将附加到totalcont Shape.commit()，因此文本永远不会被同一形状中的绘图覆盖。

类型：

str

rect

围绕绘图的矩形。此属性可供您使用，并且可以随时更改。在创建或提交形状时，其值设置为None。每个draw方法以及Shape.insert_textbox()将更新此属性（即根据需要扩展矩形）。然而，morphing操作（Shape.finish()，Shape.insert_textbox()）将被忽略。

此属性的典型用法是在稍后或外部使用时将Page.cropbox_position设置为此值。如果您未手动操作属性，则应反映一个包含到目前为止所有绘图的矩形。

如果您使用了 morphing 并且需要包含 morphed 对象的矩形，请使用以下代码：

>>> # assuming ...
>>> morph = (point, matrix)
>>> # ... recalculate the shape rectangle like so:
>>> shape.rect = (shape.rect - pymupdf.Rect(point, point)) * ~matrix + pymupdf.Rect(point, point) 

类型：

矩形

totalcont

用于 draws 和 text insertions 的总累积命令缓冲区。这将被Shape.commit()使用。

类型：

str

lastPoint

仅供参考：绘图路径的当前点。在Shape创建后以及每次finish()和commit()之后为None。

类型：

点

PyMuPDF 1.24.4 中文文档（九）（5）https://developer.aliyun.com/article/1559629