/image-utils

name: image-utils
description: Classic image manipulation with Python Pillow - resize, crop, composite, format conversion, watermarks, brightness/contrast adjustments, and web optimization. Use this skill when post-processing AI-generated images, preparing images for web delivery, batch processing image directories, creating responsive image variants, or performing any deterministic pixel-level image operation. Works standalone or alongside bria-ai for post-processing generated images.
license: MIT
metadata:
  author: Bria AI
  version: "1.3.7"

Image Utilities

Pillow-based utilities for deterministic pixel-level image operations. Use for resize, crop, composite, format conversion, watermarks, and other standard image processing tasks.

When to Use This Skill

• **Post-processing AI-generated images**: Resize, crop, optimize for web after generation
• **Format conversion**: PNG ↔ JPEG ↔ WEBP with quality control
• **Compositing**: Overlay images, paste subjects onto backgrounds
• **Batch processing**: Resize to multiple sizes, add watermarks
• **Web optimization**: Compress and resize for fast delivery
• **Social media preparation**: Crop to platform-specific aspect ratios

When NOT to Use This Skill — Use `bria-ai` Instead

This skill handles **deterministic pixel-level operations** only. For any **generative or AI-powered** image work, use the `bria-ai` skill instead:

• **Generating images from text prompts** → use `bria-ai`
• **AI background removal or replacement** → use `bria-ai`
• **AI image editing (inpainting, object removal/addition)** → use `bria-ai`
• **Style transfer or AI-driven visual effects** → use `bria-ai`
• **Creating product lifestyle shots with AI** → use `bria-ai`
• **Image upscaling with AI super-resolution** → use `bria-ai`

**Rule of thumb**: If the task requires *creating new visual content* or *understanding image semantics*, use `bria-ai`. If the task requires *transforming existing pixels* (resize, crop, format convert, watermark), use this skill.

If `bria-ai` is not available, install it with:

npx skills add bria-ai/bria-skill

Quick Reference

| Operation | Method | Description | |-----------|--------|-------------| | **Loading** | `load(source)` | Load from URL, path, bytes, or base64 | | | `load_from_url(url)` | Download image from URL | | **Saving** | `save(image, path)` | Save with format auto-detection | | | `to_bytes(image, format)` | Convert to bytes | | | `to_base64(image, format)` | Convert to base64 string | | **Resizing** | `resize(image, width, height)` | Resize to exact dimensions | | | `scale(image, factor)` | Scale by factor (0.5 = half) | | | `thumbnail(image, size)` | Fit within size, maintain aspect | | **Cropping** | `crop(image, left, top, right, bottom)` | Crop to region | | | `crop_center(image, width, height)` | Crop from center | | | `crop_to_aspect(image, ratio)` | Crop to aspect ratio | | **Compositing** | `paste(bg, fg, position)` | Overlay at coordinates | | | `composite(bg, fg, mask)` | Alpha composite | | | `fit_to_canvas(image, w, h)` | Fit onto canvas size | | **Borders** | `add_border(image, width, color)` | Add solid border | | | `add_padding(image, padding)` | Add whitespace padding | | **Transforms** | `rotate(image, angle)` | Rotate by degrees | | | `flip_horizontal(image)` | Mirror horizontally | | | `flip_vertical(image)` | Flip vertically | | **Watermarks** | `add_text_watermark(image, text)` | Add text overlay | | | `add_image_watermark(image, logo)` | Add logo watermark | | **Adjustments** | `adjust_brightness(image, factor)` | Lighten/darken | | | `adjust_contrast(image, factor)` | Adjust contrast | | | `adjust_saturation(image, factor)` | Adjust color saturation | | | `blur(image, radius)` | Apply Gaussian blur | | **Web** | `optimize_for_web(image, max_size)` | Optimize for delivery | | **Info** | `get_info(image)` | Get dimensions, format, mode |

Requirements

pip install Pillow requests

Basic Usage

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']}")

Resizing & Scaling

# 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))

Cropping

# 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")

Compositing

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

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