HOWTO · Matplotlib

Python で NumPy 配列を PIL イメージに変換する

このチュートリアルでは、PIL パッケージの Image.fromarray()を使って NumPy 配列を PIL イメージに変換する方法を説明します。

このページの内容

Pillow の Image.fromarray() を使うと、NumPy 配列から PIL 画像を作成できます。2次元配列はグレースケールの画素を表し、形状が (height, width, 3) または (height, width, 4) の配列は RGB または RGBA の画素を表します。変換前に配列の dtype と値も確認してください。PIL は一般的なインポート名で、Pillow は現在も保守されているライブラリです。

RGB 画像を作るには、3チャンネルの uint8 配列を用意して Image.fromarray() に渡します。出力では画像モード、(width, height) のサイズ、左上の画素が示されます。

このセクションのコードと表示されるラベルや出力は英語のままです。

import numpy as np
from PIL import Image

pixels = np.array(
    [[[255, 0, 0], [0, 255, 0]], [[0, 0, 255], [255, 255, 255]]],
    dtype=np.uint8,
)
image = Image.fromarray(pixels)
print(image.mode, image.size, image.getpixel((0, 0)))
RGB (2, 2) (255, 0, 0)

作成されるのはメモリ上の Pillow オブジェクトです。モードや寸法を確認し、画像プレビューに対応した環境で表示するか、ファイルに保存できます。

Image.fromarray() で NumPy 配列を PIL 画像に変換する

Image.fromarray(array) は、配列の形状と dtype から画像モードを推定します。グレースケールには形状が (height, width) の2次元配列を使います。RGB には (height, width, 3) を使い、4つ目のチャンネルを加えると RGBA になります。先頭の2つの次元は行数と列数を表すため、40行、60列の配列からは幅60ピクセル、高さ40ピクセルの画像が作られます。

値がすでに0から255までの整数である通常の8ビット画像データには np.uint8 を使います。確認せずに型変換しないでください。浮動小数点データをキャストすると小数部分が切り捨てられ、表現できる範囲を超える値は折り返されることがあります。別の尺度で測定されたデータは、変換前に表示輝度へどう対応させるか決めます。たとえば、値が0〜1なら255を掛けて丸められます。別の範囲のデータには、その意味に応じた明示的な正規化が必要です。

配列の形状、dtype、値域を整える

形状が (height, width) の配列はグレースケール画像です。RGB と RGBA の配列では末尾にチャンネル次元が加わり、各画素に3つまたは4つの値を持ちます。(height, width, 1) のような形状は通常の2次元グレースケール形式ではありません。末尾の要素がグレースケールを表す単一チャンネルなら、array[..., 0] でその次元を取り除きます。変換前に array.shape、array.dtype、最小値と最大値を確認してください。配列には規則的な長方形の格子が必要です。要素数がそろっていない入れ子のリストは画像データではありません。

以下は単体で使えるグレースケール変換例です。値は8ビットの範囲内で直接指定しているため、スケーリングは不要です。作成される画像のモードはグレースケールの L、サイズは (3, 2) です。

このセクションのコードと表示されるラベルや出力は英語のままです。

import numpy as np
from PIL import Image

gray = np.array([[0, 64, 128], [32, 160, 255]], dtype=np.uint8)
image = Image.fromarray(gray)
print(image.mode, image.size)
L (3, 2)

入力が0〜1の浮動小数点配列なら、np.round(array * 255).astype(np.uint8) のように意図を持って変換します。この処理が適切なのは、その値が正規化済みの輝度である場合に限られます。温度や任意のスコアなどの測定値には、意味のある下限と上限を選び、その範囲にクリップまたは正規化して、対応付けを記録します。そうしないと、コントラストや画素値が誤解を招くことがあります。

PIL 画像を作成する前に Matplotlib のカラーマップを適用する

2次元のスカラー場の値を色で表したい場合は、Matplotlib のカラーマップを使います。データを選んだカラーマップが想定する区間に正規化してから、カラーマップの結果を8ビットの RGB または RGBA 配列に変換します。plasma カラーマップは正規化された赤・緑・青・アルファの各チャンネルを返します。[..., :3] でアルファを除けば RGB 配列になります。これは Image.fromarray() とは別の処理です。カラーマップが色を作り、Pillow がその画素を画像として扱えるようにします。

このセクションのコードと表示されるラベルや出力は英語のままです。

import numpy as np
import matplotlib
from PIL import Image

values = np.array([[0.0, 0.25], [0.75, 1.0]])
colors = matplotlib.colormaps["plasma"](values)[..., :3]
rgb = np.round(colors * 255).astype(np.uint8)
image = Image.fromarray(rgb)
print(image.mode, image.size)
RGB (2, 2)

この例では values がすでに0〜1に正規化されていることを前提としています。実際のスカラー値が異なる範囲にある場合は、適切なデータ範囲を使ってカラーマップの適用前に正規化してください。カラーマップは可視化に便利ですが、スカラー値を表示用の色に変換します。分析に元の測定値が必要なら、それらを置き換えずに保持してください。作成される画像は RGB で、サイズは (2, 2) です。

PIL 画像をリサイズして保存する

変換後に image.resize((width, height)) を使ってリサイズします。Pillow では新しいサイズを幅、高さの順に指定します。保存と表示は別の処理です。show() はローカル環境でプレビューを開き、save() は画像ファイルを書き込みます。可逆形式の .png や JPEG の .jpg など、使いたい形式に合った拡張子を選んでください。

このセクションのコードと表示されるラベルや出力は英語のままです。

import numpy as np
from PIL import Image

pixels = np.zeros((20, 30, 3), dtype=np.uint8)
pixels[:, :15] = [255, 80, 0]
pixels[:, 15:] = [20, 90, 220]
image = Image.fromarray(pixels)
resized = image.resize((60, 40))
resized.save("resized-image.png")
print(resized.size)

この例は入力をメモリ上で作成し、現在の作業ディレクトリに resized-image.png を書き込みます。アプリケーションでは、出力先に合ったパスを指定してください。保存しても NumPy 配列は変更されません。リサイズによって変わるのは Pillow 画像の画素寸法です。

よくある変換の問題

  • 想定外のモード、または形状エラー: array.shape を確認します。グレースケールには (height, width)、RGB または RGBA には末尾に3つまたは4つのチャンネルがある形状を使います。意図しない単一チャンネルを削除するか、入力元の規約に合わせてチャンネルの順序を入れ替えてください。
  • 明るさや色が違う: 変換前に値域を確認します。0〜1の浮動小数点値は8ビット画像用に意図的なスケーリングが必要です。すでに0〜255の値には再度255を掛けないでください。それ以外の範囲では、記録した上下限に合わせて正規化します。
  • 想定外の dtype: array.dtype を調べ、適切な変換方法を決めます。キャストだけでは値域は変わりません。元の精度が重要なら、変換前のデータのコピーを保持してください。
  • カラーマップの出力が不自然: スカラー入力が意図したとおりに正規化されているか確認し、結果が RGB の3チャンネルか RGBA の4チャンネルかを調べます。画像を作成する前に、正規化された色チャンネルを uint8 に変換してください。
  • 画像ファイルが作成されない: 書き込み可能なパスと対応する拡張子を指定して save() を呼び出します。プレビューが必要なときは show() を使います。これは画像を保存しません。