image-utils

画像ユーティリティ

ピクセル単位の決定論的な画像処理を行う、Pillow ベースのユーティリティです。サイズ変更、トリミング、合成、形式変換、透かしの追加、その他の一般的な画像処理に使用できます。

このスキルを使用する場面

• AI 生成画像の後処理：生成後にサイズ変更、トリミング、Web 向けに最適化します
• 形式変換：品質を調整しながら、PNG ↔ JPEG ↔ WEBP に変換します
• 合成：画像を重ねたり、被写体を背景に貼り付けたりします
• バッチ処理：複数のサイズに変更したり、透かしを追加したりします
• Web 向け最適化：高速配信のために圧縮およびサイズ変更します
• ソーシャルメディア向けの準備：プラットフォーム固有のアスペクト比に合わせてトリミングします

このスキルを使用しない場面 — 代わりに bria-ai を使用

このスキルで扱うのは、決定論的なピクセル単位の処理のみです。生成または AI を活用した画像処理には、代わりに bria-ai スキルを使用してください。

• テキストプロンプトから画像を生成する → bria-ai を使用
• AI による背景の削除または置き換え → bria-ai を使用
• AI 画像編集（インペインティング、オブジェクトの削除・追加） → bria-ai を使用
• スタイル転送または AI による視覚効果 → bria-ai を使用
• AI で商品イメージ写真を作成する → bria-ai を使用
• AI 超解像による画像のアップスケーリング → bria-ai を使用

判断の目安：新しい視覚コンテンツの作成や画像の意味内容の理解が必要なタスクには、bria-ai を使用してください。既存のピクセルの変換（サイズ変更、トリミング、形式変換、透かしの追加）が必要なタスクには、このスキルを使用してください。

bria-ai が利用できない場合は、次のコマンドでインストールしてください。

npx skills add bria-ai/bria-skill

クイックリファレンス

操作	メソッド	説明
読み込み	load(source)	URL、パス、バイト列、または base64 から読み込みます
	load_from_url(url)	URL から画像をダウンロードします
保存	save(image, path)	形式を自動判別して保存します
	to_bytes(image, format)	バイト列に変換します
	to_base64(image, format)	base64 文字列に変換します
サイズ変更	resize(image, width, height)	指定した寸法にサイズを変更します
	scale(image, factor)	指定した倍率で拡大・縮小します（0.5 = 半分）
	thumbnail(image, size)	アスペクト比を保ちながら、指定サイズ内に収めます
トリミング	crop(image, left, top, right, bottom)	指定した領域にトリミングします
	crop_center(image, width, height)	中央からトリミングします
	crop_to_aspect(image, ratio)	指定したアスペクト比にトリミングします
合成	paste(bg, fg, position)	指定した座標に重ねます
	composite(bg, fg, mask)	アルファ合成します
	fit_to_canvas(image, w, h)	指定したキャンバスサイズに収めます
境界線	add_border(image, width, color)	単色の境界線を追加します
	add_padding(image, padding)	余白を追加します
変換	rotate(image, angle)	指定した角度で回転します
	flip_horizontal(image)	水平方向に反転します
	flip_vertical(image)	垂直方向に反転します
透かし	add_text_watermark(image, text)	テキストの透かしを重ねます
	add_image_watermark(image, logo)	ロゴの透かしを追加します
調整	adjust_brightness(image, factor)	明るさを調整します
	adjust_contrast(image, factor)	コントラストを調整します
	adjust_saturation(image, factor)	色の彩度を調整します
	blur(image, radius)	ガウスぼかしを適用します
Web	optimize_for_web(image, max_size)	配信用に最適化します
情報	get_info(image)	寸法、形式、モードを取得します

必要条件

pip install Pillow requests

基本的な使い方

from image_utils import ImageUtils

# Load from URL
image = ImageUtils.load_from_url("https://example.com/image.jpg")

# Or load from various sources
image = ImageUtils.load("/path/to/image.png")         # File path
image = ImageUtils.load(image_bytes)                  # Bytes
image = ImageUtils.load("data:image/png;base64,...")  # Base64

# Resize and save
resized = ImageUtils.resize(image, width=800, height=600)
ImageUtils.save(resized, "output.webp", quality=90)

# Get image info
info = ImageUtils.get_info(image)
print(f"{info['width']}x{info['height']} {info['mode']}")

サイズ変更と拡大・縮小

# Resize to exact dimensions
resized = ImageUtils.resize(image, width=800, height=600)

# Resize maintaining aspect ratio (fit within bounds)
fitted = ImageUtils.resize(image, width=800, height=600, maintain_aspect=True)

# Resize by width only (height auto-calculated)
resized = ImageUtils.resize(image, width=800)

# Scale by factor
half = ImageUtils.scale(image, 0.5)    # 50% size
double = ImageUtils.scale(image, 2.0)  # 200% size

# Create thumbnail
thumb = ImageUtils.thumbnail(image, (150, 150))

トリミング

# Crop to specific region
cropped = ImageUtils.crop(image, left=100, top=50, right=500, bottom=350)

# Crop from center
center = ImageUtils.crop_center(image, width=400, height=400)

# Crop to aspect ratio (for social media)
square = ImageUtils.crop_to_aspect(image, "1:1")      # Instagram
wide = ImageUtils.crop_to_aspect(image, "16:9")       # YouTube thumbnail
story = ImageUtils.crop_to_aspect(image, "9:16")      # Stories/Reels

# Control crop anchor
top_crop = ImageUtils.crop_to_aspect(image, "16:9", anchor="top")
bottom_crop = ImageUtils.crop_to_aspect(image, "16:9", anchor="bottom")

合成

# Paste foreground onto background
result = ImageUtils.paste(background, foreground, position=(100, 50))

# Alpha composite (foreground must have transparency)
result = ImageUtils.composite(background, foreground)

# Fit image onto canvas with letterboxing
canvas = ImageUtils.fit_to_canvas(
    image,
    width=1200,
    height=800,
    background_color=(255, 255, 255, 255),  # White
    position="center"  # or "top", "bottom"
)

形式変換

# Convert to different formats
png_bytes = ImageUtils.to_bytes(image, "PNG")
jpeg_bytes = ImageUtils.to_bytes(image, "JPEG", quality=85)
webp_bytes = ImageUtils.to_bytes(image, "WEBP", quality=90)

# Get base64 for data URLs
base64_str = ImageUtils.to_base64(image, "PNG")
data_url = ImageUtils.to_base64(image, "PNG", include_data_url=True)
# Returns: "data:image/png;base64,..."

# Save with format auto-detected from extension
ImageUtils.save(image, "output.png")
ImageUtils.save(image, "output.jpg", quality=85)
ImageUtils.save(image, "output.webp", quality=90)

透かし

# Text watermark
watermarked = ImageUtils.add_text_watermark(
    image,
    text="© 2024 My Company",
    position="bottom-right",  # bottom-left, top-right, top-left, center
    font_size=24,
    color=(255, 255, 255, 128),  # Semi-transparent white
    margin=20
)

# Logo/image watermark
logo = ImageUtils.load("logo.png")
watermarked = ImageUtils.add_image_watermark(
    image,
    watermark=logo,
    position="bottom-right",
    opacity=0.5,
    scale=0.15,  # 15% of image width
    margin=20
)

調整

# Brightness (1.0 = original, <1 darker, >1 lighter)
bright = ImageUtils.adjust_brightness(image, 1.3)
dark = ImageUtils.adjust_brightness(image, 0.7)

# Contrast (1.0 = original)
high_contrast = ImageUtils.adjust_contrast(image, 1.5)

# Saturation (0 = grayscale, 1.0 = original, >1 more vivid)
vivid = ImageUtils.adjust_saturation(image, 1.3)
grayscale = ImageUtils.adjust_saturation(image, 0)

# Sharpness
sharp = ImageUtils.adjust_sharpness(image, 2.0)

# Blur
blurred = ImageUtils.blur(image, radius=5)

変換

# Rotate (counter-clockwise, degrees)
rotated = ImageUtils.rotate(image, 45)
rotated = ImageUtils.rotate(image, 90, expand=False)  # Don't expand canvas

# Flip
mirrored = ImageUtils.flip_horizontal(image)
flipped = ImageUtils.flip_vertical(image)

境界線と余白

# Add solid border
bordered = ImageUtils.add_border(image, width=5, color=(0, 0, 0))

# Add padding (whitespace)
padded = ImageUtils.add_padding(image, padding=20)  # Uniform
padded = ImageUtils.add_padding(image, padding=(10, 20, 10, 20))  # left, top, right, bottom

Web 向け最適化

# Optimize for web delivery
optimized_bytes = ImageUtils.optimize_for_web(
    image,
    max_dimension=1920,  # Resize if larger
    format="WEBP",       # Best compression
    quality=85
)

# Save optimized
with open("optimized.webp", "wb") as f:
    f.write(optimized_bytes)

Bria AI との連携

AI 生成画像の後処理には、bria-ai スキル と併用してください。Bria の API で画像を生成または編集した後、image-utils を使ってサイズ変更、トリミング、透かしの追加、Web 向け最適化を行います。

import requests
from image_utils import ImageUtils

# Generate with Bria AI (see bria-ai skill for full API reference)
response = requests.post(
    "https://engine.prod.bria-api.com/v2/image/generate",
    headers={"api_token": BRIA_API_KEY, "Content-Type": "application/json"},
    json={"prompt": "product photo of headphones", "aspect_ratio": "1:1", "sync": True}
)
image_url = response.json()["result"]["image_url"]

# Download and post-process
image = ImageUtils.load_from_url(image_url)

# Create multiple sizes for responsive images
sizes = {
    "large": ImageUtils.resize(image, width=1200),
    "medium": ImageUtils.resize(image, width=600),
    "thumb": ImageUtils.thumbnail(image, (150, 150))
}

# Save all as optimized WebP
for name, img in sizes.items():
    ImageUtils.save(img, f"product_{name}.webp", quality=85)

バッチ処理の例

from pathlib import Path
from image_utils import ImageUtils

def process_catalog(input_dir, output_dir):
    """Process all images in a directory."""
    output_path = Path(output_dir)
    output_path.mkdir(exist_ok=True)

    for image_file in Path(input_dir).glob("*.{jpg,png,webp}"):
        image = ImageUtils.load(image_file)

        # Crop to square
        square = ImageUtils.crop_to_aspect(image, "1:1")

        # Resize to standard size
        resized = ImageUtils.resize(square, width=800, height=800)

        # Add watermark
        final = ImageUtils.add_text_watermark(resized, "© My Brand")

        # Save optimized
        output_file = output_path / f"{image_file.stem}.webp"
        ImageUtils.save(final, output_file, quality=85)

process_catalog("./raw_images", "./processed")

API リファレンス

docstring を含む完全な実装については、image_utils.py を参照してください。