# ImageMagick 7 Reference > Named colors: red, green, blue, cyan, magenta, yellow, black, white, gray, orange, gold, navy, teal, plus 700+ X11/SVG names. - Skill: `tools-only/imagemagick-7-reference` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add tools-only/imagemagick-7-reference` - Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/imagemagick-7-reference/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tools-only (https://skillmd.com/u/tools-only) - Updated: 2026-09-29 - Page: https://skillmd.com/skills/tools-only/imagemagick-7-reference --- # ImageMagick 7 Reference ## Command Structure ``` magick [input...] [settings] [operators] [output] ``` **Settings** persist until changed (`-font`, `-fill`, `-gravity`, `-compose`, `-quality`, `-background`, `-channel`, `-colorspace`, `-density`, `-depth`, `-fuzz`). **Operators** execute immediately then are forgotten (`-resize`, `-crop`, `-blur`, `-rotate`, `-annotate`, `-draw`, `-composite`). ```bash magick input.jpg -resize 800x600 -quality 85 -strip output.jpg ``` ## Geometry Strings | Syntax | Meaning | |--------|---------| | `WxH` | Fit within box, preserve aspect ratio | | `WxH!` | Force exact dimensions (distort if needed) | | `WxH>` | Shrink only if larger | | `WxH<` | Enlarge only if smaller | | `WxH^` | Fill box (minimum dimension matches, may overflow) | | `W%` or `W%xH%` | Percentage scale | | `@N` | Total pixel area limit | | `+X+Y` | Offset from origin or gravity anchor | | `x:y` | Aspect ratio target | | `x:y^` | Crop to aspect ratio | | `x:y#` | Pad to aspect ratio | Inline read-time shortcuts: ```bash magick 'image.jpg[800x600]' # resize on read magick 'image.jpg[600x400+100+50]' # crop on read magick 'animation.gif[0]' # single frame magick 'animation.gif[0-3]' # frame range ``` **Shell escaping**: `>`, `<`, `^` need quoting or escaping: ```bash magick input.jpg -resize '800x600>' output.jpg ``` ## Resize ```bash # Fit within 800x600, preserve aspect ratio magick input.jpg -resize 800x600 output.jpg # Force exact dimensions magick input.jpg -resize 800x600! output.jpg # Shrink only if larger magick input.jpg -resize '800x600>' output.jpg # Fill then center-crop to exact size magick input.jpg -resize 800x600^ -gravity center -extent 800x600 output.jpg # Percentage magick input.jpg -resize 50% output.jpg # Thumbnail (strips metadata, optimized for small output) magick input.jpg -thumbnail 200x200 output.jpg # Scale (fast, no interpolation -- pixel art) magick input.jpg -scale 200% output.png # With specific filter magick input.jpg -filter Lanczos -resize 800x600 output.jpg ``` ## Crop ```bash # Crop WxH at offset +X+Y from top-left magick input.jpg -crop 600x400+100+50 +repage output.jpg # Center crop magick input.jpg -gravity center -crop 600x400+0+0 +repage output.jpg # Auto-trim whitespace/border magick input.jpg -trim +repage output.jpg # Trim with fuzz tolerance magick input.jpg -fuzz 10% -trim +repage output.jpg # Pad to exact size (extend canvas) magick input.jpg -gravity center -background white -extent 1000x1000 output.jpg # Shave equal border from all sides magick input.jpg -shave 20x20 output.jpg ``` **Always use `+repage` after `-crop`** to reset virtual canvas offset. ## Compositing ```bash # Overlay at position magick background.png foreground.png -geometry +50+100 -composite output.png # With blend mode magick background.png overlay.png -compose Multiply -composite output.png # With opacity (70% overlay) magick background.png overlay.png -compose Blend -define compose:args=70 -composite output.png # Multi-layer (parenthesized sub-expressions) magick background.png \ \( overlay1.png -geometry +10+20 \) -compose Over -composite \ \( overlay2.png -geometry +200+50 \) -compose Over -composite \ output.png ``` See `compositing.md` for the full operator reference. ## Alpha Channel ```bash # Activate alpha (set to opaque if new) magick input.jpg -alpha set output.png # Remove alpha (flatten onto color) magick input.png -background white -alpha remove output.jpg # Make color transparent magick input.png -fuzz 15% -transparent white output.png # Apply grayscale mask (white=visible, black=transparent) magick source.png mask.png -alpha off -compose CopyOpacity -composite masked.png # Extract alpha as grayscale magick input.png -alpha extract alpha_mask.png # Flatten transparency onto color magick input.png -background "#ff6600" -flatten output.jpg ``` **IM7 gotcha**: `-alpha off` permanently removes alpha data. Use `-alpha deactivate`/`-alpha activate` for temporary toggle. ## Color Space ```bash # Convert to CMYK (print) magick input.jpg -colorspace CMYK output.tiff # Convert to grayscale magick input.jpg -colorspace Gray output.jpg # Separate HSL channels magick input.jpg -colorspace HSL -separate hsl_%d.png # Recombine channels magick hsl_0.png hsl_1.png hsl_2.png -set colorspace HSL -combine -colorspace sRGB output.jpg ``` **`-colorspace`** converts pixel data. **`-set colorspace`** relabels metadata without transforming values. ## Color Adjustment ```bash # Modulate: Brightness, Saturation, Hue (100 = no change) magick input.jpg -modulate 110,130,100 output.jpg # +10% bright, +30% sat # Brightness-contrast magick input.jpg -brightness-contrast 10x20 output.jpg # Levels (black-point, white-point, gamma) magick input.jpg -level 5%,95% output.jpg # Auto-level / normalize magick input.jpg -auto-level output.jpg magick input.jpg -normalize output.jpg # Gamma correction magick input.jpg -gamma 1.2 output.jpg # Sigmoidal contrast (strength x midpoint%) magick input.jpg -sigmoidal-contrast 5x50% output.jpg # Tint/colorize magick input.jpg -fill "#ff6600" -colorize 30% output.jpg # Sepia magick input.jpg -sepia-tone 80% output.jpg # Negate (invert) magick input.jpg -negate output.jpg ``` **`-modulate` arg order is B,S,H** -- not H,S,L. ## Channel Operations ```bash # Process single channel magick input.jpg -channel R -negate +channel output.jpg # Per-channel levels magick input.jpg -channel R -level 10%,90% +channel output.jpg # Swap channels magick input.jpg -channel red,blue -separate -swap 0,1 -combine output.jpg # IM7 channel syntax: # red<=>blue swap # red=>green copy red to green # red=50% set red to constant ``` ## Text and Annotation ```bash # Simple text magick input.jpg -fill white -pointsize 36 -annotate +10+50 'Hello World' output.jpg # With font and gravity magick input.jpg -font Helvetica-Bold -fill white -pointsize 48 \ -gravity south -annotate +0+10 'Caption' output.jpg # Outlined text (draw twice: outline then fill) magick input.jpg -font Helvetica-Bold -pointsize 48 \ -stroke black -strokewidth 3 -fill none -annotate +20+60 'Text' \ -stroke none -fill white -annotate +20+60 'Text' output.jpg # Auto-sized label magick -background none -fill white -font Helvetica -size 400x label:'Title' label.png # Word-wrapped caption magick -background none -fill white -font Helvetica -size 400x200 \ caption:'Long text that wraps automatically.' caption.png ``` **Gravity values**: `NorthWest`, `North`, `NorthEast`, `West`, `Center`, `East`, `SouthWest`, `South`, `SouthEast`. Reset with `+gravity`. ## Drawing ```bash # Filled rectangle magick input.jpg -fill "rgba(0,0,0,0.5)" -draw "rectangle 10,10 200,100" output.jpg # Outline rectangle magick input.jpg -fill none -stroke red -strokewidth 2 -draw "rectangle 10,10 200,100" output.jpg # Rounded rectangle magick input.jpg -fill blue -draw "roundrectangle 10,10 200,100 15,15" output.jpg # Circle (center_x,center_y edge_x,edge_y) magick input.jpg -fill "rgba(255,0,0,0.5)" -draw "circle 250,250 250,50" output.jpg # Line magick input.jpg -stroke red -strokewidth 3 -draw "line 0,0 500,500" output.jpg # Create canvas from scratch magick -size 500x500 xc:white \ -fill none -stroke black -strokewidth 2 \ -draw "rectangle 50,50 450,450" output.png ``` ## Blur and Sharpen ```bash # Gaussian blur (radius x sigma -- sigma is the key parameter) magick input.jpg -blur 0x3 output.jpg # Sharpen magick input.jpg -sharpen 0x1 output.jpg # Unsharp mask (radius x sigma + amount + threshold) magick input.jpg -unsharp 0x0.5+1+0.05 output.jpg # Motion blur (radius x sigma + angle) magick input.jpg -motion-blur 0x5+45 output.jpg ``` ## Format Conversion and I/O ```bash # Convert format magick input.png output.jpg # JPEG quality (1-100) magick input.png -quality 85 output.jpg # PNG compression (0-9 mapped to quality 0-90) magick input.jpg -quality 95 output.png # Strip all metadata magick input.jpg -strip output.jpg # Set DPI magick input.jpg -density 300 output.jpg # WebP conversion magick input.jpg -quality 80 output.webp # AVIF conversion magick input.jpg -quality 50 output.avif # Pipe support magick logo: gif:- | magick - -resize 200% output.jpg ``` ## Batch Processing ```bash # mogrify: in-place batch (use -path for non-destructive) magick mogrify -path output/ -resize 800x600 *.jpg magick mogrify -path output/ -format png -resize 50% *.jpg magick mogrify -path output/ -quality 85 -strip -auto-orient *.jpg # Shell loop with custom naming for f in *.jpg; do magick "$f" -resize 800x600 -quality 85 "thumb_${f}" done # Parallel processing ls *.jpg | xargs -P 4 -I {} magick {} -resize 800x600 output/{} ``` **`mogrify` without `-path` overwrites originals.** ## Identify (Inspection) ```bash # Dimensions magick identify -format "%wx%h" input.jpg # Detailed info magick identify -format "Size: %wx%h\nFormat: %m\nColorspace: %r\nDepth: %z-bit\n" input.jpg # Verbose (full dump) magick identify -verbose input.jpg ``` ## Image Stacks Parentheses create sub-image-lists for isolated processing: ```bash magick input.jpg \( +clone -blur 0x8 \) -compose Overlay -composite output.jpg # Key operators: # +clone duplicate last image # -clone N duplicate image at index N # -delete N remove image at index N # +swap swap last two images ``` ## Color Specification Formats ``` #rgb, #rrggbb, #rrggbbaa Hex (fastest) rgb(255,0,0) Functional rgba(255,0,0,0.5) With alpha hsl(120,100%,50%) HSL hsla(120,100%,50%,0.5) HSL with alpha cmyk(0,0,0,100%) CMYK gray(50%) Grayscale none / transparent Fully transparent ``` Named colors: `red`, `green`, `blue`, `cyan`, `magenta`, `yellow`, `black`, `white`, `gray`, `orange`, `gold`, `navy`, `teal`, plus 700+ X11/SVG names. ## Montage ```bash # Thumbnail grid magick montage *.jpg -geometry 200x200+5+5 -tile 4x -background white contact.jpg # With labels magick montage *.jpg -geometry 200x200+5+5 -tile 4x -label '%f' -font Helvetica -pointsize 10 contact.jpg ``` ## Common Gotchas 1. **`+repage` after `-crop`** -- Virtual canvas offset persists without it 2. **`-modulate` order is B,S,H** -- Not H,S,L 3. **`-alpha off` is permanent in IM7** -- Use `-alpha deactivate`/`-alpha activate` instead 4. **Shell escaping for `>`, `<`, `^`** -- Quote geometry: `-resize '800x600>'` 5. **sRGB vs linear RGB** -- Resize works in linear RGB by default; can cause darkening 6. **HDRI builds** -- Pixel values are floating point; affects threshold ops 7. **HEIC odd-width corruption** -- Use `-define heic:even-size=true` 8. **`%` in text** -- Special in `-annotate`/`-label` (property escape); use `%%` for literal 9. **`+` vs `-` prefix** -- `+` resets/disables, `-` enables (e.g., `+antialias` disables) 10. **Order matters** -- Settings persist, operators execute immediately