ImageDraw 模組

ImageDraw 模組為 Image 物件提供簡單的 2D 圖形功能。您可以使用此模組來建立新的影像、註解或修飾現有影像，以及即時產生用於網路的圖形。

若要取得更進階的 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)[來源]

建立一個可用於在指定影像中繪圖的物件。

請注意，影像將會就地修改。

參數：

  • 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 >= 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.circle(xy, radius, fill=None, outline=None, width=1)[原始碼]

繪製一個以給定點為中心，具有指定半徑的圓形。

在 10.4.0 版本中新增。

參數：

  • xy – 圓心的點，例如 (x, y)。

  • radius – 圓的半徑。

  • outline – 用於輪廓的顏色。

  • fill – 用於填充的顏色。

  • width – 線條寬度，以像素為單位。

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), ...] 的 2 元組序列，或是類似 [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)[原始碼]

與 arc 相同，但也會在端點和邊界框中心之間繪製直線。

參數：

  • 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), ...] 的 2 元組序列，或是類似 [x, y, x, y, ...] 的數值。

  • fill – 用於點的顏色。

ImageDraw.polygon(xy, fill=None, outline=None, width=1)[原始碼]

繪製多邊形。

多邊形輪廓由給定座標之間的直線組成，以及最後一個座標和第一個座標之間的直線。 座標像素包含在繪製的多邊形中。

參數：

  • xy – 可以是類似 [(x, y), (x, y), ...] 的 2 元組序列，或是類似 [x, y, x, y, ...] 的數值。

  • fill – 用於填充的顏色。

  • outline – 用於輪廓的顏色。

  • width – 線條寬度，以像素為單位。

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

繪製一個內接於 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)[原始碼]

繪製一個矩形。

參數：

  • 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)[原始碼]

繪製一個圓角矩形。

參數：

  • xy – 定義邊界框的兩個點。可以是 [(x0, y0), (x1, y1)] 或 [x0, y0, x1, y1] 的序列，其中 x1 >= x0 且 y1 >= y0。邊界框包含兩個端點。

  • radius – 角的半徑。

  • fill – 用於填充的顏色。

  • outline – 用於輪廓的顏色。

  • width – 線條寬度，以像素為單位。

  • corners – 一個元組，表示是否要圓角每個角，(左上, 右上, 右下, 左下)。僅限關鍵字參數。

在 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, font_size=None)[原始碼]

在給定位置繪製字串。

參數：

  • 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)[原始碼]

在給定位置繪製字串。

參數：

  • 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)[原始碼]

傳回以指定字體、方向、功能和語言渲染給定文字時的長度（以像素為單位，精度為 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)[原始碼]

傳回給定文字在以提供的方向、功能和語言使用字體渲染時，相對於給定錨點的邊界框（以像素為單位）。 僅支援 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 版本中新增。

傳回：

(左, 上, 右, 下) 邊界框

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)[原始碼]

傳回給定文字在以提供的方向、功能和語言使用字體渲染時，相對於給定錨點的邊界框（以像素為單位）。 僅支援 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 版本中新增。

傳回：

(左, 上, 右, 下) 邊界框

PIL.ImageDraw.getdraw(im=None, hints=None)[原始碼]

警告

此方法為實驗性質。

一個更進階的 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[原始碼]

警告

此方法為實驗性質。

用指定的顏色填充一個有界區域。

參數：

  • image – 目標圖像。

  • xy – 種子位置（一個包含 2 個項目的座標元組）。請參閱座標系統。

  • value – 填充顏色。

  • border – 可選的邊界值。如果指定，則該區域由顏色與邊界顏色不同的像素組成。如果未指定，則該區域由與種子像素顏色相同的像素組成。

  • thresh – 可選的閾值，指定像素值與「背景」的最大可容忍差異，以便替換它。適用於填充非均質但顏色相似的區域。