Python と Oxipng による効率的な PNG 最適化
pyoxipng で PNG をメモリ内で圧縮し、保存先が存在しない場合にのみ保存します。このチュートリアルでは、単一ファイルと小規模バッチ向けのスクリプトを紹介します。サイズの計測、失敗時の非ゼロ終了コードに加え、デコード後のピクセルが変わらないことを別途検証します。
OptiPNG と Oxipng の違い
OptiPNG と
Oxipng は別々の PNG 最適化ツールです。ここで使う Python パッケージ
pyoxipng は、Oxipng の Rust ライブラリをラップし、oxipng としてインポートします。呼び出しに OptiPNG の実行ファイルやサブプロセスは必要ありません。
保持する情報の決定
可逆最適化では、デコード後のピクセルを保持しながら PNG の圧縮方式、パレット、カラータイプを変更できます。特定の削減率を保証するものではありません。すでに小さいファイルは、まったく縮小しない場合もあります。
この例ではソースファイルを変更せず、既存の保存先への書き込みを拒否し、メタデータの削除も要求しません。また、optimize_alpha=False により、透明ピクセルの色も変更しません。管理下のディレクトリにあるローカルの静的 PNG アセットに使用してください。後述のピクセル検証は 8 ビット RGB および RGBA 入力が対象です。アニメーション、16 ビット精度、カラーマネジメント適用後の見え方は検証しません。
前提条件
以下のコマンドでは Bash と Python 3.12、および venv と pip を使います。Linux 上の Python 3.12.13 と pyoxipng 9.1.1 でテストしました。png-demo がまだ存在しないディレクトリから始めてください。
mkdir png-demo &&
cd png-demo &&
python3.12 -m venv .venv &&
.venv/bin/python -m pip install --only-binary=:all: pyoxipng==9.1.1 Pillow==12.3.0
&& による連結は、いずれかの手順が失敗するとセットアップを停止します。png-demo ディレクトリがすでに存在する場合も同様です。--only-binary オプションは、Rust のソースビルドを開始せず、互換性のある wheel を必須とします。利用可能な wheel は PyPI に掲載されています。Pillow はピクセルの検証にのみ使用し、最適化には使用しません。以降のコマンドは png-demo から実行してください。
単一 PNG の最適化
以下を optimize_png.py として保存してください。エンコード済み PNG バイト列を
optimize_from_memory に渡すため、Pillow や NumPy のピクセル配列から画像を再構築することはありません。
import argparse
from pathlib import Path
import sys
from time import perf_counter
import oxipng
def optimize_bytes(data: bytes, level: int) -> bytes:
candidate = oxipng.optimize_from_memory(
data,
level=level,
strip=oxipng.StripChunks.none(),
optimize_alpha=False,
)
return candidate if len(candidate) < len(data) else data
def optimize_file(source: Path, destination: Path, level: int) -> None:
start = perf_counter()
original = source.read_bytes()
optimized = optimize_bytes(original, level)
# Exclusive creation fails even for a dangling destination symlink.
output = destination.open("xb")
try:
with output:
output.write(optimized)
except OSError:
# Only remove the file this invocation successfully created.
destination.unlink()
raise
saved = len(original) - len(optimized)
print(
f"{source.name}: {len(original)} -> {len(optimized)} bytes; "
f"saved {saved} bytes; {perf_counter() - start:.3f} s"
)
def main() -> int:
parser = argparse.ArgumentParser(description="Optimize PNGs without overwriting outputs")
parser.add_argument("source", type=Path, help="PNG file or directory")
parser.add_argument("destination", type=Path, help="New PNG file or output directory")
parser.add_argument("--level", type=int, choices=range(7), default=2)
args = parser.parse_args()
try:
source = args.source.resolve(strict=True)
if source.is_dir():
if source == args.destination.resolve():
raise ValueError("Source and output directories must differ")
files = sorted(
path for path in source.iterdir()
if path.suffix.lower() == ".png" and not path.is_symlink() and path.is_file()
)
if not files:
raise ValueError("No PNG files found")
args.destination.mkdir(exist_ok=True)
pairs = [(path, args.destination / path.name) for path in files]
else:
pairs = [(source, args.destination)]
except (OSError, ValueError) as error:
parser.exit(1, f"Error: {error}\n")
failed = False
for input_path, output_path in pairs:
try:
optimize_file(input_path, output_path, args.level)
except (OSError, oxipng.PngError) as error:
print(f"Failed {input_path.name}: {type(error).__name__}: {error}", file=sys.stderr)
failed = True
return int(failed)
if __name__ == "__main__":
sys.exit(main())
input.png という名前の PNG をスクリプトと同じディレクトリに置き、実行します。
.venv/bin/python optimize_png.py input.png output.png
成功すると、入出力のバイト数、削減バイト数、ファイル I/O を含む経過秒数を表示します。削減バイト数がゼロでも正常です。最適化候補が元より小さくない場合は、元のファイルのコピーを書き込みます。同じコマンドを再実行すると FileExistsError を報告し、ステータス 1 で終了して、output.png は変更しません。入力自体を保存先に指定した場合も、入力を変更せずに失敗します。
Python の "xb" モードは、ファイル作成時に上書きを拒否する判断を行います。入力が破損しているか存在しない場合は、その前に失敗します。新規作成したファイルの書き込みやクローズで OSError が発生すると、スクリプトは不完全な出力の削除を試みます。これはローカルスクリプトであり、アトミックな公開の仕組みではありません。強制終了すると不完全なファイルが残る場合があるため、成功するまで別のプロセスで保存先を読み取らないでください。
ディレクトリの最適化
PNG を images_source に置き、同じスクリプトを使用します。
.venv/bin/python optimize_png.py images_source images_optimized --level 2
必要に応じて images_optimized を作成し、直下の通常ファイルのうち、大文字と小文字を区別せず .png で終わるものだけを処理します。サブディレクトリとシンボリックリンクはスキップします。ファイル名の空白とリテラルの % 文字に対応しています。- で始まるコマンドラインパスには、./ を先頭に付けるか、位置引数の前に -- を置いてください。
出力がすでに存在する場合、そのファイルの処理は失敗します。他のファイルの処理は続行し、成功した出力は残ります。いずれかのファイルが失敗すると、バッチはステータス 1 で終了します。ソースディレクトリが存在しない場合、PNG がない場合、ソースと出力が同じディレクトリの場合は、処理前に失敗します。バッチ全体を再実行するには、新しい出力ディレクトリを選んでください。
このループは、一度にメモリに常駐するデコード済み画像の数を抑えるため、画像を一つずつ処理します。Oxipng 自体がマルチスレッドに対応しており、このワークロードで Python のスレッドプールを追加しても、高速化することは実証されていません。それでも、画像ごとに入力バイト列、出力バイト列、最適化ツールの作業用メモリがメモリ内に収まる必要があります。
適切な最適化レベルの選択
このバインディングは 0 から 6 までのレベルを受け付け、デフォルトは 2 です。これらは探索のプリセットであり、品質設定でも、削減量を保証するものでもありません。まず 2 を使い、実際のアセットで結果を比較してください。
| レベル | 試す用途 |
|---|---|
| 0 | 手早く基準値を得るための処理 |
| 2 | 通常のアセットビルド |
| 4 | 探索により多くの処理をかけた比較 |
| 6 | 実行時間の重要度が低い場合の比較 |
ベンチマーク用ファイルを作らずに計測
以下を benchmark_png.py として optimize_png.py と同じディレクトリに保存し、.venv/bin/python benchmark_png.py input.png を実行してください。一つのファイルを読み込み、四つのレベルを試し、ターミナルにのみ出力します。既存のファイル名と衝突する一時出力ファイル名はありません。
import argparse
from pathlib import Path
import sys
from time import perf_counter
import oxipng
from optimize_png import optimize_bytes
parser = argparse.ArgumentParser()
parser.add_argument("source", type=Path)
args = parser.parse_args()
try:
data = args.source.read_bytes()
for level in (0, 2, 4, 6):
start = perf_counter()
result = optimize_bytes(data, level)
print(f"level={level}: {len(data)} -> {len(result)} bytes; {perf_counter() - start:.3f} s")
except (OSError, oxipng.PngError) as error:
sys.exit(f"Benchmark failed: {error}")
各レベルは元のバイト列から処理を始めます。計測時間には最適化を含みますが、最初のファイル読み込みは含みません。代表的なファイルで計測を繰り返してください。一回の計測にはウォームアップやシステム負荷の影響が含まれます。高いプリセットでも、すべての画像で結果がより小さくなるとは限りません。
メタデータの保持と削除
StripChunks.none() は、メタデータを削除しないよう要求します。ただし、すべてのチャンクをバイト単位で保持することとは異なります。Oxipng はカラータイプやビット深度の変更によって無効になったチャンクを削除することがあります。また、このスクリプトはファイルシステム上に新しいファイルを作成するため、ソースファイルのタイムスタンプやアクセス権はコピーしません。
StripChunks.safe() は、テキストコメントなど、描画に不要と判断されたメタデータを削除します。StripChunks.all() は、カラープロファイルやアニメーションチャンクも削除することがあります。これらの情報を保持する必要がある場合は、どちらにも置き換えないでください。ファイルが小さくなったことも、ピクセルバッファが一致することも、メタデータの保持を証明しません。アプリケーションが必要とする個々のフィールドを確認してください。
デコード後のピクセルの比較
以下を check_pixels.py として保存し、.venv/bin/python check_pixels.py input.png output.png を実行してください。静的な 8 ビット RGB/RGBA のソース PNG を対象に、寸法とデコード後の RGBA バイト列を比較します。完全に透明なピクセルの色値も比較に含みます。最適化後のファイルはパレットを使用する場合があるため、両方の画像を共通のモードにデコードしてから比較します。
import argparse
import sys
from PIL import Image
parser = argparse.ArgumentParser()
parser.add_argument("source")
parser.add_argument("output")
args = parser.parse_args()
try:
with Image.open(args.source) as before, Image.open(args.output) as after:
if before.format != "PNG" or after.format != "PNG":
raise ValueError("Both files must be PNGs")
if before.n_frames != 1 or after.n_frames != 1:
raise ValueError("This check covers static PNGs only")
if before.mode not in ("RGB", "RGBA"):
raise ValueError("Use an 8-bit RGB or RGBA source for this check")
if before.size != after.size or before.convert("RGBA").tobytes() != after.convert("RGBA").tobytes():
raise ValueError("Decoded pixels differ")
print("Decoded RGBA pixels match")
except (OSError, ValueError) as error:
sys.exit(f"Pixel check failed: {error}")
Pillow の tobytes() は、デコード済みのピクセルデータを返します。この比較では ICC プロファイルを適用せず、テキスト、EXIF、解像度、その他のメタデータも比較しません。記載のとおり、8 ビットのソースを指定してください。Pillow の RGB モードだけでは、元の PNG のビット深度は判断できません。
トラブルシューティング
| エラー | 対処 |
|---|---|
ModuleNotFoundError | プロジェクトの .venv/bin/python を使い、その環境でインストール手順を繰り返してください。 |
FileExistsError | 新しい保存先を選んでください。古い出力を手動で削除する前に、内容を確認してください。 |
FileNotFoundError | ソースと出力先の親ディレクトリを確認してください。 |
PngError | 入力が完全で有効な PNG であることを確認してください。 |
PermissionError | 読み取り可能なソースと、書き込み可能な出力ディレクトリを選んでください。 |
バッチが失敗しても、成功した出力が失敗分とともに残る場合があります。対象のファイル名は標準エラー出力で確認してください。終了ステータスはバッチの結果を示すものであり、ロールバックを意味しません。メモリ使用量が多すぎる場合は、ループを逐次処理のままにし、最適化レベルを上げる前に小さい画像でテストしてください。
マネージドサービスという選択肢
Transloadit が管理するアップロードワークフローについては、/image/optimize のドキュメントを参照し、ローカルスクリプトの設定とは別にメタデータポリシーを選んでください。
