`ImageFont` 模块¶

ImageFont 模块定义了一个同名类。此类的实例存储位图字体，并与 PIL.ImageDraw.ImageDraw.text() 方法一起使用。

PIL 使用自己的字体文件格式来存储位图字体，限制为 256 个字符。您可以使用 pilfont.py 来自 pillow-scripts 将 BDF 和 PCF 字体描述符 (X 窗口字体格式) 转换为此格式。

从 1.1.4 版本开始，PIL 可以配置为支持 TrueType 和 OpenType 字体（以及 FreeType 库支持的其他字体格式）。对于早期版本，TrueType 支持仅作为 imToolkit 包的一部分提供。

警告

为了防止在使用任意字符串作为文本输入时可能发生的 DOS 攻击，Pillow 会在字符数量超过某个限制（MAX_STRING_LENGTH）时引发 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[source]¶

加载字体文件。此函数从给定的位图字体文件加载字体对象，并返回相应的字体对象。要加载 TrueType 或 OpenType 字体，请参见 truetype()。

参数：: filename – 字体文件的名称。
返回值：: 一个字体对象。
引发：: OSError – 如果无法读取文件。

PIL.ImageFont.load_path(filename: str | bytes) → ImageFont[source]¶

加载字体文件。与 load() 相同，但在 Python 路径中搜索位图字体。

参数：: filename – 字体文件的名称。
返回值：: 一个字体对象。
引发：: OSError – 如果无法读取文件。

从文件或类文件对象加载 TrueType 或 OpenType 字体，并创建一个字体对象。此函数从给定的文件或类文件对象加载字体对象，并为给定大小的字体创建一个字体对象。要加载位图字体，请参见 load() 和 load_path().

Pillow 使用 FreeType 来打开字体文件。在 Windows 上，请注意 FreeType 会在 FreeTypeFont 对象存在时一直保持文件打开。Windows 将 C 中一次可以打开的文件数量限制为 512，因此，如果同时打开了多个字体并且接近此限制，则可能会抛出 OSError，报告 FreeType “无法打开资源”。一种解决方法是将文件(s) 复制到内存中，然后打开该内存。

此函数需要 _imagingft 服务。

参数：

font –
包含 TrueType 字体的文件名或类文件对象。如果在该文件名中找不到该文件，加载程序也可能在其他目录中搜索，例如
- Windows 上的 fonts/ 目录，
- /Library/Fonts/、/System/Library/Fonts/ 和 ~/Library/Fonts/ 在 macOS 上。
- ~/.local/share/fonts、/usr/local/share/fonts 和 /usr/share/fonts 在 Linux 上；或分别由 XDG_DATA_HOME 和 XDG_DATA_DIRS 环境变量指定的用于用户安装和系统范围字体的目录。
size – 所需大小，以像素为单位。
index – 要加载的字体字形（默认值为第一个可用的字形）。
encoding –
要使用的字体编码（默认值为 Unicode）。可能的编码包括（有关更多信息，请参见 FreeType 文档）
- ”unic”（Unicode）
- ”symb”（Microsoft Symbol）
- ”ADOB”（Adobe 标准）
- ”ADBE”（Adobe 专业版）
- ”ADBC”（Adobe 自定义）
- ”armn”（Apple Roman）
- ”sjis”（Shift JIS）
- ”gb “（PRC）
- ”big5”
- ”wans”（扩展 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[source]¶

如果可用 FreeType 支持，则加载具有更多限制字符集的 Aileron Regular 版本，https://dotcolon.net/font/aileron。

否则，加载一个“比没有好”的字体。

添加到版本 1.1.4 中。

参数：

size –

Aileron Regular 的字体大小。

添加到版本 10.1.0 中。

返回值：

一个字体对象。

PIL.ImageFont.load_default_imagefont() → ImageFont[source]¶

方法¶

class PIL.ImageFont.ImageFont[source]¶

PIL 字体包装器

getbbox(text: str | bytes | bytearray, *args: Any, **kwargs: Any) → tuple[int, int, int, int][source]¶

返回给定文本的边界框（以像素为单位）。

添加到版本 9.2.0 中。

参数：: text – 要渲染的文本。
返回值：: (left, top, right, bottom) 边界框

getlength(text: str | bytes | bytearray, *args: Any, **kwargs: Any) → int[source]¶: 返回给定文本的长度（以像素为单位）。这是应偏移后续文本的量。

添加到版本 9.2.0 中。

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

为文本创建位图。

如果字体使用抗锯齿，则位图应具有 L 模式并使用最大值为 255。否则，它应具有 1 模式。

参数：

text – 要渲染的文本。
mode –
由某些图形驱动程序使用，指示驱动程序首选的模式；如果为空，则渲染器可能会返回任一模式。请注意，该模式始终是字符串，以简化 C 级实现。

添加到版本 1.1.5 中。

返回值：

由 PIL.Image.core 接口模块定义的内部 PIL 存储内存实例。

FreeType 字体包装器（需要 _imagingft 服务）

使用任何指定的参数来覆盖设置，创建此 FreeTypeFont 对象的副本。

参数与用于初始化此对象的参数相同。

返回值：: FreeTypeFont 对象。

get_variation_axes() → list[Axis][source]¶

返回值：: 变体字体中轴的列表。
引发：: OSError – 如果字体不是变体字体。

get_variation_names() → list[bytes][source]¶

返回值：: 变体字体中命名样式的列表。
引发：: OSError – 如果字体不是变体字体。

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

使用 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[source]¶

返回给定文本在提供的方向、特征和语言的字体中渲染时的长度（以 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。

返回值：

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

为文本创建位图。

如果字体使用抗锯齿，则位图的模式应为 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]][source]¶

为文本创建位图。

参数：

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 存储内存实例，以及文本偏移量，即起始坐标和第一个标记之间的间隙。

getmetrics() → tuple[int, int][source]¶

返回值：: 包含字体升高（基线到最高轮廓点的距离）和下降（基线到最低轮廓点的距离，一个负值）的元组。

getname() → tuple[str | None, str | None][source]¶

返回值：: 包含字体族（例如 Helvetica）和字体样式（例如 Bold）的元组。

set_variation_by_axes(axes: list[float]) → None[source]¶

参数：: axes – 每个轴的值列表。
引发：: OSError – 如果字体不是变体字体。

set_variation_by_name(name: str | bytes) → None[source]¶

参数：: name – 样式的名称。
引发：: OSError – 如果字体不是变体字体。

class PIL.ImageFont.TransposedFont(font: ImageFont | FreeTypeFont, orientation: Transpose | None = None)[source]¶

用于编写旋转或镜像文本的包装器。

getbbox(text: str | bytes, *args: Any, **kwargs: Any) → tuple[int, int, float, float][source]¶

getlength(text: str | bytes, *args: Any, **kwargs: Any) → float[source]¶

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

常量¶

class PIL.ImageFont.Layout[source]¶

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[source]¶

基类： TypedDict

default: int | None¶

maximum: int | None¶

minimum: int | None¶

name: bytes | None¶

ImageFont 模块¶

示例¶

函数¶

方法¶

常量¶

字典¶

`ImageFont` 模块¶