ImageDraw 模块#

这个 ImageDraw 模块提供简单的二维图形 Image 物体。您可以使用此模块创建新图像、对现有图像进行注释或润色,以及动态生成图形以供Web使用。

有关PIL的更高级绘图库,请参见 aggdraw module .

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

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 模块。请注意,此功能依赖于第三方库,可能在所有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)[源代码]#

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

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

参数:
  • 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()[源代码]#

获取当前默认字体, ImageDraw.font

如果当前默认字体为 None ,则将其初始化为 ImageFont.load_default()

返回:

图像字体。

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

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

参数:
  • xy -- 定义边界框的两点。序列 [(x0, y0), (x1, y1)][x0, y0, x1, y1] 在哪里 x1 >= x0y1 >= 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 >= x0y1 >= 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 >= x0y1 >= 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 >= x0y1 >= 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, width=1)[源代码]#

绘制多边形。

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

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

绘制内接的正多边形 bounding_circlen_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)[源代码]#

绘制矩形。

参数:
  • xy -- 定义边界框的两个点。其中之一的顺序 [(x0, y0), (x1, y1)][x0, y0, x1, y1] ,在哪里 x1 >= x0y1 >= y0 。边界框包含两个端点。

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

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

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

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

绘制圆角矩形。

参数:
  • xy -- 定义边界框的两个点。其中之一的顺序 [(x0, y0), (x1, y1)][x0, y0, x1, y1] ,在哪里 x1 >= x0y1 >= y0 。边界框包含两个端点。

  • radius -- 角的半径。

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

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

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

  • corners -- 是否绕过每个角落的元组, (top_left, top_right, bottom_right, bottom_left) 。仅限关键字的参数。

在 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.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)。

返回:

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

使用提供的方向、功能和语言以字体呈现时,返回给定文本相对于给定锚点的边框(以像素为单位)。仅支持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)。

返回:

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

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 -- 可选阈值,指定像素值与“背景”的最大允许差异,以便替换。用于填充颜色不均匀但相似的区域。