ImageDraw 模块

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

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")

概念

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

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)[源代码]

创建可用于绘制给定图像的对象。

请注意，图像将在适当的位置进行修改。

参数

• im -- 要绘制的图像。

• mode -- 用于颜色值的可选模式。对于RGB图像，此参数可以是RGB或RGBA（将图形混合到图像中）。对于所有其他模式，此参数必须与图像模式相同。如果忽略，则模式默认为图像的模式。

方法

ImageDraw.getfont()[源代码]

获取当前默认字体。

返回

图像字体。

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

在给定的边界框内，在起始角和结束角之间绘制圆弧（圆轮廓的一部分）。

参数

• 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)[源代码]

使用非零部分的当前填充颜色在给定位置绘制位图（遮罩）。位图应该是有效的透明蒙版（模式“1”）或蒙版（模式“l”或“rgba”）。

这相当于 image.paste(xy, color, bitmap) .

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

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

等同于 arc() ，但用直线连接端点。

参数

• xy -- 定义边界框的两点。序列 [(x0, y0), (x1, y1)] 或 [x0, y0, x1, y1] 在哪里 x1 >= x0 和 y1 >= y0 .

• outline -- 用于轮廓的颜色。

• fill -- 用于填充的颜色。

• width -- 线条宽度，以像素为单位。…添加的版本：5.3.0

ImageDraw.ellipse(xy, fill=None, outline=None, width=1)[源代码]

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

参数

• 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)[源代码]

在中的坐标之间绘制一条线 xy 名单。

参数

• xy -- 两个元组的序列 [(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)[源代码]

与圆弧相同，但也在端点和边界框中心之间绘制直线。

参数

• 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)[源代码]

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

参数

• xy -- 两个元组的序列 [(x, y), (x, y), ...] 或类似的数值 [x, y, x, y, ...] .

• fill -- 用于点的颜色。

ImageDraw.polygon(xy, fill=None, outline=None)[源代码]

绘制多边形。

多边形轮廓由给定坐标之间的直线以及最后一个坐标和第一个坐标之间的直线组成。

参数

• xy -- 两个元组的序列 [(x, y), (x, y), ...] 或类似的数值 [x, y, x, y, ...] .

• outline -- 用于轮廓的颜色。

• fill -- 用于填充的颜色。

ImageDraw.regular_polygon(bounding_circle, n_sides, rotation=0, fill=None, outline=None)[源代码]

绘制内接的正多边形 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 -- 用于轮廓的颜色。

ImageDraw.rectangle(xy, fill=None, outline=None, width=1)[源代码]

绘制矩形。

参数

• xy -- 定义边界框的两点。任何一个的序列 [(x0, y0), (x1, y1)] 或 [x0, y0, x1, y1] . 第二个点正好在绘制的矩形之外。

• outline -- 用于轮廓的颜色。

• fill -- 用于填充的颜色。

• width -- 线条宽度，以像素为单位。…添加的版本：5.3.0

ImageDraw.rounded_rectangle(xy, radius=0, fill=None, outline=None, width=1)[源代码]

绘制圆角矩形。

参数

• xy -- 定义边界框的两点。任何一个的序列 [(x0, y0), (x1, y1)] 或 [x0, y0, x1, y1] . 第二个点正好在绘制的矩形之外。

• radius -- 角的半径。

• outline -- 用于轮廓的颜色。

• fill -- 用于填充的颜色。

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

8.2.0 新版功能.

ImageDraw.shape(shape, fill=None, outline=None)[源代码]

警告

这种方法是实验性的。

画一个形状。

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)[源代码]

在给定位置绘制字符串。

参数

• xy -- 文本的锚点坐标。

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

• fill -- 用于文本的颜色。

• font -- 安 ImageFont 实例。

• anchor -- 文本锚点对齐方式。确定锚点相对于文本的相对位置。默认对齐方式为左上角。看见 文本锚点 有效值。对于非TrueType字体，此参数将被忽略。。。注意：此参数在Pillow的早期版本中存在，但仅在版本8.0.0中实现。

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

• align -- 如果将文本传递给 multiline_text() ， "left" ， "center" 或 "right" 。确定线条的相对对齐方式。使用 anchor 参数指定对齐方式。 xy 。

• direction -- 文本的方向。它可以 "rtl" （从右到左）， "ltr" （从左到右）或 "ttb" （从上到下）。需要libraqm。。版本2.0 ADDED:：4

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

• language -- 文本的语言。不同的语言可以使用不同的字形或连字。此参数告诉文本使用哪种语言的字体，并根据需要应用正确的替换（如果可用）。应该是一个 BCP 47 language code . 需要libraqm。。版本添加：：6.0.0

• stroke_width -- 文本笔划的宽度。。版本号：6.2.0

• stroke_fill -- 用于文本笔划的颜色。如果未给出，将默认为 fill 参数。。版本号：6.2.0

• embedded_color -- 是否使用字体嵌入颜色字形(COLR、CBDT、SBIX)。。。添加的版本：：8.0.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)[源代码]

在给定位置绘制字符串。

参数

• xy -- 文本的锚点坐标。

• text -- 要绘制的字符串。

• fill -- 用于文本的颜色。

• font -- 安 ImageFont 实例。

• anchor -- 文本锚点对齐方式。确定锚点相对于文本的相对位置。默认对齐方式为左上角。看见 文本锚点 有效值。对于非TrueType字体，此参数将被忽略。。。注意：此参数在Pillow的早期版本中存在，但仅在版本8.0.0中实现。

• spacing -- 行与行之间的像素数。

• align -- "left" ， "center" 或 "right" 。确定线条的相对对齐方式。使用 anchor 参数指定对齐方式。 xy 。

• direction -- 文本的方向。它可以 "rtl" （从右到左）， "ltr" （从左到右）或 "ttb" （从上到下）。需要libraqm。。版本2.0 ADDED:：4

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

• language -- 文本的语言。不同的语言可以使用不同的字形或连字。此参数告诉文本使用哪种语言的字体，并根据需要应用正确的替换（如果可用）。应该是一个 BCP 47 language code . 需要libraqm。。版本添加：：6.0.0

• stroke_width -- 文本笔划的宽度。。版本号：6.2.0

• stroke_fill -- 用于文本笔触的颜色。如果未指定，则默认为 fill 参数。。。添加的版本：：6.2.0

• embedded_color -- 是否使用字体嵌入颜色字形(COLR、CBDT、SBIX)。。。添加的版本：：8.0.0

ImageDraw.textsize(text, font=None, spacing=4, direction=None, features=None, language=None, stroke_width=0)[源代码]

返回给定字符串的大小（像素）。

使用 textlength() 若要以1/64像素精度测量后续文本的偏移量，请执行以下操作。使用 textbbox() 若要获取基于锚点的准确边界框，请执行以下操作。

注解

由于历史原因，此函数从上升行而不是从顶部测量文本高度，请参见 文本锚点 。如果要从顶部测量文本高度，建议使用 textbbox() 使用 anchor='lt' 取而代之的是。

参数

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

• font -- 安 ImageFont 实例。

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

• direction -- 文本的方向。它可以 "rtl" （从右到左）， "ltr" （从左到右）或 "ttb" （从上到下）。需要libraqm。。版本2.0 ADDED:：4

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

• language -- 文本的语言。不同的语言可以使用不同的字形或连字。此参数告诉文本使用哪种语言的字体，并根据需要应用正确的替换（如果可用）。应该是一个 BCP 47 language code . 需要libraqm。。版本添加：：6.0.0

• stroke_width -- 文本笔划的宽度。。版本号：6.2.0

ImageDraw.multiline_textsize(text, font=None, spacing=4, direction=None, features=None, language=None, stroke_width=0)[源代码]

返回给定字符串的大小（像素）。

使用 textlength() 若要以1/64像素精度测量后续文本的偏移量，请执行以下操作。使用 textbbox() 若要获取基于锚点的准确边界框，请执行以下操作。

注解

由于历史原因，此函数将文本高度测量为上行和下行之间的距离，而不是文本的顶部和底部之间的距离，请参见 文本锚点 。如果要从文本顶部到底部测量文本高度，建议使用 multiline_textbbox() 取而代之的是。

参数

• text -- 要测量的文本。

• font -- 安 ImageFont 实例。

• spacing -- 行与行之间的像素数。

• direction -- 文本的方向。它可以 "rtl" （从右到左）， "ltr" （从左到右）或 "ttb" （从上到下）。需要libraqm。。版本2.0 ADDED:：4

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

• language -- 文本的语言。不同的语言可以使用不同的字形或连字。此参数告诉文本使用哪种语言的字体，并根据需要应用正确的替换（如果可用）。应该是一个 BCP 47 language code . 需要libraqm。。版本添加：：6.0.0

• stroke_width -- 文本笔划的宽度。。版本号：6.2.0

ImageDraw.textlength(text, font=None, direction=None, features=None, language=None, embedded_color=False)[源代码]

使用提供的方向、功能和语言以字体呈现时，返回给定文本的长度(以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" （从上到下）。需要QMLibra。

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

• language -- 文本的语言。不同的语言可以使用不同的字形或连字。此参数告诉文本使用哪种语言的字体，并根据需要应用正确的替换（如果可用）。应该是一个 BCP 47 language code . 需要QMLibra。

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

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

使用提供的方向、功能和语言以字体呈现时，返回给定文本相对于给定锚点的边框(以像素为单位)。仅支持TrueType字体。

使用 textlength() 若要以1/64像素精度获取后续文本的偏移量，请执行以下操作。边界框包括某些字体的额外边距，例如斜体或重音。

8.0.0 新版功能.

参数

• xy -- 文本的锚点坐标。

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

• font -- A FreeTypeFont 实例。

• anchor -- 文本锚点对齐方式。确定锚点相对于文本的相对位置。默认对齐方式为左上角。看见 文本锚点 有效值。对于非TrueType字体，此参数将被忽略。

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

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

• direction -- 文本的方向。它可以 "rtl" （从右到左）， "ltr" （从左到右）或 "ttb" （从上到下）。需要QMLibra。

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

• language -- 文本的语言。不同的语言可以使用不同的字形或连字。此参数告诉文本使用哪种语言的字体，并根据需要应用正确的替换（如果可用）。应该是一个 BCP 47 language code . 需要QMLibra。

• stroke_width -- 文本笔划的宽度。

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

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)[源代码]

使用提供的方向、功能和语言以字体呈现时，返回给定文本相对于给定锚点的边框(以像素为单位)。仅支持TrueType字体。

使用 textlength() 若要以1/64像素精度获取后续文本的偏移量，请执行以下操作。边界框包括某些字体的额外边距，例如斜体或重音。

8.0.0 新版功能.

参数

• xy -- 文本的锚点坐标。

• text -- 要测量的文本。

• font -- A FreeTypeFont 实例。

• anchor -- 文本锚点对齐方式。确定锚点相对于文本的相对位置。默认对齐方式为左上角。看见 文本锚点 有效值。对于非TrueType字体，此参数将被忽略。

• spacing -- 行与行之间的像素数。

• align -- "left" ， "center" 或 "right" 。确定线条的相对对齐方式。使用 anchor 参数指定对齐方式。 xy 。

• direction -- 文本的方向。它可以 "rtl" （从右到左）， "ltr" （从左到右）或 "ttb" （从上到下）。需要QMLibra。

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

• language -- 文本的语言。不同的语言可以使用不同的字形或连字。此参数告诉文本使用哪种语言的字体，并根据需要应用正确的替换（如果可用）。应该是一个 BCP 47 language code . 需要QMLibra。

• stroke_width -- 文本笔划的宽度。

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

PIL.ImageDraw.getdraw(im=None, hints=None)[源代码]

警告

这种方法是实验性的。

基于WCK接口的PIL图像更高级的二维绘图接口。

参数

• im -- 要绘制的图像。

• hints -- 提示的可选列表。

返回

（绘图上下文、绘图资源工厂）元组。

PIL.ImageDraw.floodfill(image, xy, value, border=None, thresh=0)[源代码]

警告

这种方法是实验性的。

用给定颜色填充有界区域。

参数

• image -- 目标图像。

• xy -- 种子位置（2项坐标元组）。

• value -- 填充颜色。

• border -- 可选边框值。如果给定，该区域由颜色与边框颜色不同的像素组成。如果没有给出，该区域由与种子像素颜色相同的像素组成。

• thresh -- 可选阈值，指定像素值与“背景”的最大允许差异，以便替换。用于填充颜色不均匀但相似的区域。