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将引发 ValueError 如果字符数量超过某一限制， MAX_STRING_LENGTH 。

此阈值可通过设置 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)[源代码]#

加载字体文件。此函数从给定的位图字体文件加载字体对象，并返回相应的字体对象。

参数:

filename -- 字体文件的名称。

返回:

字体对象。

抛出:

OSError -- 如果无法读取文件。

PIL.ImageFont.load_path(filename)[源代码]#

加载字体文件。等同于 load() ，但沿python路径搜索位图字体。

参数:

filename -- 字体文件的名称。

返回:

字体对象。

抛出:

OSError -- 如果无法读取文件。

PIL.ImageFont.truetype(font=None, size=10, index=0, encoding='', layout_engine=None)[源代码]#

从文件或类似文件的对象加载TrueType或OpenType字体，然后创建字体对象。此函数从给定的文件或类似文件的对象加载字体对象，并为给定大小的字体创建字体对象。

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

此功能需要“Imagingft”服务。

参数:

  • font -- 包含TrueType字体的文件名或类似文件的对象。如果在此文件名中找不到该文件，加载程序还可以在其他目录中搜索，例如 fonts/ Windows上的目录或 /Library/Fonts/ ， /System/Library/Fonts/ 和 ~/Library/Fonts/ 关于MaOS.

  • size -- 请求的大小，以像素为单位。

  • index -- 要加载的字体（默认为第一个可用的字体）。

  • encoding -- 要使用的字体编码（默认为Unicode）。可能的编码包括（有关详细信息，请参阅FreeType文档）： “unic”（Unicode） “symb”（Microsoft符号） “ADOB”（Adobe标准） “ADBE”（Adobe专家） “ADBC”（Adobe自定义） “阿姆”（苹果罗马语） “sjis”（班次JIS） “gb”（中国） “大5” “广域网”（扩展的广域网） “约翰”（约翰） “lat1”（拉丁语-1）指定要使用的字符集。它不会更改后续操作中提供的任何文本的编码。

  • layout_engine -- 要使用的布局引擎(如果可用)： ImageFont.Layout.BASIC 或 ImageFont.Layout.RAQM 。如果可用，默认情况下将使用Raqm布局。否则，将使用基本布局。对于所有非英文文本，建议使用Raqm布局。如果不需要Raqm布局，基本布局会有更好的性能。您可以使用以下命令检查对Raqm布局的支持 PIL.features.check_feature() 使用 feature="raqm" 。。。添加的版本：：4.2.0

返回:

字体对象。

抛出:

OSError -- 如果无法读取文件。

PIL.ImageFont.load_default()[源代码]#

加载“Better than Nothing”默认字体。

在 1.1.4 版本加入.

返回:

字体对象。

方法#

class PIL.ImageFont.ImageFont[源代码]#

PIL字体包装

getbbox(text, *args, **kwargs)[源代码]#

返回给定文本的边框(以像素为单位)。

在 9.2.0 版本加入.

参数:

  • text -- 要渲染的文本。

  • mode -- 某些图形驱动程序使用它来指示驱动程序喜欢哪种模式；如果为空，渲染器可能返回任一模式。请注意，模式始终是字符串，以简化C级实现。

返回:

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

getlength(text, *args, **kwargs)[源代码]#

返回给定文本的长度(以像素为单位)。这是以下文本应偏移量。

在 9.2.0 版本加入.

getmask(text, mode='', *args, **kwargs)[源代码]#

为文本创建位图。

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

参数:

  • text -- 要渲染的文本。

  • mode -- 某些图形驱动程序使用它来指示驱动程序喜欢哪种模式；如果为空，渲染器可能返回任一模式。请注意，模式始终是字符串，以简化C级实现。…添加的版本：1.1.5

返回:

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

class PIL.ImageFont.FreeTypeFont(font=None, size=10, index=0, encoding='', layout_engine=None)[源代码]#

freetype字体包装（需要“imagingft”服务）

font_variant(font=None, size=None, index=None, encoding=None, layout_engine=None)[源代码]#

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

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

返回:

FreeTypeFont对象。

get_variation_axes()[源代码]#
返回:

变体字体中的轴列表。

抛出:

OSError -- 如果字体不是变体字体。

get_variation_names()[源代码]#
返回:

变体字体中命名样式的列表。

抛出:

OSError -- 如果字体不是变体字体。

getbbox(text, mode='', direction=None, features=None, language=None, stroke_width=0, anchor=None)[源代码]#

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

使用 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要求库。

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

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

  • anchor -- 文本锚点对齐方式。确定锚点相对于文本的相对位置。默认对齐方式为左上角。看见 文本锚点 有效值。

返回:

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

getlength(text, mode='', direction=None, features=None, language=None)[源代码]#

使用提供的方向、功能和语言以字体呈现时，返回给定文本的长度(以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要求库。

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

返回:

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

getmask(text, mode='', direction=None, features=None, language=None, stroke_width=0, anchor=None, ink=0, start=None)[源代码]#

为文本创建位图。

如果字体使用抗锯齿，则位图应具有模式 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要求库。。。添加的版本：：4.2.0

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

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

  • anchor -- 文本锚点对齐方式。确定锚点相对于文本的相对位置。默认对齐方式为左上角。看见 文本锚点 有效值。。。添加的版本：：8.0.0

  • ink -- 用于在RGBA模式下渲染的前景墨迹。。。添加的版本：：8.0.0

  • start -- 水平和垂直偏移量的元组，因为从分数坐标开始时，文本的呈现方式可能不同。。。版本已添加：：9.4.0

返回:

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

getmask2(text, mode='', direction=None, features=None, language=None, stroke_width=0, anchor=None, ink=0, start=None, *args, **kwargs)[源代码]#

为文本创建位图。

如果字体使用抗锯齿，则位图应具有模式 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要求库。。。添加的版本：：4.2.0

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

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

  • anchor -- 文本锚点对齐方式。确定锚点相对于文本的相对位置。默认对齐方式为左上角。看见 文本锚点 有效值。。。添加的版本：：8.0.0

  • ink -- 用于在RGBA模式下渲染的前景墨迹。。。添加的版本：：8.0.0

  • start -- 水平和垂直偏移量的元组，因为从分数坐标开始时，文本的呈现方式可能不同。。。版本已添加：：9.4.0

返回:

内部PIL存储内存实例的元组，由 PIL.Image.core 接口模块，以及文本偏移量，起始坐标和第一个标记之间的间隙

getmetrics()[源代码]#
返回:

字体上升（从基线到最高轮廓点的距离）和下降（从基线到最低轮廓点的距离，负值）的元组

getname()[源代码]#
返回:

字体系列的元组（例如Helvetica）和字体样式（例如粗体）

set_variation_by_axes(axes)[源代码]#
参数:

axes -- 每个轴的值列表。

抛出:

OSError -- 如果字体不是变体字体。

set_variation_by_name(name)[源代码]#
参数:

name -- 样式的名称。

抛出:

OSError -- 如果字体不是变体字体。

class PIL.ImageFont.TransposedFont(font, orientation=None)[源代码]#

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

getbbox(text, *args, **kwargs)[源代码]#
getlength(text, *args, **kwargs)[源代码]#
getmask(text, mode='', *args, **kwargs)[源代码]#

常量#

PIL.ImageFont.Layout.BASIC#

使用TrueType字体的基本文本布局。不支持文本方向等高级功能。

PIL.ImageFont.Layout.RAQM#

对TrueType字体使用Raqm文本布局。支持高级功能。

需要Raqm，您可以使用 PIL.features.check_feature() 具有 feature="raqm" .

常量#

PIL.ImageFont.MAX_STRING_LENGTH#

设置为1,000,000，以防止潜在的DOS攻击。枕头将提高一个 ValueError 如果字符数超过此限制。可通过设置禁用该检查 ImageFont.MAX_STRING_LENGTH = None 。