画像処理

bin/ に含まれる img-process を一般的な操作に使用します。複雑またはカスタムワークフローの場合は、ユーザーの環境に適応した Pillow スクリプトを生成します。

クイックリファレンス — img-process CLI

img-process resize hero.png --width 1920
img-process convert logo.png --format webp
img-process trim logo-raw.jpg -o logo-clean.png --padding 10
img-process thumbnail photo.jpg --size 200
img-process optimise hero.jpg --quality 85 --max-width 1920
img-process og-card -o og.png --title "My App" --subtitle "Built for speed"
img-process batch ./images --action convert --format webp -o ./optimised

img-process を使う場合: 操作が標準的な場合（リサイズ、変換、トリミング、サムネイル、最適化、OG カード、バッチ処理）。毎回スクリプトを生成するより高速です。

カスタムスクリプトを生成する場合: img-process でカバーされていないロジックが必要な場合（複数画像の合成、ウォーターマーク、複雑なテキストレイアウト、条件付き処理）。

前提条件

Pillow は img-process とカスタムスクリプトの両方で必要です：

pip install Pillow

Pillow が利用できない場合は、以下の代替手段を使用してください：

代替手段	プラットフォーム	インストール	最適な用途
sips	macOS (ビルトイン)	なし	リサイズ、変換（トリミング/OG なし）
sharp	Node.js	npm install sharp	全機能、高パフォーマンス
ffmpeg	クロスプラットフォーム	brew install ffmpeg	リサイズ、変換

出力形式ガイド

ユースケース	形式	理由
写真、ヒーロー画像	WebP	最高の圧縮率、ブラウザサポートが広い
ロゴ、アイコン（透明度が必要）	PNG	ロスレス、アルファをサポート
古いブラウザ向けフォールバック	JPG	ユニバーサルサポート
サムネイル	WebP または JPG	ファイルサイズを優先
OG カード	PNG	ソーシャルプラットフォームが PNG を最適にサポート

コアパターン

形式固有の品質で保存

異なる形式は異なる保存パラメーターを必要とします。常に RGBA から JPG への合成を処理してください — JPG は透明度をサポートしないため、最初に白い背景に合成します。

from PIL import Image
import os

def save_image(img, output_path, quality=None):
    os.makedirs(os.path.dirname(output_path) or ".", exist_ok=True)
    kwargs = {}
    ext = output_path.lower().rsplit(".", 1)[-1]

    if ext == "webp":
        kwargs = {"quality": quality or 85, "method": 6}
    elif ext in ("jpg", "jpeg"):
        kwargs = {"quality": quality or 90, "optimize": True}
        # RGBA → RGB: 白い背景に合成
        if img.mode == "RGBA":
            bg = Image.new("RGB", img.size, (255, 255, 255))
            bg.paste(img, mask=img.split()[3])
            img = bg
    elif ext == "png":
        kwargs = {"optimize": True}

    img.save(output_path, **kwargs)

アスペクト比を保持してリサイズ

幅または高さのみが指定される場合、アスペクト比から他方を計算します。高品質なダウンスケーリングには Image.LANCZOS を使用します。

def resize_image(img, width=None, height=None):
    if width and height:
        return img.resize((width, height), Image.LANCZOS)
    elif width:
        ratio = width / img.width
        return img.resize((width, int(img.height * ratio)), Image.LANCZOS)
    elif height:
        ratio = height / img.height
        return img.resize((int(img.width * ratio), height), Image.LANCZOS)
    return img

空白をトリミング（自動クロップ）

ロゴとアイコンの周囲の空白を削除します。最初に RGBA に変換し、getbbox() を使用してコンテンツの境界を見つけます。

img = Image.open(input_path)
if img.mode != "RGBA":
    img = img.convert("RGBA")
bbox = img.getbbox()  # ゼロ以外のピクセルの境界ボックス
if bbox:
    img = img.crop(bbox)

サムネイル

アスペクト比を保持しながら最大寸法内に収まるように調整します：

img.thumbnail((size, size), Image.LANCZOS)

ウェブ用に最適化

リサイズと圧縮を1ステップで実行します。最高の圧縮率のために WebP に変換します。一般的な設定：幅 1920、品質 85。

クロスプラットフォームフォント検出

システムフォントパスは OS によって異なります。複数のパスを試行し、Pillow のデフォルトにフォールバックします。Linux では、fc-list でフォントを動的に検出できます。

from PIL import ImageFont

def get_font(size):
    font_paths = [
        # macOS
        "/System/Library/Fonts/Helvetica.ttc",
        "/System/Library/Fonts/SFNSText.ttf",
        # Linux
        "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
        "/usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf",
        # Windows
        "C:/Windows/Fonts/arial.ttf",
    ]
    for path in font_paths:
        if os.path.exists(path):
            try:
                return ImageFont.truetype(path, size)
            except Exception:
                continue
    return ImageFont.load_default()

OG カード生成（1200x630）

背景画像または単色の上にテキストを合成します。テキストの可読性のために半透明オーバーレイを適用します。テキストを水平方向の中央に配置します。

from PIL import Image, ImageDraw, ImageFont

width, height = 1200, 630

# 背景：画像または単色
if background_path:
    img = Image.open(background_path).resize((width, height), Image.LANCZOS)
else:
    img = Image.new("RGB", (width, height), bg_color or "#1a1a2e")

# テキスト可読性用の半透明オーバーレイ
overlay = Image.new("RGBA", (width, height), (0, 0, 0, 128))
img = img.convert("RGBA")
img = Image.alpha_composite(img, overlay)

draw = ImageDraw.Draw(img)
font_title = get_font(48)
font_sub = get_font(24)

# タイトルを中央に配置
if title:
    bbox = draw.textbbox((0, 0), title, font=font_title)
    tw = bbox[2] - bbox[0]
    draw.text(((width - tw) // 2, height // 2 - 60), title, fill="white", font=font_title)

img = img.convert("RGB")

一般的なワークフロー

ロゴのクリーンアップ（クライアント提供の白い背景付き JPG）

img-process trim logo-raw.jpg -o logo-trimmed.png --padding 10
img-process thumbnail logo-trimmed.png --size 512 -o favicon-512.png

本番用ヒーロー画像の準備

img-process optimise hero.jpg --max-width 1920 --quality 85
# 出力：hero.webp — リサイズおよび圧縮済み

バッチ処理

img-process batch ./raw-images --action convert --format webp --quality 85 -o ./optimised
img-process batch ./photos --action resize --width 800 -o ./thumbnails

Gemini Image Gen とのパイプライン

gemini-image-gen スキルで画像を生成してから処理します：

# Gemini で生成後（生の PNG 出力）:
img-process optimise generated-image.png --max-width 1920 --quality 85
# または生成されたすべての画像をバッチ処理:
img-process batch ./generated --action optimise -o ./production