ImageFont 模組

ImageFont 模組定義了一個同名的類別。此類別的實例儲存點陣字型，並與 PIL.ImageDraw.ImageDraw.text() 方法一起使用。

PIL 使用自己的字型檔案格式來儲存點陣字型，限制為 256 個字元。您可以使用來自 pillow-scripts 的 pilfont.py 將 BDF 和 PCF 字型描述符（X window 字型格式）轉換為此格式。

從 1.1.4 版開始，PIL 可以設定為支援 TrueType 和 OpenType 字型（以及 FreeType 函式庫支援的其他字型格式）。對於較早的版本，TrueType 支援僅作為 imToolkit 套件的一部分提供。

警告

為了防止在使用任意字串作為文字輸入時發生潛在的 DOS 攻擊，如果字元數超過特定限制 MAX_STRING_LENGTH，Pillow 將會引發 ValueError。

可以透過設定 MAX_STRING_LENGTH 來變更此閾值。可以透過設定 ImageFont.MAX_STRING_LENGTH = None 來停用此限制。

範例

from PIL import ImageFont, ImageDraw

draw = ImageDraw.Draw(image)

# use a bitmap font
font = ImageFont.load("arial.pil")

draw.text((10, 10), "hello", font=font)

# use a truetype font
font = ImageFont.truetype("arial.ttf", 15)

draw.text((10, 25), "world", font=font)

函式

PIL.ImageFont.load(filename: str) → ImageFont[來源]

載入字型檔案。此函式從給定的點陣字型檔案載入字型物件，並傳回對應的字型物件。對於載入 TrueType 或 OpenType 字型，請參閱 truetype()。

參數:

filename – 字型檔案的名稱。

傳回:

一個字型物件。

引發:

OSError – 如果無法讀取檔案。

PIL.ImageFont.load_path(filename: str | bytes) → ImageFont[來源]

載入字型檔案。與 load() 相同，但會沿著 Python 路徑搜尋點陣字型。

參數:

filename – 字型檔案的名稱。

傳回:

一個字型物件。

引發:

OSError – 如果無法讀取檔案。

PIL.ImageFont.truetype(font: str | bytes | PathLike[str] | PathLike[bytes] | BinaryIO, size: float = 10, index: int = 0, encoding: str = '', layout_engine: Layout | None = None) → FreeTypeFont[原始碼]

從檔案或類檔案物件載入 TrueType 或 OpenType 字體，並建立字體物件。此函式從給定的檔案或類檔案物件載入字體物件，並為給定大小的字體建立字體物件。若要改為載入點陣字體，請參閱 load() 和 load_path()。

Pillow 使用 FreeType 開啟字體檔案。在 Windows 上，請注意只要 FreeTypeFont 物件存在，FreeType 就會保持檔案開啟。Windows 限制 C 中一次可以開啟的檔案數為 512 個，因此如果同時開啟許多字體並接近該限制，可能會擲回 OSError，回報 FreeType「無法開啟資源」。一個變通方法是將檔案複製到記憶體中，然後改為開啟該檔案。

此函式需要 _imagingft 服務。

參數:

  • font –

    包含 TrueType 字體的檔案名稱或類檔案物件。如果在此檔案名稱中找不到該檔案，載入器也可能會在其他目錄中搜尋，例如

    • Windows 上的 fonts/ 目錄，

    • macOS 上的 /Library/Fonts/、/System/Library/Fonts/ 和 ~/Library/Fonts/。

    • Linux 上的 ~/.local/share/fonts、/usr/local/share/fonts 和 /usr/share/fonts；或是分別由使用者安裝和系統範圍的字體的 XDG_DATA_HOME 和 XDG_DATA_DIRS 環境變數指定的字體。

  • size – 要求的尺寸，以像素為單位。

  • index – 要載入的字體面 (預設為第一個可用的字體面)。

  • encoding –

    要使用的字體編碼 (預設為 Unicode)。可能的編碼包括 (如需更多資訊，請參閱 FreeType 文件)

    • 「unic」(Unicode)

    • 「symb」(Microsoft Symbol)

    • 「ADOB」(Adobe Standard)

    • 「ADBE」(Adobe Expert)

    • 「ADBC」(Adobe Custom)

    • 「armn」(Apple Roman)

    • 「sjis」(Shift JIS)

    • 「gb 」(PRC)

    • 「big5」

    • 「wans」(Extended Wansung)

    • 「joha」(Johab)

    • 「lat1」(Latin-1)

    這會指定要使用的字元集。它不會變更後續作業中提供的任何文字的編碼。

  • layout_engine –

    要使用的版面配置引擎 (如果可用)：ImageFont.Layout.BASIC 或 ImageFont.Layout.RAQM。如果可用，預設會使用 Raqm 版面配置。否則，將使用基本版面配置。

    建議所有非英文文字使用 Raqm 版面配置。如果不需要 Raqm 版面配置，基本版面配置會有較佳的效能。

    您可以使用 PIL.features.check_feature() 和 feature="raqm" 檢查 Raqm 版面配置的支援。

    在 4.2.0 版本中新增。

傳回:

一個字型物件。

引發:

  • OSError – 如果無法讀取檔案。

  • ValueError – 如果字體大小不超過零。

PIL.ImageFont.load_default(size: float | None = None) → FreeTypeFont | ImageFont[原始碼]

如果 FreeType 支援可用，則載入 Aileron Regular 的版本，https://dotcolon.net/font/aileron，具有更有限的字元集。

否則，載入「勝於無」的字體。

在 1.1.4 版本中新增。

參數:

size –

Aileron Regular 的字體大小。

在 10.1.0 版本中新增。

傳回:

一個字型物件。

PIL.ImageFont.load_default_imagefont() → ImageFont[原始碼]

方法

class PIL.ImageFont.ImageFont[原始碼]

PIL 字體包裝函式

getbbox(text: str | bytes | bytearray, *args: Any, **kwargs: Any) → tuple[int, int, int, int][原始碼]

傳回指定文字的邊界框 (以像素為單位)。

在 9.2.0 版本中新增。

參數:

text – 要呈現的文字。

傳回:

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

getlength(text: str | bytes | bytearray, *args: Any, **kwargs: Any) → int[原始碼]

傳回指定文字的長度 (以像素為單位)。這是後續文字應該偏移的量。

在 9.2.0 版本中新增。

getmask(text: str | bytes, mode: str = '', *args: Any, **kwargs: Any) → Image.core.ImagingCore[原始碼]

為文字建立點陣圖。

如果字型使用反鋸齒，點陣圖應具有模式 L 並使用最大值 255。否則，它應具有模式 1。

參數:

  • text – 要呈現的文字。

  • mode –

    某些圖形驅動程式使用此參數來指示驅動程式偏好的模式；如果為空，則渲染器可能會傳回任一模式。請注意，模式始終是一個字串，以簡化 C 級實作。

    在 1.1.5 版中新增。

傳回:

由 PIL.Image.core 介面模組定義的內部 PIL 儲存記憶體實例。

class PIL.ImageFont.FreeTypeFont(font: str | bytes | PathLike[str] | PathLike[bytes] | BinaryIO, size: float = 10, index: int = 0, encoding: str = '', layout_engine: Layout | None = None)[原始碼]

FreeType 字型包裝函式 (需要 _imagingft 服務)

font_variant(font: str | bytes | PathLike[str] | PathLike[bytes] | BinaryIO | None = None, size: float | None = None, index: int | None = None, encoding: str | None = None, layout_engine: Layout | None = None) → FreeTypeFont[原始碼]

建立此 FreeTypeFont 物件的複本，使用任何指定的引數來覆寫設定。

參數與用於初始化此物件的參數相同。

傳回:

一個 FreeTypeFont 物件。

get_variation_axes() → list[Axis][原始碼]
傳回:

變體字型中軸的清單。

引發:

OSError – 如果字型不是變體字型。

get_variation_names() → list[bytes][原始碼]
傳回:

傳回可變字體中已命名樣式的列表。

引發:

OSError – 如果字型不是變體字型。

getbbox(text: str | bytes, mode: str = '', direction: str | None = None, features: list[str] | None = None, language: str | None = None, stroke_width: float = 0, anchor: str | None = None) → tuple[float, float, float, float][原始碼]

傳回在指定方向、特徵和語言下，以字體渲染的指定文字相對於指定錨點的邊界框（以像素為單位）。

使用 getlength() 可以取得後續文字偏移量，精確度為 1/64 像素。邊界框包含某些字體（例如斜體或重音符號）的額外邊距。

版本 8.0.0 新增。

參數:

  • text – 要呈現的文字。

  • mode – 某些圖形驅動程式會使用此參數來指出驅動程式偏好的模式；如果為空，渲染器可能會傳回任一模式。請注意，為了簡化 C 語言層級的實作，此模式一律為字串。

  • direction – 文字的方向。它可以是 'rtl' (由右至左)、'ltr' (由左至右) 或 'ttb' (由上至下)。需要 libraqm。

  • features – 文字排版期間要使用的 OpenType 字體特徵清單。這通常用於啟用預設未啟用的可選字體特徵，例如 'dlig' 或 'ss01'，但也可以用於關閉預設字體特徵，例如 '-liga' 停用連字或 '-kern' 停用字距調整。如需取得所有支援的特徵，請參閱 https://learn.microsoft.com/en-us/typography/opentype/spec/featurelist 需要 libraqm。

  • language – 文字的語言。不同的語言可能會使用不同的字形形狀或連字。此參數會告知字體文字的語言為何，並在適當時套用正確的替代 (如果有的話)。它應為 BCP 47 語言代碼。需要 libraqm。

  • stroke_width – 文字筆劃的寬度。

  • anchor – 文字錨點對齊方式。決定錨點相對於文字的相對位置。預設對齊方式為左上角，水平文字為 la，垂直文字為 lt。詳細資訊請參閱 文字錨點。

傳回:

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

getlength(text: str | bytes, mode: str = '', direction: str | None = None, features: list[str] | None = None, language: str | None = None) → float[原始碼]

傳回在指定方向、特徵和語言下，以字體渲染的指定文字的長度（以像素為單位，精確度為 1/64）。

這是後續文字應偏移的量。文字邊界框可能會超出某些字體的長度，例如使用斜體或重音符號時。

結果以浮點數形式傳回；如果使用基本排版，則為整數。

請注意，由於字距調整，兩個長度的總和可能不等於串連字串的長度。如果您需要調整字距調整，請包含下列字元並減去其長度。

例如，不要用

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

改用

hello = font.getlength("HelloW") - font.getlength("W")  # adjusted for kerning
world = font.getlength("World")
hello_world = hello + world  # adjusted for kerning
assert hello_world == font.getlength("HelloWorld")  # 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"])

版本 8.0.0 新增。

參數:

  • text – 要測量的文字。

  • mode – 某些圖形驅動程式會使用此參數來指出驅動程式偏好的模式；如果為空，渲染器可能會傳回任一模式。請注意，為了簡化 C 語言層級的實作，此模式一律為字串。

  • direction – 文字的方向。它可以是 'rtl' (由右至左)、'ltr' (由左至右) 或 'ttb' (由上至下)。需要 libraqm。

  • features – 文字排版期間要使用的 OpenType 字體特徵清單。這通常用於啟用預設未啟用的可選字體特徵，例如 'dlig' 或 'ss01'，但也可以用於關閉預設字體特徵，例如 '-liga' 停用連字或 '-kern' 停用字距調整。如需取得所有支援的特徵，請參閱 https://learn.microsoft.com/en-us/typography/opentype/spec/featurelist 需要 libraqm。

  • language –

    文字的語言。不同的語言可能會使用不同的字形形狀或連字。此參數會告知字體文字的語言為何，並在適當時套用正確的替代 (如果有的話)。它應為 BCP 47 語言代碼。需要 libraqm。

傳回:

水平文字為寬度，垂直文字為高度。

getmask(text: str | bytes, mode: str = '', direction: str | None = None, features: list[str] | None = None, language: str | None = None, stroke_width: float = 0, anchor: str | None = None, ink: int = 0, start: tuple[float, float] | None = None) → Image.core.ImagingCore[原始碼]

為文字建立點陣圖。

如果字體使用反鋸齒，點陣圖的模式應為 L，並使用最大值 255。如果字體有嵌入的顏色資料，點陣圖的模式應為 RGBA。否則，其模式應為 1。

參數:

  • text – 要呈現的文字。

  • mode –

    某些圖形驅動程式使用此參數來指示驅動程式偏好的模式；如果為空，則渲染器可能會傳回任一模式。請注意，模式始終是一個字串，以簡化 C 級實作。

    在 1.1.5 版中新增。

  • direction –

    文字的方向。它可以是 'rtl'（從右到左）、'ltr'（從左到右）或 'ttb'（從上到下）。需要 libraqm。

    在 4.2.0 版本中新增。

  • features –

    在文字排版期間要使用的 OpenType 字體功能的列表。這通常用於開啟預設未啟用的可選字體功能，例如 'dlig' 或 'ss01'，但也可以用於關閉預設字體功能，例如 '-liga' 禁用連字或 '-kern' 禁用字距調整。要取得所有支援的功能，請參閱 https://learn.microsoft.com/en-us/typography/opentype/spec/featurelist 需要 libraqm。

    在 4.2.0 版本中新增。

  • language –

    文字的語言。不同的語言可能會使用不同的字形形狀或連字。此參數會告知字體文字的語言為何，並在適當時套用正確的替代 (如果有的話)。它應為 BCP 47 語言代碼。需要 libraqm。

    在 6.0.0 版本中新增。

  • stroke_width –

    文字描邊的寬度。

    在 6.2.0 版本中新增。

  • anchor –

    文字錨點對齊方式。決定錨點相對於文字的位置。預設的對齊方式是左上角，具體來說，水平文字為 la，垂直文字為 lt。請參閱 文字錨點 以了解詳細資訊。

    版本 8.0.0 新增。

  • ink –

    在 RGBA 模式下渲染的前景墨水。

    版本 8.0.0 新增。

  • start –

    水平和垂直偏移量的元組，因為當從小數座標開始時，文字的呈現方式可能會有所不同。

    在 9.4.0 版本中新增。

傳回:

由 PIL.Image.core 介面模組定義的內部 PIL 儲存記憶體實例。

getmask2(text: str | bytes, mode: str = '', direction: str | None = None, features: list[str] | None = None, language: str | None = None, stroke_width: float = 0, anchor: str | None = None, ink: int = 0, start: tuple[float, float] | None = None, *args: Any, **kwargs: Any) → tuple[Image.core.ImagingCore, tuple[int, int]][原始碼]

為文字建立點陣圖。

如果字體使用反鋸齒，點陣圖的模式應為 L，並使用最大值 255。如果字體有嵌入的顏色資料，點陣圖的模式應為 RGBA。否則，其模式應為 1。

參數:

  • text – 要呈現的文字。

  • mode –

    某些圖形驅動程式使用此參數來指示驅動程式偏好的模式；如果為空，則渲染器可能會傳回任一模式。請注意，模式始終是一個字串，以簡化 C 級實作。

    在 1.1.5 版中新增。

  • direction –

    文字的方向。它可以是 'rtl'（從右到左）、'ltr'（從左到右）或 'ttb'（從上到下）。需要 libraqm。

    在 4.2.0 版本中新增。

  • features –

    在文字排版期間要使用的 OpenType 字體功能的列表。這通常用於開啟預設未啟用的可選字體功能，例如 'dlig' 或 'ss01'，但也可以用於關閉預設字體功能，例如 '-liga' 禁用連字或 '-kern' 禁用字距調整。要取得所有支援的功能，請參閱 https://learn.microsoft.com/en-us/typography/opentype/spec/featurelist 需要 libraqm。

    在 4.2.0 版本中新增。

  • language –

    文字的語言。不同的語言可能會使用不同的字形形狀或連字。此參數會告知字體文字的語言為何，並在適當時套用正確的替代 (如果有的話)。它應為 BCP 47 語言代碼。需要 libraqm。

    在 6.0.0 版本中新增。

  • stroke_width –

    文字描邊的寬度。

    在 6.2.0 版本中新增。

  • anchor –

    文字錨點對齊方式。決定錨點相對於文字的位置。預設的對齊方式是左上角，具體來說，水平文字為 la，垂直文字為 lt。請參閱 文字錨點 以了解詳細資訊。

    版本 8.0.0 新增。

  • ink –

    在 RGBA 模式下渲染的前景墨水。

    版本 8.0.0 新增。

  • start –

    水平和垂直偏移量的元組，因為當從小數座標開始時，文字的呈現方式可能會有所不同。

    在 9.4.0 版本中新增。

傳回:

一個由內部 PIL 儲存記憶體實例組成的元組，由 PIL.Image.core 介面模組定義，以及文字偏移量，即起始座標和第一個標記之間的間距。

getmetrics() → tuple[int, int][原始碼]
傳回:

字體上升高度（從基線到最高輪廓點的距離）和下降高度（從基線到最低輪廓點的距離，為負值）的元組。

getname() → tuple[str | None, str | None][原始碼]
傳回:

字體系列（例如 Helvetica）和字體樣式（例如 Bold）的元組。

set_variation_by_axes(axes: list[float]) → None[原始碼]
參數:

axes – 每個軸的值的列表。

引發:

OSError – 如果字型不是變體字型。

set_variation_by_name(name: str | bytes) → None[原始碼]
參數:

name – 樣式的名稱。

引發:

OSError – 如果字型不是變體字型。

class PIL.ImageFont.TransposedFont(font: ImageFont | FreeTypeFont, orientation: Transpose | None = None)[原始碼]

用於書寫旋轉或鏡像文字的封裝器

getbbox(text: str | bytes, *args: Any, **kwargs: Any) → tuple[int, int, float, float][原始碼]
getlength(text: str | bytes, *args: Any, **kwargs: Any) → float[原始碼]
getmask(text: str | bytes, mode: str = '', *args: Any, **kwargs: Any) → Image.core.ImagingCore[原始碼]

常數

class PIL.ImageFont.Layout[原始碼]
BASIC

對 TrueType 字型使用基本文字排版。不支援文字方向等進階功能。

RAQM

對 TrueType 字型使用 Raqm 文字排版。支援進階功能。

需要 Raqm，您可以使用 PIL.features.check_feature() 及 feature="raqm" 來檢查是否支援。

PIL.ImageFont.MAX_STRING_LENGTH

設定為 1,000,000，以防止潛在的 DOS 攻擊。如果字元數超過此限制，Pillow 將引發 ValueError。可以透過設定 ImageFont.MAX_STRING_LENGTH = None 來停用此檢查。

字典

class PIL.ImageFont.Axis[原始碼]

基底類別： TypedDict

default: int | None
maximum: int | None
minimum: int | None
name: bytes | None