ImageDraw 模块

ImageDraw 模块为 Image 对象提供简单的 2D 图形。您可以使用此模块创建新图像，注释或修饰现有图像，并为 Web 使用动态生成图形。

有关 PIL 的更高级绘图库，请参见 aggdraw 模块。

示例：在图像上绘制灰色十字

import sys
from PIL import Image, ImageDraw

with Image.open("hopper.jpg") as im:

    draw = ImageDraw.Draw(im)
    draw.line((0, 0) + im.size, fill=128)
    draw.line((0, im.size[1], im.size[0], 0), fill=128)

    # write to stdout
    im.save(sys.stdout, "PNG")

概念

坐标

图形界面使用与 PIL 本身相同的坐标系，左上角为 (0, 0)。绘制在图像边界之外的任何像素将被丢弃。

颜色

要指定颜色，您可以使用数字或元组，就像您在 PIL.Image.new() 或 PIL.Image.Image.putpixel() 中使用一样。对于 “1”、”L“ 和 “I” 图像，请使用整数。对于 “RGB” 图像，请使用包含整数值的 3 元组。对于 “F” 图像，请使用整数或浮点值。

对于调色板图像 (模式 “P”)，请使用整数作为颜色索引。在 1.1.4 及更高版本中，您还可以使用 RGB 3 元组或颜色名称 (见下文)。绘制层将自动分配颜色索引，只要您绘制的颜色不超过 256 种即可。

颜色名称

有关 Pillow 支持的颜色名称，请参见 颜色名称。

字体

PIL 可以使用位图字体或 OpenType/TrueType 字体。

位图字体存储在 PIL 自己的格式中，其中每个字体通常包含两个文件，一个名为 .pil，另一个通常名为 .pbm。前者包含字体度量，后者包含光栅数据。

要加载位图字体，请使用 ImageFont 模块中的加载函数。

要加载 OpenType/TrueType 字体，请使用 ImageFont 模块中的 truetype 函数。请注意，此函数依赖于第三方库，并且可能并非在所有 PIL 构建中都可用。

示例：绘制部分不透明文本

from PIL import Image, ImageDraw, ImageFont

# get an image
with Image.open("Pillow/Tests/images/hopper.png").convert("RGBA") as base:

    # make a blank image for the text, initialized to transparent text color
    txt = Image.new("RGBA", base.size, (255, 255, 255, 0))

    # get a font
    fnt = ImageFont.truetype("Pillow/Tests/fonts/FreeMono.ttf", 40)
    # get a drawing context
    d = ImageDraw.Draw(txt)

    # draw text, half opacity
    d.text((10, 10), "Hello", font=fnt, fill=(255, 255, 255, 128))
    # draw text, full opacity
    d.text((10, 60), "World", font=fnt, fill=(255, 255, 255, 255))

    out = Image.alpha_composite(base, txt)

    out.show()

示例：绘制多行文本

from PIL import Image, ImageDraw, ImageFont

# create an image
out = Image.new("RGB", (150, 100), (255, 255, 255))

# get a font
fnt = ImageFont.truetype("Pillow/Tests/fonts/FreeMono.ttf", 40)
# get a drawing context
d = ImageDraw.Draw(out)

# draw multiline text
d.multiline_text((10, 10), "Hello\nWorld", font=fnt, fill=(0, 0, 0))

out.show()

函数

PIL.ImageDraw.Draw(im, mode=None)[source]

创建一个对象，可用于在给定图像中绘制。

请注意，图像将被就地修改。

参数：:

  • im – 要绘制的图像。

  • mode – 用于颜色值的可选模式。对于 RGB 图像，此参数可以是 RGB 或 RGBA (将绘制与图像混合)。对于所有其他模式，此参数必须与图像模式相同。如果省略，则模式默认为图像的模式。

属性

ImageDraw.fill: bool = False

选择是否将 ImageDraw.ink 用作填充色或轮廓色。

ImageDraw.font

当前默认字体。

可以为每个实例设置

from PIL import ImageDraw, ImageFont
draw = ImageDraw.Draw(image)
draw.font = ImageFont.truetype("Tests/fonts/FreeMono.ttf")

或者为所有未来的 ImageDraw 实例全局设置

from PIL import ImageDraw, ImageFont
ImageDraw.ImageDraw.font = ImageFont.truetype("Tests/fonts/FreeMono.ttf")
ImageDraw.fontmode

当前字体绘制模式。

设置为 "1" 以禁用抗锯齿或 "L" 以启用抗锯齿。

ImageDraw.ink: int

当前默认颜色的内部表示。

方法

ImageDraw.getfont()[source]

获取当前默认字体，ImageDraw.font。

如果当前默认字体为 None，则使用 ImageFont.load_default() 初始化它。

返回：:

图像字体。

ImageDraw.arc(xy, start, end, fill=None, width=0)[source]

在给定的边界框内，在开始角和结束角之间绘制圆弧 (圆形轮廓的一部分)。

参数：:

  • xy – 用于定义边界框的两个点。序列为 [(x0, y0), (x1, y1)] 或 [x0, y0, x1, y1]，其中 x1 >= x0 且 y1 >= y0。

  • start – 起始角度，以度为单位。角度从 3 点钟位置开始测量，顺时针方向递增。

  • end – 结束角度，以度为单位。

  • fill – 用于弧形的颜色。

  • width –

    线条宽度，以像素为单位。

    在版本 5.3.0 中添加。

ImageDraw.bitmap(xy, bitmap, fill=None)[source]

在给定位置绘制位图（蒙版），使用当前填充颜色表示非零部分。位图应为有效的透明蒙版（模式“1”）或哑光（模式“L”或“RGBA”）。

这等效于执行 image.paste(xy, color, bitmap)。

要将像素数据粘贴到图像中，请使用图像本身的 paste() 方法。

ImageDraw.chord(xy, start, end, fill=None, outline=None, width=1)[source]

与 arc() 相同，但用直线连接端点。

参数：:

  • xy – 用于定义边界框的两个点。序列为 [(x0, y0), (x1, y1)] 或 [x0, y0, x1, y1]，其中 x1 >= x0 且 y1 >= y0。

  • outline – 用于轮廓的颜色。

  • fill – 用于填充的颜色。

  • width –

    线条宽度，以像素为单位。

    在版本 5.3.0 中添加。

ImageDraw.circle(xy, radius, fill=None, outline=None, width=1)[source]

绘制一个半径为给定半径的圆，圆心位于一个点上。

在版本 10.4.0 中添加。

参数：:

  • xy – 圆心的点，例如 (x, y)。

  • radius – 圆的半径。

  • outline – 用于轮廓的颜色。

  • fill – 用于填充的颜色。

  • width – 线条宽度，以像素为单位。

ImageDraw.ellipse(xy, fill=None, outline=None, width=1)[source]

在给定的边界框内绘制一个椭圆。

参数：:

  • xy – 用于定义边界框的两个点。序列为 [(x0, y0), (x1, y1)] 或 [x0, y0, x1, y1]，其中 x1 >= x0 且 y1 >= y0。

  • outline – 用于轮廓的颜色。

  • fill – 用于填充的颜色。

  • width –

    线条宽度，以像素为单位。

    在版本 5.3.0 中添加。

ImageDraw.line(xy, fill=None, width=0, joint=None)[source]

在 xy 列表中的坐标之间绘制一条线。坐标像素包含在绘制的线中。

参数：:

  • xy – 2 元组序列，如 [(x, y), (x, y), ...]，或数字值序列，如 [x, y, x, y, ...]。

  • fill – 用于线条的颜色。

  • width –

    线条宽度，以像素为单位。

    在版本 1.1.5 中添加。

    注意

    此选项在版本 1.1.6 之前是损坏的。

  • joint –

    线条序列之间的连接类型。可以是 "curve"（圆角）或 None。

    在版本 5.3.0 中添加。

ImageDraw.pieslice(xy, start, end, fill=None, outline=None, width=1)[source]

与弧形相同，但还会绘制连接端点和边界框中心的直线。

参数：:

  • xy – 用于定义边界框的两个点。序列为 [(x0, y0), (x1, y1)] 或 [x0, y0, x1, y1]，其中 x1 >= x0 且 y1 >= y0。

  • start – 起始角度，以度为单位。角度从 3 点钟位置开始测量，顺时针方向递增。

  • end – 结束角度，以度为单位。

  • fill – 用于填充的颜色。

  • outline – 用于轮廓的颜色。

  • width –

    线条宽度，以像素为单位。

    在版本 5.3.0 中添加。

ImageDraw.point(xy, fill=None)[source]

在给定的坐标处绘制点（单个像素）。

参数：:

  • xy – 2 元组序列，如 [(x, y), (x, y), ...]，或数字值序列，如 [x, y, x, y, ...]。

  • fill – 用于点的颜色。

ImageDraw.polygon(xy, fill=None, outline=None, width=1)[source]

绘制一个多边形。

多边形轮廓由给定坐标之间的直线组成，以及最后一个坐标和第一个坐标之间的直线。坐标像素包含在绘制的多边形中。

参数：:

  • xy – 2 元组序列，如 [(x, y), (x, y), ...]，或数字值序列，如 [x, y, x, y, ...]。

  • fill – 用于填充的颜色。

  • outline – 用于轮廓的颜色。

  • width – 线条宽度，以像素为单位。

ImageDraw.regular_polygon(bounding_circle, n_sides, rotation=0, fill=None, outline=None, width=1)[source]

绘制一个内接于 bounding_circle 的正多边形，具有 n_sides 个边，旋转 rotation 度。

参数：:

  • bounding_circle – 边界圆是一个由点和半径定义的元组。（例如 bounding_circle=(x, y, r) 或 ((x, y), r)）。多边形内接于此圆。

  • n_sides – 边数（例如 n_sides=3 表示三角形，6 表示六边形）。

  • rotation – 对多边形应用任意旋转（例如 rotation=90，应用 90 度旋转）。

  • fill – 用于填充的颜色。

  • outline – 用于轮廓的颜色。

  • width – 线条宽度，以像素为单位。

ImageDraw.rectangle(xy, fill=None, outline=None, width=1)[source]

绘制一个矩形。

参数：:

  • xy – 定义边界框的两个点。序列可以是 [(x0, y0), (x1, y1)] 或 [x0, y0, x1, y1]，其中 x1 >= x0 且 y1 >= y0。边界框包含两个端点。

  • fill – 用于填充的颜色。

  • outline – 用于轮廓的颜色。

  • width –

    线条宽度，以像素为单位。

    在版本 5.3.0 中添加。

ImageDraw.rounded_rectangle(xy, radius=0, fill=None, outline=None, width=1, corners=None)[source]

绘制一个圆角矩形。

参数：:

  • xy – 定义边界框的两个点。序列可以是 [(x0, y0), (x1, y1)] 或 [x0, y0, x1, y1]，其中 x1 >= x0 且 y1 >= y0。边界框包含两个端点。

  • radius – 角的半径。

  • fill – 用于填充的颜色。

  • outline – 用于轮廓的颜色。

  • width – 线条宽度，以像素为单位。

  • corners – 一个元组，表示是否对每个角进行圆角处理，(top_left, top_right, bottom_right, bottom_left)。关键字参数。

在版本 8.2.0 中添加。

ImageDraw.shape(shape, fill=None, outline=None)[source]

警告

此方法处于实验阶段。

绘制一个形状。

ImageDraw.text(xy, text, fill=None, font=None, anchor=None, spacing=4, align='left', direction=None, features=None, language=None, stroke_width=0, stroke_fill=None, embedded_color=False, font_size=None)[source]

在给定位置绘制字符串。

参数：:

  • xy – 文本的锚点坐标。

  • text – 要绘制的字符串。如果它包含任何换行符，则文本将传递给 multiline_text()。

  • fill – 用于文本的颜色。

  • font – 一个 ImageFont 实例。

  • anchor –

    文本锚点对齐方式。确定锚点相对于文本的相对位置。默认对齐方式为左上角，具体来说，对于水平文本为 la，对于垂直文本为 lt。有关详细信息，请参阅 文本锚点。此参数对于非 TrueType 字体将被忽略。

    注意

    此参数存在于 Pillow 的早期版本中，但在版本 8.0.0 中才得以实现。

  • spacing – 如果文本传递给 multiline_text()，则行之间的像素数。

  • align – 如果文本传递给 multiline_text()，则为 "left"、"center" 或 "right"。确定行的相对对齐方式。使用 anchor 参数指定相对于 xy 的对齐方式。

  • direction –

    文本方向。它可以是 "rtl"（从右到左）、"ltr"（从左到右）或 "ttb"（从上到下）。需要 libraqm。

    在版本 4.2.0 中添加。

  • features –

    用于文本布局的 OpenType 字体功能列表。这通常用于打开默认情况下未启用的可选字体功能，例如 "dlig" 或 "ss01"，但也可以用于关闭默认字体功能，例如 "-liga" 来禁用连字或 "-kern" 来禁用字距调整。要获取所有支持的功能，请参阅 OpenType 文档。需要 libraqm。

    在版本 4.2.0 中添加。

  • language –

    文本的语言。不同的语言可能使用不同的字形形状或连字。此参数告诉字体文本的语言，并在可用时应用正确的替换，如果适用。它应该是 BCP 47 语言代码。需要 libraqm。

    在版本 6.0.0 中添加。

  • stroke_width –

    文本描边的宽度。

    在版本 6.2.0 中添加。

  • stroke_fill –

    用于文本描边的颜色。如果没有给出，将默认为 fill 参数。

    在版本 6.2.0 中添加。

  • embedded_color –

    是否使用字体嵌入的颜色字形 (COLR、CBDT、SBIX)。

    在版本 8.0.0 中添加。

  • font_size –

    如果未提供 font，则为默认字体使用的尺寸。

    字体。关键字参数。

    在版本 10.1.0 中添加。

ImageDraw.multiline_text(xy, text, fill=None, font=None, anchor=None, spacing=4, align='left', direction=None, features=None, language=None, stroke_width=0, stroke_fill=None, embedded_color=False, font_size=None)[source]

在给定位置绘制字符串。

参数：:

  • xy – 文本的锚点坐标。

  • text – 要绘制的字符串。

  • fill – 用于文本的颜色。

  • font – 一个 ImageFont 实例。

  • anchor –

    文本锚点对齐方式。确定锚点相对于文本的相对位置。默认对齐方式为左上角，具体来说，对于水平文本为 la，对于垂直文本为 lt。有关详细信息，请参阅 文本锚点。此参数对于非 TrueType 字体将被忽略。

    注意

    此参数存在于 Pillow 的早期版本中，但在版本 8.0.0 中才得以实现。

  • spacing – 行之间的像素数。

  • align – "left", "center" 或 "right"。确定行的相对对齐方式。使用 anchor 参数将对齐方式指定为 xy。

  • direction –

    文本方向。它可以是 "rtl"（从右到左）、"ltr"（从左到右）或 "ttb"（从上到下）。需要 libraqm。

    在版本 4.2.0 中添加。

  • features –

    用于文本布局的 OpenType 字体功能列表。这通常用于打开默认情况下未启用的可选字体功能，例如 "dlig" 或 "ss01"，但也可以用于关闭默认字体功能，例如 "-liga" 来禁用连字或 "-kern" 来禁用字距调整。要获取所有支持的功能，请参阅 OpenType 文档。需要 libraqm。

    在版本 4.2.0 中添加。

  • language –

    文本的语言。不同的语言可能使用不同的字形形状或连字。此参数告诉字体文本的语言，并在可用时应用正确的替换，如果适用。它应该是 BCP 47 语言代码。需要 libraqm。

    在版本 6.0.0 中添加。

  • stroke_width –

    文本描边的宽度。

    在版本 6.2.0 中添加。

  • stroke_fill –

    用于文本描边的颜色。如果没有给出，将默认为

    fill 参数。

    在版本 6.2.0 中添加。

  • embedded_color –

    是否使用字体嵌入的颜色字形 (COLR、CBDT、SBIX)。

    在版本 8.0.0 中添加。

  • font_size –

    如果未提供 font，则为默认字体使用的尺寸。

    字体。关键字参数。

    在版本 10.1.0 中添加。

ImageDraw.textlength(text, font=None, direction=None, features=None, language=None, embedded_color=False, font_size=None)[source]

返回在给定方向、特征和语言的字体中渲染的给定文本的长度（以像素为单位，精度为 1/64）。

这是应该偏移后续文本的量。文本边界框可能会延伸到某些字体的长度之外，例如使用斜体或重音符号时。

结果以浮点数返回；如果使用基本布局，则为整数。

请注意，由于字距调整，两个长度的总和可能不等于连接字符串的长度。如果需要调整字距调整，请包含以下字符并减去其长度。

例如，而不是

hello = draw.textlength("Hello", font)
world = draw.textlength("World", font)
hello_world = hello + world  # not adjusted for kerning
assert hello_world == draw.textlength("HelloWorld", font)  # may fail

使用

hello = draw.textlength("HelloW", font) - draw.textlength(
    "W", font
)  # adjusted for kerning
world = draw.textlength("World", font)
hello_world = hello + world  # adjusted for kerning
assert hello_world == draw.textlength("HelloWorld", font)  # True

或使用 (需要 libraqm) 禁用字距调整

hello = draw.textlength("Hello", font, features=["-kern"])
world = draw.textlength("World", font, features=["-kern"])
hello_world = hello + world  # kerning is disabled, no need to adjust
assert hello_world == draw.textlength("HelloWorld", font, features=["-kern"])  # True

在版本 8.0.0 中添加。

参数：:

  • text – 要测量的文本。可能不包含任何换行符。

  • font – 一个 ImageFont 实例。

  • direction – 文本的方向。它可以是 "rtl"（从右到左）、"ltr"（从左到右）或 "ttb"（从上到下）。需要 libraqm。

  • features – 在文本布局期间要使用的 OpenType 字体特征列表。这通常用于打开默认情况下未启用的可选字体特征，例如 "dlig" 或 "ss01"，但也可以用于关闭默认字体特征，例如 "-liga" 以禁用连字或 "-kern" 以禁用字距调整。要获取所有支持的特征，请参见 OpenType 文档。需要 libraqm。

  • language – 文本的语言。不同的语言可能会使用不同的字形形状或连字。此参数告诉字体文本的语言，并根据需要应用正确的替换（如果可用）。它应该是 BCP 47 语言代码。需要 libraqm。

  • embedded_color – 是否使用字体嵌入式颜色字形 (COLR、CBDT、SBIX)。

  • font_size –

    如果未提供 font，则为默认字体使用的尺寸。

    字体。关键字参数。

    在版本 10.1.0 中添加。

返回：:

水平文本的宽度或垂直文本的高度。

ImageDraw.textbbox(xy, text, font=None, anchor=None, spacing=4, align='left', direction=None, features=None, language=None, stroke_width=0, embedded_color=False, font_size=None)[source]

返回在给定方向、特征和语言的字体中渲染的给定文本相对于给定锚点的边界框（以像素为单位）。仅支持 TrueType 字体。

使用 textlength() 获取后续文本的偏移量，精度为 1/64 像素。边界框包含某些字体的额外边距，例如斜体或重音符号。

在版本 8.0.0 中添加。

参数：:

  • xy – 文本的锚点坐标。

  • text – 要测量的文本。如果它包含任何换行符，则文本将传递给 multiline_textbbox()。

  • font – 一个 FreeTypeFont 实例。

  • anchor – 文本锚点对齐方式。确定锚点相对于文本的相对位置。默认对齐方式为左上角，具体来说是水平文本的 la 和垂直文本的 lt。有关详细信息，请参见 文本锚点。此参数对于非 TrueType 字体将被忽略。

  • spacing – 如果文本传递给 multiline_textbbox()，则行之间的像素数。

  • align – 如果文本传递给 multiline_textbbox()，则 "left"、"center" 或 "right"。确定行的相对对齐方式。使用 anchor 参数将对齐方式指定为 xy。

  • direction – 文本的方向。它可以是 "rtl"（从右到左）、"ltr"（从左到右）或 "ttb"（从上到下）。需要 libraqm。

  • features – 在文本布局期间要使用的 OpenType 字体特征列表。这通常用于打开默认情况下未启用的可选字体特征，例如 "dlig" 或 "ss01"，但也可以用于关闭默认字体特征，例如 "-liga" 以禁用连字或 "-kern" 以禁用字距调整。要获取所有支持的特征，请参见 OpenType 文档。需要 libraqm。

  • language – 文本的语言。不同的语言可能会使用不同的字形形状或连字。此参数告诉字体文本的语言，并根据需要应用正确的替换（如果可用）。它应该是 BCP 47 语言代码。需要 libraqm。

  • stroke_width – 文本描边的宽度。

  • embedded_color – 是否使用字体嵌入式颜色字形 (COLR、CBDT、SBIX)。

  • font_size –

    如果未提供 font，则为默认字体使用的尺寸。

    字体。关键字参数。

    在版本 10.1.0 中添加。

返回：:

(left, top, right, bottom) 边界框

ImageDraw.multiline_textbbox(xy, text, font=None, anchor=None, spacing=4, align='left', direction=None, features=None, language=None, stroke_width=0, embedded_color=False, font_size=None)[source]

返回在给定方向、特征和语言的字体中渲染的给定文本相对于给定锚点的边界框（以像素为单位）。仅支持 TrueType 字体。

使用 textlength() 获取后续文本的偏移量，精度为 1/64 像素。边界框包含某些字体的额外边距，例如斜体或重音符号。

在版本 8.0.0 中添加。

参数：:

  • xy – 文本的锚点坐标。

  • text – 要测量的文本。

  • font – 一个 FreeTypeFont 实例。

  • anchor – 文本锚点对齐方式。确定锚点相对于文本的相对位置。默认对齐方式为左上角，具体来说是水平文本的 la 和垂直文本的 lt。有关详细信息，请参见 文本锚点。此参数对于非 TrueType 字体将被忽略。

  • spacing – 行之间的像素数。

  • align – "left", "center" 或 "right"。确定行的相对对齐方式。使用 anchor 参数将对齐方式指定为 xy。

  • direction – 文本的方向。它可以是 "rtl"（从右到左）、"ltr"（从左到右）或 "ttb"（从上到下）。需要 libraqm。

  • features – 在文本布局期间要使用的 OpenType 字体特征列表。这通常用于打开默认情况下未启用的可选字体特征，例如 "dlig" 或 "ss01"，但也可以用于关闭默认字体特征，例如 "-liga" 以禁用连字或 "-kern" 以禁用字距调整。要获取所有支持的特征，请参见 OpenType 文档。需要 libraqm。

  • language – 文本的语言。不同的语言可能会使用不同的字形形状或连字。此参数告诉字体文本的语言，并根据需要应用正确的替换（如果可用）。它应该是 BCP 47 语言代码。需要 libraqm。

  • stroke_width – 文本描边的宽度。

  • embedded_color – 是否使用字体嵌入式颜色字形 (COLR、CBDT、SBIX)。

  • font_size –

    如果未提供 font，则为默认字体使用的尺寸。

    字体。关键字参数。

    在版本 10.1.0 中添加。

返回：:

(left, top, right, bottom) 边界框

PIL.ImageDraw.getdraw(im=None, hints=None)[source]

警告

此方法处于实验阶段。

用于 PIL 图像的更高级的 2D 绘图接口，基于 WCK 接口。

参数：:

  • im – 要绘制的图像。

  • hints – 可选的提示列表。

返回：:

一个 (绘图上下文, 绘图资源工厂) 元组。

PIL.ImageDraw.floodfill(image: Image, xy: tuple[int, int], value: float | tuple[int, ...], border: float | tuple[int, ...] | None = None, thresh: float = 0) → None[source]

警告

此方法处于实验阶段。

使用给定颜色填充边界区域。

参数：:

  • image – 目标图像。

  • xy – 种子位置（一个包含 2 个元素的坐标元组）。参见 坐标系.

  • value – 填充颜色。

  • border – 可选的边界值。如果给出，则区域由颜色与边界颜色不同的像素组成。如果没有给出，则区域由与种子像素具有相同颜色的像素组成。

  • thresh – 可选的阈值，它指定像素值与“背景”之间的最大容差值，以便对其进行替换。对于填充非均匀但颜色相似的区域很有用。