imagemagick✓ Pass

SKILL.md Content

---
name: imagemagick
description: Guide for using ImageMagick command-line tools to perform advanced image processing tasks including format conversion, resizing, cropping, effects, transformations, and batch operations. Use when manipulating images programmatically via shell commands.
license: MIT
version: 1.0.0
---

# ImageMagick Skill

ImageMagick is a comprehensive, free, open-source software suite for creating, editing, converting, and manipulating images in over 250 formats. This skill covers command-line usage of ImageMagick tools for programmatic image processing.

## When to Use This Skill

Use this skill when:
- Converting images between formats (PNG, JPEG, WebP, GIF, etc.)
- Resizing, cropping, or transforming images
- Applying effects, filters, or adjustments to images
- Creating thumbnails or image previews
- Batch processing multiple images
- Compositing or combining images
- Adding watermarks, borders, or text to images
- Optimizing images for web or print

## Core Concepts

### Primary Commands

ImageMagick provides several command-line tools:

- **magick**: Modern unified command for all operations (ImageMagick v7+)
- **convert**: Legacy command for image conversion and manipulation (still widely used)
- **mogrify**: Modify images in-place (batch processing)
- **identify**: Display image metadata and properties
- **montage**: Create image composites and contact sheets
- **composite**: Overlay images

**Note**: In ImageMagick v7+, `magick` is the recommended command. Legacy `convert` syntax: `convert input.png output.jpg` becomes `magick input.png output.jpg`

### Command Structure

Basic syntax:
```bash
magick [input-options] input-file [operations] [output-options] output-file
```

Operations are applied **left to right** in the order specified.

### Geometry Specifications

ImageMagick uses geometry strings for dimensions:

- `100x100` - Resize to fit within 100×100 (maintains aspect ratio)
- `100x100!` - Force exact size (ignores aspect ratio)
- `100x100^` - Fill 100×100 (may crop, maintains aspect ratio)
- `100x` - Resize to width 100 (auto height)
- `x100` - Resize to height 100 (auto width)
- `50%` - Scale to 50% of original
- `100x100+10+20` - 100×100 region at offset (10, 20)

## Installation

**macOS:**
```bash
brew install imagemagick
```

**Ubuntu/Debian:**
```bash
sudo apt-get install imagemagick
```

**Verify installation:**
```bash
magick -version
# or
convert -version
```

## Common Operations

### Format Conversion

Convert between image formats:

```bash
# PNG to JPEG
magick input.png output.jpg

# JPEG to WebP
magick input.jpg output.webp

# Multiple formats
magick input.png output.jpg output.webp output.gif

# Set JPEG quality (0-100)
magick input.png -quality 85 output.jpg

# Convert with compression
magick input.png -quality 90 -strip output.jpg
```

### Resizing

Resize images while maintaining aspect ratio:

```bash
# Resize to fit within 800×600
magick input.jpg -resize 800x600 output.jpg

# Resize to specific width (auto height)
magick input.jpg -resize 800x output.jpg

# Resize to specific height (auto width)
magick input.jpg -resize x600 output.jpg

# Resize to exact dimensions (ignores aspect ratio)
magick input.jpg -resize 800x600! output.jpg

# Scale by percentage
magick input.jpg -resize 50% output.jpg

# Resize only if larger (shrink only)
magick input.jpg -resize 800x600\> output.jpg

# Resize only if smaller (enlarge only)
magick input.jpg -resize 800x600\< output.jpg
```

### Cropping

Extract portions of images:

```bash
# Crop 400×400 pixels starting at (100, 100)
magick input.jpg -crop 400x400+100+100 output.jpg

# Crop from center
magick input.jpg -gravity center -crop 400x400+0+0 output.jpg

# Remove virtual canvas after crop
magick input.jpg -crop 400x400+100+100 +repage output.jpg

# Crop to aspect ratio from center
magick input.jpg -gravity center -crop 16:9 output.jpg
```

### Resize + Crop (Thumbnail Generation)

Common pattern for creating square thumbnails:

```bash
# Resize to fill 100×100, then crop from center
magick input.jpg -resize 100x100^ -gravity center -extent 100x100 output.jpg

# Alternative using crop
magick input.jpg -resize 275x275^ -gravity center -crop 275x275+0+0 +repage output.jpg

# Create thumbnail with specific background
magick input.jpg -resize 100x100 -background white -gravity center -extent 100x100 output.jpg
```

### Effects and Filters

Apply visual effects:

```bash
# Blur
magick input.jpg -blur 0x8 output.jpg

# Gaussian blur with radius 5, sigma 3
magick input.jpg -gaussian-blur 5x3 output.jpg

# Sharpen
magick input.jpg -sharpen 0x1 output.jpg

# Grayscale
magick input.jpg -colorspace Gray output.jpg

# Sepia tone
magick input.jpg -sepia-tone 80% output.jpg

# Negate (invert colors)
magick input.jpg -negate output.jpg

# Edge detection
magick input.jpg -edge 3 output.jpg

# Emboss
magick input.jpg -emboss 2 output.jpg

# Oil painting effect
magick input.jpg -paint 4 output.jpg

# Charcoal drawing
magick input.jpg -charcoal 2 output.jpg
```

### Adjustments

Modify brightness, contrast, and colors:

```bash
# Adjust brightness (+/- 0-100)
magick input.jpg -brightness-contrast 10x0 output.jpg

# Adjust contrast
magick input.jpg -brightness-contrast 0x20 output.jpg

# Both brightness and contrast
magick input.jpg -brightness-contrast 10x20 output.jpg

# Adjust saturation
magick input.jpg -modulate 100,150,100 output.jpg

# Adjust hue
magick input.jpg -modulate 100,100,120 output.jpg

# Auto level (normalize contrast)
magick input.jpg -auto-level output.jpg

# Auto gamma correction
magick input.jpg -auto-gamma output.jpg

# Normalize (stretch histogram)
magick input.jpg -normalize output.jpg
```

### Rotation and Flipping

Transform image orientation:

```bash
# Rotate 90 degrees clockwise
magick input.jpg -rotate 90 output.jpg

# Rotate 180 degrees
magick input.jpg -rotate 180 output.jpg

# Rotate counter-clockwise
magick input.jpg -rotate -90 output.jpg

# Rotate with background color
magick input.jpg -background white -rotate 45 output.jpg

# Flip vertically
magick input.jpg -flip output.jpg

# Flip horizontally (mirror)
magick input.jpg -flop output.jpg

# Auto-orient based on EXIF
magick input.jpg -auto-orient output.jpg
```

### Borders and Frames

Add borders to images:

```bash
# Add 10px black border
magick input.jpg -border 10x10 output.jpg

# Add border with specific color
magick input.jpg -bordercolor red -border 10x10 output.jpg

# Add frame effect
magick input.jpg -mattecolor gray -frame 10x10+5+5 output.jpg

# Add shadow effect
magick input.jpg \( +clone -background black -shadow 80x3+5+5 \) \
  +swap -background white -layers merge +repage output.jpg
```

### Text and Watermarks

Add text overlays:

```bash
# Add simple text
magick input.jpg -pointsize 30 -fill white -annotate +10+30 "Hello" output.jpg

# Add text with positioning
magick input.jpg -gravity south -pointsize 20 -fill white \
  -annotate +0+10 "Copyright 2025" output.jpg

# Add text with background
magick input.jpg -gravity center -pointsize 40 -fill white \
  -undercolor black -annotate +0+0 "Watermark" output.jpg

# Add semi-transparent watermark
magick input.jpg \( -background none -fill "rgba(255,255,255,0.5)" \
  -pointsize 50 label:"DRAFT" \) -gravity center -compose over -composite output.jpg
```

### Compositing

Combine multiple images:

```bash
# Overlay watermark on image
magick input.jpg watermark.png -gravity southeast -composite output.jpg

# Overlay with transparency
magick input.jpg watermark.png -gravity center \
  -compose over -composite output.jpg

# Tile pattern
magick input.jpg pattern.png -compose over -tile -composite output.jpg

# Side-by-side images
magick input1.jpg input2.jpg +append output.jpg

# Stack images vertically
magick input1.jpg input2.jpg -append output.jpg
```

### Format-Specific Options

Optimize for different formats:

```bash
# JPEG with quality and strip metadata
magick input.png -quality 85 -strip output.jpg

# Progressive JPEG
magick input.png -quality 85 -interlace Plane output.jpg

# PNG with compression level (0-9)
magick input.jpg -quality 95 output.png

# WebP with quality
magick input.jpg -quality 80 output.webp

# WebP lossless
magick input.png -define webp:lossless=true output.webp

# GIF with optimization
magick input.png -colors 256 output.gif

# Transparent background PNG
magick input.jpg -transparent white output.png
```

## Batch Processing

### Using mogrify

Modify multiple files in-place:

```bash
# Convert all JPEGs to PNG in current directory
mogrify -format png *.jpg

# Resize all images in directory
mogrify -resize 800x600 *.jpg

# Apply to output directory (preserves originals)
mogrify -path ./output -resize 800x600 *.jpg

# Batch thumbnail generation
mogrify -path ./thumbnails -resize 275x275^ -gravity center \
  -crop 275x275+0+0 +repage *.jpg

# Batch format conversion with quality
mogrify -path ./optimized -format jpg -quality 85 -strip *.png
```

### Using shell loops

For more complex batch operations:

```bash
# Convert with custom naming
for img in *.jpg; do
  magick "$img" -resize 800x600 "resized_$img"
done

# Multi-step processing
for img in *.jpg; do
  magick "$img" -resize 1920x1080^ -gravity center \
    -crop 1920x1080+0+0 +repage -quality 85 "processed_$img"
done

# Different output format
for img in *.png; do
  magick "$img" -quality 90 "${img%.png}.jpg"
done
```

## Image Information

### Using identify

Get image metadata:

```bash
# Basic info
identify image.jpg

# Detailed information
identify -verbose image.jpg

# Format only
identify -format "%f: %wx%h %b\n" image.jpg

# Specific attributes
identify -format "%f: %wx%h, %[colorspace], %[type]\n" image.jpg

# File size
identify -format "%f: %b\n" image.jpg

# Multiple images
identify *.jpg
```

### Common format strings

- `%f` - filename
- `%w` - width
- `%h` - height
- `%b` - file size
- `%[colorspace]` - colorspace
- `%[type]` - image type
- `%[channels]` - number of channels
- `%[depth]` - bit depth

## Advanced Techniques

### Creating Contact Sheets

Use montage:

```bash
# Basic grid
montage *.jpg -geometry 200x200+2+2 contact-sheet.jpg

# With labels
montage *.jpg -geometry 200x200+2+2 -label '%f' contact-sheet.jpg

# Custom layout (3 columns)
montage *.jpg -tile 3x -geometry 200x200+5+5 contact-sheet.jpg
```

### Animated GIFs

Create animations:

```bash
# Create GIF from images
magick -delay 100 -loop 0 frame*.png animated.gif

# Optimize GIF
magick animated.gif -fuzz 5% -layers Optimize optimized.gif

# Extract frames from GIF
magick animated.gif frame_%03d.png
```

### Complex Pipelines

Chain multiple operations:

```bash
# Resize, crop, add border, adjust brightness
magick input.jpg \
  -resize 1000x1000^ \
  -gravity center \
  -crop 1000x1000+0+0 +repage \
  -bordercolor black -border 5x5 \
  -brightness-contrast 5x10 \
  -quality 90 \
  output.jpg

# Create thumbnail with watermark
magick input.jpg \
  -resize 400x400^ \
  -gravity center \
  -extent 400x400 \
  \( watermark.png -resize 100x100 \) \
  -gravity southeast -geometry +10+10 \
  -composite \
  output.jpg
```

## Performance Optimization

### Memory and Speed

```bash
# Limit memory usage (useful for large images)
magick -limit memory 2GB -limit map 4GB input.jpg -resize 50% output.jpg

# Set thread count
magick -limit thread 4 input.jpg -resize 50% output.jpg

# Use streaming for large files
magick -define stream:buffer-size=0 huge.jpg -resize 50% output.jpg
```

### Quality vs Size Trade-offs

```bash
# High quality (larger file)
magick input.jpg -quality 95 output.jpg

# Balanced (recommended for web)
magick input.jpg -quality 85 -strip output.jpg

# Lower quality (smaller file)
magick input.jpg -quality 70 -sampling-factor 4:2:0 -strip output.jpg

# Progressive JPEG (better for web)
magick input.jpg -quality 85 -interlace Plane -strip output.jpg
```

## Common Patterns

### Avatar/Profile Picture Generation

```bash
# Square thumbnail from any aspect ratio
magick input.jpg -resize 200x200^ -gravity center -extent 200x200 avatar.jpg

# Circular avatar (PNG with transparency)
magick input.jpg -resize 200x200^ -gravity center -extent 200x200 \
  \( +clone -threshold -1 -negate -fill white -draw "circle 100,100 100,0" \) \
  -alpha off -compose copy_opacity -composite avatar.png
```

### Responsive Images

```bash
# Generate multiple sizes
for size in 320 640 1024 1920; do
  magick input.jpg -resize ${size}x -quality 85 "output-${size}w.jpg"
done
```

### Watermarking

```bash
# Bottom-right watermark
magick input.jpg watermark.png -gravity southeast \
  -geometry +10+10 -composite output.jpg

# Tiled watermark
magick input.jpg \( watermark.png -alpha set -channel A \
  -evaluate multiply 0.3 +channel \) -tile -composite output.jpg
```

## Error Handling

Common issues and solutions:

**File not found:**
```bash
# Check file exists
[ -f input.jpg ] && magick input.jpg output.png || echo "File not found"
```

**Invalid geometry:**
```bash
# Validate dimensions first
identify -format "%wx%h" input.jpg
```

**Memory errors:**
```bash
# Limit resources
magick -limit memory 1GB -limit map 2GB input.jpg output.png
```

## Best Practices

1. **Always use `-strip`** to remove metadata (reduces file size)
2. **Set appropriate quality** (85 for JPEG is good balance)
3. **Use `+repage`** after crop to reset virtual canvas
4. **Quote file paths** with spaces: `"my image.jpg"`
5. **Test on sample** before batch processing
6. **Backup originals** when using mogrify
7. **Use `-auto-orient`** to respect EXIF orientation
8. **Progressive JPEGs** for web (use `-interlace Plane`)
9. **Limit memory** for large batches to prevent crashes
10. **Check output** after complex operations

## Troubleshooting

### Policy Restrictions

Some systems restrict ImageMagick operations for security:

```bash
# Check policy
identify -list policy

# Edit policy file (if needed)
sudo nano /etc/ImageMagick-6/policy.xml
# or
sudo nano /etc/ImageMagick-7/policy.xml
```

### Common Errors

**"convert: not authorized"**
- ImageMagick security policy blocking operation
- Edit policy.xml to allow specific formats/operations

**"convert: no decode delegate"**
- Missing format support library
- Install additional libraries (libjpeg, libpng, libwebp, etc.)

**"convert: memory allocation failed"**
- Image too large or insufficient memory
- Use `-limit` flags or process in smaller chunks

## Resources

- Official Documentation: https://imagemagick.org/
- Command-line Options: https://imagemagick.org/script/command-line-options.php
- Examples: https://imagemagick.org/Usage/
- Format Support: https://imagemagick.org/script/formats.php

## Command Reference Quick Guide

**Format Conversion:**
```bash
magick input.ext output.ext
```

**Resize:**
```bash
magick input.jpg -resize WIDTHxHEIGHT output.jpg
```

**Crop:**
```bash
magick input.jpg -crop WIDTHxHEIGHT+X+Y output.jpg
```

**Thumbnail:**
```bash
magick input.jpg -resize 100x100^ -gravity center -extent 100x100 thumb.jpg
```

**Effects:**
```bash
magick input.jpg -blur 0x8 output.jpg
```

**Batch:**
```bash
mogrify -resize 800x600 *.jpg
```

**Info:**
```bash
identify -verbose image.jpg
```

License

Declared license: MIT

MIT License

Copyright (c) 2026 majiayu000

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

View the license in the source repository — the version published there is authoritative.