image-fit

name	image_fit
description	Fit images into specific dimensions with fit, fill, or stretch modes. Supports auto-trimming borders and adding margins. Use this skill when the user needs to fit images into exact dimensions.

Image Fit

This skill provides utilities to fit images into specific dimensions using different modes: fit (preserve aspect ratio), fill (crop to exact size), or stretch (ignore aspect ratio).

Usage

uv run python .claude/skills/image_fit/fit.py <image_path> [options]

Note: For brevity, examples below use fit.py - prepend the full path .claude/skills/image_fit/ when running.

The script will:

1. Open the specified image file
2. Detect background type from corners (transparent or white)
3. Auto-trim borders when margin is requested with detected background
4. Fit the image into target dimensions using specified mode
5. Add margin with appropriate background color (transparent for RGBA images)
6. Save the result with mode and dimensions in filename

Options

• -w, --width - Target width in pixels (required)
• --height - Target height in pixels (required)
• -m, --mode - Fit mode (default: "fit")
  • fit: Preserve aspect ratio, fit within bounds (may be smaller)
  • fill: Crop to fill exact dimensions (preserves aspect ratio)
  • stretch: Ignore aspect ratio, stretch to exact dimensions
• --trim - Auto-crop transparent/white borders before fitting
• --margin - Add margin (in pixels) around the fitted image (default: 0)
• --no-center - Disable centering (place at top-left with margin offset instead). Centering is enabled by default.
• -q, --quality - JPEG quality (1-100, default: 95)

Supported Formats

• Input: Any format supported by PIL/Pillow (JPG, PNG, BMP, GIF, WEBP, etc.)
• Output: Same format as input

Examples

# Fit within 800x600 box, preserve aspect ratio
fit.py image.jpg --width 800 --height 600

# Fill exact 800x600, crop to fit (preserves aspect ratio)
fit.py image.jpg --width 800 --height 600 --mode fill

# Stretch to exact 800x600, ignore aspect ratio (may distort)
fit.py image.jpg --width 800 --height 600 --mode stretch

# Trim borders then fit
fit.py image.jpg --width 800 --height 600 --trim

# Add 8px margin - auto-detects background and trims first
fit.py dragon.png --width 1024 --height 1024 --margin 8

# Add 20px margin around fitted image
fit.py image.jpg --width 800 --height 600 --margin 20

# Trim, fill to 48x48, with quality setting
fit.py icon.png --width 48 --height 48 --mode fill --quality 90

Notes

• Auto Background Detection: The script checks corner pixels to detect if the image has transparent or white background. When margin is requested with detected background, it automatically trims first, then scales content, then adds the margin.
• Fit Mode (default): Preserves aspect ratio. Result fits within target dimensions but may be smaller.
• Fill Mode: Automatically trims, then scales and crops to fill exact dimensions. Perfect for creating icons and thumbnails.
• Stretch Mode: Ignores aspect ratio and stretches to exact dimensions. May distort the image.
• Trim: Auto-crops transparent or white borders before fitting. Automatically enabled in fill mode and when margin is used with detected background.
• Margin: Adds padding around the final image. Uses transparent background for RGBA images, preserving transparency. Applied after fitting.
• Centering (default: on): Automatically centers the fitted image within the target dimensions. Use --no-center to place at top-left instead.
• Quality: Only affects JPEG output. Higher values = better quality but larger file size.
• Output Naming: Files are named original_MODE_WIDTHxHEIGHT.ext (e.g., photo_fit_800x600.jpg)

Use Cases

• Creating thumbnails with exact dimensions
• Preparing images for social media (specific size requirements)
• Fitting images into fixed-size containers
• Creating icons from images with padding
• Batch processing images to uniform sizes

Requirements

• Python 3.x
• Pillow (PIL) library

The script will automatically install Pillow if it's not available.