ImageFont モジュール

ImageFont モジュールは、同じ名前のクラスを定義します。このクラスのインスタンスはビットマップフォントを格納し、PIL.ImageDraw.ImageDraw.text() メソッドで使用されます。

PIL は独自のフォントファイル形式を使用してビットマップフォントを格納します。これは256文字に制限されています。pilfont.py（pillow-scripts）を使用して、BDF および PCF フォント記述子（X Window システムのフォント形式）をこの形式に変換できます。

バージョン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 – ファイルを読み取ることができなかった場合。

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

ファイルまたはファイル様オブジェクトから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”（拡張Wansung）

    • ”joha”（Johab）

    • ”lat1”（Latin-1）

    これは使用する文字セットを指定します。後続の操作で提供されるテキストのエンコーディングを変更しません。

  • **layout_engine** –

    利用可能な場合、使用するレイアウトエンジン：ImageFont.Layout.BASICまたはImageFont.Layout.RAQM。利用可能な場合、デフォルトでRaqmレイアウトが使用されます。そうでない場合は、基本レイアウトが使用されます。

    Raqmレイアウトは、英語以外のすべてのテキストにお勧めします。Raqmレイアウトが必要ない場合は、基本レイアウトの方がパフォーマンスが向上します。

    feature="raqm"を使用してPIL.features.check_feature()で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内部ストレージメモリインスタンス。

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

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

指定された引数を使用して、このFreeTypeFontオブジェクトの設定を上書きし、このFreeTypeFontオブジェクトのコピーを作成します。

パラメータは、このオブジェクトの初期化に使用されるパラメータと同じです。

戻り値：

FreeTypeFontオブジェクト。

get_variation_axes() → list[Axis][source]
戻り値：

バリエーションフォントの軸のリスト。

例外：

OSError – フォントがバリエーションフォントでない場合。

get_variation_names() → list[bytes][source]
戻り値：

バリエーションフォントにおける名前付きスタイルのリストを返します。

例外：

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

指定されたアンカーを基準とした、指定されたテキストのバウンディングボックス（ピクセル単位）を返します。レンダリングは、指定された方向、機能、言語を使用してフォントで行われます。

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ピクセルの精度を持つピクセル単位）を返します。レンダリングは、指定された方向、機能、言語を使用してフォントで行われます。

これは、次のテキストをオフセットする必要がある量です。テキストのバウンディングボックスは、イタリック体やアクセントを使用する場合など、一部のフォントでは長さよりも広がる可能性があります。

結果は浮動小数点数として返されます。基本レイアウトを使用している場合は、整数になります。

カーニングのために、2つの長さの合計が連結された文字列の長さに等しくない場合があります。カーニングを調整する必要がある場合は、次の文字を含めてその長さを減算してください。

例えば、

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

テキストのビットマップを作成します。

フォントがアンチエイリアシングを使用する場合は、ビットマップのモードは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]

テキストのビットマップを作成します。

フォントがアンチエイリアシングを使用する場合は、ビットマップのモードは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内部ストレージメモリインスタンスと、テキストオフセット（開始座標と最初のマーキングの間隔）のタプルを返します。

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: PIL.ImageFont.ImageFont | PIL.ImageFont.FreeTypeFont, orientation: PIL.Image.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) → PIL.Image.core.ImagingCore [ソース]

定数

class PIL.ImageFont.Layout [ソース]
BASIC

TrueTypeフォントの基本的なテキストレイアウトを使用します。テキストの方向などの高度な機能はサポートされていません。

RAQM

TrueTypeフォントのRaqmテキストレイアウトを使用します。高度な機能がサポートされています。

Raqmが必要です。サポートを確認するには、feature="raqm" を使用して PIL.features.check_feature() を使用してください。

PIL.ImageFont.MAX_STRING_LENGTH

潜在的なDoS攻撃から保護するために1,000,000に設定されています。文字数がこの制限を超えると、PillowはValueErrorを発生させます。チェックを無効にするには、ImageFont.MAX_STRING_LENGTH = None と設定します。

辞書

class PIL.ImageFont.Axis [ソース]

ベース: TypedDict

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