Pillow ImageDraw textbbox() メソッド

textbbox()メソッドはImageDrawモジュールの中でも非常に実用的な機能で、指定されたテキストを画像上に描画する際に占める境界ボックス（bounding box）を計算するために使用されます。

textbbox()メソッドは実際にテキストを描画するのではなく、テキストが占める矩形領域の座標を返します。

メソッドの構文

textbbox(xy, text, font=None, anchor=None, spacing=4, align="left", direction=None, features=None, language=None, stroke_width=0)

パラメータの詳細

1. xy (必須)

  • 型: 2つの要素からなるタプル (x, y)
  • 説明: テキストの開始座標位置を指定します
  • 注意: 実際のテキスト位置はさらにanchorパラメータの影響を受けます

2. text (必須)

  • 型: 文字列
  • 説明: 境界ボックスを計算する必要があるテキストの内容

3. font (オプション)

  • 型: ImageFontオブジェクト
  • デフォルト値: None (デフォルトフォントを使用)
  • 説明: テキストで使用するフォントを指定します

4. anchor (オプション)

  • 型: 文字列
  • デフォルト値: None ("la" と同等)
  • 説明: xy 座標に対するテキストの配置方法を制御します
  • 一般的な値:
    • "la": 左寄せ、ベースライン揃え (デフォルト)
    • "lt": 左寄せ、上揃え
    • "ma": 中央揃え、ベースライン揃え
    • "mm": 完全に中央揃え (水平・垂直)

5. spacing (オプション)

  • 型: 整数
  • デフォルト値: 4
  • 説明: 複数行テキストの行間隔

6. align (オプション)

  • 型: 文字列
  • デフォルト値: "left"
  • 説明: 複数行テキストの配置方法 ("left", "center", "right")

7-10. その他の詳細パラメータ

  • direction, features, language, stroke_widthなどのパラメータはテキスト描画の高度な特性を制御するために使用され、初心者は通常すぐに習得する必要はありません。

戻り値

textbboxメソッドは4つの要素からなるタプルを返します(left, top, right, bottom)テキストの境界ボックス座標を表します。

実際の応用例

例1: 基本的な使い方

例

from PIL import Image, ImageDraw, ImageFont

# 空の画像を作成する
image = Image.new('RGB', (400, 200), 'white')
draw = ImageDraw.Draw(image)

# フォントを読み込む
font = ImageFont.truetype('arial.ttf', 24)

# テキストの境界ボックスを計算する
bbox = draw.textbbox((50, 50), "Hello Pillow!", font=font)

print("テキスト境界ボックス:", bbox)  # 出力: (left, top, right, bottom)

# 境界ボックスを描画する（可視化）
draw.rectangle(bbox, outline='red')

# 実際にテキストを描画する
draw.text((50, 50), "Hello Pillow!", font=font, fill='black')

image.show()

例2: anchor パラメータを使用する

例

# 上記の image と draw オブジェクトを引き続き使用する

# 中心点の座標
center_x, center_y = 200, 100

# 中央揃えのテキスト境界ボックスを計算する
bbox = draw.textbbox((center_x, center_y), "Centered", font=font, anchor="mm")

print("中央揃えの境界ボックス:", bbox)

# 中心点と境界ボックスを描画する
draw.rectangle(bbox, outline='blue')
draw.ellipse([(center_x-2, center_y-2), (center_x+2, center_y+2)], fill='green')

# テキストを描画する
draw.text((center_x, center_y), "Centered", font=font, fill='black', anchor="mm")

image.show()

よくある応用シーン

  1. テキストレイアウトの計算: テキストを描画する前にその占有領域を決定する
  2. 自動改行処理: 利用可能な幅に基づいてテキストの折り返し方法を計算する
  3. テキストの中央揃え: 境界ボックスの計算と組み合わせて正確な中央揃えを実現する
  4. 衝突検出: テキストが他の要素と重ならないようにする

注意事項

  1. フォントの影響: フォントが異なると返される境界ボックスのサイズが大きく異なる場合があります
  2. 複数行テキスト: 複数行テキストの場合、境界ボックスにはすべての行の領域が含まれます
  3. パフォーマンスの考慮: 頻繁に呼び出すとパフォーマンスに影響する可能性があるため、結果をキャッシュすることをお勧めします
  4. 精度: 境界ボックスの計算は近似値であり、実際の描画とは若干異なる場合があります

textsize との比較

旧バージョンの Pillow では、よくtextsizeメソッドを使用してテキストサイズを取得していましたが、このメソッドは非推奨になりました。textbboxより正確な情報（幅と高さだけでなく位置情報も含む）を提供するため、新しいコードでの推奨メソッドです。

例

# 旧メソッド (非推奨)
width, height = draw.textsize("Text", font=font)

# 新メソッド (推奨)
left, top, right, bottom = draw.textbbox((0, 0), "Text", font=font)
width = right - left
height = bottom - top

まとめ

ImageDraw.textbboxメソッドは Pillow ライブラリの中でも強力で実用的なツールであり、テキストレイアウトを正確に制御する必要がある場面に特に適しています。パラメータと戻り値を理解することで、開発者は複雑なテキストレイアウトの要件を簡単に実現できます。

その他の拡張