image-forge

Image Forge

3 段階のルーティングによる、ピクセル単位で正確な画像編集です。厳密な操作には決定論的な CLI ツール、意味的な編集には AI モデル、分析にはビジョンモデルを使用します。

ルーティングの判断

画像に何が写っているかを理解する必要がある編集には AI を使用します。ピクセルに対して何をするかを正確に指定する必要がある編集には ImageMagick を使用します。

Tier 1：決定論的（magick、sips、transparent-background）

正確な数値パラメーターを指定する操作に使用します。

タスク	ツール	コマンド
正確なサイズにリサイズ	magick	magick in.jpg -resize 800x600! out.jpg
アスペクト比を維持してリサイズ	magick	magick in.jpg -resize 800x600 out.jpg
リサイズして塗りつぶし、トリミング	magick	magick in.jpg -resize 800x600^ -gravity center -extent 800x600 out.jpg
縮小のみリサイズ	magick	magick in.jpg -resize '800x600>' out.jpg
オフセットを指定してトリミング	magick	magick in.jpg -crop 600x400+100+50 +repage out.jpg
中央をトリミング	magick	magick in.jpg -gravity center -crop 600x400+0+0 +repage out.jpg
余白を自動トリミング	magick	magick in.jpg -fuzz 10% -trim +repage out.jpg
フォーマット変換	magick	magick in.png -quality 85 out.jpg
テキストを追加	magick	magick in.jpg -fill white -pointsize 36 -annotate +10+50 'Text' out.jpg
オーバーレイを合成	magick	magick bg.png fg.png -geometry +50+100 -composite out.png
透かし	magick	magick photo.jpg wm.png -gravity SouthEast -geometry +10+10 -compose Dissolve -define compose:args=25 -composite out.jpg
明るさ／コントラストを調整	magick	magick in.jpg -brightness-contrast 10x20 out.jpg
彩度を調整	magick	magick in.jpg -modulate 100,130,100 out.jpg
グレースケール	magick	magick in.jpg -colorspace Gray out.jpg
セピア	magick	magick in.jpg -sepia-tone 80% out.jpg
ぼかし	magick	magick in.jpg -blur 0x3 out.jpg
シャープ化	magick	magick in.jpg -sharpen 0x1 out.jpg
背景を削除（AI）	transparent-background	下記の背景の削除セクションを参照
背景を削除（シンプルな方法）	magick	magick in.jpg -fuzz 15% -transparent white -trim +repage out.png
メタデータを削除	magick	magick in.jpg -strip out.jpg
DPI を設定	magick	magick in.jpg -density 300 out.jpg
一括リサイズ	batch_ops.py	python3 scripts/batch_ops.py *.jpg --op resize --width 800 --output resized/
モンタージュ／コンタクトシート	magick	magick montage *.jpg -geometry 200x200+5+5 -tile 4x out.jpg
フォーマットをすばやく変換（macOS）	sips	sips -s format jpeg in.png --out out.jpg
すばやくリサイズ（macOS）	sips	sips -Z 800 in.jpg --out out.jpg

Tier 2：AI による意味的な編集（nano-banana-pro / Gemini）

画像の内容を理解する必要がある編集では、nano-banana-pro スキルに委任します。

• 写真から人物や物体を削除する
• 空、天候、時刻を変更する
• 芸術的なスタイル変換を適用する
• 領域をインペイント／アウトペイントする
• 画像をゼロから生成する
• 物体を削除した後、コンテンツに応じて塗りつぶす

**Nano Banana は画像を編集するのではなく、再生成します。**領域をそのまま保持するようプロンプトで指示しても、呼び出すたびにフレーム全体が再生成されます。対象領域外のピクセルの約 40% が変化すると想定してください。これは仮説ではなく、実測値です（経験的に測定）。顔を変更し、ほかの部分はすべて同一に保つような外科手術のように限定的な領域編集には、references/compositing.md § 外科手術のように限定的な領域編集に記載されたハイブリッド手法を使用します。NB に変化した参照画像を生成させた後、フェザー処理したアルファマスクを使って、対象領域だけを元の未加工画像に合成します。

Nano Banana が対応するアスペクト比は、限られた選択肢（1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9）のみです。それ以外の比率の入力（例：3:1 のパノラマ）については、パディング、生成、トリミングの手順を記載した references/recipes.md § アスペクト比のパディングを参照してください。

Tier 3：ビジョン分析（Claude Read ツール）

編集前後の画像を調べるには Read ツールを使用します。

• 編集が成功したか確認する
• 画像の内容を説明する
• 構図とフレーミングを確認する
• 画像内の色、物体、テキストを特定する

背景の削除

AI による背景の削除には transparent-background（InSPyReNet モデル）を使用します。滑らかでアンチエイリアス処理されたエッジを持つ、きれいなアルファマットを生成します。凹んだ領域に白い縁が残り、エッジがギザギザになる ImageMagick の -transparent／-fuzz を使う方法よりもはるかに優れています。

使い分け：

方法	用途	品質
transparent-background	複雑な前景（髪、半透明のエッジ、凹んだ領域）がある写真やレンダリング画像全般	滑らかなアルファ、縁なし
magick -transparent white -fuzz N%	真っ白な背景上の単純な形状を手早く処理する場合	高速ですがエッジにエイリアスが生じ、内部の白色部分を見逃します
magick floodfill	内部の白色部分を残したまま、隅の背景だけを削除する場合	連結した領域のみを処理します

Python API（推奨）：

from transparent_background import Remover
from PIL import Image

remover = Remover()
img = Image.open("input.jpg").convert("RGB")
out = remover.process(img, type="rgba")
out.save("output.png")

トリミングとの併用（最も一般的なワークフロー）：

python3 -c "
from transparent_background import Remover
from PIL import Image
remover = Remover()
img = Image.open('input.jpg').convert('RGB')
remover.process(img, type='rgba').save('/tmp/nobg.png')
"
magick /tmp/nobg.png -trim +repage output.png

インストール： uv pip install --system transparent-background

パフォーマンス： Apple Silicon（MPS）では画像 1 枚あたり約 2～3 秒です。初回実行時に InSPyReNet モデル（約 170MB）がダウンロードされます。

注： rembg は代替手段ですが、2026 年 5 月現在、gradio の依存関係に不具合があります。transparent-background のほうが信頼性の高い選択肢です。

スクリプト

すべてのスクリプトは ~/.claude/skills/image-forge/scripts/ にあります。python3 で実行してください。

image_info.py — 画像メタデータの確認

python3 ~/.claude/skills/image-forge/scripts/image_info.py photo.jpg
python3 ~/.claude/skills/image-forge/scripts/image_info.py photo.jpg --field dimensions
python3 ~/.claude/skills/image-forge/scripts/image_info.py photo.jpg --field width

寸法、形式、色空間、ビット深度、アルファ、DPI、ICC プロファイル、EXIF を含む、整った JSON を返します。

image_pipeline.py — 宣言型編集パイプライン

JSON 仕様を記述すると、連結された単一の magick コマンドを生成します。中間ファイルは作成されません。

# Create spec
cat > /tmp/pipeline.json << 'EOF'
{
    "input": "photo.jpg",
    "output": "result.png",
    "steps": [
        {"op": "resize", "width": 800, "height": 600, "mode": "fill"},
        {"op": "brightness_contrast", "brightness": 5, "contrast": 10},
        {"op": "annotate", "text": "Title", "gravity": "South", "pointsize": 36, "fill": "white", "stroke": "black", "strokewidth": 2},
        {"op": "composite", "overlay": "watermark.png", "gravity": "SouthEast", "opacity": 25},
        {"op": "quality", "value": 90},
        {"op": "strip"}
    ]
}
EOF

# Dry run (print command)
python3 ~/.claude/skills/image-forge/scripts/image_pipeline.py /tmp/pipeline.json --dry-run

# Execute
python3 ~/.claude/skills/image-forge/scripts/image_pipeline.py /tmp/pipeline.json

利用可能な操作：

操作	パラメーター
resize	width、height、mode（fit/fill/exact/shrink/enlarge/percent）、filter
crop	w／width、h／height、x、y、gravity
trim	fuzz（%）
annotate	text、font、pointsize、fill、stroke、strokewidth、gravity、x、y
composite	overlay、gravity、x、y、opacity、compose、resize
rotate	angle、background
blur	sigma、radius
sharpen	sigma、radius
unsharp	sigma、radius、amount、threshold
modulate	brightness、saturation、hue（100 = 変更なし）
brightness_contrast	brightness、contrast
levels	black、white、gamma
gamma	value
sigmoidal_contrast	strength、midpoint
colorize	color、amount（%）
sepia	threshold（%）
grayscale	（なし）
negate	（なし）
auto_level	（なし）
normalize	（なし）
auto_orient	（なし）
flip／flop	（なし）
border	color、size
extent	width、height、background、gravity
shadow	opacity、sigma、x、y
transparent	color、fuzz（%）
alpha_remove	background
alpha_set	（なし）
quality	value（1～100）
strip	（なし）
density	value（DPI）
draw	primitive、fill、stroke、strokewidth
raw	args（生の magick 引数の文字列または配列）

smart_crop.py — 重心に基づくスマートクロップ

python3 ~/.claude/skills/image-forge/scripts/smart_crop.py photo.jpg --target 800x600
python3 ~/.claude/skills/image-forge/scripts/smart_crop.py photo.jpg --target 800x600 --gravity north
python3 ~/.claude/skills/image-forge/scripts/smart_crop.py photo.jpg --target 1080x1080 --output cropped/
python3 ~/.claude/skills/image-forge/scripts/smart_crop.py photo.jpg --target 800x600 --dry-run

重心：center、north、south、east、west、northwest、northeast、southwest、southeast。

batch_ops.py — 並列バッチ処理

python3 ~/.claude/skills/image-forge/scripts/batch_ops.py *.jpg --op resize --width 800 --output resized/
python3 ~/.claude/skills/image-forge/scripts/batch_ops.py *.png --op format --to jpg --quality 85 --output converted/
python3 ~/.claude/skills/image-forge/scripts/batch_ops.py *.jpg --op thumbnail --width 200 --height 200 --output thumbs/
python3 ~/.claude/skills/image-forge/scripts/batch_ops.py *.jpg --op strip --output clean/
python3 ~/.claude/skills/image-forge/scripts/batch_ops.py *.jpg --op watermark --overlay wm.png --opacity 25 --output marked/
python3 ~/.claude/skills/image-forge/scripts/batch_ops.py *.jpg --op resize --width 800 --parallel 8 --output resized/

操作：resize、thumbnail、format、strip、auto_orient、watermark、crop。

montage_builder.py — コンタクトシート

python3 ~/.claude/skills/image-forge/scripts/montage_builder.py *.jpg --output contact.jpg
python3 ~/.claude/skills/image-forge/scripts/montage_builder.py *.jpg --cols 3 --thumb 300x300 --label --output grid.jpg
python3 ~/.claude/skills/image-forge/scripts/montage_builder.py *.jpg --background '#1a1a2e' --border 2 --output dark_grid.jpg

すぐに使えるレシピ

ソーシャルメディア向けクロップ

# Instagram square
magick in.jpg -resize 1080x1080^ -gravity center -extent 1080x1080 instagram.jpg

# Instagram story
magick in.jpg -resize 1080x1920^ -gravity center -extent 1080x1920 story.jpg

# Twitter/X header
magick in.jpg -resize 1500x500^ -gravity center -extent 1500x500 header.jpg

# OG image
magick in.jpg -resize 1200x630^ -gravity center -extent 1200x630 og.jpg

透かし

# Text watermark
magick photo.jpg -fill 'rgba(255,255,255,0.3)' -gravity SouthEast \
  -font Helvetica -pointsize 24 -annotate +10+10 '© 2026' out.jpg

# Image watermark at 25%
magick photo.jpg wm.png -gravity SouthEast -geometry +10+10 \
  -compose Dissolve -define compose:args=25 -composite out.jpg

枠線とシャドウ

# Solid border
magick in.jpg -bordercolor '#333' -border 10 out.jpg

# Drop shadow
magick in.png \( +clone -background black -shadow 60x5+5+5 \) \
  +swap -background none -layers merge +repage shadow.png

色の効果

# Vintage
magick in.jpg -modulate 105,80,100 -fill '#704214' -colorize 15% \
  -sigmoidal-contrast 3x60% vintage.jpg

# High contrast B&W
magick in.jpg -colorspace Gray -sigmoidal-contrast 10x50% bw.jpg

ジオメトリ構文のクイックリファレンス

構文	意味
800x600	アスペクト比を維持して、ボックス内に収めます
800x600!	正確なサイズに強制します（歪みます）
800x600>	元画像のほうが大きい場合のみ縮小します
800x600<	元画像のほうが小さい場合のみ拡大します
800x600^	ボックスを埋めます（最小寸法を一致させます）
50%	パーセンテージで拡大・縮小します
+X+Y	重心アンカーからのオフセット

シェルでのエスケープ：>、<、^ を含むジオメトリは引用符で囲みます。

magick in.jpg -resize '800x600>' out.jpg

重要な注意事項

1. -cropの後は必ず+repageを実行してください — これを実行しないと、仮想キャンバスのオフセットが保持されます
2. -modulateの順序はB、S、Hです — 明るさ、彩度、色相です（H、S、Lではありません）
3. 設定は保持され、オペレーターは直ちに実行されます — magickコマンドでは順序が重要です
4. 背景の削除にはrembgを使用してください — rembg i input.jpg output.png（アルファマッティングを追加するには-aを指定します）
5. ジオメトリは引用符で囲んでください — >、<、^はシェルのメタ文字です
6. IM7では-alpha offは永続的です — 一時的に切り替えるには-alpha deactivate/-alpha activateを使用してください
7. 編集前に確認してください — まずimage_info.pyを実行し、寸法、形式、アルファ状態を確認してください
8. 複数ステップの処理にはパイプラインを使用してください — シェルコマンドを連結する代わりにimage_pipeline.pyを使用してください
9. Nano Bananaはフレーム全体を変化させます — NBが領域を変更せずに保持すると決して信頼しないでください。領域編集には、外科的合成パターンを使用してください（compositing.md § 外科的な領域編集を参照）。magick compare -metric AE -fuzz 5% before after diff.pngで検証してください — AEが低ければ問題なく、約40%以上なら全体が再生成されています。

参考資料

詳細な参考資料は~/.claude/skills/image-forge/references/にあります。

• magick-reference.md — ImageMagick 7のコマンド完全リファレンス（リサイズ、クロップ、色、テキスト、描画、バッチ、identify）
• compositing.md — すべての合成オペレーター（Duff-Porter、数学的、ライティング、HSL、特殊）
• recipes.md — 30以上のレシピ（枠線、影、透かし、ソーシャルメディア向けサイズ、色効果、スプライト、バッチパターン）

依存関係

ツール	バージョン	インストール
ImageMagick	7.1.2-7 (Q16-HDRI)	brew install imagemagick
rembg	2.0.72	uv pip install rembg
sips	macOS標準搭載	—
Pillow	10.4.0	uv pip install Pillow