Image Processing

Process images for web development using Pillow (Python). Resize, convert, trim, optimise, and composite — no ImageMagick or native dependencies required.

Prerequisites

Pillow is usually pre-installed. If not:

pip install Pillow

Commands

All commands use scripts/process-image.py. Each takes --output (-o) and optional --quality (-q).

Resize

Scale an image to specific dimensions or by width/height (maintains aspect ratio if only one given).

python3 plugins/design-assets/skills/image-processing/scripts/process-image.py \
  resize input.png -o resized.png --width 1920 --height 1080

# Width only — height calculated from aspect ratio
python3 .../process-image.py resize input.png -o resized.png -w 800

Convert Format

Convert between PNG, JPG, WebP. RGBA→JPG automatically composites onto white background.

python3 .../process-image.py convert logo.png -o logo.webp
python3 .../process-image.py convert photo.webp -o photo.jpg -q 90

Trim Whitespace

Auto-crop surrounding whitespace from logos and icons.

python3 .../process-image.py trim logo-with-padding.png -o logo-trimmed.png

Thumbnail

Create a thumbnail fitting within a max dimension (maintains aspect ratio).

python3 .../process-image.py thumbnail product.jpg -o thumb.jpg --size 300

Optimise for Web

Resize + compress in one step. Ideal for preparing uploaded images for production.

python3 .../process-image.py optimise hero.jpg -o hero.webp -w 1920 -q 85

OG Card

Generate a 1200×630 Open Graph card image with title and subtitle overlay.

# With background image
python3 .../process-image.py og-card \
  --background hero.jpg \
  --title "My Page Title" \
  --subtitle "A brief description" \
  -o og-image.png

# Solid colour background
python3 .../process-image.py og-card \
  --bg-color "#1a1a2e" \
  --title "My Page Title" \
  -o og-image.png

Common Workflows

Logo Cleanup (client-supplied JPG with white background)

# 1. Trim whitespace
python3 .../process-image.py trim client-logo.jpg -o logo-trimmed.png

# 2. Convert to PNG (for transparency on non-white backgrounds)
python3 .../process-image.py convert logo-trimmed.png -o logo.png

# 3. Create favicon-sized version
python3 .../process-image.py thumbnail logo.png -o favicon-source.png --size 512

Prepare Hero Image for Production

# Resize to max width, convert to WebP, compress
python3 .../process-image.py optimise uploaded-hero.jpg -o public/images/hero.webp -w 1920 -q 85

Batch Process (Multiple Images)

For batch operations, write a quick script rather than running commands one by one:

import subprocess, glob
for img in glob.glob("uploads/*.jpg"):
    name = img.rsplit("/", 1)[-1].replace(".jpg", ".webp")
    subprocess.run(["python3", ".../process-image.py", "optimise", img, "-o", f"public/images/{name}", "-w", "1200", "-q", "85"])

Pipeline with Gemini Image Gen

Generate → Process → Deploy:

# 1. Generate with Gemini
python3 plugins/design-assets/skills/gemini-image-gen/scripts/generate-image.py \
  --prompt "..." --output raw-hero.png --count 3

# 2. User picks favourite (e.g. raw-hero-2.png)

# 3. Optimise for web
python3 plugins/design-assets/skills/image-processing/scripts/process-image.py \
  optimise raw-hero-2.png -o public/images/hero.webp -w 1920 -q 85

Output Format Guide