domains / design / batch-image-conversion / image-processing

image-processing

Skill card

combined

The two skills cover overlapping ground (Pillow-based image processing) but serve different primary workflows. The first skill (jezweb) focuses on a CLI tool (`img-process`) for individual operations like resizing, trimming, and generating OG cards, providing specific Python patterns for these tasks. The second skill (aipoch) focuses on a batch directory conversion script (`convert_images.py`) with specific flags for recursion, overwriting, and error handling, emphasizing a CI/automation pipeline. Neither is a strict reproduction of the other; the first lacks the batch directory logic and error-handling contract of the second, while the second lacks the specific utility commands (trim, OG card) and code patterns of the first. Combining them provides a complete toolkit for both single-file manipulation and batch directory processing.

Repositories

Other copies

Combined skill

---
name: image-processing
description: "Process images for web development and batch conversion. Supports single-file operations (resize, trim, OG cards) via CLI or custom scripts, and batch directory conversion via Python. Uses Pillow."
---

# Image Processing

This skill covers two main workflows:
1. **Single-File Operations**: Resize, crop, trim, convert, and generate OG cards using the `img-process` CLI or custom Pillow scripts.
2. **Batch Directory Conversion**: Convert entire directories of images to a target format with error handling and structure preservation.

## Prerequisites

```bash
pip install Pillow
```

## Workflow 1: Single-File Operations

Use the `img-process` CLI for standard tasks. For complex logic (compositing, watermarks), write a custom Pillow script.

### CLI Examples

```bash
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 og-card -o og.png --title "My App"
```

### Custom Script Patterns

**Save with Format-Specific Quality:**
```python
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}
        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)
```

**Trim Whitespace:**
```python
img = Image.open(input_path)
if img.mode != "RGBA":
    img = img.convert("RGBA")
bbox = img.getbbox()
if bbox:
    img = img.crop(bbox)
```

## Workflow 2: Batch Directory Conversion

Use `scripts/convert_images.py` for batch processing. This script preserves directory structure and handles errors gracefully.

### Usage

```bash
# Install dependencies if using the aipoch script structure
pip install -r scripts/requirements.txt

# Convert all images in <src> to WebP
python scripts/convert_images.py \
  --source-dir "<src>" \
  --output-dir "<out>" \
  --format webp \
  --quality 80 \
  --recursive \
  --overwrite
```

### Batch Behavior
- **Error Handling**: Continues processing remaining files if some fail; summarizes errors at the end.
- **Structure**: Preserves relative paths from source to output.
- **Formats**: 
  - WebP: `method=6`.
  - JPG: RGB mode, progressive output.
  - PNG: Compression level derived from quality.

## Output Format Guide

| Use case | Format | Why |
|----------|--------|-----|
| Photos, hero images | WebP | Best compression |
| Logos, icons | PNG | Lossless, alpha support |
| Fallback | JPG | Universal support |
| OG cards | PNG | Social platform compatibility |