image-forge

# Image Forge Pixel-precise image editing with three-tier routing: deterministic CLI tools for exact operations, AI models for semantic edits, vision models for analysis. ## Routing Decision **Use AI when the edit requires understanding what is in the image. Use ImageMagick when the edit requires knowing exactly what to do to the pixels.** ### Tier 1: Deterministic (magick, sips, transparent-background) Use for operations with exact, numeric parameters: | Task | Tool | Command | |------|------|---------| | Resize to exact dimensions | magick | `magick in.jpg -resize 800x600! out.jpg` | | Resize fit (preserve aspect) | magick | `magick in.jpg -resize 800x600 out.jpg` | | Resize fill + crop | magick | `magick in.jpg -resize 800x600^ -gravity center -extent 800x600 out.jpg` | | Resize shrink only | magick | `magick in.jpg -resize '800x600>' out.jpg` | | Crop at offset | magick | `magick in.jpg -crop 600x400+100+50 +repage out.jpg` | | Center crop | magick | `magick in.jpg -gravity center -crop 600x400+0+0 +repage out.jpg` | | Auto-trim whitespace | magick | `magick in.jpg -fuzz 10% -trim +repage out.jpg` | | Format convert | magick | `magick in.png -quality 85 out.jpg` | | Add text | magick | `magick in.jpg -fill white -pointsize 36 -annotate +10+50 'Text' out.jpg` | | Composite overlay | magick | `magick bg.png fg.png -geometry +50+100 -composite out.png` | | Watermark | magick | `magick photo.jpg wm.png -gravity SouthEast -geometry +10+10 -compose Dissolve -define compose:args=25 -composite out.jpg` | | Adjust brightness/contrast | magick | `magick in.jpg -brightness-contrast 10x20 out.jpg` | | Adjust saturation | magick | `magick in.jpg -modulate 100,130,100 out.jpg` | | Grayscale | magick | `magick in.jpg -colorspace Gray out.jpg` | | Sepia | magick | `magick in.jpg -sepia-tone 80% out.jpg` | | Blur | magick | `magick in.jpg -blur 0x3 out.jpg` | | Sharpen | magick | `magick in.jpg -sharpen 0x1 out.jpg` | | Remove background (AI) | transparent-background | See **Background Removal** section below | | Remove background (simple) | magick | `magick in.jpg -fuzz 15% -transparent white -trim +repage out.png` | | Strip metadata | magick | `magick in.jpg -strip out.jpg` | | Set DPI | magick | `magick in.jpg -density 300 out.jpg` | | Batch resize | `batch_ops.py` | `python3 scripts/batch_ops.py *.jpg --op resize --width 800 --output resized/` | | Montage/contact sheet | magick | `magick montage *.jpg -geometry 200x200+5+5 -tile 4x out.jpg` | | Quick format convert (macOS) | sips | `sips -s format jpeg in.png --out out.jpg` | | Quick resize (macOS) | sips | `sips -Z 800 in.jpg --out out.jpg` | ### Tier 2: AI Semantic (nano-banana-pro / Gemini) Delegate to the `nano-banana-pro` skill when the edit requires understanding image content: - Remove a person/object from a photo - Change sky, weather, time of day - Apply artistic style transfer - Inpaint/outpaint regions - Generate new image from scratch - Content-aware fill after object removal **Nano Banana regenerates, it does not edit.** Every call re-rolls the entire frame, even when the prompt asks to preserve regions verbatim. Expect ~40% of pixels to drift outside the target area — measured empirically, not hypothesized. For surgical regional edits (change the face, keep everything else identical), use the hybrid pattern in `references/compositing.md` § Surgical Regional Edits: let NB produce a drifted reference, then composite only the target region onto the pristine original with a feathered alpha mask. Nano Banana also supports only discrete aspect ratios (1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9). For inputs at other ratios (e.g. 3:1 panoramics), see `references/recipes.md` § Aspect Ratio Padding for the pad-generate-crop recipe. ### Tier 3: Vision Analysis (Claude Read tool) Use the Read tool to inspect images before/after edits: - Verify an edit succeeded - Describe image contents - Check composition and framing - Identify colors, objects, text in image ## Background Removal Use `transparent-background` (InSPyReNet model) for AI background removal. It produces clean alpha mattes with smooth anti-aliased edges — far superior to ImageMagick's `-transparent`/`-fuzz` approach, which leaves white fringing in concave regions and jagged edges. **When to use each:** | Method | When | Quality | |--------|------|---------| | `transparent-background` | Any photo/render with complex foreground (hair, translucent edges, concave regions) | Smooth alpha, no fringing | | `magick -transparent white -fuzz N%` | Simple shapes on pure white, quick-and-dirty | Fast but aliased edges, misses interior white | | `magick floodfill` | Remove background from corners only, preserve interior white | Only hits connected regions | **Python API (recommended):** ```python 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") ``` **With trim (most common workflow):** ```bash 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 ``` **Install:** `uv pip install --system transparent-background` **Performance:** ~2-3s per image on Apple Silicon (MPS). First run downloads the InSPyReNet model (~170MB). **Note:** `rembg` is an alternative but has a broken `gradio` dependency as of May 2026. `transparent-background` is the more reliable option. ## Scripts All scripts are in `~/.claude/skills/image-forge/scripts/`. Run with `python3`. ### image_info.py — Inspect Image Metadata ```bash 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 ``` Returns clean JSON: dimensions, format, color space, depth, alpha, DPI, ICC profile, EXIF. ### image_pipeline.py — Declarative Edit Pipeline Write a JSON spec, get a single chained `magick` command. No intermediate files. ```bash # 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 ``` **Available operations:** | Op | Parameters | |----|-----------| | `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 = no change) | | `brightness_contrast` | `brightness`, `contrast` | | `levels` | `black`, `white`, `gamma` | | `gamma` | `value` | | `sigmoidal_contrast` | `strength`, `midpoint` | | `colorize` | `color`, `amount` (%) | | `sepia` | `threshold` (%) | | `grayscale` | (none) | | `negate` | (none) | | `auto_level` | (none) | | `normalize` | (none) | | `auto_orient` | (none) | | `flip` / `flop` | (none) | | `border` | `color`, `size` | | `extent` | `width`, `height`, `background`, `gravity` | | `shadow` | `opacity`, `sigma`, `x`, `y` | | `transparent` | `color`, `fuzz` (%) | | `alpha_remove` | `background` | | `alpha_set` | (none) | | `quality` | `value` (1-100) | | `strip` | (none) | | `density` | `value` (DPI) | | `draw` | `primitive`, `fill`, `stroke`, `strokewidth` | | `raw` | `args` (string or array of raw magick args) | ### smart_crop.py — Gravity-Based Smart Crop ```bash 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 ``` Gravities: `center`, `north`, `south`, `east`, `west`, `northwest`, `northeast`, `southwest`, `southeast`. ### batch_ops.py — Parallel Batch Processing ```bash 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/ ``` Operations: `resize`, `thumbnail`, `format`, `strip`, `auto_orient`, `watermark`, `crop`. ### montage_builder.py — Contact Sheets ```bash 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 ``` ## Quick Recipes ### Social Media Crops ```bash # 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 ``` ### Watermark