1 2 3 4 5<!DOCTYPE html> 6<html lang="en"> 7<head> 8 <meta charset="utf-8" /> 9 <meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1,shrink-to-fit=no" /> 10 <title>ImageMagick - Command-line Options</title> 11 <meta name="application-name" content="ImageMagick" /> 12 <meta name="description" content="Use ImageMagick® to create, edit, compose, and convert bitmap images. Resize an image, crop it, change its shades and colors, add captions, and more." /> 13 <meta name="application-url" content="https://imagemagick.org" /> 14 <meta name="generator" content="PHP" /> 15 <meta name="keywords" content="command-line, options, ImageMagick, PerlMagick, image processing, image, photo, software, Magick++, OpenMP, convert" /> 16 <meta name="rating" content="GENERAL" /> 17 <meta name="robots" content="INDEX, FOLLOW" /> 18 <meta name="generator" content="ImageMagick Studio LLC" /> 19 <meta name="author" content="ImageMagick Studio LLC" /> 20 <meta name="revisit-after" content="2 DAYS" /> 21 <meta name="resource-type" content="document" /> 22 <meta name="copyright" content="Copyright (c) 1999-2020 ImageMagick Studio LLC" /> 23 <meta name="distribution" content="Global" /> 24 <meta name="magick-serial" content="P131-S030410-R485315270133-P82224-A6668-G1245-1" /> 25 <meta property='og:url' content='../' /> 26 <meta property='og:title' content='ImageMagick' /> 27 <meta property='og:image' content='../images/logo.png' /> 28 <meta property='og:type' content='website' /> 29 <meta property='og:site_name' content='ImageMagick' /> 30 <meta property='og:description' content="Convert, Edit, or Compose Bitmap Images" /> 31 <meta name="google-site-verification" content="_bMOCDpkx9ZAzBwb2kF3PRHbfUUdFj2uO8Jd1AXArz4" /> 32 <link href="../www/command-line-options.html" rel="canonical" /> 33 <link href="../images/wand.png" rel="icon" /> 34 <link href="../images/wand.ico" rel="shortcut icon" /> 35 <link href="assets/magick.css" rel="stylesheet" /> 36</head> 37<body> 38 <nav class="navbar navbar-expand-md navbar-dark fixed-top bg-dark"> 39 <a class="navbar-brand" href="../index.html"><img class="d-block" id="icon" alt="ImageMagick" width="32" height="32" src="../images/wand.ico"/></a> 40 <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarsMagick" aria-controls="navbarsMagick" aria-expanded="false" aria-label="Toggle navigation"> 41 <span class="navbar-toggler-icon"></span> 42 </button> 43 44 <div class="navbar-collapse collapse" id="navbarsMagick" style=""> 45 <ul class="navbar-nav mr-auto"> 46 <li class="nav-item "> 47 <a class="nav-link" href="../index.html">Home <span class="sr-only">(current)</span></a> 48 </li> 49 <li class="nav-item "> 50 <a class="nav-link" href="download.html">Download</a> 51 </li> 52 <li class="nav-item "> 53 <a class="nav-link" href="command-line-tools.html">Tools</a> 54 </li> 55 <li class="nav-item "> 56 <a class="nav-link" href="command-line-processing.html">Command-line</a> 57 </li> 58 <li class="nav-item "> 59 <a class="nav-link" href="resources.html">Resources</a> 60 </li> 61 <li class="nav-item "> 62 <a class="nav-link" href="develop.html">Develop</a> 63 </li> 64 <li class="nav-item"> 65 <a class="nav-link" target="_blank" href="https://imagemagick.org/discourse-server/">Community</a> 66 </li> 67 </ul> 68 <form class="form-inline my-2 my-lg-0" action="https://imagemagick.org/script/search.php"> 69 <input class="form-control mr-sm-2" type="text" name="q" placeholder="Search" aria-label="Search"> 70 <button class="btn btn-outline-success my-2 my-sm-0" type="submit" name="sa">Search</button> 71 </form> 72 </div> 73 </nav> 74 <div class="container"> 75 <script async="async" src="http://localhost/pagead/js/adsbygoogle.js"></script> <ins class="adsbygoogle" 76 style="display:block" 77 data-ad-client="ca-pub-3129977114552745" 78 data-ad-slot="6345125851" 79 data-full-width-responsive="true" 80 data-ad-format="horizontal"></ins> 81 <script> 82 (adsbygoogle = window.adsbygoogle || []).push({}); 83 </script> 84 85 </div> 86 87 <main class="container"> 88 <div class="magick-template"> 89<div class="magick-header"> 90<p class="text-center"><a href="command-line-options.html#adaptive-blur">‑adaptive‑blur</a> • <a href="command-line-options.html#adaptive-resize">‑adaptive‑resize</a> • <a href="command-line-options.html#adaptive-sharpen">‑adaptive‑sharpen</a> • <a href="command-line-options.html#adjoin">‑adjoin</a> • <a href="command-line-options.html#affine">‑affine</a> • <a href="command-line-options.html#alpha">‑alpha</a> • <a href="command-line-options.html#annotate">‑annotate</a> • <a href="command-line-options.html#antialias">‑antialias</a> • <a href="command-line-options.html#append">‑append</a> • <a href="command-line-options.html#attenuate">‑attenuate</a> • <a href="command-line-options.html#authenticate">‑authenticate</a> • <a href="command-line-options.html#auto-gamma">‑auto‑gamma</a> • <a href="command-line-options.html#auto-level">‑auto‑level</a> • <a href="command-line-options.html#auto-orient">‑auto‑orient</a> • <a href="command-line-options.html#auto-threshold">‑auto‑threshold</a> • <a href="command-line-options.html#backdrop">‑backdrop</a> • <a href="command-line-options.html#background">‑background</a> • <a href="command-line-options.html#bench">‑bench</a> • <a href="command-line-options.html#bias">‑bias</a> • <a href="command-line-options.html#black-point-compensation">‑black‑point‑compensation</a> • <a href="command-line-options.html#black-threshold">‑black‑threshold</a> • <a href="command-line-options.html#blend">‑blend</a> • <a href="command-line-options.html#blue-primary">‑blue‑primary</a> • <a href="command-line-options.html#blue-shift">‑blue‑shift</a> • <a href="command-line-options.html#blur">‑blur</a> • <a href="command-line-options.html#border">‑border</a> • <a href="command-line-options.html#bordercolor">‑bordercolor</a> • <a href="command-line-options.html#borderwidth">‑borderwidth</a> • <a href="command-line-options.html#brightness-contrast">‑brightness‑contrast</a> • <a href="command-line-options.html#cache">‑cache</a> • <a href="command-line-options.html#canny">‑canny</a> • <a href="command-line-options.html#caption">‑caption</a> • <a href="command-line-options.html#cdl">‑cdl</a> • <a href="command-line-options.html#channel">‑channel</a> • <a href="command-line-options.html#charcoal">‑charcoal</a> • <a href="command-line-options.html#channel-fx">‑channel‑fx</a> • <a href="command-line-options.html#chop">‑chop</a> • <a href="command-line-options.html#clahe">‑clahe</a> • <a href="command-line-options.html#clamp">‑clamp</a> • <a href="command-line-options.html#clip">‑clip</a> • <a href="command-line-options.html#clip-mask">‑clip‑mask</a> • <a href="command-line-options.html#clip-path">‑clip‑path</a> • <a href="command-line-options.html#clone">‑clone</a> • <a href="command-line-options.html#clut">‑clut</a> • <a href="command-line-options.html#coalesce">‑coalesce</a> • <a href="command-line-options.html#colorize">‑colorize</a> • <a href="command-line-options.html#colormap">‑colormap</a> • <a href="command-line-options.html#color-matrix">‑color‑matrix</a> • <a href="command-line-options.html#colors">‑colors</a> • <a href="command-line-options.html#colorspace">‑colorspace</a> • <a href="command-line-options.html#combine">‑combine</a> • <a href="command-line-options.html#comment">‑comment</a> • <a href="command-line-options.html#compare">‑compare</a> • <a href="command-line-options.html#complex">‑complex</a> • <a href="command-line-options.html#compose">‑compose</a> • <a href="command-line-options.html#composite">‑composite</a> • <a href="command-line-options.html#compress">‑compress</a> • <a href="command-line-options.html#connected-components">‑connected‑components</a> • <a href="command-line-options.html#contrast">‑contrast</a> • <a href="command-line-options.html#contrast-stretch">‑contrast‑stretch</a> • <a href="command-line-options.html#convolve">‑convolve</a> • <a href="command-line-options.html#copy">‑copy</a> • <a href="command-line-options.html#crop">‑crop</a> • <a href="command-line-options.html#cycle">‑cycle</a> • <a href="command-line-options.html#debug">‑debug</a> • <a href="command-line-options.html#decipher">‑decipher</a> • <a href="command-line-options.html#deconstruct">‑deconstruct</a> • <a href="command-line-options.html#define">‑define</a> • <a href="command-line-options.html#delay">‑delay</a> • <a href="command-line-options.html#delete">‑delete</a> • <a href="command-line-options.html#density">‑density</a> • <a href="command-line-options.html#depth">‑depth</a> • <a href="command-line-options.html#descend">‑descend</a> • <a href="command-line-options.html#deskew">‑deskew</a> • <a href="command-line-options.html#despeckle">‑despeckle</a> • <a href="command-line-options.html#direction">‑direction</a> • <a href="command-line-options.html#displace">‑displace</a> • <a href="command-line-options.html#display">‑display</a> • <a href="command-line-options.html#dispose">‑dispose</a> • <a href="command-line-options.html#dissimilarity-threshold">‑dissimilarity‑threshold</a> • <a href="command-line-options.html#dissolve">‑dissolve</a> • <a href="command-line-options.html#distort">‑distort</a> • <a href="command-line-options.html#distribute-cache">‑distribute‑cache</a> • <a href="command-line-options.html#dither">‑dither</a> • <a href="command-line-options.html#draw">‑draw</a> • <a href="command-line-options.html#duplicate">‑duplicate</a> • <a href="command-line-options.html#edge">‑edge</a> • <a href="command-line-options.html#emboss">‑emboss</a> • <a href="command-line-options.html#encipher">‑encipher</a> • <a href="command-line-options.html#encoding">‑encoding</a> • <a href="command-line-options.html#endian">‑endian</a> • <a href="command-line-options.html#enhance">‑enhance</a> • <a href="command-line-options.html#equalize">‑equalize</a> • <a href="command-line-options.html#evaluate">‑evaluate</a> • <a href="command-line-options.html#evaluate-sequence">‑evaluate‑sequence</a> • <a href="command-line-options.html#extent">‑extent</a> • <a href="command-line-options.html#extract">‑extract</a> • <a href="command-line-options.html#family">‑family</a> • <a href="command-line-options.html#features">‑features</a> • <a href="command-line-options.html#fft">‑fft</a> • <a href="command-line-options.html#fill">‑fill</a> • <a href="command-line-options.html#filter">‑filter</a> • <a href="command-line-options.html#flatten">‑flatten</a> • <a href="command-line-options.html#flip">‑flip</a> • <a href="command-line-options.html#floodfill">‑floodfill</a> • <a href="command-line-options.html#flop">‑flop</a> • <a href="command-line-options.html#font">‑font</a> • <a href="command-line-options.html#foreground">‑foreground</a> • <a href="command-line-options.html#format">‑format</a> • <a href="command-line-options.html#format_identify_">‑format[identify]</a> • <a href="command-line-options.html#frame">‑frame</a> • <a href="command-line-options.html#frame_import_">‑frame[import]</a> • <a href="command-line-options.html#function">‑function</a> • <a href="command-line-options.html#fuzz">‑fuzz</a> • <a href="command-line-options.html#fx">‑fx</a> • <a href="command-line-options.html#gamma">‑gamma</a> • <a href="command-line-options.html#gaussian-blur">‑gaussian‑blur</a> • <a href="command-line-options.html#geometry">‑geometry</a> • <a href="command-line-options.html#gravity">‑gravity</a> • <a href="command-line-options.html#grayscale">‑grayscale</a> • <a href="command-line-options.html#green-primary">‑green‑primary</a> • <a href="command-line-options.html#hald-clut">‑hald‑clut</a> • <a href="command-line-options.html#help">‑help</a> • <a href="command-line-options.html#highlight-color">‑highlight‑color</a> • <a href="command-line-options.html#hough-lines">‑hough‑lines</a> • <a href="command-line-options.html#iconGeometry">‑iconGeometry</a> • <a href="command-line-options.html#iconic">‑iconic</a> • <a href="command-line-options.html#identify">‑identify</a> • <a href="command-line-options.html#ift">‑ift</a> • <a href="command-line-options.html#immutable">‑immutable</a> • <a href="command-line-options.html#implode">‑implode</a> • <a href="command-line-options.html#insert">‑insert</a> • <a href="command-line-options.html#intensity">‑intensity</a> • <a href="command-line-options.html#intent">‑intent</a> • <a href="command-line-options.html#interlace">‑interlace</a> • <a href="command-line-options.html#interpolate">‑interpolate</a> • <a href="command-line-options.html#interline-spacing">‑interline‑spacing</a> • <a href="command-line-options.html#interword-spacing">‑interword‑spacing</a> • <a href="command-line-options.html#kerning">‑kerning</a> • <a href="command-line-options.html#kmeans">‑kmeans</a> • <a href="command-line-options.html#kuwahara">‑kuwahara</a> • <a href="command-line-options.html#label">‑label</a> • <a href="command-line-options.html#lat">‑lat</a> • <a href="command-line-options.html#layers">‑layers</a> • <a href="command-line-options.html#level">‑level</a> • <a href="command-line-options.html#level-colors">‑level‑colors</a> • <a href="command-line-options.html#limit">‑limit</a> • <a href="command-line-options.html#linear-stretch">‑linear‑stretch</a> • <a href="command-line-options.html#linewidth">‑linewidth</a> • <a href="command-line-options.html#liquid-rescale">‑liquid‑rescale</a> • <a href="command-line-options.html#list">‑list</a> • <a href="command-line-options.html#log">‑log</a> • <a href="command-line-options.html#loop">‑loop</a> • <a href="command-line-options.html#lowlight-color">‑lowlight‑color</a> • <a href="command-line-options.html#magnify">‑magnify</a> • <a href="command-line-options.html#map">‑map</a> • <a href="command-line-options.html#map_stream_">‑map[stream]</a> • <a href="command-line-options.html#mattecolor">‑mattecolor</a> • <a href="command-line-options.html#median">‑median</a> • <a href="command-line-options.html#mean-shift">‑mean‑shift</a> • <a href="command-line-options.html#metric">‑metric</a> • <a href="command-line-options.html#mode">‑mode</a> • <a href="command-line-options.html#modulate">‑modulate</a> • <a href="command-line-options.html#moments">‑moments</a> • <a href="command-line-options.html#monitor">‑monitor</a> • <a href="command-line-options.html#monochrome">‑monochrome</a> • <a href="command-line-options.html#morph">‑morph</a> • <a href="command-line-options.html#morphology">‑morphology</a> • <a href="command-line-options.html#mosaic">‑mosaic</a> • <a href="command-line-options.html#motion-blur">‑motion‑blur</a> • <a href="command-line-options.html#name">‑name</a> • <a href="command-line-options.html#negate">‑negate</a> • <a href="command-line-options.html#noise">‑noise</a> • <a href="command-line-options.html#normalize">‑normalize</a> • <a href="command-line-options.html#opaque">‑opaque</a> • <a href="command-line-options.html#ordered-dither">‑ordered‑dither</a> • <a href="command-line-options.html#orient">‑orient</a> • <a href="command-line-options.html#page">‑page</a> • <a href="command-line-options.html#paint">‑paint</a> • <a href="command-line-options.html#path">‑path</a> • <a href="command-line-options.html#pause_animate_">‑pause[animate]</a> • <a href="command-line-options.html#pause_import_">‑pause[import]</a> • <a href="command-line-options.html#perceptible">‑perceptible</a> • <a href="command-line-options.html#ping">‑ping</a> • <a href="command-line-options.html#pointsize">‑pointsize</a> • <a href="command-line-options.html#polaroid">‑polaroid</a> • <a href="command-line-options.html#poly">‑poly</a> • <a href="command-line-options.html#posterize">‑posterize</a> • <a href="command-line-options.html#precision">‑precision</a> • <a href="command-line-options.html#preview">‑preview</a> • <a href="command-line-options.html#print">‑print</a> • <a href="command-line-options.html#process">‑process</a> • <a href="command-line-options.html#profile">‑profile</a> • <a href="command-line-options.html#quality">‑quality</a> • <a href="command-line-options.html#quantize">‑quantize</a> • <a href="command-line-options.html#quiet">‑quiet</a> • <a href="command-line-options.html#radial-blur">‑radial‑blur</a> • <a href="command-line-options.html#raise">‑raise</a> • <a href="command-line-options.html#random-threshold">‑random‑threshold</a> • <a href="command-line-options.html#range-threshold">‑range‑threshold</a> • <a href="command-line-options.html#read-mask">‑read‑mask</a> • <a href="command-line-options.html#red-primary">‑red‑primary</a> • <a href="command-line-options.html#regard-warnings">‑regard‑warnings</a> • <a href="command-line-options.html#region">‑region</a> • <a href="command-line-options.html#remap">‑remap</a> • <a href="command-line-options.html#remote">‑remote</a> • <a href="command-line-options.html#render">‑render</a> • <a href="command-line-options.html#repage">‑repage</a> • <a href="command-line-options.html#resample">‑resample</a> • <a href="command-line-options.html#resize">‑resize</a> • <a href="command-line-options.html#respect-parentheses">‑respect‑parentheses</a> • <a href="command-line-options.html#reverse">‑reverse</a> • <a href="command-line-options.html#roll">‑roll</a> • <a href="command-line-options.html#rotate">‑rotate</a> • <a href="command-line-options.html#sample">‑sample</a> • <a href="command-line-options.html#sampling-factor">‑sampling‑factor</a> • <a href="command-line-options.html#scale">‑scale</a> • <a href="command-line-options.html#scene">‑scene</a> • <a href="command-line-options.html#screen">‑screen</a> • <a href="command-line-options.html#seed">‑seed</a> • <a href="command-line-options.html#segment">‑segment</a> • <a href="command-line-options.html#selective-blur">‑selective‑blur</a> • <a href="command-line-options.html#separate">‑separate</a> • <a href="command-line-options.html#sepia-tone">‑sepia‑tone</a> • <a href="command-line-options.html#set">‑set</a> • <a href="command-line-options.html#shade">‑shade</a> • <a href="command-line-options.html#shadow">‑shadow</a> • <a href="command-line-options.html#shared-memory">‑shared‑memory</a> • <a href="command-line-options.html#sharpen">‑sharpen</a> • <a href="command-line-options.html#shave">‑shave</a> • <a href="command-line-options.html#shear">‑shear</a> • <a href="command-line-options.html#sigmoidal-contrast">‑sigmoidal‑contrast</a> • <a href="command-line-options.html#silent">‑silent</a> • <a href="command-line-options.html#similarity-threshold">‑similarity‑threshold</a> • <a href="command-line-options.html#size">‑size</a> • <a href="command-line-options.html#sketch">‑sketch</a> • <a href="command-line-options.html#smush">‑smush</a> • <a href="command-line-options.html#snaps">‑snaps</a> • <a href="command-line-options.html#solarize">‑solarize</a> • <a href="command-line-options.html#sparse-color">‑sparse‑color</a> • <a href="command-line-options.html#splice">‑splice</a> • <a href="command-line-options.html#spread">‑spread</a> • <a href="command-line-options.html#statistic">‑statistic</a> • <a href="command-line-options.html#stegano">‑stegano</a> • <a href="command-line-options.html#stereo">‑stereo</a> • <a href="command-line-options.html#storage-type">‑storage‑type</a> • <a href="command-line-options.html#stretch">‑stretch</a> • <a href="command-line-options.html#strip">‑strip</a> • <a href="command-line-options.html#stroke">‑stroke</a> • <a href="command-line-options.html#strokewidth">‑strokewidth</a> • <a href="command-line-options.html#style">‑style</a> • <a href="command-line-options.html#subimage-search">‑subimage‑search</a> • <a href="command-line-options.html#swap">‑swap</a> • <a href="command-line-options.html#swirl">‑swirl</a> • <a href="command-line-options.html#synchronize">‑synchronize</a> • <a href="command-line-options.html#taint">‑taint</a> • <a href="command-line-options.html#text-font">‑text‑font</a> • <a href="command-line-options.html#texture">‑texture</a> • <a href="command-line-options.html#threshold">‑threshold</a> • <a href="command-line-options.html#thumbnail">‑thumbnail</a> • <a href="command-line-options.html#tile">‑tile</a> • <a href="command-line-options.html#tile-offset">‑tile‑offset</a> • <a href="command-line-options.html#tint">‑tint</a> • <a href="command-line-options.html#title">‑title</a> • <a href="command-line-options.html#transform">‑transform</a> • <a href="command-line-options.html#transparent">‑transparent</a> • <a href="command-line-options.html#transparent-color">‑transparent‑color</a> • <a href="command-line-options.html#transpose">‑transpose</a> • <a href="command-line-options.html#transverse">‑transverse</a> • <a href="command-line-options.html#treedepth">‑treedepth</a> • <a href="command-line-options.html#trim">‑trim</a> • <a href="command-line-options.html#type">‑type</a> • <a href="command-line-options.html#undercolor">‑undercolor</a> • <a href="command-line-options.html#unique-colors">‑unique‑colors</a> • <a href="command-line-options.html#units">‑units</a> • <a href="command-line-options.html#unsharp">‑unsharp</a> • <a href="command-line-options.html#update">‑update</a> • <a href="command-line-options.html#verbose">‑verbose</a> • <a href="command-line-options.html#version">‑version</a> • <a href="command-line-options.html#view">‑view</a> • <a href="command-line-options.html#vignette">‑vignette</a> • <a href="command-line-options.html#virtual-pixel">‑virtual‑pixel</a> • <a href="command-line-options.html#visual">‑visual</a> • <a href="command-line-options.html#watermark">‑watermark</a> • <a href="command-line-options.html#wave">‑wave</a> • <a href="command-line-options.html#wavelet-denoise">‑wavelet‑denoise</a> • <a href="command-line-options.html#weight">‑weight</a> • <a href="command-line-options.html#white-point">‑white‑point</a> • <a href="command-line-options.html#white-threshold">‑white‑threshold</a> • <a href="command-line-options.html#window">‑window</a> • <a href="command-line-options.html#window-group">‑window‑group</a> • <a href="command-line-options.html#write">‑write</a> • <a href="command-line-options.html#write-mask">‑write‑mask</a> </p> 91<p class="lead magick-description">Below is list of command-line options recognized by the ImageMagick <a href="command-line-tools.html">command-line tools</a>. If you want a description of a particular option, click on the option name in the navigation bar above and you will go right to it. Unless otherwise noted, each option is recognized by the commands: <a href="convert.html">convert</a> and <a href="mogrify.html">mogrify</a>.</p> 92 93<div style="margin: auto;"> 94 <h3><a class="anchor" id="adaptive-blur"></a>-adaptive-blur <var>radius</var>[x<var>sigma</var>]</h3> 95</div> 96 97<p class="magick-description">Adaptively blur pixels, with decreasing effect near edges.</p> 98 99<p>A Gaussian operator of the given radius and standard deviation (<var>sigma</var>) is used. If <var>sigma</var> is not given it 100defaults to 1.</p> 101 102<div style="margin: auto;"> 103 <h3><a class="anchor" id="adaptive-resize"></a>-adaptive-resize <var>geometry</var></h3> 104</div> 105 106<p class="magick-description">Resize the image using data-dependent triangulation.</p> 107 108<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. The <a href="command-line-options.html#adaptive-resize">-adaptive-resize</a> 109option defaults to data-dependent triangulation. Use the <a 110href="command-line-options.html#filter">-filter</a> to choose a different resampling algorithm. 111Offsets, if present in the geometry string, are ignored, and the <a 112href="command-line-options.html#gravity">-gravity</a> option has no effect.</p> 113 114<div style="margin: auto;"> 115 <h3><a class="anchor" id="adaptive-sharpen"></a>-adaptive-sharpen <var>radius</var>[x<var>sigma</var>]</h3> 116</div> 117 118<p class="magick-description">Adaptively sharpen pixels, with increasing effect near edges.</p> 119 120<p>A Gaussian operator of the given radius and standard deviation 121(<var>sigma</var>) is used. If <var>sigma</var> is not given it 122defaults to 1.</p> 123 124<div style="margin: auto;"> 125 <h3><a class="anchor" id="adjoin"></a>-adjoin</h3> 126</div> 127 128<p class="magick-description">Join images into a single multi-image file.</p> 129 130<p>This option is enabled by default. An attempt is made to save all images of 131an image sequence into the given output file. However, some formats, such as 132JPEG and PNG, do not support more than one image per file, and in that case 133ImageMagick is forced to write each image as a separate file. As such, if 134more than one image needs to be written, the filename given is modified by 135adding a <a href="command-line-options.html#scene">-scene</a> number before the suffix, in order to 136make distinct names for each image. </p> 137 138<p>Use <a href="command-line-options.html#adjoin">+adjoin</a> to force each image to be written to 139separate files, whether or not the file format allows multiple images per file 140(for example, GIF, MIFF, and TIFF). </p> 141 142<p>Including a C-style integer format string in the output filename will 143automagically enable <a href="command-line-options.html#adjoin">+adjoin</a> and are used to specify 144where the <a href="command-line-options.html#scene">-scene</a> number is placed in the filenames. These 145strings, such as '<code>%d</code>' or '<code>%03d</code>', are familiar to those 146who have used the standard <code>printf()</code>' C-library function. As an 147example, the command</p> 148 149<pre class="highlight"><code>convert logo: rose: -morph 15 my%02dmorph.jpg 150</code></pre> 151 152<p>will create a sequence of 17 images (the two given plus 15 more created by 153<a href="command-line-options.html#morph">-morph</a>), named: my00morph.jpg, my01morph.jpg, 154my02morph.jpg, ..., my16morph.jpg. </p> 155 156<p>In summary, ImageMagick tries to write all images to one file, but will 157save to multiple files, if any of the following conditions exist...</p> 158<ol> 159<li>the output image's file format does not allow multi-image files,</li> 160<li>the <a href="command-line-options.html#adjoin">+adjoin</a> option is given, or</li> 161<li>a printf() integer format string (eg: "%d") is present in the output 162 filename.</li> 163</ol> 164 165 166<div style="margin: auto;"> 167 <h3><a class="anchor" id="affine"></a>-affine 168 <var>s<sub>x</sub></var>,<var>r<sub>x</sub></var>,<var>r<sub>y</sub></var>,<var>s<sub>y</sub></var>[,<var>t<sub>x</sub></var>,<var>t<sub>y</sub></var>]</h3> 169</div> 170 171<p class="magick-description">Set the drawing transformation matrix for combined rotating and scaling.</p> 172 173<p>This option sets a transformation matrix, for use by subsequent <a 174href="command-line-options.html#draw">-draw</a> or <a href="command-line-options.html#transform">-transform</a> options. </p> 175 176<p>The matrix entries are entered as comma-separated numeric values either in 177quotes or without spaces. </p> 178 179<p>Internally, the transformation matrix has 3x3 elements, but three of them 180are omitted from the input because they are constant. The new (transformed) 181coordinates (<var>x'</var>, <var>y'</var>) of a pixel at 182position (<var>x</var>, <var>y</var>) in the original 183image are calculated using the following matrix equation.</p> 184 185<p class="text-center"><img class="img-thumbnail" alt="affine transformation" src="../images/affine.png"/> </p> 186 187<p> The size of the resulting image is that of the smallest rectangle that 188contains the transformed source image. The parameters 189<var>t<sub>x</sub></var> and <var>t<sub>y</sub></var> 190subsequently shift the image pixels so that those that are moved out of the 191image area are cut off.</p> 192 193<p>The transformation matrix complies with the left-handed pixel coordinate 194system: positive <var>x</var> and <var>y</var> directions 195are rightward and downward, resp.; positive rotation is clockwise.</p> 196 197<p> If the translation coefficients <var>t<sub>x</sub></var> and 198<var>t<sub>y</sub></var> are omitted they default to 0,0. Therefore, 199four parameters suffice for rotation and scaling without translation.</p> 200 201<p>Scaling by the factors <var>s<sub>x</sub></var> and 202<var>s<sub>y</sub></var> in the <var>x</var> and <var>y</var> directions, 203respectively, is accomplished with the following.</p> 204 205<p>See <a href="command-line-options.html#transform">-transform</a>, and the <a 206href="command-line-options.html#distort">-distort</a> method '<code>Affineprojection</code> for more 207information </p> 208 209 210<pre class="highlight"><code>-affine <var>s<sub>x</sub></var>,0,0,<var>s<sub>y</sub></var> 211</code></pre> 212 213<p>Translation by a displacement (<var>t<sub>x</sub></var>, <var>t<sub>y</sub></var>) is accomplished like so:</p> 214 215<pre class="highlight"><code>-affine 1,0,0,1,<var>t<sub>x</sub></var>,<var>t<sub>y</sub></var> 216</code></pre> 217 218<p>Rotate clockwise about the origin (the upper left-hand corner) by an angle 219<var>a</var> by letting <var>c</var> = cos(<var>a</var>), <var>s</var> 220= sin(<var>a</var>), and using the following.</p> 221 222<pre class="highlight"><code>-affine <var>c</var>,<var>s</var>,-<var>s</var>,<var>c</var> 223</code></pre> 224 225<p>The cumulative effect of a sequence of <a href="command-line-options.html#affine" >-affine</a> 226transformations can be accomplished by instead by a single <a href="command-line-options.html#affine" 227>-affine</a> operation using the matrix equal to the product of the matrices 228of the individual transformations.</p> 229 230<p>An attempt is made to detect near-singular transformation matrices. If the 231matrix determinant has a sufficiently small absolute value it is rejected.</p> 232 233<div style="margin: auto;"> 234 <h3><a class="anchor" id="alpha"></a>-alpha <var>type</var></h3> 235</div> 236 237<p class="magick-description">Gives control of the alpha/matte channel of an image.</p> 238 239<p>Used to set a flag on an image indicating whether or not to use existing alpha 240channel data, to create an alpha channel, or to perform other operations on the alpha channel. Choose the argument <var>type</var> from the list below.</p> 241 242<dl class="row"> 243 <dt class="col-md-4">Activate</dt> 244 <dd class="col-md-8"> 245 Enable the image's transparency channel. Note normally Set 246 should be used instead of this, unless you specifically need to 247 preserve existing (but specifically turned Off) transparency 248 channel. </dd> 249 250 <dt class="col-md-4">Associate</dt> 251 <dd class="col-md-8"> 252 associate the alpha channel with the image.</dd> 253 254 <dt class="col-md-4">Deactivate</dt> 255 <dd class="col-md-8"> 256 Disables the image's transparency channel. Does not delete or change the 257 existing data, just turns off the use of that data.</dd> 258 259 <dt class="col-md-4">Disassociate</dt> 260 <dd class="col-md-8"> 261 disassociate the alpha channel from the image.</dd> 262 263 <dt class="col-md-4">Set</dt> 264 <dd class="col-md-8"> 265 Activates the alpha/matte channel. If it was previously turned off 266 then it also resets the channel to opaque. If the image already had 267 the alpha channel turned on, it will have no effect.</dd> 268 269 <dt class="col-md-4">Opaque</dt> 270 <dd class="col-md-8"> 271 Enables the alpha/matte channel and forces it to be fully opaque. 272 </dd> 273 274 <dt class="col-md-4">Transparent</dt> 275 <dd class="col-md-8"> 276 Activates the alpha/matte channel and forces it to be fully 277 transparent. This effectively creates a fully transparent image the 278 same size as the original and with all its original RGB data still 279 intact, but fully transparent. </dd> 280 281 <dt class="col-md-4">Extract</dt> 282 <dd class="col-md-8"> 283 Copies the alpha channel values into all the color channels and turns 284 'Off' the the image's transparency, so as to generate 285 a grayscale mask of the image's shape. The alpha channel data is left 286 intact just deactivated. This is the inverse of 'Copy'. 287 </dd> 288 289 <dt class="col-md-4">Copy</dt> 290 <dd class="col-md-8"> 291 Turns 'On' the alpha/matte channel, then copies the 292 grayscale intensity of the image, into the alpha channel, converting 293 a grayscale mask into a transparent shaped mask ready to be colored 294 appropriately. The color channels are not modified. </dd> 295 296 <dt class="col-md-4">Shape</dt> 297 <dd class="col-md-8"> 298 As per 'Copy' but also colors the resulting shape mask with 299 the current background color. That is the RGB color channels is 300 replaced, with appropriate alpha shape. 301 </dd> 302 303 <dt class="col-md-4">Remove</dt> 304 <dd class="col-md-8"> 305 Composite the image over the background color. 306 </dd> 307 308 <dt class="col-md-4">Background</dt> 309 <dd class="col-md-8"> 310 Set any fully-transparent pixel to the background color, while leaving 311 it fully-transparent. This can make some image file formats, such as 312 PNG, smaller as the RGB values of transparent pixels are more uniform, 313 and thus can compress better. 314 </dd> 315</dl> 316 317<p>Note that while the obsolete <code>+matte</code> operation was the 318same as "<code><a href="command-line-options.html#alpha" >-alpha</a> Off</code>", the <code> 319>-matte</code> operation was the same as "<code><a href="command-line-options.html#alpha" >-alpha</a> 320Set</code>" and not "<code><a href="command-line-options.html#alpha" >-alpha</a> On</code>". </p> 321 322<div style="margin: auto;"> 323 <h3><a class="anchor" id="annotate"></a> 324 -annotate <var>degrees</var> <var>text</var><br /> 325 -annotate <var>Xdegrees</var>x<var>Ydegrees</var> <var>text</var><br /> -annotate <var>Xdegrees</var>x<var>Ydegrees</var> {+-}<var>t<sub>x</sub></var>{+-}<var>t<sub>y</sub></var> <var>text</var><br /> -annotate {+-}<var>t<sub>x</sub></var>{+-}<var>t<sub>y</sub></var> <var>text</var></h3> 326</div> 327 328<p class="magick-description">Annotate an image with text</p> 329 330<p>This is a convenience for annotating an image with text. For more precise 331control over text annotations, use <a href="command-line-options.html#draw">-draw</a>.</p> 332 333 334<p>The values <var>Xdegrees</var> and <var>Ydegrees</var> 335control the shears applied to the text, while <var>t<sub>x</sub></var> and <var>t<sub>y</sub></var> are offsets that give the location of the text relative any <a href="command-line-options.html#gravity" >-gravity</a> setting and defaults to the upper left corner of the image.</p> 336 337<p>Using <a href="command-line-options.html#annotate">-annotate</a> <var>degrees</var> 338or <a href="command-line-options.html#annotate">-annotate</a> <var>degrees</var>x<var>degrees</var> produces an unsheared rotation of the text. The 339direction of the rotation is positive, which means a clockwise rotation if <var>degrees</var> is positive. (This conforms to the usual mathematical 340convention once it is realized that the positive <var>y</var>–direction is 341conventionally considered to be <var>downward</var> for images.)</p> 342 343<p>The new (transformed) coordinates (<var>x'</var>, <var>y'</var>) of a pixel at position (<var>x</var>, <var>y</var>) in the image are calculated using the following matrix 344equation.</p> 345 346<p class="text-center"><img class="img-thumbnail" alt="annotate transformation" src="../images/annotate.png"/></p> 347 348<p>If <var>t<sub>x</sub></var> and <var>t<sub>y</sub></var> are omitted, they default to 0. This makes the 349bottom-left of the text becomes the upper-left corner of the image, which is 350probably undesirable. Adding a <a href="command-line-options.html#gravity" >-gravity</a> option in this 351case leads to nice results.</p> 352 353<p>Text is any UTF-8 encoded character sequence. If <var>text</var> 354is of the form '@mytext.txt', the text is read from the file 355<code>mytext.txt</code>. Text in a file is taken literally; no embedded 356formatting characters are recognized.</p> 357 358<div style="margin: auto;"> 359 <h3><a class="anchor" id="antialias"></a>-antialias</h3> 360</div> 361 362<p class="magick-description">Enable/Disable of the rendering of anti-aliasing pixels when drawing fonts and lines.</p> 363 364<p>By default, objects (e.g. text, lines, polygons, etc.) are antialiased when 365drawn. Use <a href="command-line-options.html#antialias">+antialias</a> to disable the addition of 366antialiasing edge pixels. This will then reduce the number of colors added to 367an image to just the colors being directly drawn. That is, no mixed colors 368are added when drawing such objects. </p> 369 370<div style="margin: auto;"> 371 <h3><a class="anchor" id="append"></a>-append</h3> 372</div> 373 374<p class="magick-description">Join current images vertically or horizontally.</p> 375 376<p>This option creates a single longer image, by joining all the current 377images in sequence top-to-bottom. Use <a href="command-line-options.html#append">+append</a> to 378stack images left-to-right. </p> 379 380<p>If they are not of the same width, narrower images are padded with the 381current <a href="command-line-options.html#background">-background</a> color setting, and their 382position relative to each other can be controlled by the current <a 383href="command-line-options.html#gravity">-gravity</a> setting. </p> 384 385 386<div style="margin: auto;"> 387 <h3><a class="anchor" id="attenuate"></a>-attenuate <var>value</var></h3> 388</div> 389 390<p class="magick-description">Lessen (or intensify) when adding noise to an image.</p> 391 392<p>If unset the value is equivalent to 1.0, or a maximum noise addition</p> 393 394<div style="margin: auto;"> 395 <h3><a class="anchor" id="authenticate"></a>-authenticate <var>password</var></h3> 396</div> 397 398<p class="magick-description">Decrypt a PDF with a password.</p> 399 400<p>Use this option to supply a <var>password</var> for decrypting 401a PDF that has been encrypted using Microsoft Crypto API (MSC API). The 402encrypting using the MSC API is not supported.</p> 403 404<p>For a different encryption method, see <a href="command-line-options.html#encipher">-encipher</a> 405and <a href="command-line-options.html#decipher">-decipher</a>. </p> 406 407 408<div style="margin: auto;"> 409 <h3><a class="anchor" id="auto-gamma"></a>-auto-gamma</h3> 410</div> 411 412<p class="magick-description">Automagically adjust gamma level of image.</p> 413 414<p>This calculates the mean values of an image, then applies a calculated <a 415href="command-line-options.html#gamma" >-gamma</a> adjustment so that the mean color in the 416image will get a value of 50%. </p> 417 418<p>This means that any solid 'gray' image becomes 50% gray. </p> 419 420<p>This works well for real-life images with little or no extreme dark and 421light areas, but tend to fail for images with large amounts of bright sky or 422dark shadows. It also does not work well for diagrams or cartoon like images. 423</p> 424 425<p>It uses the <a href="command-line-options.html#channel" >-channel</a> setting, (including the 426'<var>sync</var>' flag for channel synchronization), to determine which color 427values is used and modified. As the default <a href="command-line-options.html#channel" 428>-channel</a> setting is '<var>RGB,sync</var>', channels are modified 429together by the same gamma value, preserving colors. </p> 430 431 432 433<div style="margin: auto;"> 434 <h3><a class="anchor" id="auto-level"></a>-auto-level</h3> 435</div> 436 437<p class="magick-description">Automagically adjust color levels of image.</p> 438 439<p>This is a 'perfect' image normalization operator. It finds the exact 440minimum and maximum color values in the image and then applies a <a 441href="command-line-options.html#level" >-level</a> operator to stretch the values to the full range of 442values. </p> 443 444<p>The operator is not typically used for real-life images, image scans, or 445JPEG format images, as a single 'out-rider' pixel can set a bad min/max values 446for the <a href="command-line-options.html#level" >-level</a> operation. On the other hand it is the 447right operator to use for color stretching gradient images being used to 448generate Color lookup tables, distortion maps, or other 'mathematically' 449defined images. </p> 450 451<p>The operator is very similar to the <a href="command-line-options.html#normalize">-normalize</a>, <a 452href="command-line-options.html#contrast-stretch" >-contrast-stretch</a>, and <a href="command-line-options.html#linear-stretch" 453>-linear-stretch</a> operators, but without 'histogram binning' or 'clipping' 454problems that these operators may have. That is <a href="command-line-options.html#auto-level" 455>-auto-level</a> is the perfect or ideal version these operators. </p> 456 457<p>It uses the <a href="command-line-options.html#channel" >-channel</a> setting, (including the 458special '<var>sync</var>' flag for channel synchronization), to determine 459which color values are used and modified. As the default <a 460href="command-line-options.html#channel" >+channel</a> setting is '<var>RGB,sync</var>', the 461'<var>sync</var>' ensures that the color channels will are modified 462together by the same gamma value, preserving colors, and ignoring 463transparency. </p> 464 465 466<div style="margin: auto;"> 467 <h3><a class="anchor" id="auto-orient"></a>-auto-orient</h3> 468</div> 469 470<p class="magick-description">adjusts an image so that its orientation is suitable for viewing (i.e. top-left orientation).</p> 471 472<p>This operator reads and resets the EXIF image profile setting 'Orientation' 473and then performs the appropriate 90 degree rotation on the image to orient 474the image, for correct viewing. </p> 475 476<p>This EXIF profile setting is usually set using a gravity sensor in digital 477camera, however photos taken directly downward or upward may not have an 478appropriate value. Also images that have been orientation 'corrected' without 479reseting this setting, may be 'corrected' again resulting in a incorrect 480result. If the EXIF profile was previously stripped, the <a 481href="command-line-options.html#auto-orient" >-auto-orient</a> operator will do nothing. </p> 482 483<div style="margin: auto;"> 484 <h3><a class="anchor" id="auto-threshold"></a>-auto-threshold <var>method</var></h3> 485</div> 486 487<p class="magick-description">automatically perform image thresholding.</p> 488 489<p>Here are the valid methods:</p> 490 491<dl class="row"> 492<dt class="col-md-4">Undefined</dt><dd class="col-md-8">0: No method specified (equivalent to '<code>OTSU</code>').</dd> 493<dt class="col-md-4">Kapur</dt><dd class="col-md-8">maximum entropy thresholding.</dd> 494<dt class="col-md-4">OTSU</dt><dd class="col-md-8">cluster-based image thresholding.</dd> 495<dt class="col-md-4">Triangle</dt><dd class="col-md-8">a geometric thresholding method.</dd> 496</dl> 497 498<p>The computed threshold is returned as the <kbd>auto-threshold:threshold</kbd> image property.</p> 499 500<div style="margin: auto;"> 501 <h3><a class="anchor" id="average"></a>-average</h3> 502</div> 503 504<p class="magick-description">Average a set of images.</p> 505 506<p>An error results if the images are not identically sized.</p> 507 508 509<div style="margin: auto;"> 510 <h3><a class="anchor" id="backdrop"></a>-backdrop</h3> 511</div> 512 513<p class="magick-description">Display the image centered on a backdrop.</p> 514 515<p>This backdrop covers the entire workstation screen and is useful for hiding 516other X window activity while viewing the image. The color of the backdrop is 517specified as the background color. The color is specified using the format 518described under the <a href="command-line-options.html#fill">-fill</a> option.</p> 519 520<div style="margin: auto;"> 521 <h3><a class="anchor" id="background"></a>-background <var>color</var></h3> 522</div> 523 524<p class="magick-description">Set the background color.</p> 525 526<p>The color is specified using the format described under the <a 527href="command-line-options.html#fill">-fill</a> option. The default background color (if none is 528specified or found in the image) is white.</p> 529 530<div style="margin: auto;"> 531 <h3><a class="anchor" id="bench"></a>-bench <var>iterations</var></h3> 532</div> 533 534<p class="magick-description">Measure performance.</p> 535 536<p>Repeat the entire command for the given number of <var>iterations</var> and report the user-time and elapsed time. For instance, 537consider the following command and its output. Modify the benchmark with the 538-duration to run the benchmark for a fixed number of seconds and -concurrent 539to run the benchmark in parallel (requires the OpenMP feature).</p> 540 541<pre class="highlight"><code>-> convert logo: -resize 200% -bench 5 logo.png 542Performance[1]: 5i 1.344ips 1.000e 3.710u 0:03.720 543Performance[2]: 5i 1.634ips 0.549e 3.890u 0:03.060 544Performance[3]: 5i 2.174ips 0.618e 3.190u 0:02.300 545Performance[4]: 5i 1.678ips 0.555e 3.810u 0:02.980 546Performance[4]: 5i 0.875657ips 6.880u 0:05.710 547</code></pre> 548 549<p>In this example, 5 iterations were completed at 2.174 iterations per 550second, using 3 threads and 3.190 seconds of the user allotted time, for 551a total elapsed time of 2.300 seconds.</p> 552 553<div style="margin: auto;"> 554 <h3><a class="anchor" id="bias"></a>-bias <var>value</var>{<var>%</var>}</h3> 555</div> 556 557<p class="magick-description">Add bias when convolving an image.</p> 558 559<p>This option shifts the output of <a href="command-line-options.html#convolve">‑convolve</a> so that 560positive and negative results are relative to the specified bias value. </p> 561 562<p>This is important for non-HDRI compilations of ImageMagick when dealing 563with convolutions that contain negative as well as positive values. This is 564especially the case with convolutions involving high pass filters or edge 565detection. Without an output bias, the negative values are clipped at 566zero.</p> 567 568<p>When using an ImageMagick with the HDRI compile-time setting, <a href="command-line-options.html#bias">‑bias</a> is not needed, as ImageMagick is able to store/handle any 569negative results without clipping to the color value range 570(0..QuantumRange).</p> 571 572<p>See the discussion on HDRI implementations of ImageMagick on the page <a 573href="high-dynamic-range.html" >High Dynamic-Range Images</a>. For more 574about HDRI go the ImageMagick <a 575href="../Usage/basics/#hdri" >Usage</a> pages or this 576<a 577href="http://en.wikipedia.org/wiki/High_dynamic_range_imaging">Wikipedia</a> 578entry. </p> 579 580<div style="margin: auto;"> 581 <h3><a class="anchor" id="black-point-compensation"></a>-black-point-compensation</h3> 582</div> 583 584<p class="magick-description">Use black point compensation.</p> 585 586<div style="margin: auto;"> 587 <h3><a class="anchor" id="black-threshold"></a>-black-threshold <var>value</var>{<var>%</var>}</h3> 588</div> 589 590<p class="magick-description">Force to black all pixels below the threshold while leaving all pixels at or above the threshold unchanged.</p> 591 592<p> The threshold value can be given as a percentage or as an absolute integer 593value within [0, <var>QuantumRange</var>] corresponding to the 594desired <a href="command-line-options.html#channel">‑channel</a> value. See <a href="command-line-options.html#threshold">‑threshold</a>for more details on thresholds and resulting values. </p> 595 596 597<div style="margin: auto;"> 598 <h3><a class="anchor" id="blend"></a>-blend <var>geometry</var></h3> 599</div> 600 601<p class="magick-description">blend an image into another by the given absolute value or percent.</p> 602 603<p>Blend will average the images together ('plus') according to the 604percentages given and each pixels transparency. If only a single percentage 605value is given it sets the weight of the composite or 'source' image, while 606the background image is weighted by the exact opposite amount. That is a 607<code>-blend 30%</code> merges 30% of the 'source' image with 70% of the 608'destination' image. Thus it is equivalent to <code>-blend 30x70%</code>.</p> 609 610 611<div style="margin: auto;"> 612 <h3><a class="anchor" id="blue-primary"></a>-blue-primary <var>x</var>,<var>y</var></h3> 613</div> 614 615<p class="magick-description">Set the blue chromaticity primary point.</p> 616 617<div style="margin: auto;"> 618 <h3><a class="anchor" id="blue-shift"></a>-blue-shift <var>factor</var></h3> 619</div> 620 621<p class="magick-description">simulate a scene at nighttime in the moonlight. Start with a factor of 1.5</p> 622 623<div style="margin: auto;"> 624 625<div style="margin: auto;"> 626 <h3><a class="anchor" id="blur"></a>-blur <var>radius</var><br />-blur <var>radius</var>x<var>sigma</var></h3> 627</div> 628 629<p class="magick-description">Reduce image noise and reduce detail levels.</p> 630 631<p>Convolve the image with a Gaussian or normal distribution using the given 632<var >Sigma</var> value. The formula is:</p> 633 634<p class="text-center"><img class="img-thumbnail" alt="gaussian distribution" width="243px" height="42px" src="../images/gaussian-blur.png"/></p> 635 636<p>The <var >Sigma</var> value is the important argument, and 637determines the actual amount of blurring that will take place. </p> 638 639<p>The <var >Radius</var> is only used to determine the size of the 640array which will hold the calculated Gaussian distribution. It should be an 641integer. If not given, or set to zero, IM will calculate the largest possible 642radius that will provide meaningful results for the Gaussian distribution. 643</p> 644 645<p>The larger the <var >Radius</var> the slower the 646operation is. However too small a <var >Radius</var>, and severe 647aliasing effects may result. As a guideline, <var >Radius</var> 648should be at least twice the <var >Sigma</var> value, though three 649times will produce a more accurate result. </p> 650 651<p>This option differs from <a href="command-line-options.html#gaussian-blur">-gaussian-blur</a> simply 652by taking advantage of the separability properties of the distribution. Here 653we apply a single-dimensional Gaussian matrix in the horizontal direction, 654then repeat the process in the vertical direction.</p> 655 656<p>The <a href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting will determine how 657pixels which are outside the image proper are blurred into the final result. 658</p> 659 660 661<div style="margin: auto;"> 662 <h3><a class="anchor" id="border"></a>-border <var>geometry</var></h3> 663</div> 664 665<p class="magick-description">Surround the image with a border of color. </p> 666 667<p>Set the width and height using the <var>size</var> portion of the 668<var>geometry</var> argument. See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. Offsets are 669ignored. </p> 670 671<p>As of IM 6.7.8-8, the <var>geometry</var> arguments behave as follows:</p> 672 673<dl class="row"> 674<dt class="col-md-4"><var>value</var></dt> 675<dd class="col-md-8">value is added to both left/right and top/bottom</dd> 676<dt class="col-md-4"><var>value-x</var><code>x</code></dt> 677<dd class="col-md-8">value-x is added only to left/right and top/bottom are unchanged</dd> 678<dt class="col-md-4"><code>x</code><var>value-y</var></dt> 679<dd class="col-md-8">value-y is added only to top/bottom and left/right are unchanged</dd> 680<dt class="col-md-4"><var>value-x</var><code>x</code><var>value-y</var></dt> 681<dd class="col-md-8">value-x is added to left/right and value-y added to top/bottom</dd> 682<dt class="col-md-4"><var>value-x</var><code>x</code>0</dt> 683<dd class="col-md-8">value-x is added only to left/right and top/bottom are unchanged</dd> 684<dt class="col-md-4">0<code>x</code><var>value-y</var></dt> 685<dd class="col-md-8">value-y is added only to top/bottom and left/right are unchanged</dd> 686<dt class="col-md-4"><var>value</var>%</dt> 687<dd class="col-md-8">value % of width is added to left/right and value % of height is added to top/bottom</dd> 688<dt class="col-md-4"><var>value-x</var><code>x</code>%</dt> 689<dd class="col-md-8">value-x % of width is added to left/right and to top/bottom</dd> 690<dt class="col-md-4">x<var>value-y</var>%</dt> 691<dd class="col-md-8">value-y % of height is added to top/bottom and to left/right</dd> 692<dt class="col-md-4"><var>value-x</var>%<code>x</code><var>value-y</var>%</dt> 693<dd class="col-md-8">value-x % of width is added to left/right and value-y % of height is added to top/bottom</dd> 694<dt class="col-md-4"><var>value-x</var>%<code>x</code>0%</dt> 695<dd class="col-md-8">value-x % of width is added to left/right and top/bottom are unchanged</dd> 696<dt class="col-md-4">0%<code>x</code><var>value-y</var>%</dt> 697<dd class="col-md-8">value-y % of height is added to top/bottom and left/right are unchanged</dd> 698</dl> 699 700<p>Set the border color by preceding with the <a 701href="command-line-options.html#bordercolor">-bordercolor</a> setting.</p> 702 703<p>The <a href="command-line-options.html#border">-border</a> operation is affected by the current <a 704href="command-line-options.html#compose">-compose</a> setting and assumes that this is using the default 705'<code>Over</code>' composition method. It generates an image of the appropriate 706size colors by the current <a href="command-line-options.html#bordercolor">-bordercolor</a> before 707overlaying the original image in the center of this net image. This means that 708with the default compose method of '<code>Over</code>' any transparent parts may 709be replaced by the current <a href="command-line-options.html#bordercolor">-bordercolor</a> setting.</p> 710<p>See also the <a href="command-line-options.html#frame">-frame</a> option, which has more 711functionality.</p> 712 713<div style="margin: auto;"> 714 <h3><a class="anchor" id="bordercolor"></a>-bordercolor <var>color</var></h3> 715</div> 716 717<p class="magick-description">Set the border color.</p> 718 719<p>The color is specified using the format described under the <a href="command-line-options.html#fill">-fill</a> option.</p> 720 721<p>The default border color is <code>#DFDFDF</code>, <span style="background-color: #dfdfdf;">this shade of gray</span>.</p> 722 723<div style="margin: auto;"> 724 <h3><a class="anchor" id="borderwidth"></a>-borderwidth <var>geometry</var> </h3> 725</div> 726 727<p class="magick-description">Set the border width.</p> 728 729<div style="margin: auto;"> 730 <h3><a class="anchor" id="brightness-contrast"></a>-brightness-contrast <var>brightness</var><br />-brightness-contrast <var>brightness</var>{x<var>contrast</var>}{<var>%</var>}</h3> 731</div> 732 733<p class="magick-description">Adjust the brightness and/or contrast of the image.</p> 734 735<p>Brightness and Contrast values apply changes to the input image. They are 736not absolute settings. A brightness or contrast value of zero means no change. 737The range of values is -100 to +100 on each. Positive values increase the 738brightness or contrast and negative values decrease the brightness or contrast. 739To control only contrast, set the brightness=0. To control only brightness, 740set contrast=0 or just leave it off.</p> 741 742<p>You may also use <a href="command-line-options.html#fill">-channel</a> to control which channels to 743apply the brightness and/or contrast change. The default is to apply the same 744transformation to all channels.</p> 745 746<p>Brightness and Contrast arguments are converted to offset and slope of a 747linear transform and applied 748using <a href="command-line-options.html#fill">-function polynomial "slope,offset"</a>.</p> 749 750<p>The slope varies from 0 at contrast=-100 to almost vertical at 751contrast=+100. For brightness=0 and contrast=-100, the result are totally 752midgray. For brightness=0 and contrast=+100, the result will approach but 753not quite reach a threshold at midgray; that is the linear transformation 754is a very steep vertical line at mid gray.</p> 755 756<p>Negative slopes, i.e. negating the image, are not possible with this 757function. All achievable slopes are zero or positive.</p> 758 759<p>The offset varies from -0.5 at brightness=-100 to 0 at brightness=0 to +0.5 760at brightness=+100. Thus, when contrast=0 and brightness=100, the result is 761totally white. Similarly, when contrast=0 and brightness=-100, the result is 762totally black.</p> 763 764<p>As the range of values for the arguments are -100 to +100, adding the '%' 765symbol is no different than leaving it off.</p> 766 767<div style="margin: auto;"> 768 <h3><a class="anchor" id="cache"></a>-cache <var>threshold</var></h3> 769</div> 770 771<p class="magick-description">(This option has been replaced by the <a href='command-line-options.html#limit'>-limit</a> option).</p> 772 773<div style="margin: auto;"> 774 <h3><a class="anchor" id="canny"></a>-canny <var>radius</var><br/>-canny <var>radius</var>x<var>sigma</var>{<var>+lower-percent</var>}{<var>+upper-percent</var>}</h3> 775</div> 776 777<p class="magick-description">Canny edge detector uses a multi-stage algorithm to detect a wide range of edges in the image.</p> 778 779<p>The thresholds range from 0 to 100% (e.g. -canny 0x1+10%+30%) with {<var>+lower-percent</var>} < {<var>+upper-percent</var>}. If {<var>+upper-percent</var>} is increased but {<var>+lower-percent</var>} remains the same, lesser edge components will be detected, but their lengths will be the same. If {<var>+lower-percent</var>} is increased but {<var>+upper-percent</var>} is the same, the same number of edge components will be detected but their lengths will be shorter. The default thresholds are shown. The <var>radius</var>x<var>sigma</var> controls a gaussian blur applied to the input image to reduce noise and smooth the edges.</p> 780 781<div style="margin: auto;"> 782 <h3><a class="anchor" id="caption"></a>-caption <var>string</var></h3> 783</div> 784 785<p class="magick-description">Assign a caption to an image.</p> 786 787<p>This option sets the caption meta-data of an image read in after this 788option has been given. To modify a caption of images already in memory use 789"<code><a href="command-line-options.html#set">-set</a> caption</code>". </p> 790 791<p>The caption can contain special format characters listed in the <a 792href="../www/escape.html">Format and 793Print Image Properties</a>. These attributes are expanded when the caption 794is finally assigned to the individual images. </p> 795 796<p>If the first character of <var>string</var> is <var>@</var>, the image caption is read from a file titled by the 797remaining characters in the string. Comments read in from a file are literal; 798no embedded formatting characters are recognized.</p> 799 800<p>Caption meta-data is not visible on the image itself. To do that use the 801<a href="command-line-options.html#annotate">-annotate</a> or <a href="command-line-options.html#draw">-draw</a> options 802instead.</p> 803 804<p>For example,</p> 805 806<pre class="highlight"><code>-caption "%m:%f %wx%h" bird.miff 807</code></pre> 808 809<p>produces an image caption of <code>MIFF:bird.miff 512x480</code> (assuming 810that the image <code>bird.miff</code> has a width of 512 and a height of 811480.</p> 812 813 814<div style="margin: auto;"> 815 <h3><a class="anchor" id="cdl"></a>-cdl <var>filename</var></h3> 816</div> 817 818<p class="magick-description">color correct with a color decision list.</p> 819 820<p>Here is an example color correction collection:</p> 821 822<pre class="highlight"><code><?xml version="1.0" encoding="UTF-8"?> 823<ColorCorrectionCollection xmlns="urn:ASC:CDL:v1.2"> 824 <ColorCorrection id="cc06668"> 825 <SOPNode> 826 <Slope> 0.9 1.2 0.5 </Slope> 827 <Offset> 0.4 -0.5 0.6 </Offset> 828 <Power> 1.0 0.8 1.5 </Power> 829 </SOPNode> 830 <SATNode> 831 <Saturation> 0.85 </Saturation> 832 </SATNode> 833 </ColorCorrection> 834</ColorCorrectionCollection> 835</code></pre> 836 837<div style="margin: auto;"> 838 <h3><a class="anchor" id="channel"></a>-channel <var>type</var></h3> 839</div> 840 841<p class="magick-description">Specify those image color channels to which subsequent operators are limited.</p> 842 843<p>Choose from: <code>Red</code>, <code>Green</code>, <code>Blue</code>, 844<code>Alpha</code>, <code>Gray</code>, <code>Cyan</code>, <code>Magenta</code>, 845<code>Yellow</code>, <code>Black</code>, <code>Opacity</code>, 846<code>Index</code>, <code>RGB</code>, <code>RGBA</code>, <code>CMYK</code>, or 847<code>CMYKA</code>.</p> 848 849<p>The channels above can also be specified as a comma-separated list or can be 850abbreviated as a concatenation of the letters '<code>R</code>', '<code>G</code>', 851'<code>B</code>', '<code>A</code>', '<code>O</code>', '<code>C</code>', 852'<code>M</code>', '<code>Y</code>', '<code>K</code>'.</p> 853 854<p>The numerals 0 to 31 may also be used to specify channels, where 0 to 5 are: <br /> 855'<code>0</code>' equals <code>Red</code> or <code>Cyan</code> <br /> 856'<code>1</code>' equals <code>Green</code> or <code>Magenta</code> <br /> 857'<code>2</code>' equals <code>Blue</code> or <code>Yellow</code> <br /> 858'<code>3</code>' equals <code>Black</code> <br /> 859'<code>4</code>' equals <code>Alpha</code> or <code>Opacity</code> <br /> 860'<code>5</code>' equals <code>Index</code></p> 861 862<p>For example, to only select the <code>Red</code> and <code>Blue</code> channels 863you can use any of the following:</p> 864<pre class="highlight"> 865<code>-channel Red,Blue</code> 866<code>-channel R,B</code> 867<code>-channel RB</code> 868<code>-channel 0,2</code> 869</pre> 870 871<p>All the channels that are present in an image can be specified using the 872special channel type <code>All</code>. Not all operators are 'channel capable', 873but generally any operators that are generally 'grey-scale' image operators, 874will understand this setting. See individual operator documentation. </p> 875 876<br/> 877 878<p>On top of the normal channel selection an extra flag can be specified, 879'<code>Sync</code>'. This is turned on by default and if set means that 880operators that understand this flag should perform: cross-channel 881synchronization of the channels. If not specified, then most grey-scale 882operators will apply their image processing operations to each individual 883channel (as specified by the rest of the <a href="command-line-options.html#channel">-channel</a> 884setting) completely independently from each other. </p> 885 886<p>For example for operators such as <a href="command-line-options.html#auto-level">-auto-level</a> and 887<a href="command-line-options.html#auto-gamma">-auto-gamma</a> the color channels are modified 888together in exactly the same way so that colors will remain in-sync. Without 889it being set, then each channel is modified separately and 890independently, which may produce color distortion. </p> 891 892<p>The <a href="command-line-options.html#morphology">-morphology</a> '<code>Convolve</code>' method 893and the <a href="command-line-options.html#compose">-compose</a> mathematical methods, also understands 894the '<code>Sync</code>' flag to modify the behavior of pixel colors according 895to the alpha channel (if present). That is to say it will modify the image 896processing with the understanding that fully-transparent colors should not 897contribute to the final result. </p> 898 899<p>Basically, by default, operators work with color channels in synchronous, and 900treats transparency as special, unless the <a href="command-line-options.html#channel">-channel</a> 901setting is modified so as to remove the effect of the '<code>Sync</code>' flag. 902How each operator does this depends on that operators current implementation. 903Not all operators understands this flag at this time, but that is changing. 904</p> 905 906<p>To print a complete list of channel types, use <a href="command-line-options.html#list">-list 907channel</a>.</p> 908 909<p>By default, ImageMagick sets <a href="command-line-options.html#channel">-channel</a> to the value 910'<code>RGBK,sync</code>', which specifies that operators act on all color 911channels except the transparency channel, and that all the color channels are 912to be modified in exactly the same way, with an understanding of transparency 913(depending on the operation being applied). The 'plus' form <a 914href="command-line-options.html#channel" >+channel</a> will reset the value back to this default. </p> 915 916<p>Options that are affected by the <a href="command-line-options.html#channel" >-channel</a> setting 917include the following. 918 919<a href="command-line-options.html#auto-gamma">-auto-gamma</a>, 920<a href="command-line-options.html#auto-level">-auto-level</a>, 921<a href="command-line-options.html#black-threshold">-black-threshold</a>, 922<a href="command-line-options.html#blur">-blur</a>, 923<a href="command-line-options.html#clamp">-clamp</a>, 924<a href="command-line-options.html#clut">-clut</a>, 925<a href="command-line-options.html#combine">-combine</a>, 926<a href="command-line-options.html#composite">-composite</a> (Mathematical compose methods only), 927<a href="command-line-options.html#convolve">-convolve</a>, 928<a href="command-line-options.html#contrast-stretch">-contrast-stretch</a>, 929<a href="command-line-options.html#evaluate">-evaluate</a>, 930<a href="command-line-options.html#function">-function</a>, 931<a href="command-line-options.html#fx">-fx</a>, 932<a href="command-line-options.html#gaussian-blur">-gaussian-blur</a>, 933<a href="command-line-options.html#hald-clut">-hald-clut</a>, 934<a href="command-line-options.html#motion-blur">-motion-blur</a>, 935<a href="command-line-options.html#morphology">-morphology</a>, 936<a href="command-line-options.html#negate">-negate</a>, 937<a href="command-line-options.html#normalize">-normalize</a>, 938<a href="command-line-options.html#ordered-dither">-ordered-dither</a>, 939<a href="command-line-options.html#radial-blur">-radial-blur</a>, 940<a href="command-line-options.html#random-threshold">-random-threshold</a>, 941<a href="command-line-options.html#range-threshold">-range-threshold</a>, 942<a href="command-line-options.html#separate">-separate</a>, 943<a href="command-line-options.html#threshold">-threshold</a>, and 944<a href="command-line-options.html#white-threshold">-white-threshold</a>. 945</p> 946 947<p>Warning, some operators behave differently when the <a href="command-line-options.html#channel" 948>+channel</a> default setting is in effect, versus ANY user defined <a 949href="command-line-options.html#channel" >-channel</a> setting (including the equivalent of the 950default). These operators have yet to be made to understand the newer 'Sync' 951flag. </p> 952 953<p>For example <a href="command-line-options.html#threshold">-threshold</a> will by default grayscale 954the image before thresholding, if no <a href="command-line-options.html#channel" >-channel</a> setting 955has been defined. This is not 'Sync flag controlled, yet. </p> 956 957<p>Also some operators such as <a href="command-line-options.html#blur">-blur</a>, <a 958href="command-line-options.html#gaussian-blur">-gaussian-blur</a>, will modify their handling of the 959color channels if the '<code>alpha</code>' channel is also enabled by <a 960href="command-line-options.html#channel" >-channel</a>. Generally this done to ensure that 961fully-transparent colors are treated as being fully-transparent, and thus any 962underlying 'hidden' color has no effect on the final results. Typically 963resulting in 'halo' effects. The newer <a href="command-line-options.html#morphology">-morphology</a> 964convolution equivalents however does have a understanding of the 'Sync' flag 965and will thus handle transparency correctly by default. </p> 966 967<p>As an alpha channel is optional within images, some operators will read the 968color channels of an image as a greyscale alpha mask, when the image has no 969alpha channel present, and the <a href="command-line-options.html#channel" >-channel</a> setting tells 970the operator to apply the operation using alpha channels. The <a 971href="command-line-options.html#clut">-clut</a> operator is a good example of this. </p> 972 973<div style="margin: auto;"> 974 <h3><a class="anchor" id="channel-fx"></a>-channel-fx <var>expression</var></h3> 975</div> 976 977<p class="magick-description">exchange, extract, or copy one or more image channels.</p> 978 979<p>The expression consists of one or more channels, either mnemonic or numeric (e.g. red or 0, green or 1, etc.), separated by certain operation symbols as follows:</p> 980 981<pre class="highlight"><code><=> exchange two channels (e.g. red<=>blue) 982=> copy one channel to another channel (e.g. red=>green) 983= assign a constant value to a channel (e.g. red=50%) 984, write new image with channels in the specified order (e.g. red, green) 985; add a new output image for the next set of channel operations (e.g. red; green; blue) 986| move to the next input image for the source of channel data (e.g. | gray=>alpha) 987</code></pre> 988 989<p>For example, to create 3 grayscale images from the red, green, and blue channels of an image, use:</p> 990 991<pre class="highlight"><code>-channel-fx "red; green; blue" 992</code></pre> 993 994<p>A channel without an operation symbol implies separate (i.e, semicolon).</p> 995 996<p>Here we take an sRGB image and a grayscale image and inject the grayscale image into the alpha channel:</p> 997<pre class="highlight"><code>convert wizard.png mask.pgm -channel-fx '| gray=>alpha' wizard-alpha.png 998</code></pre> 999<p>Use a similar command to define a read mask:</p> 1000<pre class="highlight"><code>convert wizard.png mask.pgm -channel-fx '| gray=>read-mask' wizard-mask.png 1001</code></pre> 1002 1003<p>Add <code>-debug pixel</code> prior to the <code>-channel-fx</code> option to track the channel morphology.</p> 1004 1005<div style="margin: auto;"> 1006 <h3><a class="anchor" id="charcoal"></a>-charcoal <var>factor</var></h3> 1007</div> 1008 1009<p class="magick-description">Simulate a charcoal drawing.</p> 1010 1011<div style="margin: auto;"> 1012 <h3><a class="anchor" id="chop"></a>-chop <var>geometry</var></h3> 1013</div> 1014 1015<p class="magick-description">Remove pixels from the interior of an image.</p> 1016 1017<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. The <var>width</var> 1018and <var>height</var> given in the of the <var>size</var> 1019portion of the <var>geometry</var> argument give the number of 1020columns and rows to remove. The <var>offset</var> portion of 1021the <var>geometry</var> argument is influenced by 1022a <a href="command-line-options.html#gravity">-gravity</a> setting, if present.</p> 1023 1024<p>The <a href="command-line-options.html#chop">-chop</a> option removes entire rows and columns, 1025and moves the remaining corner blocks leftward and upward to close the gaps.</p> 1026 1027<p>While it can remove internal rows and columns of pixels, it is more 1028typically used with as <a href="command-line-options.html#gravity">-gravity</a> setting and zero 1029offsets so as to remove a single edge from an image. Compare this to <a 1030href="command-line-options.html#shave" >-shave</a> which removes equal numbers of pixels from opposite 1031sides of the image. </p> 1032 1033<p>Using <a href="command-line-options.html#chop">-chop</a> effectively undoes the results of a <a 1034href="command-line-options.html#splice">-splice</a> that was given the same <var>geometry</var> and <a href="command-line-options.html#gravity">-gravity</a> settings. </p> 1035 1036<div style="margin: auto;"> 1037 <h3><a class="anchor" id="clahe"></a>-clahe <var>width</var>x<var>height</var>{%}{+}<var>number-bins</var>{+}<var>clip-limit</var>{!}</h3> 1038</div> 1039 1040<p class="magick-description">contrast limited adaptive histogram equalization.</p> 1041<p> The image is divided into tiles of <var>width</var> and <var>height</var> pixels. Append <code>%</code> to define the width and height as percentages of the image's dimensions. The tile size should be larger than the size of features to be preserved and respects the aspect ratio of the image. Add <code>!</code> to force an exact tile width and height. <var>number-bins</var> is the number of histogram bins per tile (min 2, max 65536). The number of histogram bins should be smaller than the number of pixels in a single tile. <var>clip-limit</var> is the contrast limit for localized changes in contrast. A clip-limit of 2 to 3 is a good starting place (e.g. -clahe 50x50%+128+3). Very large values will let the histogram equalization do whatever it wants to do, that is result in maximal local contrast. The value 1 will result in the original image. Note, if the number of bins and the clip-limit are ommitted, they default to 128 and no clipping respectively.</p> 1042 1043 1044<div style="margin: auto;"> 1045 <h3><a class="anchor" id="clamp"></a>-clamp</h3> 1046</div> 1047 1048<p class="magick-description">set each pixel whose value is below zero to zero and any the pixel whose value is above the quantum range to the quantum range (e.g. 65535) otherwise the pixel value remains unchanged.</p> 1049 1050<div style="margin: auto;"> 1051 <h3><a class="anchor" id="clip"></a>-clip</h3> 1052</div> 1053 1054<p class="magick-description">Apply the clipping path if one is present.</p> 1055 1056<p>If a clipping path is present, it is applied to subsequent operations.</p> 1057 1058<p>For example, in the command</p> 1059 1060<pre class="highlight"><code>convert cockatoo.tif -clip -negate negated.tif 1061</code></pre> 1062 1063<p>only the pixels within the clipping path are negated.</p> 1064 1065<p>The <a href="command-line-options.html#clip">-clip</a> feature requires SVG support. If the SVG 1066delegate library is not present, the option is ignored.</p> 1067 1068<p>Use <a href="command-line-options.html#clip">+clip</a> to disable clipping for subsequent operations.</p> 1069 1070<div style="margin: auto;"> 1071 <h3><a class="anchor" id="clip-mask"></a>-clip-mask</h3> 1072</div> 1073 1074<p class="magick-description">Clip the image as defined by this mask.</p> 1075 1076<p>Use the alpha channel of the current image as a mask. Any areas that is 1077white is not modified by any of the 'image processing operators' that follow, 1078until the mask is removed. Pixels in the black areas of the clip mask are 1079modified per the requirements of the operator. </p> 1080 1081<p>In some ways this is similar to (though not the same) as defining 1082a rectangular <a href="command-line-options.html#region" >-region</a>, or using the negative of the 1083mask (third) image in a three image <a href="command-line-options.html#composite" >-composite</a>, 1084operation. </p> 1085 1086<p>Use <a href="command-line-options.html#clip-mask">+clip-mask</a> to disable clipping for subsequent operations.</p> 1087 1088<div style="margin: auto;"> 1089 <h3><a class="anchor" id="clip-path"></a>-clip-path <var>id</var></h3> 1090</div> 1091 1092<p class="magick-description">Clip along a named path from the 8BIM profile.</p> 1093 1094<p>This is identical to <a href="command-line-options.html#clip">-clip</a> except choose a specific clip path in the event the image has more than one path available. </p> 1095 1096<p>Use <a href="command-line-options.html#clip-path">+clip-path</a> to disable clipping for subsequent operations.</p> 1097 1098<div style="margin: auto;"> 1099 <h3><a class="anchor" id="clone"></a>-clone <var>index(s)</var></h3> 1100</div> 1101 1102<p class="magick-description">make a clone of an image (or images).</p> 1103 1104<p>Inside parenthesis (where the operator is normally used) it will make a 1105clone of the images from the last 'pushed' image sequence, and adds them to 1106the end of the current image sequence. Outside parenthesis 1107(not recommended) it clones the images from the current image sequence. </p> 1108 1109<p>Specify the image by its index in the sequence. The first image is index 11100. Negative indexes are relative to the end of the sequence; for 1111example, <code>−1</code> 1112represents the last image of the sequence. Specify a range of images with a 1113dash (e.g. <code>0−4</code>). Separate multiple indexes with commas but no 1114spaces (e.g. <code>0,2,5</code>). A value of '<code>0−−1</code> will 1115effectively clone all the images. </p> 1116 1117<p>The <a href="command-line-options.html#clone">+clone</a> will simply make a copy of the last image 1118in the image sequence, and is thus equivalent to using an argument of 1119'<code>−1</code>'. </p> 1120 1121<div style="margin: auto;"> 1122 <h3><a class="anchor" id="clut"></a>-clut</h3> 1123</div> 1124 1125<p class="magick-description">Replace the channel values in the first image using each corresponding channel in the second image as a <b>c</b>olor <b>l</b>ook<b>u</b>p <b>t</b>able.</p> 1126 1127<p>The second (LUT) image is ordinarily a gradient image containing the 1128histogram mapping of how each channel should be modified. Typically it is a 1129either a single row or column image of replacement color values. If larger 1130than a single row or column, values are taken from a diagonal line from 1131top-left to bottom-right corners.</p> 1132 1133<p>The lookup is further controlled by the <a 1134href="command-line-options.html#interpolate">-interpolate</a> setting, which is especially handy for an 1135LUT which is not the full length needed by the ImageMagick installed Quality 1136(Q) level. Good settings for this are the '<code>bilinear</code>' and 1137'<code>bicubic</code>' interpolation settings, which give smooth color 1138gradients, and the '<code>integer</code>' setting for a direct, unsmoothed 1139lookup of color values. </p> 1140 1141<p>This operator is especially suited to replacing a grayscale image with a 1142specific color gradient from the CLUT image. </p> 1143 1144<p>Only the channel values defined by the <a href="command-line-options.html#channel">-channel</a> 1145setting will have their values replaced. In particular, since the default <a 1146href="command-line-options.html#channel">-channel</a> setting is <code>RGB</code>, this means that 1147transparency (alpha/matte channel) is not affected, unless the <a 1148href="command-line-options.html#channel">-channel</a> setting is modified. When the alpha channel is 1149set, it is treated by the <a href="command-line-options.html#clut" >-clut</a> operator in the same way 1150as the other channels, implying that alpha/matte values are replaced using the 1151alpha/matte values of the original image. </p> 1152 1153<p>If either the image being modified, or the lookup image, contains no 1154transparency (i.e. <a href="command-line-options.html#alpha" >-alpha</a> is turned 'off') but the <a 1155href="command-line-options.html#channel">-channel</a> setting includes alpha replacement, then it is 1156assumed that image represents a grayscale gradient which is used for the 1157replacement alpha values. That is you can use a grayscale CLUT image to 1158adjust a existing images alpha channel, or you can color a grayscale image 1159using colors form CLUT containing the desired colors, including transparency. 1160</p> 1161 1162<p>See also <a href="command-line-options.html#hald-clut" >-hald-clut</a> which replaces colors 1163according to the lookup of the full color RGB value from a 2D representation 1164of a 3D color cube. </p> 1165 1166 1167<div style="margin: auto;"> 1168 <h3><a class="anchor" id="coalesce"></a>-coalesce</h3> 1169</div> 1170 1171<p class="magick-description">Fully define the look of each frame of an GIF animation sequence, to form a 'film strip' animation.</p> 1172 1173<p>Overlay each image in an image sequence according to 1174its <a href="command-line-options.html#dispose">-dispose</a> meta-data, to reproduce the look of 1175an animation at each point in the animation sequence. All images should be 1176the same size, and are assigned appropriate GIF disposal settings for the 1177animation to continue working as expected as a GIF animation. Such frames 1178are more easily viewed and processed than the highly optimized GIF overlay 1179images. </p> 1180 1181<p>The animation can be re-optimized after processing using 1182the <a href="command-line-options.html#layers">-layers</a> method '<code>optimize</code>', although 1183there is no guarantee that the restored GIF animation optimization is 1184better than the original. </p> 1185 1186 1187<div style="margin: auto;"> 1188 <h3><a class="anchor" id="colorize"></a>-colorize <var>value</var></h3> 1189</div> 1190 1191<p class="magick-description">Colorize the image by an amount specified by <var>value</var> using the color specified by the most recent <a href="command-line-options.html#fill" >-fill</a> setting.</p> 1192 1193<p>Specify the amount of colorization as a percentage. Separate colorization 1194values can be applied to the red, green, and blue channels of the image with 1195a comma-delimited list of colorization 1196values (e.g., <code>-colorize 0,0,50</code>).</p> 1197 1198<div style="margin: auto;"> 1199 <h3><a class="anchor" id="colormap"></a>-colormap <var>type</var></h3> 1200</div> 1201 1202<p class="magick-description">Define the colormap type.</p> 1203 1204<p>The <var>type</var> can be <code>shared</code> or <code>private</code>.</p> 1205 1206<p>This option only applies when the default X server visual 1207is <code>PseudoColor</code> or <code>GrayScale</code>. Refer 1208to <a href="command-line-options.html#visual">-visual</a> for more details. By default, 1209a shared colormap is allocated. The image shares colors with 1210other X clients. Some image colors could be approximated, 1211therefore your image may look very different than intended. 1212If <code>private</code> is chosen, the image colors appear exactly 1213as they are defined. However, other clients may go <var>technicolor</var> 1214when the image colormap is installed.</p> 1215 1216<div style="margin: auto;"> 1217 <h3><a class="anchor" id="colors"></a>-colors <var>value</var></h3> 1218</div> 1219 1220<p class="magick-description">Set the preferred number of colors in the image.</p> 1221 1222<p>The actual number of colors in the image may be less than your request, 1223but never more. Note that this a color reduction option. Images with fewer 1224unique colors than specified by <var>value</var> will have any 1225duplicate or unused colors removed. The ordering of an existing color 1226palette may be altered. When converting an image from color to grayscale, 1227it is more efficient to convert the image to the gray colorspace before 1228reducing the number of colors. Refer to 1229the <a href="../www/quantize.html"> 1230color reduction algorithm</a> for more details.</p> 1231 1232<div style="margin: auto;"> 1233 <h3><a class="anchor" id="color-matrix"></a>-color-matrix <var>matrix</var></h3> 1234</div> 1235 1236<p class="magick-description">apply color correction to the image.</p> 1237 1238<p>This option permits saturation changes, hue rotation, luminance to alpha, 1239and various other effects. Although variable-sized transformation matrices 1240can be used, typically one uses a 5x5 matrix for an RGBA image and a 6x6 1241for CMYKA (or RGBA with offsets). The matrix is similar to those used by 1242Adobe Flash except offsets are in column 6 rather than 5 (in support of 1243CMYKA images) and offsets are normalized (divide Flash offset by 255).</p> 1244 1245<p>As an example, to add contrast to an image with offsets, try this command:</p> 1246 1247<pre class="highlight"><code>convert kittens.jpg -color-matrix \ 1248 " 1.5 0.0 0.0 0.0, 0.0, -0.157 \ 1249 0.0 1.5 0.0 0.0, 0.0, -0.157 \ 1250 0.0 0.0 1.5 0.0, 0.0, -0.157 \ 1251 0.0 0.0 0.0 1.0, 0.0, 0.0 \ 1252 0.0 0.0 0.0 0.0, 1.0, 0.0 \ 1253 0.0 0.0 0.0 0.0, 0.0, 1.0" kittens.png 1254</code></pre> 1255<div style="margin: auto;"> 1256 <h3><a class="anchor" id="colorspace"></a>-colorspace <var>value</var></h3> 1257</div> 1258 1259<p class="magick-description">Set the image colorspace.</p> 1260 1261<p>Choices are:</p> 1262 1263<pre class="highlight"><code>CMY CMYK Gray HCL 1264HCLp HSB HSI HSL 1265HSV HWB Lab LCHab 1266LCHuv LMS Log Luv 1267OHTA Rec601YCbCr Rec709YCbCr RGB 1268scRGB sRGB Transparent xyY 1269XYZ YCbCr YCC YDbDr 1270YIQ YPbPr YUV Undefined 1271</code></pre> 1272 1273<p>To print a complete list of colorspaces, use <a href="command-line-options.html#list">-list colorspace</a>.</p> 1274 1275<p>For a more accurate color conversion to or from the linear RGB, CMYK, or grayscale colorspaces, use the <a href="command-line-options.html#profile">-profile</a> option. Note, ImageMagick assumes the sRGB colorspace if the image format does not indicate otherwise. For colorspace conversion, the gamma function is first removed to produce linear RGB.</p> 1276 1277<table class="table table-sm table-striped"> 1278 <caption>Conversion of RGB to Other Color Spaces</caption> 1279 <tr><th valign="middle">CMY</th></tr> 1280 <tr><td valign="middle">C=<var>QuantumRange</var>−R</td></tr> 1281 <tr><td valign="middle">M=<var>QuantumRange</var>−G</td></tr> 1282 <tr><td valign="middle">Y=<var>QuantumRange</var>−B</td></tr> 1283 <tr><th valign="middle">CMYK — starts with CMY from above</th></tr> 1284 <tr><td valign="middle">K=min(C,Y,M)</td></tr> 1285 <tr><td valign="middle">C=<var>QuantumRange</var>*(C−K)/(<var>QuantumRange</var>−K)</td></tr> 1286 <tr><td valign="middle">M=<var>QuantumRange</var>*(M−K)/(<var>QuantumRange</var>−K)</td></tr> 1287 <tr><td valign="middle">Y=<var>QuantumRange</var>*(Y−K)/(<var>QuantumRange</var>−K)</td></tr> 1288 1289 <tr><th valign="middle">Gray</th></tr> 1290 <tr><td valign="middle">Gray = 0.212656*R+0.715158*G+0.072186*B</td></tr> 1291 1292 <tr><th valign="middle">HSB — Hue, Saturation, Brightness; like a cone peak downward</th></tr> 1293 <tr><td valign="middle">H=angle around perimeter (0 to 360 deg); H=0 is red; increasing angles toward green</td></tr> 1294 <tr><td valign="middle">S=distance from axis outward</td></tr> 1295 <tr><td valign="middle">B=distance along axis from bottom upward; B=max(R,G,B); <var>intensity-like</var></td></tr> 1296 1297 <tr><th valign="middle">HSL — Hue, Saturation, Lightness; like a double cone end-to-end with peaks at very top and bottom</th></tr> 1298 <tr><td valign="middle">H=angle around perimeter (0 to 360 deg); H=0 is red; increasing angles toward green</td></tr> 1299 <tr><td valign="middle">S=distance from axis outward</td></tr> 1300 <tr><td valign="middle">L=distance along axis from bottom upward; L=0.5*max(R,G,B) + 0.5*min(R,G,B); <var>intensity-like</var></td></tr> 1301 1302 <tr><th valign="middle">HWB — Hue, Whiteness, Blackness</th></tr> 1303 <tr><td valign="middle">Hue (complicated equation)</td></tr> 1304 <tr><td valign="middle">Whiteness (complicated equation)</td></tr> 1305 <tr><td valign="middle">Blackness (complicated equation)</td></tr> 1306 1307 <tr><th valign="middle">LAB</th></tr> 1308 <tr><td valign="middle">L (complicated equation relating X,Y,Z)</td></tr> 1309 <tr><td valign="middle">A (complicated equation relating X,Y,Z)</td></tr> 1310 <tr><td valign="middle">B (complicated equation relating X,Y,Z)</td></tr> 1311 <tr><th valign="middle">LinearGray</th></tr> 1312 <tr><td valign="middle">LinearGray = 0.298839*R+0.586811*G+0.114350*B</td></tr> 1313 1314 <tr><th valign="middle">LOG</th></tr> 1315 <tr><td valign="middle">I1 (complicated equation involving logarithm of R)</td></tr> 1316 <tr><td valign="middle">I2 (complicated equation involving logarithm of G)</td></tr> 1317 <tr><td valign="middle">I3 (complicated equation involving logarithm of B)</td></tr> 1318 1319 <tr><th valign="middle">OHTA — approximates principal components transformation</th></tr> 1320 <tr><td valign="middle">I1=0.33333*R+0.33334*G+0.33333*B; <var>intensity-like</var></td></tr> 1321 <tr><td valign="middle">I2=(0.50000*R+0.00000*G−0.50000*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1322 <tr><td valign="middle">I3=(−0.25000*R+0.50000*G−0.25000*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1323 1324 <tr><th valign="middle">Rec601Luma</th></tr> 1325 <tr><td valign="middle">Gray = 0.298839*R+0.586811*G+0.114350*B</td></tr> 1326 1327 <tr><th valign="middle">Rec601YCbCr</th></tr> 1328 <tr><td valign="middle">Y=0.2988390*R+0.5868110*G+0.1143500*B; <var>intensity-like</var></td></tr> 1329 <tr><td valign="middle">Cb=(−0.168736*R-0.331264*G+0.500000*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1330 <tr><td valign="middle">Cr=(0.500000*R−0.418688*G−0.081312*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1331 1332 <tr><th valign="middle">Rec709Luma</th></tr> 1333 <tr><td valign="middle">Gray=0.212656*R+0.715158*G+0.072186*B</td></tr> 1334 1335 <tr><th valign="middle">Rec709YCbCr</th></tr> 1336 <tr><td valign="middle">Y=0.212656*R+0.715158*G+0.072186*B; <var>intensity-like</var></td></tr> 1337 <tr><td valign="middle">Cb=(−0.114572*R−0.385428*G+0.500000*B)+(<var>QuantumRange</var>+1)/2</td></tr> 1338 <tr><td valign="middle">Cr=(0.500000*R−0.454153*G−0.045847*B)+(<var>QuantumRange</var>+1)/2</td></tr> 1339 <tr><th valign="middle">sRGB</th></tr> 1340 <tr><td valign="middle">if R ≤ .0.0031308 then Rs=R/12.92 else Rs=1.055 R ^ (1.0 / 2.4) - 0.055</td></tr> 1341 <tr><td valign="middle">if G ≤ .0.0031308 then Gs=B/12.92 else Gs=1.055 R ^ (1.0 / 2.4) - 0.055</td></tr> 1342 <tr><td valign="middle">if B ≤ .0.0031308 then Bs=B/12.92 else Bs=1.055 R ^ (1.0 / 2.4) - 0.055</td></tr> 1343 1344 <tr><th valign="middle">XYZ</th></tr> 1345 <tr><td valign="middle">X=0.4124564*R+0.3575761*G+0.1804375*B</td></tr> 1346 <tr><td valign="middle">Y=0.2126729*R+0.7151522*G+0.0721750*B</td></tr> 1347 <tr><td valign="middle">Z=0.0193339*R+0.1191920*G+0.9503041*B</td></tr> 1348 1349 <tr><th valign="middle">YCC</th></tr> 1350 <tr><td valign="middle">Y=(0.298839*R+0.586811*G+0.114350*B) (with complicated scaling); <var>intensity-like</var></td></tr> 1351 <tr><td valign="middle">C1=(−0.298839*R−0.586811*G+0.88600*B) (with complicated scaling)</td></tr> 1352 <tr><td valign="middle">C2=(0.70100*R−0.586811*G−0.114350*B) (with complicated scaling)</td></tr> 1353 1354 <tr><th valign="middle">YCbCr</th></tr> 1355 <tr><td valign="middle">Y=0.2988390*R+0.5868110*G+0.1143500*B; <var>intensity-like</var></td></tr> 1356 <tr><td valign="middle">Cb=(−0.168736*R−0.331264*G+0.500000*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1357 <tr><td valign="middle">Cr=(0.500000*R−0.418688*G−0.081312*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1358 1359 <tr><th valign="middle">YIQ</th></tr> 1360 <tr><td valign="middle">Y=0.298839*R+0.586811*G+0.114350*B; <var>intensity-like</var></td></tr> 1361 <tr><td valign="middle">I=(0.59600*R−0.27400*G−0.32200*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1362 <tr><td valign="middle">Q=(0.21100*R−0.52300*G+0.31200*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1363 1364 <tr><th valign="middle">YPbPr</th></tr> 1365 <tr><td valign="middle">Y=0.2988390*R+0.5868110*G+0.1143500*B; <var>intensity-like</var></td></tr> 1366 <tr><td valign="middle">Pb=(−0.168736*R−0.331264*G+0.500000*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1367 <tr><td valign="middle">Pr=(0.500000*R−0.418688*G−0.081312*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1368 1369 <tr><th valign="middle">YUV</th></tr> 1370 <tr><td valign="middle">Y=0.298839*R+0.586811*G+0.114350*B; <var>intensity-like</var></td></tr> 1371 <tr><td valign="middle">U=(−0.14740*R−0.28950*G+0.43690*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1372 <tr><td valign="middle">V=(0.61500*R−0.51500*G−0.10000*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1373</table> 1374 1375<p>Note the scRGB colorspace requires HDRI support otherwise it behaves just like linear RGB.</p> 1376 1377<p>Use the <code>Undefined</code> colorspace to identify multi-spectral images.</p> 1378 1379<div style="margin: auto;"> 1380 <h3><a class="anchor" id="combine"></a>-combine</h3> 1381 <h3>+combine <var>colorspace</var></h3> 1382</div> 1383 1384<p class="magick-description">Combine one or more images into a single image.</p> 1385 1386<p>The channels (previously set by <a href="command-line-options.html#channel">-channel</a>) of the 1387combined image are taken from the grayscale values of each image in the 1388sequence, in order. For the default -channel setting of <code>RGB</code>, this 1389means the first image is assigned to the <code>Red</code> channel, the second 1390to the <code>Green</code> channel, the third to the <code>Blue</code>.</p> 1391 1392<p>This option can be thought of as the inverse to <a 1393href="command-line-options.html#separate">-separate</a>, so long as the channel settings are the same. 1394Thus, in the following example, the final image should be a copy of the 1395original. </p> 1396 1397<pre class="highlight"><code>convert original.png -channel RGB -separate sepimage.png 1398convert sepimage-0.png sepimage-1.png sepimage-2.png -channel RGB \ 1399 -combine imagecopy.png 1400</code></pre> 1401 1402<div style="margin: auto;"> 1403 <h3><a class="anchor" id="comment"></a>-comment <var>string</var></h3> 1404</div> 1405 1406<p class="magick-description">Embed a comment in an image.</p> 1407 1408<p>This option sets the comment meta-data of an image read in after this 1409option has been given. To modify a comment of images already in memory use 1410"<code><a href="command-line-options.html#set">-set</a> comment</code>". </p> 1411 1412<p>The comment can contain special format characters listed in the <a 1413href="../www/escape.html">Format and 1414Print Image Properties</a>. These attributes are expanded when the comment 1415is finally assigned to the individual images. </p> 1416 1417<p>If the first character of <var>string</var> is <var>@</var>, the image comment is read from a file titled by the 1418remaining characters in the string. Comments read in from a file are literal; 1419no embedded formatting characters are recognized.</p> 1420 1421<p>Comment meta-data are not visible on the image itself. To do that use the 1422<a href="command-line-options.html#annotate">-annotate</a> or <a href="command-line-options.html#draw">-draw</a> options 1423instead.</p> 1424 1425<p>For example,</p> 1426 1427<pre class="highlight"><code>-comment "%m:%f %wx%h" bird.miff 1428</code></pre> 1429 1430<p>produces an image comment of <code>MIFF:bird.miff 512x480</code> (assuming 1431that the image <code>bird.miff</code> has a width of 512 and a height of 1432480.</p> 1433 1434<div style="margin: auto;"> 1435 <h3><a class="anchor" id="compare"></a>-compare</h3> 1436</div> 1437 1438<p class="magick-description">mathematically and visually annotate the difference between an image and its reconstruction</p> 1439 1440<p>This is a convert version of "<code>compare</code>" for two same sized images. The syntax is as follows, but other metrics are allowed.</p> 1441 1442<pre class="highlight"><code>convert image.png reference.png -metric RMSE -compare \ <br/> difference.png 1443</code></pre> 1444 1445<p>To get the metric value use the string format "%[distortion]".</p> 1446 1447<pre class="highlight"><code>convert image.png reference.png -metric RMSE -compare -format \ 1448 "%[distortion]" info: 1449</code></pre> 1450 1451<div style="margin: auto;"> 1452 <h3><a class="anchor" id="complex"></a>-complex <var>operator</var></h3> 1453</div> 1454 1455<p class="magick-description">perform complex mathematics on an image sequence</p> 1456 1457Choose from these operators: 1458 1459<pre class="highlight"><code>add 1460conjugate 1461divide 1462magnitude-phase 1463multiply 1464real-imaginary 1465subtract 1466</code></pre> 1467 1468<p>Optionally specify the <code>divide</code> operator SNR with <code><a href="command-line-options.html#define">-define</a> complex:snr=float</code>.</p> 1469 1470<div style="margin: auto;"> 1471 <h3><a class="anchor" id="compose"></a>-compose <var>operator</var></h3> 1472</div> 1473 1474<p class="magick-description">Set the type of image composition.</p> 1475 1476<p>See <a href="../www/compose.html">Alpha Compositing</a> for 1477a detailed discussion of alpha compositing.</p> 1478 1479<p>This setting affects image processing operators that merge two (or more) 1480images together in some way. This includes the operators, 1481<a href="command-line-options.html#composite">-compare</a>, 1482<a href="command-line-options.html#composite">-composite</a>, 1483<a href="command-line-options.html#layers">-layers</a> composite, 1484<a href="command-line-options.html#flatten">-flatten</a>, 1485<a href="command-line-options.html#mosaic">-mosaic</a>, 1486<a href="command-line-options.html#layers">-layers</a> merge, 1487<a href="command-line-options.html#border">-border</a>, 1488<a href="command-line-options.html#frame">-frame</a>, 1489and <a href="command-line-options.html#extent">-extent</a>. </p> 1490 1491<p>It is also one of the primary options for the "<code>composite</code>" 1492command. </p> 1493 1494 1495<div style="margin: auto;"> 1496 <h3><a class="anchor" id="composite"></a>-composite</h3> 1497</div> 1498 1499<p class="magick-description">Perform alpha composition on two images and an optional mask</p> 1500 1501<p>Take the first image 'destination' and overlay the second 'source' image 1502according to the current <a href="command-line-options.html#compose">-compose</a> setting. The location 1503of the 'source' or 'overlay' image is controlled according to <a 1504href="command-line-options.html#gravity" >-gravity</a>, and <a href="command-line-options.html#geometry" >-geometry</a> 1505settings. </p> 1506 1507<p>If a third image is given this is treated as a grayscale blending 'mask' image 1508relative to the first 'destination' image. This mask is blended with the 1509source image. However for the '<code>displace</code>' compose method, the 1510mask is used to provide a separate Y-displacement image instead. </p> 1511 1512<p>If a <a href="command-line-options.html#compose">-compose</a> method requires extra numerical 1513arguments or flags these can be provided by setting the <a 1514href="command-line-options.html#set">-set</a> '<code>option:compose:args</code>' 1515appropriately for the compose method. </p> 1516 1517<p>Some <a href="command-line-options.html#compose">-compose</a> methods can modify the 'destination' 1518image outside the overlay area. It is disabled by default. You can enable this by setting the define: <a href="command-line-options.html#define">-define</a> '<code>compose:clip-to-self=true</code>'.</p> 1519 1520<p>The SVG compositing specification requires that color and opacity values range between zero and QuantumRange inclusive. You can permit values outside this range with this option: <a href="command-line-options.html#set">-set</a> '<code>option:compose:clamp=false</code></p> 1521 1522 1523<div style="margin: auto;"> 1524 <h3><a class="anchor" id="compress"></a>-compress <var>type</var></h3> 1525</div> 1526 1527<p class="magick-description">Use pixel compression specified by <var>type</var> when writing the image.</p> 1528 1529<p>Choices are: <code>None</code>, <code>BZip</code>, <code 1530>Fax</code>, <code>Group4</code>, <code 1531>JPEG</code>, <code>JPEG2000</code>, <code 1532>Lossless</code>, <code>LZW</code>, <code 1533>RLE</code> or <code>Zip</code>.</p> 1534 1535<p>To print a complete list of compression types, use <a href="command-line-options.html#list">-list 1536compress</a>.</p> 1537 1538<p>Specify <a href="command-line-options.html#compress">+compress</a> to store the binary image in an 1539uncompressed format. The default is the compression type of the specified 1540image file.</p> 1541 1542<p>If <code>LZW</code> compression is specified but LZW compression has not been 1543enabled, the image data is written in an uncompressed LZW format that can be 1544read by LZW decoders. This may result in larger-than-expected GIF files.</p> 1545 1546<p><code>Lossless</code> refers to lossless JPEG, which is only available if the 1547JPEG library has been patched to support it. Use of lossless JPEG is generally 1548not recommended.</p> 1549 1550<p> 1551When writing an ICO file, you may request that the images be encoded in 1552PNG format, by specifying <code>Zip</code> compression.</p> 1553 1554<p> 1555When writing a JNG file, specify <code>Zip</code> compression to request that 1556the alpha channel be encoded in PNG "IDAT" format, or <code>JPEG</code> 1557to request that it be encoded in JPG "JDAA" format.</p> 1558 1559<p>Use the <a href="command-line-options.html#quality">-quality</a> option to set the compression level 1560to be used by JPEG, PNG, MIFF, and MPEG encoders. 1561Use the <a href="command-line-options.html#sampling-factor">-sampling-factor</a> option to set the 1562sampling factor to be used by JPEG, MPEG, and YUV encoders for down-sampling 1563the chroma channels.</p> 1564 1565<div style="margin: auto;"> 1566 <h3><a class="anchor" id="connected-components"></a>-connected-components <var>connectivity</var></h3> 1567</div> 1568 1569<p class="magick-description"><a href="connected-components.html">connected-components</a> labeling detects connected regions in an image, choose from 4 or 8 way connectivity.</p> 1570 1571<p>Use <code><a href="command-line-options.html#define" >-define</a> connected-components:verbose=true</code> to output statistics associated with each unique label.</p> 1572 1573<div style="margin: auto;"> 1574 <h3><a class="anchor" id="contrast"></a>-contrast</h3> 1575</div> 1576 1577<p class="magick-description">Enhance or reduce the image contrast.</p> 1578 1579<p>This option enhances the intensity differences between the lighter and 1580darker elements of the image. Use <a href="command-line-options.html#contrast">-contrast</a> to enhance 1581the image or <a href="command-line-options.html#contrast">+contrast</a> to reduce the image 1582contrast.</p> 1583 1584<p>For a more pronounced effect you can repeat the option:</p> 1585 1586<pre class="highlight"><code>convert rose: -contrast -contrast rose_c2.png 1587</code></pre> 1588 1589<div style="margin: auto;"> 1590 <h3><a class="anchor" id="contrast-stretch"></a>-contrast-stretch <var>black-point</var><br />-contrast-stretch <var>black-point</var>{x<var>white-point</var>}{<var>%</var>}</h3> 1591</div> 1592 1593<p class="magick-description">Increase the contrast in an image by <var>stretching</var> the range of intensity values.</p> 1594 1595<p>While performing the stretch, black-out at most <var>black-point</var> pixels and white-out at most <var>white-point</var> pixels. Or, if percent is used, black-out at most 1596<var >black-point %</var> pixels and white-out at most <var>white-point %</var> pixels.</p> 1597 1598<p>Prior to ImageMagick 6.4.7-0, <a href="command-line-options.html#contrast-stretch" 1599>-contrast-stretch</a> will black-out at most <var>black-point</var> pixels and white-out at most <var >total pixels 1600minus white-point</var> pixels. Or, if percent is used, black-out at most <var>black-point %</var> pixels and white-out at most <var>100% minus white-point %</var> pixels.</p> 1601 1602<p>Note that <code>-contrast-stretch 0</code> will modify the image such that 1603the image's min and max values are stretched to 0 and <var>QuantumRange</var>, respectively, without any loss of data due to burn-out or 1604clipping at either end. This is not the same as <a href="command-line-options.html#normalize" 1605>-normalize</a>, which is equivalent to <code>-contrast-stretch 0.15x0.05%</code> (or 1606prior to ImageMagick 6.4.7-0, <code>-contrast-stretch 2%x99%</code>).</p> 1607 1608<p>Internally operator works by creating a histogram bin, and then uses that 1609bin to modify the image. As such some colors may be merged together when they 1610originally fell into the same 'bin'. </p> 1611 1612<p>All the channels are normalized in concert by the same amount so as to 1613preserve color integrity, when the default <a href="command-line-options.html#channel" >+channel</a> 1614setting is in use. Specifying any other <a href="command-line-options.html#channel" >-channel</a> 1615setting will normalize the RGB channels independently.</p> 1616 1617<p>See also <a href="command-line-options.html#auto-level" >-auto-level</a> for a 'perfect' 1618normalization of mathematical images. </p> 1619 1620<p>This operator is under review for re-development. </p> 1621 1622 1623<div style="margin: auto;"> 1624 <h3><a class="anchor" id="convolve"></a>-convolve <var>kernel</var></h3> 1625</div> 1626 1627<p class="magick-description">Convolve an image with a user-supplied convolution kernel.</p> 1628 1629<p>The <var>kernel</var> is a matrix specified as 1630a comma-separated list of integers (with no spaces), ordered left-to right, 1631starting with the top row. Presently, only odd-dimensioned kernels are 1632supported, and therefore the number of entries in the specified <var>kernel</var> must be 3<sup>2</sup>=9, 5<sup>2</sup>=25, 16337<sup>2</sup>=49, etc. </p> 1634 1635<p>Note that the <a href="command-line-options.html#convolve">‑convolve</a> operator supports the <a href="command-line-options.html#bias">‑bias</a> setting. This option shifts the convolution so that 1636positive and negative results are relative to a user-specified bias value. 1637This is important for non-HDRI compilations of ImageMagick when dealing with 1638convolutions that contain negative as well as positive values. This is 1639especially the case with convolutions involving high pass filters or edge 1640detection. Without an output bias, the negative values is clipped at zero. 1641</p> 1642 1643<p>When using an ImageMagick with the HDRI compile-time setting, <a href="command-line-options.html#bias">‑bias</a> is not needed, as ImageMagick is able to store/handle any 1644negative results without clipping to the color value range (0..QuantumRange). 1645See the discussion on HDRI implementations of ImageMagick on the page <a 1646href="high-dynamic-range.html">High 1647Dynamic-Range Images</a>. For more about HDRI go the ImageMagick <a 1648href="../Usage/basics/#hdri">Usage</a> pages or this 1649<a href="http://en.wikipedia.org/wiki/High_dynamic_range_imaging">Wikipedia</a> 1650entry. </p> 1651 1652 1653<div style="margin: auto;"> 1654 <h3><a class="anchor" id="copy"></a>-copy <var>geometry</var> <var>offset</var></h3> 1655</div> 1656 1657<p class="magick-description">copy pixels from one area of an image to another.</p> 1658 1659<div style="margin: auto;"> 1660 <h3><a class="anchor" id="crop"></a>-crop <var>geometry</var>{<var>@</var>}{<var>!</var>}</h3> 1661</div> 1662 1663<p class="magick-description">Cut out one or more rectangular regions of the image.</p> 1664 1665<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 1666 1667<p>The <var>width</var> and <var>height</var> of the <var>geometry</var> argument give the size of the image that remains 1668after cropping, and <var>x</var> and <var>y</var> in the 1669<var>offset</var> (if present) gives the location of the top left 1670corner of the cropped image with respect to the original image. To specify the 1671amount to be removed, use <a href="command-line-options.html#shave">-shave</a> instead.</p> 1672 1673<p>If the <var>x</var> and <var>y</var> offsets are 1674present, a single image is generated, consisting of the pixels from the 1675cropping region. The offsets specify the location of the upper left corner of 1676the cropping region measured downward and rightward with respect to the upper 1677left corner of the image. If the <a href="command-line-options.html#gravity">-gravity</a> option is 1678present with <code>NorthEast</code>, <code>East</code>, or <code>SouthEast</code> 1679gravity, it gives the distance leftward from the right edge of the image to 1680the right edge of the cropping region. Similarly, if the <a 1681href="command-line-options.html#gravity">-gravity</a> option is present with <code>SouthWest</code>, 1682<code>South</code>, or <code>SouthEast</code> gravity, the distance is measured 1683upward between the bottom edges.</p> 1684 1685<p>If the <var>x</var> and <var>y</var> offsets are 1686omitted, a set of tiles of the specified geometry, covering the entire input 1687image, is generated. The rightmost tiles and the bottom tiles are smaller if 1688the specified geometry extends beyond the dimensions of the input image.</p> 1689 1690<p>You can add the <var>@</var> to the geometry argument to equally divide the image into the number of tiles generated.</p> 1691 1692<p>By adding a exclamation character flag to the geometry argument, the 1693cropped images virtual canvas page size and offset is set as if the 1694geometry argument was a viewport or window. This means the canvas page size 1695is set to exactly the same size you specified, the image offset set 1696relative top left corner of the region cropped. </p> 1697 1698<p>If the cropped image 'missed' the actual image on its virtual canvas, a 1699special single pixel transparent 'missed' image is returned, and a 'crop 1700missed' warning given. </p> 1701 1702<p>It might be necessary to <a href="command-line-options.html#repage" >+repage</a> the image prior to 1703cropping the image to ensure the crop coordinate frame is relocated to the 1704upper-left corner of the visible image. 1705 1706Similarly you may want to use <a href="command-line-options.html#repage" >+repage</a> after cropping to 1707remove the page offset that will be left behind. This is especially true when 1708you are going to write to an image format such as PNG that supports an image 1709offset.</p> 1710 1711<div style="margin: auto;"> 1712 <h3><a class="anchor" id="cycle"></a>-cycle <var>amount</var></h3> 1713</div> 1714 1715<p class="magick-description">displace image colormap by amount.</p> 1716 1717<p><var>Amount</var> defines the number of positions each 1718colormap entry is shifted.</p> 1719 1720 1721<div style="margin: auto;"> 1722 <h3><a class="anchor" id="debug"></a>-debug <var>events</var></h3> 1723</div> 1724 1725<p class="magick-description">enable debug printout.</p> 1726 1727<p>The <code>events</code> parameter specifies which events are to be logged. It 1728can be either <code>None</code>, <code>All</code>, <code>Trace</code>, or 1729a comma-separated list consisting of one or more of the following domains: 1730<code>Accelerate</code>, <code>Annotate</code>, <code>Blob</code>, <code>Cache</code>, 1731<code>Coder</code>, <code>Configure</code>, <code>Deprecate</code>, 1732<code>Exception</code>, <code>Locale</code>, <code>Render</code>, 1733<code>Resource</code>, <code>Security</code>, <code>TemporaryFile</code>, 1734<code>Transform</code>, <code>X11</code>, or <code>User</code>. </p> 1735 1736 1737<p>For example, to log cache and blob events, use.</p> 1738 1739<pre class="highlight"><code>convert -debug "Cache,Blob" rose: rose.png 1740</code></pre> 1741 1742<p>The <code>User</code> domain is normally empty, but developers can log user 1743events in their private copy of ImageMagick.</p> 1744 1745<p>To print the complete list of debug methods, use <a href="command-line-options.html#list">-list 1746debug</a>.</p> 1747 1748<p>Use the <a href="command-line-options.html#log">-log</a> option to specify the format for debugging 1749output.</p> 1750 1751<p>Use <a href="command-line-options.html#debug">+debug</a> to turn off all logging.</p> 1752 1753<p>Debugging may also be set using the <code>MAGICK_DEBUG</code> <a href="resources.html#environment" 1754>environment variable</a>. The allowed values for the <code>MAGICK_DEBUG</code> 1755environment variable are the same as for the <a href="command-line-options.html#debug">-debug</a> 1756option.</p> 1757 1758 1759<div style="margin: auto;"> 1760 <h3><a class="anchor" id="decipher"></a>-decipher <var>filename</var></h3> 1761</div> 1762 1763<p class="magick-description">Decipher and restore pixels that were previously transformed by <a href="command-line-options.html#encipher">-encipher</a>.</p> 1764 1765<p>Get the passphrase from the file specified by <var>filename</var>.</p> 1766 1767<p>For more information, see the webpage, <a href="cipher.html">ImageMagick: Encipher or 1768Decipher an Image</a>.</p> 1769 1770 1771<div style="margin: auto;"> 1772 <h3><a class="anchor" id="deconstruct"></a>-deconstruct</h3> 1773</div> 1774 1775<p class="magick-description">find areas that has changed between images </p> 1776 1777<p>Given a sequence of images all the same size, such as produced by <a 1778href="command-line-options.html#coalesce">-coalesce</a>, replace the second and later images, with 1779a smaller image of just the area that changed relative to the previous image. 1780</p> 1781 1782<p>The resulting sequence of images can be used to optimize an animation 1783sequence, though will not work correctly for GIF animations when parts of the 1784animation can go from opaque to transparent. </p> 1785 1786<p>This option is actually equivalent to the <a href="command-line-options.html#layers">-layers</a> 1787method '<code>compare-any</code>'. </p> 1788 1789 1790<div style="margin: auto;"> 1791 <h3><a class="anchor" id="define"></a>-define <var>key</var>{<var>=value</var>}<var>...</var></h3> 1792</div> 1793 1794<p class="magick-description">add specific global settings generally used to control coders and image processing operations.</p> 1795 1796<p>This option creates one or more definitions for coders and decoders to use 1797while reading and writing image data. Definitions are generally used to 1798control image file format coder modules, and image processing operations, 1799beyond what is provided by normal means. Defined settings are listed in <a 1800href="command-line-options.html#verbose" >-verbose</a> information ("<code>info:</code>" output format) 1801as "Artifacts". </p> 1802 1803<p>If <var>value</var> is missing for a definition, an empty-valued 1804definition of a flag is created with that name. This used to control on/off 1805options. Use <a href="command-line-options.html#define">+define key</a> to remove definitions 1806previously created. Use <a href="command-line-options.html#define">+define "*"</a> to remove all 1807existing definitions.</p> 1808 1809<p>The same 'artifact' settings can also be defined using the <a 1810href="command-line-options.html#set" >-set "option:<var>key</var>" "<var>value</var>"</a> option, which also allows the use of <a href="../www/escape.html" >Format and Print Image 1811Properties</a> in the defined value. </p> 1812 1813<p>The <var>option</var> and <var>key</var> are case-independent (they are 1814converted to lowercase for use within the decoders) while the <var>value</var> 1815is case-dependent.</p> 1816 1817<p>Such settings are global in scope, and affect all images and operations. </p> 1818 1819<p>The following definitions are just some of the artifacts that are 1820available:</p> 1821 1822<table class="table table-sm table-striped"> 1823 <tr> 1824 <td>bmp3:alpha=<var>true|false</var></td> 1825 <td>include any alpha channel when writing in the BMP image format.</td> 1826 </tr> 1827 1828 <tr> 1829 <td>bmp:format=<var>value</var></td> 1830 <td> valid values are <var>bmp2</var>, <var>bmp3</var>, 1831 and <var>bmp4</var>. This option can be useful when the 1832 method of prepending "BMP2:" to the output filename is inconvenient or 1833 is not available, such as when using the <a href="mogrify.html">mogrify</a> utility.</td> 1834 </tr> 1835 1836 <tr> 1837 <td>bmp:subtype=<var>RGB555|RGB565|ARGB4444|ARGB1555</var></td> 1838 <td>BMP channel depth subtypes. Only support in BMP (BMP4). BMP3 and BMP2 do not 1839 contain header fields to support these options.</td> 1840 </tr> 1841 1842 <tr> 1843 <td>colorspace:auto-grayscale=<var>on|off</var></td> 1844 <td>prevent automatic conversion to grayscale inside coders that support 1845 grayscale. This should be accompanied by -type truecolor. PNG and TIF do 1846 not need this define. With PNG, just use PNG24:image. With TIF, just use 1847 -type truecolor. JPG and PSD will need this define.</td> 1848 </tr> 1849 1850 <tr> 1851 <td>complex:snr=<var>value</var></td> 1852 <td>Set the divide SNR constant<a href="command-line-options.html#complex">-complex</a>.</td> 1853 </tr> 1854 1855 <tr> 1856 <td>compose:args=<var>arguments</var></td> 1857 <td>Sets certain compose argument values when using convert ... -compose ... 1858 -composite. See <a href="compose.html" 1859 >Image Composition</a>.</td> 1860 </tr> 1861 1862 <tr> 1863 <td>compose:clip-to-self=<var>true|false</var></td> 1864 <td>Some <a href="command-line-options.html#compose" >-compose</a> methods can modify the 'destination' image outside the overlay area. It is disabled by default.</td> 1865 </tr> 1866 1867 <tr> 1868 <td>compose:clamp=<var>on|off</var></td> 1869 <td>set each pixel whose value is below zero to zero and any the pixel 1870 whose value is above the quantum range to the quantum range (e.g. 65535) 1871 otherwise the pixel value remains unchanged. Define supported in 1872 ImageMagick 6.9.1-3 and above.</td> 1873 </tr> 1874 1875 <tr> 1876 <td>connected-components:area-threshold=<var>value</var></td> 1877 <td>Merges any region with area smaller than <var>value</var> into its surrounding region or largest neighbor.</td> 1878 </tr> 1879 1880 <tr> 1881 <td>connected-components:keep=<var>list-of-ids</var></td> 1882 <td>Comma and/or hyphenated list of id values to keep in the output. 1883 Supported in Imagemagick 6.9.3-0.</td> 1884 </tr> 1885 1886 <tr> 1887 <td>connected-components:mean-color=<var>true</var></td> 1888 <td>Changes the output image from id values to mean color values. Supported 1889 in Imagemagick 6.9.2-8.</td> 1890 </tr> 1891 1892 <tr> 1893 <td>connected-components:remove=<var>list-of-ids</var></td> 1894 <td>Comma and/or hyphenated list of id values to remove from the output. 1895 Supported in Imagemagick 6.9.2-9.</td> 1896 </tr> 1897 1898 <tr> 1899 <td>connected-components:verbose=<var>true</var></td> 1900 <td>Lists id, bounding box, centroid, area, mean color for each region.</td> 1901 </tr> 1902 1903 <tr> 1904 <td>convolve:scale=<var>{kernel_scale}[!^] [,{origin_addition}] [%]</var></td> 1905 <td>Defines the kernel scaling. The special flag ! automatically scales to 1906 full dynamic range. The ! flag can be used in combination with a factor or 1907 percent. The factor or percent is then applied after the automatic scaling. 1908 An example is 50%!. This produces a result 50% darker than full dynamic 1909 range scaling. The ^ flag assures the kernel is 'zero-summing', for 1910 example when some values are positive and some are negative as in edge 1911 detection kernels. The origin addition adds that value to the center 1912 pixel of the kernel. This produces an effect that is like adding the image 1913 that many times to the result of the filtered image. The typical value 1914 is 1 so that the original image is added to the result of the convolution. 1915 The default is 0.</td> 1916 </tr> 1917 1918 <tr> 1919 <td>dcm:display-range=<var>reset</var></td> 1920 <td>Sets the display range to the minimum and maximum pixel values for the 1921 DCM image format.</td> 1922 </tr> 1923 1924 <tr> 1925 <td>dds:cluster-fit=<var>true|false</var></td> 1926 <td>Enables the dds cluster-fit.</td> 1927 </tr> 1928 1929 <tr> 1930 <td>dds:compression=<var>dxt1|dxt5|none</var></td> 1931 <td>Sets the dds compression.</td> 1932 </tr> 1933 1934 <tr> 1935 <td>dds:mipmaps=<var>value</var></td> 1936 <td>Sets the dds number of mipmaps.</td> 1937 </tr> 1938 1939 <tr> 1940 <td>dds:weight-by-alpha=<var>true|false</var></td> 1941 <td>Enables the dds alpha weighting.</td> 1942 </tr> 1943 1944 <tr> 1945 <td>deskew:auto-crop=<var>true</var></td> 1946 <td>auto crop the image after deskewing.</td> 1947 </tr> 1948 1949 <tr> 1950 <td>delegate:bimodal=<var>true</var></td> 1951 <td>Specifies direct conversion from Postscript to PDF.</td> 1952 </tr> 1953 1954 <tr> 1955 <td>distort:scale=<var>value</var></td> 1956 <td>Sets the output scaling factor for use with <a href="command-line-options.html#distort" 1957 >-distort</a>.</td> 1958 </tr> 1959 1960 <tr> 1961 <td>distort:viewport=<var>WxH+X+Y</var></td> 1962 <td>Sets the viewport for use with <a href="command-line-options.html#distort">-distort</a>.</td> 1963 </tr> 1964 1965 <tr> 1966 <td>dither:diffusion-amount=<var>X%</var></td> 1967 <td>Sets the amount of diffusion to use with Floyd-Steinberg diffusion</td> 1968 </tr> 1969 1970 <tr> 1971 1972 <tr> 1973 <td>dot:layout-engine=<var>value</var></td> 1974 <td>Specifies the layout engine for the DOT image format (e.g. 1975 <code>neato</code>).</td> 1976 </tr> 1977 1978 <tr> 1979 <td>exr:color-type=<var>value</var></td> 1980 <td>Specifies the color type for the EXR format: RGB, RGBA, YC, YCA, Y, YA, R, G, B, A).</td> 1981 </tr> 1982 1983 <tr> 1984 <td>filter:option=<var>value</var></td> 1985 <td>Set a filter option for use with <a href="command-line-options.html#resize">-resize</a>. 1986 See <a href="command-line-options.html#filter">-filter</a> for details.</td> 1987 </tr> 1988 1989 <tr> 1990 <td>fourier:normalize=<var>inverse</var></td> 1991 <td>Sets the location for the FFT/IFT normalization as use by 1992 <a href="command-line-options.html#fft">+-fft</a> and <a href="command-line-options.html#ift">+-ift</a>. The default is 1993 <var>forward</var>.</td> 1994 </tr> 1995 1996 <tr> 1997 <td>h:format=<var>value</var></td> 1998 <td>Set the image encoding format use when writing a C-style header. 1999 <var>format</var> can be any output format supported by ImageMagick 2000 except for <var>h</var> and <var>magick</var>. If this 2001 option is omitted, the default is <var>GIF</var> for PseudoClass 2002 images and <var>PNM</var> for DirectClass images. 2003 </td> 2004 </tr> 2005 2006 <tr> 2007 <td>hough-lines:accumulator=true</td> 2008 <td>Returns the accumulator image in addition to the lines image.</td> 2009 </tr> 2010 2011 <tr> 2012 <td>heic:preserve-orientation=true</td> 2013 <td>Preserve the original EXIF orientation during HEIC decoding and rotate the pixels accordingly. 2014 By default, EXIF orientation is reset to "1" to match the actual orientation of pixels in HEIC. 2015 </td> 2016 </tr> 2017 2018 <tr> 2019 <td>icon:auto-resize</td> 2020 <td>Automatically stores multiple sizes when writing an ico image 2021 (requires a 256x256 input image).</td> 2022 </tr> 2023 2024 <tr> 2025 <td>identify:locate=<var>minimum|maximum</var></td> 2026 <td>Locates the coordinates of one or more image minimum or maximum.</td> 2027 </tr> 2028 2029 <tr> 2030 <td>identify:limit=<var>number</var></td> 2031 <td>Locates the coordinates for the number of minima or maxima specified.</td> 2032 </tr> 2033 2034 <tr> 2035 <td>jp2:layer-number=<var>value</var></td> 2036 <td>Sets the maximum number of quality layers to decode. Same for JPT, JC2, 2037 and J2K.</td> 2038 </tr> 2039 2040 <tr> 2041 <td>jp2:number-resolutions=<var>value</var></td> 2042 <td>Sets the number of resolutions to encode.Same for JPT, JC2, and 2043 J2K.</td> 2044 </tr> 2045 2046 <tr> 2047 <td>jp2:progression-order=<var>value</var></td> 2048 <td>choose from LRCP, RLCP, RPCL, PCRL or CPRL. Same for JPT, JC2, and 2049 J2K.</td> 2050 </tr> 2051 2052 <tr> 2053 <td>jp2:quality=<var>value,value...</var></td> 2054 <td>Sets the quality layer PSNR, given in dB. The order is from left to 2055 right in ascending order. The default is a single lossless quality layer. 2056 Same for JPT, JC2, and J2K.</td> 2057 </tr> 2058 2059 <tr> 2060 <td>jp2:rate=<var>value</var></td> 2061 <td>Specify the compression factor to use while writing JPEG-2000 files. 2062 The compression factor is the reciprocal of the compression ratio. The 2063 valid range is 0.0 to 1.0, with 1.0 indicating lossless compression. If 2064 defined, this value overrides the -quality setting. A quality setting 2065 of 75 results in a rate value of 0.06641. Same for JPT, JC2, and J2K.</td> 2066 </tr> 2067 2068 <tr> 2069 <td>jp2:reduce-factor=<var>value</var></td> 2070 <td>Sets the number of highest resolution levels to be discarded.Same for 2071 JPT, JC2, and J2K.</td> 2072 </tr> 2073 2074 <tr> 2075 <td>jpeg:block-smoothing=<var>on|off</var></td> 2076 <td> </td> 2077 </tr> 2078 2079 <tr> 2080 <td>jpeg:colors=<var>value</var></td> 2081 <td>Set the desired number of colors and let the JPEG encoder do the 2082 quantizing.</td> 2083 </tr> 2084 2085 <tr> 2086 <td>jpeg:dct-method=<var>value</var></td> 2087 <td>Choose from <code>default</code>, <code>fastest</code>, 2088 <code>float</code>, <code>ifast</code>, and <code>islow</code>.</td> 2089 </tr> 2090 2091 <tr> 2092 <td>jpeg:extent=<var>value</var></td> 2093 <td>Restrict the maximum JPEG file size, for example <code>-define 2094 jpeg:extent=400KB</code>. The JPEG encoder will search for the highest 2095 compression quality level that results in an output file that does not 2096 exceed the value. The <code>-quality</code> option also will be respected 2097 starting with version 6.9.2-5. Between 6.9.1-0 and 6.9.2-4, add -quality 2098 100 in order for the jpeg:extent to work properly. Prior to 6.9.1-0, the 2099 -quality setting was ignored.</td> 2100 </tr> 2101 2102 <tr> 2103 <td>jpeg:fancy-upsampling=<var>on|off</var></td> 2104 <td> </td> 2105 </tr> 2106 2107 <tr> 2108 <td>jpeg:optimize-coding=<var>on|off</var></td> 2109 <td> </td> 2110 </tr> 2111 2112 <tr> 2113 <td>jpeg:q-table=<var>table</var></td> 2114 <td> </td> 2115 </tr> 2116 2117 <tr> 2118 <td>jpeg:sampling-factor=<var>sampling-factor-string</var></td> 2119 <td> </td> 2120 </tr> 2121 2122 <tr> 2123 <td>jpeg:size=<var>geometry</var></td> 2124 <td>Set the size hint of a JPEG image, for 2125 example, <code>-define jpeg:size=128x128</code>. 2126 It is most useful for increasing performance and reducing the memory 2127 requirements when reducing the size of a large JPEG image.</td> 2128 </tr> 2129 2130 <tr> 2131 <td>json:features</td> 2132 <td>includes features in verbose information.</td> 2133 </tr> 2134 2135 <tr> 2136 <td>json:limit</td> 2137 <td> </td> 2138 </tr> 2139 2140 <tr> 2141 <td>json:locate</td> 2142 <td> </td> 2143 </tr> 2144 2145 <tr> 2146 <td>json:moments</td> 2147 <td>includes image moments in verbose information.</td> 2148 </tr> 2149 2150 <tr> 2151 <td>magick:format=<var>value</var></td> 2152 <td>Set the image encoding format use when writing a C-style header. 2153 This is the same as "h:format=format" described above.</td> 2154 </tr> 2155 2156 <tr> 2157 <td>mng:need-cacheoff</td> 2158 <td>turn playback caching off for streaming MNG.</td> 2159 </tr> 2160 2161 <tr> 2162 <td>morphology:compose=<var>compose-method</var></td> 2163 <td>Specifies how to merge results generated by multiple<a 2164 href="command-line-options.html#morphology" >-morphology</a> kernel. The default is none. One 2165 typical value is 'lighten' as used, for example, with the sobel edge 2166 kernels. </td> 2167 </tr> 2168 2169 <tr> 2170 <td>morphology:showKernel=<var>1</var></td> 2171 <td>Outputs (to 'standard error') all the information about a generated <a 2172 href="command-line-options.html#morphology" >-morphology</a> kernel.</td> 2173 </tr> 2174 2175 <tr> 2176 <td>pcl:fit-to-page=<var>true</var></td> 2177 </tr> 2178 2179 <tr> 2180 <td>pdf:fit-page=<var>geometry</var></td> 2181 <td> geometry specifies the scaling dimensions for resizing when the PDF is 2182 being read. The geometry is either WxH{%} or page size. No offsets are 2183 allowed. (introduced in IM 6.8.8-8)</td> 2184 </tr> 2185 2186 <tr> 2187 <td>pdf:fit-to-page=<var>true</var></td> 2188 <td> </td> 2189 </tr> 2190 2191 <tr> 2192 <td>pdf:use-cropbox=<var>true</var></td> 2193 <td> </td> 2194 </tr> 2195 2196 <tr> 2197 <td>pdf:use-trimbox=<var>true</var></td> 2198 <td> </td> 2199 </tr> 2200 2201 <tr> 2202 <td>pdf:stop-on-error=<var>true</var></td> 2203 <td> </td> 2204 </tr> 2205 2206 <tr> 2207 <td>pdf:pdf:page-direction=<var>right-to-left</var></td> 2208 <td> </td> 2209 </tr> 2210 2211 <tr> 2212 <td>phash:colorspaces=<var>colorspace,colorspace,...</var></td> 2213 <td>the perceptual hash defaults to the sRGB and HCLp colorspaces. When 2214 using this define, you can specify up to six alternative colorspaces. (as 2215 of IM 7.0.3-8)</td> 2216 </tr> 2217 2218 <tr> 2219 <td>phash:normalize=<var>true</var></td> 2220 <td>normalizes the phash metric by dividing by the number of channels 2221 specified by <code>-define phash:colorspaces</code> when using compare 2222 -metric phash. (as of IM 7.0.3-8)</td> 2223 </tr> 2224 2225 <tr> 2226 <td>png:bit-depth=<var>value</var></td> 2227 <td> </td> 2228 </tr> 2229 2230 <tr> 2231 <td>png:color-type=<var>value</var></td> 2232 <td>desired bit-depth and color-type for PNG output. You can force the PNG 2233 encoder to use a different bit-depth and color-type than it would have 2234 normally selected, but only if this does not cause any loss of image 2235 quality. Any attempt to reduce image quality is treated as an error and no 2236 PNG file is written. E.g., if you have a 1-bit black-and-white image, you 2237 can use these "defines" to cause it to be written as an 8-bit grayscale, 2238 indexed, or even a 64-bit RGBA. But if you have a 16-million color image, 2239 you cannot force it to be written as a grayscale or indexed PNG. If you 2240 wish to do this, you must use the appropriate <a href="command-line-options.html#depth">-depth</a>, 2241 <a href="command-line-options.html#colors">-colors</a>, or <a href="command-line-options.html#type">-type</a> directives to 2242 reduce the image quality prior to using the PNG encoder. Note that in 2243 indexed PNG files, "bit-depth" refers to the number of bits per index, 2244 which can be 1, 2, 4, or 8. In such files, the color samples always have 2245 8-bit depth.</td> 2246 </tr> 2247 2248 <tr> 2249 <td>png:compression-filter=<var>value</var></td> 2250 <td> valid values are 0 through 9. 0-4 are the corresponding PNG filters, 2251 5 means adaptive filtering except for images with a colormap, 6 means 2252 adaptive filtering for all images, 7 means MNG "loco" compression, 8 means 2253 Z_RLE strategy with adaptive filtering, and 9 means Z_RLE strategy with no 2254 filtering.</td> 2255 </tr> 2256 2257 <tr> 2258 <td>png:compression-level=<var>value</var></td> 2259 <td> valid values are 0 through 9, with 0 providing the least but fastest 2260 compression and 9 usually providing the best and always the slowest.</td> 2261 </tr> 2262 2263 <tr> 2264 <td>png:compression-strategy=<var>value</var></td> 2265 <td> valid values are 0 through 4, meaning default, filtered, huffman_only, 2266 rle, and fixed ZLIB compression strategy. If you are using an old zlib 2267 that does not support Z_RLE (before 1.2.0) or Z_FIXED (before 1.2.2.2), 2268 values 3 and 4, respectively, will use the zlib default strategy 2269 instead.</td> 2270 </tr> 2271 2272 <tr> 2273 <td>png:format=<var>value</var></td> 2274 <td> valid values are <var>png8</var>, <var>png24</var>, 2275 <var>png32</var>, <var>png48</var>, 2276 <var>png64</var>, and <var>png00</var>. 2277 This property can be useful for specifying 2278 the specific PNG format to be used, when the usual method of prepending the 2279 format name to the output filename is inconvenient, such as when writing 2280 a PNG-encoded ICO file or when using <a href="mogrify.html">mogrify</a>. 2281 Value = <var>png8</var> reduces the number of colors to 256, 2282 only one of which may be fully transparent, if necessary. The other 2283 values do not force any reduction of quality; it is an error to request 2284 a format that cannot represent the image data without loss (except that 2285 it is allowed to reduce the bit-depth from 16 to 8 for all formats). 2286 Value = <var>png24</var> and <var>png48</var> 2287 allow transparency, only if a single color is fully transparent and that 2288 color does not also appear in an opaque pixel; such transparency is 2289 written in a PNG <code>tRNS</code> chunk. 2290 Value = <var>png00</var> causes the image to inherit its 2291 color-type and bit-depth from the input image, if the input was also 2292 a PNG.</td> 2293 </tr> 2294 2295 <tr> 2296 <td>png:exclude-chunk=<var>value</var></td> 2297 2298 <tr> 2299 <td>png:include-chunk=<var>value</var></td> 2300 <td>ancillary chunks to be excluded from or included in PNG output. 2301 2302 <p>The <var>value</var> can be the name of a PNG chunk-type such 2303 as <var>bKGD</var>, a comma-separated list of chunk-names 2304 (which can include the word <var>date</var>, the word 2305 <var>all</var>, or the word <var>none</var>). 2306 Although PNG chunk-names are case-dependent, you can use all lowercase 2307 names if you prefer.</p> 2308 2309 <p>The "include-chunk" and "exclude-chunk" lists only affect the behavior 2310 of the PNG encoder and have no effect on the PNG decoder.</p> 2311 2312 <p>As a special case, if the <code>sRGB</code> chunk is excluded and 2313 the <code>gAMA</code> chunk is included, the <code>gAMA</code> chunk will 2314 only be written if gamma is not 1/2.2, since most decoders assume 2315 sRGB and gamma=1/2.2 when no colorspace information is included in 2316 the PNG file. Because the list is processed from left to right, you 2317 can achieve this with a single define:</p> 2318 2319<pre class="highlight"><code>-define png:include-chunk=none,gAMA 2320</code></pre> 2321 2322 <p>As a special case, if the <code>sRGB</code> chunk is not excluded and 2323 the PNG encoder recognizes that the image contains the sRGB ICC profile, 2324 the PNG encoder will write the <code>sRGB</code> chunk instead of the 2325 entire ICC profile. To force the PNG encoder to write the sRGB 2326 profile as an <code>iCCP</code> chunk in the output PNG instead of the 2327 <code>sRGB</code> chunk, exclude the <code>sRGB</code> chunk.</p> 2328 2329 <p>The critical PNG chunks <code>IHDR</code>, <code>PLTE</code>, 2330 <code>IDAT</code>, and <code>IEND</code> cannot be excluded. Any such 2331 entries appearing in the list will be ignored.</p> 2332 2333 <p>If the ancillary PNG <code>tRNS</code> chunk is excluded and the 2334 image has transparency, the PNG colortype is forced to be 4 or 6 2335 (GRAY_ALPHA or RGBA). If the image is not transparent, then the 2336 <code>tRNS</code> chunk isn't written anyhow, and there is no effect 2337 on the PNG colortype of the output image.</p> 2338 2339 <p>The <a href="command-line-options.html#strip">-strip</a> option does the equivalent of the 2340 following for PNG output:</p> 2341 2342<pre class="highlight"><code>-define png:exclude-chunk=EXIF,iCCP,iTXt,sRGB,tEXt,zCCP,zTXt,date 2343</code></pre> 2344 2345 <p>The default behavior is to include all known PNG ancillary chunks 2346 plus ImageMagick's private <code>vpAg</code> ("virtual page") chunk, 2347 and to exclude all PNG chunks that are unknown to ImageMagick, 2348 regardless of their PNG "copy-safe" status as described in the 2349 PNG specification.</p> 2350 2351 <p>Any chunk names that are not known to ImageMagick are ignored 2352 if they appear in either the "include-chunk" or "exclude-chunk" list. 2353 The ancillary chunks currently known to ImageMagick are 2354 <code>bKGD</code>, <code>cHRM</code>, <code>gAMA</code>, <code>iCCP</code>, 2355 <code>oFFs</code>, <code>pHYs</code>, <code>sRGB</code>, <code>tEXt</code>, 2356 <code>tRNS</code>, <code>vpAg</code>, and <code>zTXt</code>.</p> 2357 2358 <p>You can also put <code>date</code> in the list to include or exclude 2359 the "Date:create" and "Date:modify" text chunks that ImageMagick normally 2360 inserts in the output PNG.</p></td> 2361 </tr> 2362 2363 <tr> 2364 <td>png:ignore-crc[=<var>true</var>]</td> 2365 <td>When you know your image has no CRC or ADLER32 errors, this can speed up 2366 decoding. It is also helpful in debugging bug reports from "fuzzers".</td> 2367 </tr> 2368 2369 <tr> 2370 <td>png:preserve-colormap[=<var>true</var>]</td> 2371 <td>Use the existing image->colormap. Normally the PNG encoder will 2372 try to optimize the palette, eliminating unused entries and putting 2373 the transparent colors first. If this flag is set, that behavior 2374 is suppressed.</td> 2375 </tr> 2376 2377 <tr> 2378 <td>png:preserve-iCCP[=<var>true</var>]</td> 2379 <td>By default, the PNG decoder and encoder examine any ICC profile 2380 that is present, either from an <code>iCCP</code> chunk in the PNG 2381 input or supplied via an option, and if the profile is recognized 2382 to be the sRGB profile, converts it to the <code>sRGB</code> chunk. 2383 You can use <code>-define png:preserve-iCCP</code> to prevent 2384 this from happening; in such cases the <code>iCCP</code> chunk 2385 will be read or written and no <code>sRGB</code> chunk will be 2386 written. There are some ICC profiles that claim to be sRGB but 2387 have various errors that cause them to be rejected by libpng16; such 2388 profiles are recognized anyhow and converted to the <code>sRGB</code> 2389 chunk, but are rejected if the <code>-define png:preserve-iCCP</code> 2390 is present. Note that not all "sRGB" ICC profiles are recognized 2391 yet; we will add them to the list as we encounter them.</td> 2392 </tr> 2393 2394 <tr> 2395 <td>png:swap-bytes[=<var>true</var>]</td> 2396 <td>The PNG specification requires that any multi-byte integers be stored in 2397 network byte order (MSB-LSB endian). This option allows you to 2398 fix any invalid PNG files that have 16-bit samples stored incorrectly 2399 in little-endian order (LSB-MSB). The "-define png:swap-bytes" option 2400 must appear before the input filename on the commandline. The swapping 2401 is done during the libpng decoding operation.</td> 2402 </tr> 2403 2404 <tr> 2405 <td>profile:skip=<var>name1,name2,...</var></td> 2406 <td>Skip the named profile[s] when reading the image. Use skip="*" to 2407 skip all named profiles in the image. Many named profiles exist, 2408 including ICC, EXIF, APP1, IPTC, XMP, and others.</td> 2409 </tr> 2410 2411 <tr> 2412 <td>ps:imagemask</td> 2413 <td>If the ps:imagemask flag is defined, the PS3 and EPS3 coders will 2414 create Postscript files that render bilevel images with the Postscript 2415 imagemask operator instead of the image operator.</td> 2416 </tr> 2417 2418 <tr> 2419 <td>psd:additional-info=all|selective</td> 2420 <td>This option should only be used when converting from a PSD file to 2421 another PSD file. This should be placed after the image is read. The two 2422 options are 'all' and 'selective'. The 'selective' option will preserve 2423 all additional information that is not related to the geometry of the 2424 image. The 'all' option should only be used when the geometry of the 2425 image has not been changed. This option is helpful when transferring 2426 non-simple layers, such as adjustment layers from the input PSD file to 2427 the output PSD file. If this option is not used, the additional 2428 information will not be preserved. This define is available as of 2429 Imagemagick version 6.9.5-8. 2430</td> 2431 </tr> 2432 2433 <tr> 2434 <td>psd:alpha-unblend=off</td> 2435 <td>Disables new automatic un-blending of transparency with the base image 2436 for the flattened layer 0 before adding the alpha channel to the output 2437 image. This define must be placed before the input psd image. (Available 2438 as of IM 6.9.2.5). The automatic un-blending is new to IM 6.9.2.5 and 2439 prevents the transparency from being applied twice in the output 2440 image. This option should be set before reading the image.</td> 2441 </tr> 2442 2443 <tr> 2444 <td>psd:preserve-opacity-mask=true</td> 2445 <td>This option should only be used when converting from a PSD file to 2446 another PSD file. It will preserve the opacity mask of a layer and add it 2447 back to the layer when the image is saved. Setting this to 'true' will 2448 enable this feature. This define is available as of Imagemagick version 2449 6.9.5-10. 2450</td> 2451 </tr> 2452 2453 <tr> 2454 <td>preserve-timestamp=<var>{True, False}</var></td> 2455 <td>Preserve file timestamp (<code>mogrify</code> only).</td> 2456 </tr> 2457 2458 <tr> 2459 <td>q-table=<var>quantization-table.xml</var></td> 2460 <td>Custom JPEG quantization tables.</td> 2461 </tr> 2462 2463 <tr> 2464 <td>quantum:format=<var>type</var></td> 2465 <td>Set the type to <code>floating-point</code> to specify a floating-point 2466 format for raw files (e.g. GRAY:) or for MIFF and TIFF images in HDRI mode 2467 to preserve negative values. If <a href="command-line-options.html#depth">-depth</a> 16 is 2468 included, the result is a single precision floating point format. 2469 If <a href="command-line-options.html#depth">-depth</a> 32 is included, the result is 2470 double precision floating point format.</td> 2471 </tr> 2472 2473 <tr> 2474 <td>quantum:polarity=<var>photometric-interpretation</var></td> 2475 <td>Set the photometric-interpretation of an image (typically for TIFF 2476 image file format) to either <code>min-is-black</code> (default) or 2477 <code>min-is-white</code>.</td> 2478 </tr> 2479 2480 <tr> 2481 <td>sample:offset=<var>geometry</var></td> 2482 <td>Location of the sampling point within the sub-region being sampled, 2483 expressed as percentages (see <a href="command-line-options.html#sample" >-sample</a>).</td> 2484 </tr> 2485 2486 <tr> 2487 <td>morphology:showKernel=<var>1</var></td> 2488 <td>Outputs (to 'standard error') all the information about a generated <a 2489 href="command-line-options.html#morphology" >-morphology</a> kernel.</td> 2490 </tr> 2491 2492 <tr> 2493 <td>stream:buffer-size=<var>value</var></td> 2494 <td>Set the stream buffer size. Select 0 for unbuffered I/O.</td> 2495 </tr> 2496 2497 <tr> 2498 <td>tiff:alpha=<var>associated|unassociated|unspecified</var></td> 2499 <td>Specify the alpha extra samples as associated, unassociated or 2500 unspecified.</td> 2501 </tr> 2502 2503 <tr> 2504 <td>tiff:endian=<var>msb|lsb</var></td> 2505 <td> </td> 2506 </tr> 2507 2508 <tr> 2509 <td>tiff:exif-properties=<var>true</var></td> 2510 <td>Enables reading the EXIF properties.</td> 2511 </tr> 2512 2513 <tr> 2514 <td>tiff:fill-order=<var>msb|lsb</var></td> 2515 <td> </td> 2516 </tr> 2517 2518 <tr> 2519 <td>tiff:ignore-layers=<var>true</var></td> 2520 <td>Ignores the photoshop layers.</td> 2521 </tr> 2522 2523 <tr> 2524 <td>tiff:ignore-tags=<var>comma-separate-list-of-tag-IDs</var></td> 2525 <td>Allows one or more tag ID values to be ignored.</td> 2526 </tr> 2527 2528 <tr> 2529 <td>tiff:predictor=<var>[1, 2 or 3]</var></td> 2530 <td>A mathematical operator that is applied to the image data before an encoding scheme is applied. The general idea is that subsequent pixels of an image resemble each other. Thus, substracting the information from a pixel that is already contained in previous one is likely to reduce its information density considerably and aid subsequent compression. 1 = No prediction scheme used before coding. 2 = Horizontal differencing. 3 = Floating point horizontal differencing.</td> 2531 </tr> 2532 2533 <tr> 2534 <td>tiff:rows-per-strip=<var>value</var></td> 2535 <td>Sets the number of rows per strip.</td> 2536 </tr> 2537 2538 <tr> 2539 <td>tiff:tile-geometry=<var>WxH</var></td> 2540 <td>Sets the tile size for pyramid tiffs. Requires the suffix 2541 PTIF: before the outputname.</td> 2542 </tr> 2543 2544 <tr> 2545 <td>type:features=<var>string</var></td> 2546 <td> </td> 2547 </tr> 2548 2549 <tr> 2550 <td>type:hinting=<var>off</var></td> 2551 <td> </td> 2552 </tr> 2553 2554 <tr> 2555 <td>txt:compliance=<var>css</var></td> 2556 <td>The first argument of a hsl() color is integer, not percentage.</td> 2557 </tr> 2558 2559 <tr> 2560 <td>x:screen=<var>true</var></td> 2561 <td>Obtains the image from the root window.</td> 2562 </tr> 2563 2564 <tr> 2565 <td>x:silent=<var>true</var></td> 2566 <td>Turns off the beep when importing an image.</td> 2567 </tr> 2568</table> 2569 2570<p>For example, to create a postscript file that will render only the black 2571pixels of a bilevel image, use:</p> 2572 2573<pre class="highlight"><code>convert bilevel.tif -define ps:imagemask eps3:stencil.ps 2574</code></pre> 2575 2576<p>Set attributes of the image registry by prefixing the value with 2577<code>registry:</code>. For example, to set a temporary path to put work files, 2578use:</p> 2579 2580<pre class="highlight"><code>-define registry:temporary-path=/data/tmp 2581</code></pre> 2582 2583<div style="margin: auto;"> 2584 <h3><a class="anchor" id="delay"></a>-delay <var>ticks</var> <br />-delay <var>ticks</var>x<var>ticks-per-second</var> {<var><</var>} {<var>></var>}</h3> 2585</div> 2586 2587<p class="magick-description">display the next image after pausing.</p> 2588 2589<p>This option is useful for regulating the animation of image sequences 2590<var>ticks/ticks-per-second</var> seconds must expire before the display of the 2591next image. The default is no delay between each showing of the image 2592sequence. The default ticks-per-second is 100.</p> 2593 2594<p>Use <code>></code> to change the image delay <var>only</var> if its current 2595value exceeds the given delay. <code><</code> changes the image delay 2596<var>only</var> if current value is less than the given delay. For example, if 2597you specify <code>30></code> and the image delay is 20, the image delay does 2598not change. However, if the image delay is 40 or 50, the delay it is changed 2599to 30. Enclose the given delay in quotation marks to prevent the 2600<code><</code> or <code>></code> from being interpreted by your shell as 2601a file redirection.</p> 2602 2603 2604<div style="margin: auto;"> 2605 <h3><a class="anchor" id="delete"></a>-delete <var>indexes</var></h3> 2606</div> 2607 2608<p class="magick-description">delete the images specified by index, from the image sequence.</p> 2609 2610<p>Specify the image by its index in the sequence. The first image is index 26110. Negative indexes are relative to the end of the sequence, for example, -1 2612represents the last image of the sequence. Specify a range of images with 2613a dash (e.g. 0-4). Separate indexes with a comma (e.g. 0,2). Use 2614<code>+delete</code> to delete the last image in the current image sequence. Use <code>-delete 0--1</code> to delete the entire image sequence.</p> 2615 2616 2617<div style="margin: auto;"> 2618 <h3><a class="anchor" id="density"></a>-density <var>width</var><br />-density <var>width</var>x<var>height</var></h3> 2619</div> 2620 2621<p class="magick-description">Set the horizontal and vertical resolution of an image for rendering to devices.</p> 2622 2623<p>This option specifies the image resolution to store while encoding a raster 2624image or the canvas resolution while rendering (reading) vector formats such 2625as Postscript, PDF, WMF, and SVG into a raster image. Image resolution 2626provides the unit of measure to apply when rendering to an output device or 2627raster image. The default unit of measure is in dots per inch (DPI). The <a 2628href="command-line-options.html#units">-units</a> option may be used to select dots per centimeter 2629instead.</p> 2630 2631<p>The default resolution is 72 dots per inch, which is equivalent to one 2632point per pixel (Macintosh and Postscript standard). Computer screens are 2633normally 72 or 96 dots per inch, while printers typically support 150, 300, 2634600, or 1200 dots per inch. To determine the resolution of your display, use 2635a ruler to measure the width of your screen in inches, and divide by the 2636number of horizontal pixels (1024 on a 1024x768 display).</p> 2637 2638<p>If the file format supports it, this option may be used to update the 2639stored image resolution. Note that Photoshop stores and obtains image 2640resolution from a proprietary embedded profile. If this profile is not 2641stripped from the image, then Photoshop will continue to treat the image using 2642its former resolution, ignoring the image resolution specified in the standard 2643file header.</p> 2644 2645<p>The <a href="command-line-options.html#density">-density</a> option sets an <var>attribute</var> and 2646does not alter the underlying raster image. It may be used to adjust the 2647rendered size for desktop publishing purposes by adjusting the scale applied 2648to the pixels. To resize the image so that it is the same size at a different 2649resolution, use the <a href="command-line-options.html#resample">-resample</a> option.</p> 2650 2651<div style="margin: auto;"> 2652 <h3><a class="anchor" id="depth"></a>-depth <var>value</var></h3> 2653</div> 2654 2655<p class="magick-description">depth of the image.</p> 2656 2657<p>This the number of bits in a color sample within a pixel. Use this option 2658to specify the depth of raw images whose depth is unknown such as GRAY, RGB, 2659or CMYK, or to change the depth of any image after it has been read.</p> 2660 2661<p>Use <a href="command-line-options.html#depth">+depth</a> to return depth to its default value.</p> 2662 2663<div style="margin: auto;"> 2664 <h3><a class="anchor" id="descend"></a>-descend</h3> 2665</div> 2666 2667<p class="magick-description">obtain image by descending window hierarchy.</p> 2668 2669<div style="margin: auto;"> 2670 <h3><a class="anchor" id="deskew"></a>-deskew <var>threshold{%}</var></h3> 2671</div> 2672 2673<p class="magick-description">straighten an image. A threshold of 40% works for most images.</p> 2674 2675<p>Use <a href="command-line-options.html#set">-set</a> <code>option:deskew:auto-crop 2676<var>true | false</var></code> to auto crop the image.</p> 2677 2678<div style="margin: auto;"> 2679 <h3><a class="anchor" id="despeckle"></a>-despeckle</h3> 2680</div> 2681 2682<p class="magick-description">reduce the speckles within an image.</p> 2683 2684<div style="margin: auto;"> 2685 <h3><a class="anchor" id="direction"></a>-direction <var>type</var></h3> 2686</div> 2687 2688<p class="magick-description">render text right-to-left or left-to-right. Requires the <a href="https://github.com/HOST-Oman/libraqm">RAQM</a> delegate library and <a href="https://en.wikipedia.org/wiki/Complex_text_layout">complex text layout</a>.</p> 2689 2690<div style="margin: auto;"> 2691 <h3><a class="anchor" id="displace"></a>-displace <var>horizontal-scale</var>{%}{!}<br />-displace <var>horizontal-scale</var>x<var>vertical-scale</var>{%}{!}</h3> 2692</div> 2693 2694<p class="magick-description">shift image pixels as defined by a displacement map.</p> 2695 2696<p>With this option, the 'overlay' image, and optionally the 'mask' image, 2697is used as a displacement map, which is used to displace the lookup of 2698what part of the 'background' image is seen at each point of the overlaid 2699area. Much like the displacement map is a 'lens' that redirects light shining 2700through it so as to present a distorted view the original 'background' image 2701behind it. </p> 2702 2703<p>Any perfect grey areas of the displacement map produce a zero 2704displacement of the image. Black areas produce the given maximum negative 2705displacement of the lookup point, while white produce a maximum positive 2706displacement of the lookup. </p> 2707 2708<p>Note that it is the lookup of the 'background' that is displaced, not a 2709displacement of the image itself. As such an area of the displacement map 2710containing 'white' will have the lookup point 'shifted' by a positive amount, 2711and thus generating a copy of the destination image to the right/downward from 2712the correct position. That is the image will look like it may have been 2713'shifted' in a negative left/upward direction. Understanding this is a very 2714important in understanding how displacement maps work. </p> 2715 2716<p>The given arguments define the maximum amount of displacement in pixels 2717that a particular map can produce. If the displacement scale is large enough 2718it is also possible to lookup parts of the 'background' image that lie well 2719outside the bounds of the displacement map itself. That is you could very 2720easily copy a section of the original image from outside the overlay area 2721into the overlay area. </p> 2722 2723<p>The '%' flag makes the displacement scale relative to the size of the 2724overlay image (100% = half width/height of image). Using '!' switches 2725percentage arguments to refer to the destination image size instead. 2726these flags were added as of IM v6.5.3-5.</p> 2727 2728<p>Normally a single grayscale displacement map is provided, which with the 2729given scaling values will determine a single direction (vector) in which 2730displacements can occur (positively or negatively). However, if you also 2731specify a third image which is normally used as a <var>mask</var>, 2732the <var>composite image</var> is used for horizontal X 2733displacement, while the <var>mask image</var> is used for vertical Y 2734displacement. This allows you to define completely different displacement 2735values for the X and Y directions, and allowing you to lookup any point within 2736the <var>scale</var> bounds. In other words each pixel can lookup 2737any other nearby pixel, producing complex 2 dimensional displacements, rather 2738than a simple 1 dimensional vector displacements. </p> 2739 2740<p>Alternatively rather than supplying two separate images, as of IM v6.4.4-0, 2741you can use the 'red' channel of the overlay image to specify the horizontal 2742or X displacement, and the 'green' channel for the vertical or Y displacement. 2743</p> 2744 2745<p>As of IM v6.5.3-5 any alpha channel in the overlay image is used as a 2746mask the transparency of the destination image. However areas outside the 2747overlaid areas will not be affected. </p> 2748 2749 2750<div style="margin: auto;"> 2751 <h3><a class="anchor" id="display"></a>-display <var>host:display[.screen]</var></h3> 2752</div> 2753 2754<p class="magick-description">Specifies the X server to contact.</p> 2755 2756<p>This option is used with convert for obtaining image or font from this 2757X server. See <var>X(1)</var>.</p> 2758 2759<div style="margin: auto;"> 2760 <h3><a class="anchor" id="dispose"></a>-dispose <var>method</var></h3> 2761</div> 2762 2763<p class="magick-description">define the GIF disposal image setting for images that are being created or read in. </p> 2764 2765<p>The layer disposal method defines the way each the displayed image is to be 2766modified after the current 'frame' of an animation has finished being 2767displayed (after its 'delay' period), but before the next frame on an 2768animation is to be overlaid onto the display. </p> 2769 2770<p>Here are the valid methods:</p> 2771 2772<dl class="row"> 2773<dt class="col-md-4">Undefined</dt><dd class="col-md-8">0: No disposal specified (equivalent to '<code>none</code>').</dd> 2774<dt class="col-md-4">None</dt><dd class="col-md-8">1: Do not dispose, just overlay next frame image.</dd> 2775<dt class="col-md-4">Background</dt><dd class="col-md-8">2: Clear the frame area with the background color.</dd> 2776<dt class="col-md-4">Previous</dt><dd class="col-md-8">3: Clear to the image prior to this frames overlay.</dd> 2777</dl> 2778 2779<p>You can also use the numbers given above, which is what the GIF format 2780uses internally to represent the above settings. </p> 2781 2782<p>To print a complete list of dispose methods, use <a href="command-line-options.html#list">-list dispose</a>.</p> 2783 2784<p>Use <a href="command-line-options.html#dispose" >+dispose</a>, turn off the setting and prevent 2785resetting the layer disposal methods of images being read in. </p> 2786 2787<p>Use <a href="command-line-options.html#set">-set</a> '<code>dispose</code>' method to set the image 2788disposal method for images already in memory.</p> 2789 2790<div style="margin: auto;"> 2791 <h3><a class="anchor" id="dissimilarity-threshold"></a>-dissimilarity-threshold <var>value</var></h3> 2792</div> 2793 2794<p class="magick-description">maximum RMSE for subimage match (default 0.2).</p> 2795 2796 2797<div style="margin: auto;"> 2798 <h3><a class="anchor" id="dissolve"></a>-dissolve <var>src_percent</var>[x<var>dst_percent</var>]</h3> 2799</div> 2800 2801<p class="magick-description">dissolve an image into another by the given percent.</p> 2802 2803<p>The opacity of the composite image is multiplied by the given percent, then 2804it is composited 'over' the main image. If <var>src_percent</var> 2805is greater than 100, start dissolving the main image so it becomes 2806transparent at a value of '<code>200</code>'. If both percentages 2807are given, each image are dissolved to the percentages given. </p> 2808 2809<p>Note that dissolve percentages do not add, two opaque images dissolved 2810'50,50', produce a 75% transparency. For a 50% + 50% blending of the two 2811images, you would need to use dissolve values of '50,100'. </p> 2812 2813<div style="margin: auto;"> 2814 <h3><a class="anchor" id="distort"></a>-distort <var>method arguments</var></h3> 2815</div> 2816 2817<p class="magick-description">distort an image, using the given <var>method</var> and its required <var>arguments</var>.</p> 2818 2819<p>The <var>arguments</var> is a single string containing a list 2820of floating point numbers separated by commas or spaces. The number of 2821and meaning of the floating point values depends on the distortion <var>method</var> being used. </p> 2822 2823<p>Choose from these distortion types:</p> 2824 2825<table class="table table-sm table-striped"> 2826 <tr> 2827 <th style="width: 8%">Method</th> 2828 <th>Description</th> 2829 </tr> 2830 2831 <tr> 2832 <td>ScaleRotateTranslate <br/> SRT</td> 2833 <td> 2834 Distort image by first scaling and rotating about a given 'center', 2835 before translating that 'center' to the new location, in that order. It 2836 is an alternative method of specifying a 'Affine' type of 2837 distortion, but without shearing effects. It also provides a good way 2838 of rotating and displacing a smaller image for tiling onto a larger 2839 background (IE 2-dimensional animations). <br/> 2840 2841 The number of arguments determine the specific meaning of each 2842 argument for the scales, rotation, and translation operations. <br/> 2843 2844 <dl class="row"> 2845 <dt class="col-md-4">2:</dt><dd class="col-md-8"><var>Scale Angle</var></dd> 2846 <dt class="col-md-4">3:</dt><dd class="col-md-8"><var>X,Y Angle</var></dd> 2847 <dt class="col-md-4">4:</dt><dd class="col-md-8"><var>X,Y Scale Angle</var></dd> 2848 <dt class="col-md-4">5:</dt> <dd class="col-md-8"><var>X,Y ScaleX,ScaleY Angle</var></dd> 2849 <dt class="col-md-4">6:</dt> <dd class="col-md-8"><var>X,Y Scale Angle NewX,NewY</var></dd> 2850 <dt class="col-md-4">7:</dt> <dd class="col-md-8"><var>X,Y ScaleX,ScaleY Angle NewX,NewY</var></dd> 2851 </dl> 2852 2853 This is actually an alternative way of specifying a 2 dimensional linear 2854 'Affine' or 'AffineProjection' distortion. </td> </tr> 2855 2856 <tr> 2857 <td>Affine</td> 2858 <td> 2859 Distort the image linearly by moving a list of at least 3 or more sets 2860 of control points (as defined below). Ideally 3 sets or 12 floating 2861 point values are given allowing the image to be linearly scaled, 2862 rotated, sheared, and translated, according to those three points. See 2863 also the related 'AffineProjection' and 'SRT' 2864 distortions. <br/> 2865 2866 More than 3 sets given control point pairs (12 numbers) is least 2867 squares fitted to best match a linear affine distortion. If only 2 2868 control point pairs (8 numbers) are given a two point image translation 2869 rotation and scaling is performed, without any possible shearing, 2870 flipping or changes in aspect ratio to the resulting image. If only one 2871 control point pair is provides the image is only translated, (which may 2872 be a floating point non-integer translation). <br/> 2873 2874 This distortion does not include any form of perspective distortion. 2875 </td> 2876 2877 </tr> 2878 2879 <tr> 2880 <td>AffineProjection</td> 2881 <td> 2882 Linearly distort an image using the given Affine Matrix of 6 2883 pre-calculated coefficients forming a set of Affine Equations to map 2884 the source image to the destination image. 2885 2886 <p class="text-center"><var> 2887 s<sub>x</sub>, r<sub>x</sub>, 2888 r<sub>y</sub>, s<sub>y</sub>, 2889 t<sub>x</sub>, t<sub>y</sub> 2890 </var></p> 2891 2892 See <a href="command-line-options.html#affine" >-affine</a> setting for more detail, and 2893 meanings of these coefficients. <br/> 2894 2895 The distortions 'Affine' and 'SRT' provide 2896 alternative methods of defining this distortion, with ImageMagick doing 2897 the calculations needed to generate the required coefficients. You can 2898 see the internally generated coefficients, by using a <a 2899 href="command-line-options.html#verbose" >-verbose</a> setting with those other variants. </td> 2900 2901 </tr> 2902 2903 <tr> 2904 <td>BilinearForward<br/> 2905 BilinearReverse</td> 2906 <td> 2907 Bilinear Distortion, given a minimum of 4 sets of coordinate pairs, or 2908 16 values (see below). Not that lines may not appear straight after 2909 distortion, though the distance between coordinates will remain 2910 consistent. <br/> 2911 2912 The 'BilinearForward' is used to map rectangles to any 2913 quadrilateral, while the 'BilinearReverse' form maps any 2914 quadrilateral to a rectangle, while preserving the straight line edges 2915 in each case. <br/> 2916 2917 Note that 'BilinearForward' can generate invalid pixels 2918 which will be colored using the <a href="command-line-options.html#mattecolor" >-mattecolor</a> 2919 color setting. Also if the quadrilateral becomes 'flipped' the image 2920 may disappear. <br/> 2921 2922 There are future plans to produce a true Bilinear distortion that will 2923 attempt to map any quadrilateral to any other quadrilateral, while 2924 preserving edges (and edge distance ratios). 2925 2926 </td> 2927 </tr> 2928 2929 <tr> 2930 <td>Perspective</td> 2931 <td> 2932 Perspective distort the images, using a list of 4 or more sets of 2933 control points (as defined below). More that 4 sets (16 numbers) of 2934 control points provide least squares fitting for more accurate 2935 distortions (for the purposes of image registration and panorama 2936 effects). Less than 4 sets will fall back to a 'Affine' 2937 linear distortion. <br/> 2938 2939 Perspective Distorted images ensures that straight lines remain 2940 straight, but the scale of the distorted image will vary. The horizon 2941 is anti-aliased, and the 'sky' color may be set using the 2942 <a href="command-line-options.html#mattecolor" >-mattecolor</a> setting. </td> 2943 </tr> 2944 2945 <tr> 2946 <td>PerspectiveProjection </td> 2947 <td> 2948 Do a 'Perspective' distortion biased on a set of 8 2949 pre-calculated coefficients. You can get these coefficients by looking 2950 at the <a href="command-line-options.html#verbose" >-verbose</a> output of a 2951 'Perspective' distortion, or by calculating them yourself. 2952 If the last two perspective scaling coefficients are zero, the 2953 remaining 6 represents a transposed 'Affine Matrix'. </td> 2954 </tr> 2955 2956 <tr> 2957 <td>Polynomial</td> 2958 <td> 2959 Do an Nth order 2D 'Polynomial' distortion using a set of corresponding 2960 control points. The order of the polynomial dictates the minimum number of 2961 control points needed. Order 1 is the same as -distort Affine. Order 1.5 is the 2962 same as -distort BilinearReverse. Typical use is for a 2nd order distortion. 2963 There is no +distort polynomial.</td> 2964 </tr> 2965 2966 <tr> 2967 <td>Arc</td> 2968 <td> 2969 Arc the image (variation of polar mapping) over the angle given around 2970 a circle. 2971 2972 <dl class="row"> 2973 <dt class="col-md-4">arc_angle</dt> 2974 <dd class="col-md-8">The angle over which to arc the image side-to-side</dd> 2975 <dt class="col-md-4">rotate_angle</dt> 2976 <dd class="col-md-8">Angle to rotate resulting image from vertical center</dd> 2977 <dt class="col-md-4">top_radius</dt> 2978 <dd class="col-md-8">Set top edge of source image at this radius</dd> 2979 <dt class="col-md-4">bottom_radius </dt> 2980 <dd class="col-md-8">Set bottom edge to this radius (radial scaling)</dd> 2981 </dl> 2982 2983 The resulting image is always resized to best fit the resulting image, 2984 (as if using <a href="command-line-options.html#distort" >+distort</a>) while attempting to 2985 preserve scale and aspect ratio of the original image as much as 2986 possible with the arguments given by the user. All four arguments will 2987 be needed to change the overall aspect ratio of an 'Arc'ed image. <br/> 2988 2989 This a variation of a polar distortion designed to try to preserve the 2990 aspect ratio of the image rather than direct Cartesian to Polar 2991 conversion. </td> 2992 </tr> 2993 2994 <tr> 2995 <td>Polar</td> 2996 <td> 2997 Like 'Arc' but do a complete Cartesian to Polar mapping of 2998 the image. that is the height of the input image is mapped to the 2999 radius limits, while the width is wrapped around between the 3000 angle limits. <br/> 3001 3002 Arguments: <var>Rmax,Rmin CenterX,CenterY, start,end_angle</var> <br/> 3003 3004 All arguments are optional. With <var>Rmin</var> defaulting to zero, the 3005 center to the center of the image, and the angles going from -180 (top) 3006 to +180 (top). If <var>Rmax</var> is given the special value of 3007 '0', the the distance from the center to the nearest edge 3008 is used for the radius of the output image, which will ensure the whole 3009 image is visible (though scaled smaller). However a special value of 3010 '-1' will use the distance from the center to the furthest 3011 corner, This may 'clip' the corners from the input rectangular image, 3012 but will generate the exact reverse of a 'DePolar' with 3013 the same arguments. <br/> 3014 3015 If the plus form of distort (<a href="command-line-options.html#distort" >+distort</a>) is used 3016 output image center will default to 0,0 of the virtual 3017 canvas, and the image size adjusted to ensure the whole input image is 3018 made visible in the output image on the virtual canvas. </td> 3019 3020 </tr> 3021 3022 <tr> 3023 <td>DePolar</td> 3024 <td> 3025 Uses the same arguments and meanings as a 'Polar' distortion 3026 but generates the reverse Polar to Cartesian distortion. <br/> 3027 3028 The special <var>Rmax</var> setting of '0' may however clip 3029 the corners of the input image. However using the special 3030 <var>Rmax</var> setting of '-1' (maximum center to corner 3031 distance) will ensure the whole distorted image is preserved in the 3032 generated result, so that the same argument to 'Polar' will 3033 reverse the distortion re-producing the original. 3034 3035 Note that as this distortion requires the area resampling of a circular 3036 arc, which can not be handled by the builtin EWA resampling function. 3037 As such the normal EWA filters are turned off. It is recommended some 3038 form of 'super-sampling' image processing technique be used to produce 3039 a high quality result. </td> 3040 3041 </tr> 3042 3043 <tr> 3044 <td>Barrel</td> 3045 <td> 3046 Given the four coefficients (A,B,C,D) as defined by <a 3047 href="http://wiki.panotools.org/Lens_correction_model" >Helmut 3048 Dersch</a>, perform a barrel or pin-cushion distortion appropriate to 3049 correct radial lens distortions. That is in photographs, make straight 3050 lines straight again. <br/> 3051 3052 <p class="text-center">Arguments: <var>A B C</var> [ <var>D</var> [ 3053 <var>X</var> , <var>Y</var> ] ] <br/> 3054 or <var>A<sub>x</sub> B<sub>x</sub> C<sub>x</sub> D<sub>x</sub> 3055 A<sub>y</sub> B<sub>y</sub> C<sub>y</sub> D<sub>y</sub></var> 3056 [ <var>X</var> , <var>Y</var> ] </p> 3057 So that it forms the function 3058 <p class="text-center">Rsrc = r * ( <var>A</var>*r<sup>3</sup> + <var>B</var>*r<sup>2</sup> + 3059 <var>C</var>*r + <var>D</var> )</p> 3060 3061 Where <var>X</var>,<var>Y</var> is the optional center of the distortion 3062 (defaulting to the center of the image). <br/> 3063 The second form is typically used to distort images, rather than 3064 correct lens distortions. <br/> 3065 </td> 3066 3067 </tr> 3068 3069 <tr> 3070 <td>BarrelInverse</td> 3071 <td> 3072 This is very similar to 'Barrel' with the same set of 3073 arguments, and argument handling. However it uses the inverse 3074 of the radial polynomial, 3075 so that it forms the function 3076 <p class="text-center">Rsrc = r / ( <var>A</var>*r<sup>3</sup> + <var>B</var>*r<sup>2</sup> + 3077 <var>C</var>*r + <var>D</var> )</p> 3078 Note that this is not the reverse of the 'Barrel' 3079 distortion, just a different barrel-like radial distortion method. 3080 3081 </td> 3082 </tr> 3083 3084 <tr> 3085 <td>Shepards</td> 3086 <td> 3087 Distort the given list control points (any number) using an Inverse 3088 Squared Distance Interpolation Method (<a 3089 href="http://en.wikipedia.org/wiki/Shepard%27s_method" >Shepards 3090 Method</a>). The control points in effect do 'localized' displacement 3091 of the image around the given control point (preserving the look and 3092 the rotation of the area near the control points. For best results 3093 extra control points should be added to 'lock' the positions of the 3094 corners, edges and other unchanging parts of the image, to prevent 3095 their movement. <br/> 3096 3097 The distortion has been likened to 'taffy pulling' using nails, or 3098 pins' stuck in a block of 'jelly' which is then moved to the new 3099 position, distorting the surface of the jelly. <br/> 3100 3101 Internally it is equivalent to generating a displacement map (see <a 3102 href="command-line-options.html#displace" >-displace</a>) for source image color look-up using 3103 the <a href="command-line-options.html#sparse-color" >-sparse-color</a> method of the same name. 3104 3105 </td> 3106 </tr> 3107 3108</table> 3109 3110<p>To print a complete list of distortion methods, use <a href="command-line-options.html#list">-list 3111distort</a>.</p> 3112 3113<p>Many of the above distortion methods such as '<code>Affine</code>', 3114'<code>Perspective</code>', and '<code>Shepards</code>' use a list control points 3115defining how these points in the given image should be distorted in the 3116destination image. Each set of four floating point values represent a source 3117image coordinate, followed immediately by the destination image coordinate. 3118This produces a list of values such as...</p> 3119<p class="text-center"><var> 3120 U<sub>1</sub>,V<sub>1</sub> X<sub>1</sub>,Y<sub>1</sub> 3121 U<sub>2</sub>,V<sub>2</sub> X<sub>2</sub>,Y<sub>2</sub> 3122 U<sub>3</sub>,V<sub>3</sub> X<sub>3</sub>,Y<sub>3</sub> 3123 ... 3124 U<sub>n</sub>,V<sub>n</sub> X<sub>n</sub>,Y<sub>n</sub> 3125</var></p> 3126<p>where <var>U,V</var> on the source image is mapped to <var>X,Y</var> on the 3127destination image. </p> 3128 3129<p>For example, to warp an image using '<code>perspective</code>' distortion, 3130needs a list of at least 4 sets of coordinates, or 16 numbers. Here is the 3131perspective distortion of the built-in "rose:" image. Note how spaces were 3132used to group the 4 sets of coordinate pairs, to make it easier to read and 3133understand.</p> 3134 3135<pre class="highlight"><code>convert rose: -virtual-pixel black \ 3136 -distort Perspective '0,0,0,0 0,45,0,45 69,0,60,10 69,45,60,35' \ 3137 rose_3d_rotated.gif" 3138</code></pre> 3139 3140<p>If more that the required number of coordinate pairs are given for 3141a distortion, the distortion method is 'least squares' fitted to produce the 3142best result for all the coordinate pairs given. If less than the ideal number 3143of points are given, the distort will generally fall back to a simpler form of 3144distortion that can handles the smaller number of coordinates (usually a linear 3145'<code>Affine</code>' distortion). </p> 3146 3147<p>By using more coordinates you can make use of image registration tool to 3148find matching coordinate pairs in overlapping images, so as to improve the 3149'fit' of the distortion. Of course a bad coordinate pair can also make the 3150'fit' worse. Caution is always advised. </p> 3151 3152<p>Colors are acquired from the source image according to a cylindrical 3153resampling <a href="command-line-options.html#filter" >-filter</a>, using a special technique known as 3154EWA resampling. This produces very high quality results, especially when 3155images become smaller (minified) in the output, which is very common when 3156using '<code>perspective</code>' distortion. For example here we view 3157a infinitely tiled 'plane' all the way to the horizon. </p> 3158 3159<pre class="highlight"><code>convert -size 90x90 pattern:checkerboard -normalize -virtual-pixel tile \ 3160 -distort perspective '0,0,5,45 89,0,45,46 0,89,0,89 89,89,89,89' \ 3161 checks_tiled.jpg 3162</code></pre> 3163 3164<p>Note that a infinitely tiled perspective images involving the horizon can 3165be very slow, because of the number of pixels that are compressed to generate 3166each individual pixel close to the 'horizon'. You can turn off EWA 3167resampling, by specifying the special <a href="command-line-options.html#filter" >-filter</a> setting of 3168'<code>point</code>' (recommended if you plan to use super-sampling instead). 3169</p> 3170 3171<p>If an image generates <i>invalid pixels</i>, such as the 'sky' in the last 3172example, <a href="command-line-options.html#distort" >-distort</a> will use the current <a 3173href="command-line-options.html#mattecolor" >-mattecolor</a> setting for these pixels. If you do not 3174what these pixels to be visible, set the color to match the rest of the 3175ground. </p> 3176 3177<p>The output image size will by default be the same as the input image. This 3178means that if the part of the distorted image falls outside the viewed area of 3179the 'distorted space', those parts is clipped and lost. However if you use 3180the plus form of the operator (<a href="command-line-options.html#distort" >+distort</a>) the operator 3181will attempt (if possible) to show the whole of the distorted image, while 3182retaining a correct 'virtual canvas' offset, for image layering. This offset 3183may need to be removed using <a href="command-line-options.html#repage" >+repage</a>, to remove if it 3184is unwanted. </p> 3185 3186<p>Setting <a href="command-line-options.html#verbose" >-verbose</a> setting, will cause <a 3187href="command-line-options.html#distort" >-distort</a> to attempt to output the internal coefficients, 3188and the <a href="command-line-options.html#fx" >-fx</a> equivalent to the distortion, for expert study, 3189and debugging purposes. This many not be available for all distorts. </p> 3190 3191<p>You can alternatively specify a special "<code><a href="command-line-options.html#define" 3192>-define</a> distort:viewport={geometry_string}</code>" setting which will 3193specify the size and the offset of the generated 'viewport' image of the 3194distorted image space.</p> 3195 3196<p>Setting a "<code><a href="command-line-options.html#define" >-define</a> 3197distort:scale=<var>scale_factor</var></code>" will scale the output image (viewport or 3198otherwise) by that factor without changing the viewed contents of the 3199distorted image. This can be used either for 'super-sampling' the image for 3200a higher quality result, or for panning and zooming around the image (with 3201appropriate viewport changes, or post-distort cropping and resizing). </p> 3202 3203<p>Setting "<code><a href="command-line-options.html#define" >-define</a> resample:verbose=1</code>" 3204will output the cylindrical filter lookup table created by the EWA (Elliptical 3205Weighted Average) resampling algorithm. Note this table uses a squared radius 3206lookup value. This is typically only used for debugging EWA resampling. </p> 3207 3208 3209<div style="margin: auto;"> 3210 <h3><a class="anchor" id="distribute-cache"></a>-distribute-cache <var>port</var></h3> 3211</div> 3212 3213<p class="magick-description">launch a distributed pixel cache server. </p> 3214 3215<div style="margin: auto;"> 3216 <h3><a class="anchor" id="dither"></a>-dither <var>method</var></h3> 3217</div> 3218 3219<p class="magick-description">Apply a Riemersma or Floyd-Steinberg error diffusion dither to 3220images when general color reduction is applied via an option, or automagically 3221when saving to specific formats. This enabled by default.</p> 3222 3223<p>Dithering places two or more colors in neighboring pixels so that to the 3224eye a closer approximation of the images original color is reproduced. This 3225reduces the number of colors needed to reproduce the image but at the cost of 3226a lower level pattern of colors. Error diffusion dithers can use any set of 3227colors (generated or user defined) to an image. </p> 3228 3229<p>Dithering is turned on by default, to turn it off use the plus form of the 3230setting, <a href="command-line-options.html#dither">+dither</a>. This will also also render PostScript 3231without text or graphic aliasing. Disabling dithering often (but not always) 3232leads to faster process, a smaller number of colors, but more cartoon like 3233image coloring. Generally resulting in 'color banding' effects in areas with 3234color gradients. </p> 3235 3236<p>The color reduction operators <a href="command-line-options.html#colors">-colors</a>, <a 3237href="command-line-options.html#monochrome">-monochrome</a>, <a href="command-line-options.html#remap ">-remap</a>, and <a 3238href="command-line-options.html#posterize">-posterize</a>, apply dithering to images using the reduced 3239color set they created. These operators are also used as part of automatic 3240color reduction when saving images to formats with limited color support, such 3241as <code>GIF:</code>, <code>XBM:</code>, and others, so dithering may also be used 3242in these cases. </p> 3243 3244<p>Alternatively you can use <a href="command-line-options.html#random-threshold">-random-threshold</a> 3245to generate purely random dither. Or use <a 3246href="command-line-options.html#ordered-dither">-ordered-dither</a> to apply threshold mapped dither 3247patterns, using uniform color maps, rather than specific color maps. </p> 3248<p>Use "<code><a href="command-line-options.html#define" >-define</a> dither:diffusion-amount=35%</code>, for example, to control the amount of Floyd-Steinberg dither.</p> 3249 3250 3251<div style="margin: auto;"> 3252 <h3><a class="anchor" id="draw"></a>-draw <var>string</var></h3> 3253</div> 3254 3255<p class="magick-description">Annotate an image with one or more graphic primitives.</p> 3256 3257<p>Use this option to annotate or decorate an image with one or more graphic 3258primitives. The primitives include shapes, text, transformations, and pixel 3259operations.</p> 3260 3261<p>The shape primitives:</p> 3262 3263<dl class="row"> 3264<dt class="col-md-4">point</dt><dd class="col-md-8"> x,y</dd> 3265<dt class="col-md-4">line</dt><dd class="col-md-8"> x0,y0 x1,y1</dd> 3266<dt class="col-md-4">rectangle</dt><dd class="col-md-8"> x0,y0 x1,y1</dd> 3267<dt class="col-md-4">roundRectangle</dt><dd class="col-md-8"> x0,y0 x1,y1 wc,hc</dd> 3268<dt class="col-md-4">arc</dt><dd class="col-md-8"> x0,y0 x1,y1 a0,a1</dd> 3269<dt class="col-md-4">ellipse</dt><dd class="col-md-8"> x0,y0 rx,ry a0,a1</dd> 3270<dt class="col-md-4">circle</dt><dd class="col-md-8"> x0,y0 x1,y1</dd> 3271<dt class="col-md-4">polyline</dt><dd class="col-md-8"> x0,y0 ... xn,yn</dd> 3272<dt class="col-md-4">polygon</dt><dd class="col-md-8"> x0,y0 ... xn,yn</dd> 3273<dt class="col-md-4">bezier</dt><dd class="col-md-8"> x0,y0 ... xn,yn</dd> 3274<dt class="col-md-4">path</dt><dd class="col-md-8">specification </dd> 3275<dt class="col-md-4">image</dt><dd class="col-md-8"> operator x0,y0 w,h filename</dd> 3276</dl> 3277 3278<p>The text primitive:</p> 3279 3280<dl class="row"> 3281<dt class="col-md-4">text</dt><dd class="col-md-8">x0,y0 string</dd> 3282</dl> 3283<p>The text gravity primitive:</p> 3284 3285<dl class="row"> 3286<dt class="col-md-4">gravity</dt><dd class="col-md-8">NorthWest, North, NorthEast, West, Center, East, SouthWest, South, or SouthEast</dd> 3287</dl> 3288 3289<p>The text gravity primitive only affects the placement of text and does not 3290interact with the other primitives. It is equivalent to using the <a 3291href="command-line-options.html#gravity">-gravity</a> command-line option, except that it is limited in 3292scope to the <a href="command-line-options.html#draw">-draw</a> option in which it appears.</p> 3293 3294<p>The transformation primitives:</p> 3295 3296<dl class="row"> 3297<dt class="col-md-4">rotate</dt><dd class="col-md-8">degrees</dd> 3298<dt class="col-md-4">translate</dt><dd class="col-md-8">dx,dy</dd> 3299<dt class="col-md-4">scale</dt><dd class="col-md-8">sx,sy</dd> 3300<dt class="col-md-4">skewX</dt><dd class="col-md-8">degrees</dd> 3301<dt class="col-md-4">skewY</dt><dd class="col-md-8">degrees</dd> 3302</dl> 3303 3304<p>The pixel operation primitives:</p> 3305 3306<dl class="row"> 3307<dt class="col-md-4">color</dt><dd class="col-md-8">x0,y0 method</dd> 3308<dt class="col-md-4">matte</dt><dd class="col-md-8">x0,y0 method</dd> 3309</dl> 3310 3311<p>The shape primitives are drawn in the color specified by the preceding <a 3312href="command-line-options.html#fill">-fill</a> setting. For unfilled shapes, use <a 3313href="command-line-options.html#fill">-fill none</a>. You can optionally control the stroke (the 3314"outline" of a shape) with the <a href="command-line-options.html#stroke">-stroke</a> and <a 3315href="command-line-options.html#strokewidth">-strokewidth</a> settings.</p> 3316 3317<p>A <code>point</code> primitive is specified by a single <var>point</var> in the 3318pixel plane, that is, by an ordered pair of integer coordinates, 3319<var>x</var>,<var>y</var>. (As it involves only a single pixel, a <code>point</code> 3320primitive is not affected by <a href="command-line-options.html#stroke">-stroke</a> or <a 3321href="command-line-options.html#strokewidth">-strokewidth</a>.)</p> 3322 3323<p>A <code>line</code> primitive requires a start point and end point.</p> 3324 3325<p>A <code>rectangle</code> primitive is specified by the pair of points at the 3326upper left and lower right corners.</p> 3327 3328<p>A <code>roundRectangle</code> primitive takes the same corner points as 3329a <code>rectangle</code> followed by the width and height of the rounded corners 3330to be removed.</p> 3331 3332<p>The <code>circle</code> primitive makes a disk (filled) or circle (unfilled). 3333Give the center and any point on the perimeter (boundary).</p> 3334 3335<p>The <code>arc</code> primitive is used to inscribe an elliptical segment in 3336to a given rectangle. An <code>arc</code> requires the two corners used for 3337<code>rectangle</code> (see above) followed by the start and end angles of the 3338arc of the segment segment (e.g. 130,30 200,100 45,90). The start and end 3339points produced are then joined with a line segment and the resulting segment 3340of an ellipse is filled.</p> 3341 3342<p>Use <code>ellipse</code> to draw a partial (or whole) ellipse. Give the 3343center point, the horizontal and vertical "radii" (the <var>semi-axes</var> of 3344the ellipse) and start and end angles in degrees (e.g. 100,100 100,150 33450,360).</p> 3346 3347<p>The <code>polyline</code> and <code>polygon</code> primitives require three or 3348more points to define their perimeters. A <code>polyline</code> is simply 3349a <code>polygon</code> in which the final point is not stroked to the start 3350point. When unfilled, this is a <var>polygonal line</var>. If the <a 3351href="command-line-options.html#stroke">-stroke</a> setting is <code>none</code> (the default), then 3352a <code>polyline</code> is identical to a <code>polygon</code>. </p> 3353 3354<p>A <var>coordinate</var> is a pair of integers separated by a space or 3355optional comma. </p> 3356 3357<p>As an example, to define a circle centered at 100,100 that extends to 3358150,150 use:</p> 3359 3360<pre class="highlight"><code>-draw 'circle 100,100 150,150' 3361</code></pre> 3362 3363<p>The <code>Bezier</code> primitive creates a spline curve and requires three 3364or points to define its shape. The first and last points are the 3365<var>knots</var> and these points are attained by the curve, while any 3366intermediate coordinates are <var>control points</var>. If two control points 3367are specified, the line between each end knot and its sequentially respective 3368control point determines the tangent direction of the curve at that end. If 3369one control point is specified, the lines from the end knots to the one 3370control point determines the tangent directions of the curve at each end. If 3371more than two control points are specified, then the additional control points 3372act in combination to determine the intermediate shape of the curve. In order 3373to draw complex curves, it is highly recommended either to use the 3374<code>path</code> primitive or to draw multiple four-point bezier segments with 3375the start and end knots of each successive segment repeated. For example:</p> 3376 3377<pre class="highlight"><code>-draw 'bezier 20,50 45,100 45,0 70,50' 3378-draw 'bezier 70,50 95,100 95,0 120,50' 3379</code></pre> 3380 3381<p>A <code>path</code> represents an outline of an object, defined in terms of 3382moveto (set a new current point), lineto (draw a straight line), curveto (draw 3383a Bezier curve), arc (elliptical or circular arc) and closepath (close the 3384current shape by drawing a line to the last moveto) elements. Compound paths 3385(i.e., a path with subpaths, each consisting of a single moveto followed by 3386one or more line or curve operations) are possible to allow effects such as 3387<var>donut holes</var> in objects. (See <a 3388href="http://www.w3.org/TR/SVG/paths.html">Paths</a>.)</p> 3389 3390<p>Use <code>image</code> to composite an image with another image. Follow the 3391image keyword with the composite operator, image location, image size, and 3392filename:</p> 3393 3394<pre class="highlight"><code>-draw 'image SrcOver 100,100 225,225 image.jpg' 3395</code></pre> 3396 3397<p>You can use 0,0 for the image size, which means to use the actual 3398dimensions found in the image header. Otherwise, it is scaled to the given 3399dimensions. See <a href="../www/compose.html">Alpha Compositing</a> for 3400a detailed discussion of alpha composition methods that are available. </p> 3401 3402<p>The "special augmented compose operators" such as "dissolve" that require 3403arguments cannot be used at present with the <code>-draw image</code> option. 3404 </p> 3405 3406<p>Use <code>text</code> to annotate an image with text. Follow the text 3407coordinates with a string. If the string has embedded spaces, enclose it in 3408single or double quotes.</p> 3409 3410<p>For example, the following annotates the image with <code>Works like 3411magick!</code> for an image titled <code>bird.miff</code>. </p> 3412 3413<pre class="highlight"><code>-draw "text 100,100 'Works like magick!' " 3414</code></pre> 3415 3416<p>See the <a href="command-line-options.html#annotate">-annotate</a> option for another convenient way 3417to annotate an image with text.</p> 3418 3419<p>The <code>rotate</code> primitive rotates subsequent shape primitives and 3420text primitives about the origin of the main image.</p> 3421 3422<p>The <code>translate</code> primitive translates subsequent shape and text 3423primitives.</p> 3424 3425<p>The <code>scale</code> primitive scales them.</p> 3426 3427<p>The <code>skewX</code> and <code>skewY</code> primitives skew them with respect 3428to the origin of the main image or the region.</p> 3429 3430<p>The transformations modify the current affine matrix, which is initialized 3431from the initial affine matrix defined by the <a href="command-line-options.html#affine">-affine</a> 3432option. Transformations are cumulative within the <a href="command-line-options.html#draw">-draw</a> 3433option. The initial affine matrix is not affected; that matrix is only changed 3434by the appearance of another <a href="command-line-options.html#affine">-affine</a> option. If another 3435<a href="command-line-options.html#draw">-draw</a> option appears, the current affine matrix is 3436reinitialized from the initial affine matrix.</p> 3437 3438<p>Use the <code>color</code> primitive to change the color of a pixel to the 3439fill color (see <a href="command-line-options.html#fill">-fill</a>). Follow the pixel coordinate with 3440a method:</p> 3441 3442<pre class="highlight"><code>point 3443replace 3444floodfill 3445filltoborder 3446reset 3447</code></pre> 3448 3449<p>Consider the target pixel as that specified by your coordinate. The 3450<code>point</code> method recolors the target pixel. The <code>replace</code> 3451method recolors any pixel that matches the color of the target pixel. 3452<code>Floodfill</code> recolors any pixel that matches the color of the target 3453pixel and is a neighbor, whereas <code>filltoborder</code> recolors any neighbor 3454pixel that is not the border color. Finally, <code>reset</code> recolors all 3455pixels.</p> 3456 3457<p>Use <code>matte</code> to the change the pixel matte value to transparent. 3458Follow the pixel coordinate with a method (see the <code>color</code> primitive 3459for a description of methods). The <code>point</code> method changes the matte 3460value of the target pixel. The <code>replace</code> method changes the matte 3461value of any pixel that matches the color of the target pixel. 3462<code>Floodfill</code> changes the matte value of any pixel that matches the 3463color of the target pixel and is a neighbor, whereas <code>filltoborder</code> 3464changes the matte value of any neighbor pixel that is not the border color (<a 3465href="command-line-options.html#bordercolor">-bordercolor</a>). Finally <code>reset</code> changes the 3466matte value of all pixels.</p> 3467 3468<p>You can set the primitive color, font, and font bounding box color with <a 3469href="command-line-options.html#fill">-fill</a>, <a href="command-line-options.html#font">-font</a>, and <a href="command-line-options.html#box">-box</a> 3470respectively. Options are processed in command line order so be sure to use 3471these options <var>before</var> the <a href="command-line-options.html#draw">-draw</a> option.</p> 3472 3473<p>Strings that begin with a number must be quoted (e.g. use '1.png' rather 3474than 1.png).</p> 3475 3476<p>Drawing primitives conform to the <a href="magick-vector-graphics.html" >Magick 3477Vector Graphics</a> format.</p> 3478<p>Note, drawing requires an alpha channel. If none is available, an all opaque alpha channel is implicitedly created.</p> 3479 3480 3481<div style="margin: auto;"> 3482 <h3><a class="anchor" id="duplicate"></a>-duplicate <var>count,indexes</var></h3> 3483</div> 3484 3485<p class="magick-description">duplicate an image one or more times.</p> 3486 3487<p>Specify the count and the image to duplicate by its index in the sequence. 3488The first image is index 0. Negative indexes are relative to the end of the 3489sequence, for example, -1 represents the last image of the sequence. Specify 3490a range of images with a dash (e.g. 0-4). Separate indexes with a comma (e.g. 34910,2). Use <code>+duplicate</code> to duplicate the last image in the current 3492image sequence.</p> 3493 3494<div style="margin: auto;"> 3495 <h3><a class="anchor" id="edge"></a>-edge <var>radius</var></h3> 3496</div> 3497 3498<p class="magick-description">detect edges within an image.</p> 3499 3500<div style="margin: auto;"> 3501 <h3><a class="anchor" id="emboss"></a>-emboss <var>radius</var></h3> 3502</div> 3503 3504<p class="magick-description">emboss an image.</p> 3505 3506<div style="margin: auto;"> 3507 <h3><a class="anchor" id="encipher"></a>-encipher <var>filename</var></h3> 3508</div> 3509 3510<p class="magick-description">Encipher pixels for later deciphering by <a href="command-line-options.html#decipher">-decipher</a>.</p> 3511 3512<p>Get the passphrase from the file specified by <var>filename</var>.</p> 3513 3514<p>For more information, see the webpage, <a href="cipher.html">ImageMagick: Encipher or 3515Decipher an Image</a>.</p> 3516 3517 3518 3519<div style="margin: auto;"> 3520 <h3><a class="anchor" id="encoding"></a>-encoding <var>type</var></h3> 3521</div> 3522 3523<p class="magick-description">specify the text encoding.</p> 3524 3525<p>Choose from</p> 3526 3527<pre class="highlight"><code>AdobeCustom AdobeExpert 3528AdobeStandard AppleRoman 3529BIG5 GB2312 3530Latin 2 None 3531SJIScode Symbol 3532Unicode Wansung 3533</code></pre> 3534 3535<div style="margin: auto;"> 3536 <h3><a class="anchor" id="endian"></a>-endian <var>type</var></h3> 3537</div> 3538 3539<p class="magick-description">Specify endianness (<code>MSB</code> or <code>LSB</code>) of the image.</p> 3540 3541<p>To print a complete list of endian types, use the <a href="command-line-options.html#list">-list endian</a> option.</p> 3542 3543<p>Use <a href="command-line-options.html#endian">+endian</a> to revert to unspecified endianness.</p> 3544 3545 3546<div style="margin: auto;"> 3547 <h3><a class="anchor" id="enhance"></a>-enhance</h3> 3548</div> 3549 3550<p class="magick-description">Apply a digital filter to enhance a noisy image.</p> 3551 3552 3553<div style="margin: auto;"> 3554 <h3><a class="anchor" id="equalize"></a>-equalize</h3> 3555</div> 3556 3557<p class="magick-description">perform histogram equalization on the image channel-by-channel.</p> 3558 3559<p>To perform histogram equalization on all channels in concert, transform the 3560image into some other color space, such as HSL, OHTA, YIQ or YUV, then 3561equalize the appropriate intensity-like channel, then convert back to RGB.</p> 3562 3563<p>For example using HSL, we have: ... <code>-colorspace HSL -channel lightness 3564-equalize -colorspace sRGB</code> ...</p> 3565 3566<p>For YIQ, YUV and OHTA use the red channel. For example, OHTA is a principal 3567components transformation that puts most of the information in the first 3568channel. Here we have ... <code>-colorspace OHTA -channel red -equalize 3569-colorspace sRGB</code> ...</p> 3570 3571<div style="margin: auto;"> 3572 <h3><a class="anchor" id="evaluate"></a>-evaluate <var>operator value</var></h3> 3573</div> 3574 3575<p class="magick-description">Alter channel pixels by evaluating an arithmetic, relational, or logical expression.</p> 3576 3577<p>(See the <a href="command-line-options.html#function" >-function</a> operator for some 3578multi-parameter functions. See the <a href="command-line-options.html#fx" >-fx</a> operator if more 3579elaborate calculations are needed.)</p> 3580 3581<p>The behaviors of each <var>operator</var> are summarized in the 3582following list. For brevity, the numerical value of a "pixel" referred to 3583below is the value of the corresponding channel of that pixel, while 3584a "normalized pixel" is that number divided by the maximum 3585(installation-dependent) value <var>QuantumRange</var>. (If 3586normalized pixels are used, they are restored, following the other 3587calculations, to the full range by multiplying by <var>QuantumRange</var>.)</p> 3588 3589<table class="table table-sm table-striped"> 3590 <col width="25%" /> 3591 <col width="75%" /> 3592 <thead> 3593 <tr> 3594 <th><var>operator</var></th> 3595 <th>Summary (see further below for details)</th> 3596 </tr> 3597 </thead> 3598 <tbody> 3599 3600 <tr><td>Abs </td> <td>Add <var>value</var> to pixels and return absolute value. </td></tr> 3601 <tr><td>Add </td> <td>Add <var>value</var> to pixels. </td></tr> 3602 <tr><td>AddModulus </td> <td>Add <var>value</var> to pixels modulo <var>QuantumRange</var>.</td></tr> 3603 <tr><td>And </td> <td>Binary AND of pixels with <var>value</var>.</td></tr> 3604 <tr><td>Cos, Cosine </td> <td>Apply cosine to pixels with frequency <var>value</var> with 50% bias added.</td></tr> 3605 <tr><td>Divide </td> <td>Divide pixels by <var>value</var>.</td></tr> 3606 <tr><td>Exp </td> <td>base-e exponential function</td></tr> 3607 <tr><td>Exponential </td> <td>base-e exponential function</td></tr> 3608 <tr><td>LeftShift </td> <td>Shift the pixel values left by <var>value</var> bits (i.e., multiply pixels by 2<sup><var>value</var></sup>).</td></tr> 3609 <tr><td>Log </td> <td>Apply scaled logarithm to normalized pixels.</td></tr> 3610 <tr><td>Max </td> <td>Set pixels to maximum of <var>value</var> and current pixel <var>value</var> (i.e. set any pixels currently less than <var>value</var> to <var>value</var>).</td></tr> 3611 <tr><td>Mean </td> <td>Add the <var>value</var> and divide by 2.</td></tr> 3612 <tr><td>Median </td> <td>Choose the median value from an image sequence.</td></tr> 3613 <tr><td>Min </td> <td>Set pixels to minimum of <var>value</var> and current pixel <var>value</var> (i.e. set any pixels currently greater than <var>value</var> to <var>value</var>).</td></tr> 3614 <tr><td>Multiply </td> <td>Multiply pixels by <var>value</var>.</td></tr> 3615 <tr><td>Or </td> <td>Binary OR of pixels with <var>value</var>.</td></tr> 3616 <tr><td>Pow </td> <td>Raise normalized pixels to the power <var>value</var>.</td></tr> 3617 <tr><td>RightShift </td> <td>Shift the pixel values right by <var>value</var> bits (i.e., divide pixels by 2<sup><var>value</var></sup>).</td></tr> 3618 <tr><td>RMS</td> <td>Square the pixel and add the <var>value</var>.</td></tr> 3619 <tr><td>RootMeanSquare</td> <td>Square the pixel and add the <var>value</var>.</td></tr> 3620 <tr><td>Set </td> <td>Set pixel equal to <var>value</var>.</td></tr> 3621 <tr><td>Sin, Sine </td> <td>Apply sine to pixels with frequency <var>value</var> with 50% bias added.</td></tr> 3622 <tr><td>Subtract </td> <td>Subtract <var>value</var> from pixels.</td></tr> 3623 <tr><td>Xor </td> <td>Binary XOR of pixels with <var>value.</var></td></tr> 3624 3625 <tr><td> </td><td> </td></tr> 3626 3627 <tr><td>Gaussian-noise</td><td> </td></tr> 3628 <tr><td>Impulse-noise</td><td> </td></tr> 3629 <tr><td>Laplacian-noise</td><td> </td></tr> 3630 <tr><td>Multiplicative-noise</td> <td>(These are equivalent to the corresponding <a href="command-line-options.html#noise" >-noise</a> operators.)</td></tr> 3631 <tr><td>PoissonNoise</td><td> </td></tr> 3632 <tr><td>Uniform-noise</td><td> </td></tr> 3633 3634 <tr><td> </td><td> </td></tr> 3635 3636 <tr><td>Threshold </td> <td>Threshold pixels larger than <var>value</var>.</td></tr> 3637 <tr><td>ThresholdBlack </td> <td>Threshold pixels to zero values equal to or below <var>value</var>.</td></tr> 3638 <tr><td>ThresholdWhite </td> <td>Threshold pixels to maximum values above <var>value</var>. </td></tr> 3639 </tbody> 3640 </table> 3641 3642<p>The specified functions are applied only to each previously set <a 3643href="command-line-options.html#channel" >-channel</a> in the image. If necessary, the results of the 3644calculations are truncated (clipped) to fit in the interval [0, <var>QuantumRange</var>]. The transparency channel of the image is 3645represented as a 'alpha' values (0 = fully transparent), so, for example, a 3646<code>Divide</code> by 2 of the alpha channel will make the image 3647semi-transparent. Append the percent symbol '<code>%</code>' to specify a value 3648as a percentage of the <var>QuantumRange</var>.</p> 3649 3650<p>To print a complete list of <a href="command-line-options.html#evaluate">-evaluate</a> operators, use 3651<a href="command-line-options.html#list">-list evaluate</a>.</p> 3652 3653<p>The results of the <code>Add</code>, <code>Subtract</code> and 3654<code>Multiply</code> methods can also be achieved using either the <a 3655href="command-line-options.html#level" >-level</a> or the <a href="command-line-options.html#level" >+level</a> operator, with 3656appropriate argument, to linearly modify the overall range of color values. 3657Please note, however, that <a href="command-line-options.html#level" >-level</a> treats transparency as 3658'matte' values (0 = opaque), while <a href="command-line-options.html#level" >-evaluate</a> works with 3659'alpha' values.</p> 3660 3661<p><code>AddModulus</code> has been added as of ImageMagick 6.4.8-4 and provides 3662addition modulo the <var>QuantumRange</var>. It is therefore 3663equivalent to <code>Add</code> unless the resulting pixel value is outside the 3664interval [0, <var>QuantumRange</var>]. </p> 3665 3666<p><code>Exp or Exponential</code> has been added as of ImageMagick 6.6.5-1 and 3667works on normalized pixel values. The <var>value</var> used with 3668<code>Exp</code> should be negative so as to produce a decaying exponential 3669function. Non-negative values will always produce results larger unity and 3670thus outside the interval [0, <var>QuantumRange</var>]. The 3671formula is expressed below. </p> 3672 3673<p class="text-center"> 3674exp(<var>value</var> × <b><var>u</var></b>) 3675</p> 3676 3677<p> If the input image is squared, for example, using <a href="command-line-options.html#-function" 3678>-function polynomial "2 0 0"</a>, then a decaying Gaussian function will be 3679the result.</p> 3680 3681<p><code>Log</code> has been added as of ImageMagick 6.4.2-1 and works on 3682normalized pixel values. This a <var>scaled</var> log function. The <var>value</var> used with <code>Log</code> provides a <var>scaling 3683factor</var> that adjusts the curvature in the graph of the log function. The 3684formula applied to a normalized value <b><var>u</var></b> is below. </p> 3685 3686<p class="text-center"> 3687log(<var>value</var> × <b><var>u</var></b> + 1) / log(<var>value</var> + 1) 3688</p> 3689 3690<p><code>Pow</code> has been added as of ImageMagick 6.4.1-9, and works on 3691normalized pixel values. Note that <code>Pow</code> is related to the <a 3692href="command-line-options.html#gamma" >-gamma</a> operator. For example, <b>-gamma 2</b> is equivalent 3693to <b>-evaluate pow 0.5</b>, i.e., a 'square root' function. The value used 3694with <a href="command-line-options.html#gamma" >-gamma</a> is simply the reciprocal of the value used 3695with <code>Pow</code>.</p> 3696 3697<p><code>Cosine</code> and <code>Sine</code> was added as of IM v6.4.8-8 and 3698converts the image values into a value according to a (co)sine wave function. 3699The synonyms <code>Cos</code> and <code>Sin</code> may also be used. The output 3700is biased 50% and normalized by 50% so as to fit in the respective color value 3701range. The <var>value</var> scaling of the <var>period</var> of the 3702function (its frequency), and thus determines the number of 'waves' that will 3703be generated over the input color range. For example, if the <var>value</var> is 1, the effective period is simply the <var>QuantumRange</var>; but if the <var>value</var> is 2, 3704then the effective period is the <var>half</var> the <var>QuantumRange</var>.</p> 3705 3706<p class="text-center"> 37070.5 + 0.5 × cos(2 π <b><var>u</var></b> × <var>value</var>). 3708</p> 3709 3710<p>See also the <a href="command-line-options.html#function" >-function</a> operator, which is a 3711multi-value version of evaluate. </p> 3712 3713<div style="margin: auto;"> 3714 <h3><a class="anchor" id="evaluate-sequence"></a>-evaluate-sequence <var>operator</var></h3> 3715</div> 3716 3717<p class="magick-description">Alter channel pixels by evaluating an arithmetic, relational, or logical expression over a sequence of images. Ensure all the images in the sequence are in the same colorspace, otherwise you may get unexpected results, e.g. add <a href="command-line-options.html#colorspace" >-colorspace sRGB</a> to your command-line.</p> 3718 3719<p>To print a complete list of <a 3720href="command-line-options.html#evaluate-sequence">-evaluate-sequence</a> operators, use <a 3721href="command-line-options.html#list">-list evaluate</a>.</p> 3722 3723<div style="margin: auto;"> 3724 <h3><a class="anchor" id="extent"></a>-extent <var>geometry</var></h3> 3725</div> 3726 3727<p class="magick-description">Set the image size and offset.</p> 3728 3729<p>If the image is enlarged, unfilled areas are set to the background color. 3730To position the image, use offsets in the <var>geometry</var> 3731specification or precede with a <a href="command-line-options.html#gravity">-gravity</a> setting. To 3732specify how to compose the image with the background, use <a href="command-line-options.html#compose" 3733>-compose</a>.</p> 3734 3735<p>This command reduces or expands a JPEG image to fit on an 800x600 3736display. If the aspect ratio of the input image isn't exactly 4:3, then the 3737image is centered on an 800x600 black canvas: </p> 3738 3739<pre class="highlight"><code>convert input.jpg -resize 800x600 -background black -compose Copy \ 3740 -gravity center -extent 800x600 -quality 92 output.jpg 3741</code></pre> 3742 3743<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 3744 3745<div style="margin: auto;"> 3746 <h3><a class="anchor" id="extract"></a>-extract <var>geometry</var></h3> 3747</div> 3748 3749<p class="magick-description">Extract the specified area from image.</p> 3750 3751<p>This option is most useful for extracting a subregion of a very large raw 3752image. Note that these two commands are equivalent:</p> 3753 3754<pre class="highlight"><code>convert -size 16000x16000 -depth 8 -extract 640x480+1280+960 \ 3755 image.rgb image.png", 3756convert -size 16000x16000 -depth 8 'image.rgb[640x480+1280+960]' \ 3757 image.rgb image.png" 3758</code></pre> 3759 3760<p>If you omit the offsets, as in</p> 3761 3762<pre class="highlight"><code>convert -size 16000x16000 -depth 8 -extract 640x480 \ 3763 image.rgb image.png 3764</code></pre> 3765 3766<p>the image is <var>resized</var> to the specified dimensions instead, 3767equivalent to:</p> 3768 3769<pre class="highlight"><code>convert -size 16000x16000 -depth 8 -resize 640x480 image.rgb image.png 3770</code></pre> 3771 3772<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 3773 3774<div style="margin: auto;"> 3775 <h3><a class="anchor" id="family"></a>-family <var>fontFamily</var></h3> 3776</div> 3777 3778<p class="magick-description">Set a font family for text.</p> 3779 3780<p>This setting suggests a font family that ImageMagick should try to use for 3781rendering text. If the family can be found it is used; if not, a default font 3782(e.g., "Arial") or a family known to be similar is substituted (e.g., 3783"Courier" might be used if "System" is requested but not found). </p> 3784 3785<p>For other settings that affect fonts, see the options <a 3786href="command-line-options.html#font">-font</a>, <a href="command-line-options.html#stretch">-stretch</a>, <a 3787href="command-line-options.html#style">-style</a>, and <a href="command-line-options.html#weight">-weight</a>. </p> 3788 3789<div style="margin: auto;"> 3790 <h3><a class="anchor" id="features"></a>-features <var>distance</var></h3> 3791</div> 3792 3793<p class="magick-description">display (co-occurrence matrix) texture measure features for each channel in the image in each of four directions (horizontal, vertical, left and right diagonals) for the specified distance.</p> 3794 3795<pre class="highlight"><code>Angular Second Moment Sum Entropy 3796Contrast Entropy 3797Correlation Difference Variance 3798Sum of Squares Variance Difference Entropy 3799Inverse Difference Moment Information Measure of Correlation 1 3800Sum Average Information Measure of Correlation 2 3801Sum Variance Maximum Correlation Coefficient 3802</code></pre> 3803 3804<div style="margin: auto;"> 3805 <h3><a class="anchor" id="fft"></a>-fft</h3> 3806</div> 3807 3808<p class="magick-description">implements the forward discrete Fourier transform (DFT).</p> 3809 3810<p>This option is new as of ImageMagick 6.5.4-3 (and now working for Windows 3811users in ImageMagick 6.6.0-9). It transforms an image from the normal 3812(spatial) domain to the frequency domain. In the frequency domain, an image is 3813represented as a superposition of complex sinusoidal waves of varying 3814amplitudes. The image x and y coordinates are the possible frequencies along 3815the x and y directions, respectively, and the pixel intensity values are 3816complex numbers that correspond to the sinusoidal wave amplitudes. See for 3817example, <a href="http://en.wikipedia.org/wiki/Fourier_transform">Fourier 3818Transform</a>, <a href="http://en.wikipedia.org/wiki/DFT">Discrete Fourier 3819Transform</a> and <a href="http://en.wikipedia.org/wiki/FFT">Fast Fourier 3820Transform</a>.</p> 3821 3822<p>A single image name is provided as output for this option. However, the 3823output result will have two components. It is either a two-frame image or two 3824separate images, depending upon whether the image format specified supports 3825multi-frame images. The reason that we get a dual output result is because the 3826frequency domain represents an image using complex numbers, which cannot be 3827visualized directly. Therefore, the complex values are automagically separated 3828into a two-component image representation. The first component is the 3829magnitude of the complex number and the second is the phase of the complex 3830number. See for example, <a 3831href="http://en.wikipedia.org/wiki/Complex_numbers">Complex Numbers</a>.</p> 3832 3833<p>The magnitude and phase component images must be specified using image 3834formats that do not limit the color or compress the image. Thus, MIFF, TIF, 3835PFM, EXR and PNG are the recommended image formats to use. All of these 3836formats, except PNG support multi-frame images. So for example,</p> 3837 3838<pre class="highlight"><code>convert image.png -fft fft_image.miff 3839</code></pre> 3840 3841<p>generates a magnitude image as <code>fft_image.miff[0]</code> and a phase 3842image as <code>fft_image.miff[1]</code>. Similarly,</p> 3843 3844<pre class="highlight"><code>convert image.png -fft fft_image.png 3845</code></pre> 3846 3847<p>generates a magnitude image as <code>fft_image-0.png</code> and a phase image 3848as <code>fft_image-1.png</code>. If you prefer this representation, then you can 3849force any of the other formats to produce two output images by including <a 3850href="command-line-options.html#adjoin">+adjoin</a> following -fft in the command line.</p> 3851 3852<p>The input image can be any size, but if not square and even-dimensioned, it 3853is padded automagically to the larger of the width or height of the input 3854image and to an even number of pixels. The padding will occur at the bottom 3855and/or right sides of the input image. The resulting output magnitude and 3856phase images is square at this size. The kind of padding relies on the <a 3857href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting.</p> 3858 3859<p>Both output components will have dynamic ranges that fit within 3860[0, <var>QuantumRange</var>], so that HDRI need not be enabled. 3861Phase values nominally range from 0 to 2*π, but is scaled to span the full 3862dynamic range. (The first few releases had non-HDRI scaled but HDRI not 3863scaled). The magnitude image is not scaled and thus generally will contain 3864very small values. As such, the image normally will appear totally black. In 3865order to view any detail, the magnitude image typically is enhanced with a log 3866function into what is usually called the spectrum. A log function is used to 3867enhance the darker values more in comparison to the lighter values. This can 3868be done, for example, as follows:</p> 3869 3870<pre class="highlight"><code>convert fft_image.miff[0] -contrast-stretch 0 \ 3871 -evaluate log 1000 fft_image_spectrum.png" 3872</code></pre> 3873 3874<p>where either <a href="command-line-options.html#contrast-stretch">-contrast-stretch</a> 0 or <a 3875href="command-line-options.html#auto-level">-auto-level</a> is used to scale the image to full dynamic 3876range, first. The argument to the <a href="command-line-options.html#evaluate">-evaluate</a> log 3877typically is specified between 100 and 10,000, depending upon the amount of 3878detail that one wants to bring out in the spectrum. Larger values produce more 3879visible detail. Too much detail, however, may hide the important features.</p> 3880 3881<p>The <a href="http://www.fftw.org/">FFTW</a> delegate library is required to 3882use <a href="command-line-options.html#fft">-fft</a>.</p> 3883 3884<p>Use <a href="command-line-options.html#fft">+fft</a> to produce two output images that are the real 3885and imaginary components of the complex valued Fourier transform.</p> 3886 3887<p>However, as the real and imaginary components can contain negative values, 3888this requires that IM be configured with HDRI enabled. In this case, you must 3889use either MIFF, TIF, PFM or MPC formats for the real and imaginary component 3890results, since they are formats that preserve both negative and fractional 3891values without clipping them or truncating the fractional part. With either 3892MIFF or TIF, one should add <code>-define quantum:format=32</code>, to allow those image 3893types to work properly in HDRI mode without clipping.</p> 3894 3895<p>The real and imaginary component images resulting from <a 3896href="command-line-options.html#fft">+fft</a> are also square, even dimensioned images due to the same 3897padding that was discussed above for the magnitude and phase component 3898images.</p> 3899 3900<p>See the discussion on HDRI implementations of ImageMagick on the page <a 3901href="high-dynamic-range.html" >High Dynamic-Range Images</a>. For more 3902about HDRI go the ImageMagick <a 3903href="../Usage/basics/#hdri" >Usage</a> pages, <a 3904href="http://www.fmwconcepts.com/imagemagick/fourier_transforms/fourier.html" 3905>Fred's Fourier Processing With ImageMagick page</a> or this <a 3906 href="http://en.wikipedia.org/wiki/High_dynamic_range_imaging" >Wikipedia</a> 3907 entry. </p> 3908 3909<p>By default the FFT is normalized (and the IFT is not). Use "<code><a href="command-line-options.html#define" >-define</a> fourier:normalize=forward</code> to explicitly normalize the FFT and unnormalize the IFT.</p> 3910 3911 3912<div style="margin: auto;"> 3913 <h3><a class="anchor" id="fill"></a>-fill <var>color</var></h3> 3914</div> 3915 3916<p class="magick-description">color to use when filling a graphic primitive.</p> 3917 3918<p>This option accepts a color name, a hex color, or a numerical RGB, RGBA, 3919HSL, HSLA, CMYK, or CMYKA specification. See <a href="color.html" >Color Names</a> for 3920a description of how to properly specify the color argument.</p> 3921 3922<p>Enclose the color specification in quotation marks to prevent the "#" or 3923the parentheses from being interpreted by your shell.</p> 3924 3925<p>For example,</p> 3926 3927<pre class="highlight"><code>-fill blue 3928-fill "#ddddff" 3929-fill "rgb(255,255,255)" 3930</code></pre> 3931 3932<p>See <a href="command-line-options.html#draw">-draw</a> for further details.</p> 3933 3934<p>To print a complete list of color names, use the <a href="command-line-options.html#list">-list color</a> option.</p> 3935 3936<div style="margin: auto;"> 3937 <h3><a class="anchor" id="filter"></a>-filter <var>type</var></h3> 3938</div> 3939 3940<p class="magick-description">Use this <var>type</var> of filter when resizing or distorting an image.</p> 3941 3942<p>Use this option to affect the resizing operation of an image during 3943operations such as <a href="command-line-options.html#resize">-resize</a> and <a href="command-line-options.html#distort" 3944>-distort</a>. For example you can use a simple resize filter such as:</p> 3945 3946<pre class="highlight"><code>Point Hermite Cubic 3947Box Gaussian Catrom 3948Triangle Quadratic Mitchell 3949CubicSpline 3950</code></pre> 3951 3952<p>Use <code>-define filter:lobes={2,3,4}</code> to specify the support size for filtering for the <code>CubicSpline</code> filter.</p> 3953 3954<p>The <code>Bessel</code> and <code>Sinc</code> filter is also provided (as well 3955as a faster <code>SincFast</code> equivalent form). However these filters are 3956generally useless on their own as they are infinite filters that are being 3957clipped to the filters support size. Their direct use is not recommended 3958except via expert settings (see below). </p> 3959 3960<p>Instead these special filter functions are typically windowed by a windowing 3961function that the <a href="command-line-options.html#filter" >-filter</a> setting defines. That is 3962using these functions will define a 'Windowed' filter, appropriate to the 3963operator involved. Windowed filters include: </p> 3964 3965<pre class="highlight"><code>Lanczos Hamming Parzen 3966Blackman Kaiser Welsh 3967Hanning Bartlett Bohman 3968</code></pre> 3969 3970<p>Also one special self-windowing filter is also provided 3971<code>Lagrange</code>, which will automagically re-adjust its function depending 3972on the current 'support' or 'lobes' expert settings (see below).</p> 3973 3974<p>If you do not select a filter with this option, the filter defaults to 3975<code>Mitchell</code> for a colormapped image, an image with a matte channel, or 3976if the image is enlarged. Otherwise the filter default to 3977<code>Lanczos</code>.</p> 3978 3979<p>To print a complete list of resize filters, use the <a href="command-line-options.html#list">-list 3980filter</a> option.</p> 3981 3982<p>You can modify how the filter behaves as it scales your image through the 3983use of these expert settings (see also <a href="command-line-options.html#define" >-define</a> and <a 3984href="command-line-options.html#set" >-set</a>):-</p> 3985 3986<table class="table table-sm table-striped"> 3987 <tr> 3988 <td>-define filter:blur=<var>factor</var></td> 3989 <td>Scale the X axis of the filter (and its window). Use > 1.0 for 3990 blurry or < 1.0 for sharp. This should only be used with Gaussian and 3991 Gaussian-like filters simple filters, or you may not get the expected 3992 results. </td> 3993 </tr> 3994 3995 <tr> 3996 <td>-define filter:support=<var>radius</var></td> 3997 <td>Set the filter support radius. Defines how large the filter should be and 3998 thus directly defines how slow the filtered resampling process is. All 3999 filters have a default 'preferred' support size. Some filters like 4000 <code>Lagrange</code> and windowed filters adjust themselves depending on 4001 this value. With simple filters this value either does nothing (but slow 4002 the resampling), or will clip the filter function in a detrimental way. 4003 </td> 4004 </tr> 4005 4006 <tr> 4007 <td>-define filter:lobes=<var>count</var></td> 4008 <td>Set the number of lobes to use for the Sinc/Bessel filter. This an 4009 alternative way of specifying the 'support' range of the filter, that is 4010 designed to be more suited to windowed filters, especially when used for 4011 image distorts.</td> 4012 </tr> 4013 4014 <tr> 4015 <td>-define filter:sigma=<var>value</var></td> 4016 <td>The 'sigma' value used to define the <code>Gaussian</code> filter. Default 4017 sigma value is '<code>0.5</code>'. It only affects <code>Gaussian</code> but 4018 does not shrink (but may enlarge) the filter's 'support'. It can be used 4019 to generate very small blurs but without the filter 'missing' pixels due 4020 to using a small support setting. A larger value of '<code>0.707</code>' 4021 (a value of '1/sqrt(2)') is another common setting. </td> 4022 </tr> 4023 4024 <tr> 4025 <td>-define filter:b=<var>b-spline_factor</var></td> 4026 </tr> 4027 4028 <tr> 4029 <td>-define filter:c=<var>keys_alpha_factor</var></td> 4030 <td>Redefine the values used for cubic filters such as <code>Cubic</code>, 4031 <code>Catrom</code>, <code>Mitchel</code>, and <code>Hermite</code>, as well as 4032 the <code>Parzen</code> cubic windowing function. If only one of the values 4033 are defined, the other is set so as to generate a 'Cubic-Keys' filter. 4034 The values meaning was defined by a research paper by 4035 Mitchell-Netravali.</td> 4036 </tr> 4037 4038 <tr> 4039 <td>-define filter:kaiser-beta=<var>value</var></td> 4040 <td>The 'alpha' value used to as part of the Kaiser Windowing function. 4041 Default value is '6.5'. It only affects Kaiser windowing function, and 4042 does not affect any other attributes. 4043 Before ImageMagick v6.7.6-10, this option was known as "filter:alpha", (an 4044 inheritance from the very old "zoom" program). It was changed to bring the 4045 function in line with more modern academic research usage, and better 4046 assign it be more definitive. </td> 4047 </tr> 4048 4049 <tr> 4050 <td>-define filter:kaiser-alpha=<var>value</var></td> 4051 <td>This value when multiplied by 'PI' is equivalent to "kaiser-beta", and 4052 will override that setting. It only affects Kaiser windowing function, 4053 and does not affect any other attributes. </td> 4054 </tr> 4055 4056 <tr> 4057 <td>-define filter:filter=<var>filter_function</var></td> 4058 <td>Use this function directly as the weighting filter. This will allow 4059 you to directly use a windowing function such as <code>Blackman</code>, 4060 as a resampling filter, rather than as its normal usage as a windowing 4061 function. If defined, no windowing function also defined, the window function is set 4062 to <code>Box</code>). Directly specifying <code>Sinc</code> or <code>Jinc</code> 4063 as a filter will also do this. </td> 4064 </tr> 4065 4066 <tr> 4067 <td>-define filter:window=<var>filter_function</var></td> 4068 <td>The IIR (infinite impulse response) filters <code>Sinc</code> and 4069 <code>Jinc</code> are windowed (brought down to zero over the defined 4070 support range) with the given filter. This allows you to specify a filter 4071 function to be used as a windowing function for these IIR filters. 4072 Many of the defined filters are actually windowing functions for these IIR 4073 filters. A typical choices is <code>Box</code>, (which effectively turns 4074 off the windowing function). </td> 4075 </tr> 4076 4077 <tr> 4078 <td>-define filter:win-support=<var>radius</var></td> 4079 <td>Scale windowing function to this size instead. This causes the windowing 4080 (or self-windowing Lagrange filter) to act is if the support window is 4081 larger than what is actually supplied to the calling operator. The filter 4082 however is still clipped to the real support size given. If unset this 4083 will equal the normal filter support size. </td> 4084 </tr> 4085 4086 <tr> 4087 <td>-define filter:verbose=<var>1</var></td> 4088 <td>This causes IM to print information on the final internal filter 4089 selection to standard output. This includes a commented header on the 4090 filter settings being used, and data allowing the filter weights to be 4091 easily graphed. Note however that some filters are internally defined in terms of other filters. The <code>Lanczos</code> filter for example is defined in terms of 4092 a <code>SincFast</code> windowed <code>SincFast</code> filter, while 4093 <code>Mitchell</code> is defined as a general <code>Cubic</code> family filter 4094 with specific 'B' and 'C' settings. </td> 4095 </tr> 4096 4097</table> 4098 4099<p>For example, to get a 8 lobe jinc windowed sinc filter (Genseng filter?):</p> 4100 4101<pre class="highlight"><code>convert image.png \ 4102 -filter sinc \ 4103 -set filter:window=jinc \ 4104 -set filter:lobes=8 \ 4105 -resize 150% image.jpg" 4106</code></pre> 4107 4108<p>Or a raw un-windowed Sinc filter with 4 lobes:</p> 4109 4110<pre class="highlight"><code>convert image.png \ 4111 -set filter:filter=sinc \ 4112 -set filter:lobes=4 \ 4113 -resize 150% image.jpg" 4114</code></pre> 4115 4116<p>To extract the data for a raw windowing function, combine it with 4117a '<code>Box</code>' filter. For example the '<code>Welch</code> parabolic 4118windowing function. </p> 4119 4120<pre class="highlight"><code>convert null: -define filter:filter=Box \ 4121 -define filter:window=Welch \ 4122 -define filter:support=1.0 \ 4123 -define filter:verbose=1 \ 4124 -resize 2 null: > window_welch.dat 4125gnuplot 4126 set grid 4127 plot \"window_welch.dat\" with lines 4128</code></pre> 4129 4130<p>Note that the use of expert options is provided for image processing experts 4131who have studied and understand how resize filters work. Without this 4132knowledge, and an understanding of the definition of the actual filters 4133involved, using expert settings are more likely to be detrimental to your image 4134resizing.</p> 4135 4136 4137<div style="margin: auto;"> 4138 <h3><a class="anchor" id="flatten"></a>-flatten</h3> 4139</div> 4140 4141<p class="magick-description">This is a simple alias for the <a href="command-line-options.html#layers" >-layers</a> method "flatten".</p> 4142 4143 4144<div style="margin: auto;"> 4145 <h3><a class="anchor" id="flip"></a>-flip</h3> 4146</div> 4147 4148<p class="magick-description">create a <var>mirror image</var></p> 4149 4150<p>reflect the scanlines in the vertical direction. The image will be mirrored 4151upside-down. </p> 4152 4153 4154<div style="margin: auto;"> 4155 <h3><a class="anchor" id="floodfill"></a>-floodfill {<var>+-</var>}<var>x</var>{<var>+-</var>}<var>y</var> <var>color</var></h3> 4156</div> 4157 4158<p class="magick-description">floodfill the image with color at the specified offset.</p> 4159 4160<p>Flood fill starts from the given 'seed point' which is not gravity affected. 4161Any color that matches within <a href="command-line-options.html#fuzz" >-fuzz</a> color distance of the 4162given <var>color</var> argument, connected to that 'seed point' 4163will be replaced with the current <a href="command-line-options.html#fill" >-fill</a> color. </p> 4164 4165<p>Note that if the pixel at the 'seed point' does not itself match the given 4166<var>color</var> (according to <a href="command-line-options.html#fuzz" >-fuzz</a>), then no 4167action will be taken. </p> 4168 4169<p>This operator works more like the <a href="command-line-options.html#opaque" >-opaque</a> option, than 4170a more general flood fill that reads the matching color directly at the 'seed 4171point'. For this form of flood fill, look at <a href="command-line-options.html#draw" >-draw</a> and 4172its 'color floodfill' drawing method. </p> 4173 4174 4175<div style="margin: auto;"> 4176 <h3><a class="anchor" id="flop"></a>-flop</h3> 4177</div> 4178 4179<p class="magick-description">create a <var>mirror image</var>.</p> 4180 4181<p>Reflect the scanlines in the horizontal direction, just like the image in 4182a vertical mirror. </p> 4183 4184 4185<div style="margin: auto;"> 4186 <h3><a class="anchor" id="font"></a>-font <var>name</var></h3> 4187</div> 4188 4189<p class="magick-description">set the font to use when annotating images with text, or creating labels.</p> 4190 4191<p>To print a complete list of fonts, use the <a href="command-line-options.html#list">-list font</a> 4192option (for versions prior to 6.3.6, use 'type' instead of 'font').</p> 4193 4194<p>In addition to the fonts specified by the above pre-defined list, you can 4195also specify a font from a specific source. For example <code>Arial.ttf</code> 4196is a TrueType font file, <code>ps:helvetica</code> is PostScript font, and 4197<code>x:fixed</code> is X11 font.</p> 4198 4199<p>For other settings that affect fonts, see the options <a 4200href="command-line-options.html#family">-family</a>, <a href="command-line-options.html#stretch">-stretch</a>, <a 4201href="command-line-options.html#style">-style</a>, and <a href="command-line-options.html#weight">-weight</a>. </p> 4202 4203 4204<div style="margin: auto;"> 4205 <h3><a class="anchor" id="foreground"></a>-foreground <var>color</var></h3> 4206</div> 4207 4208<p class="magick-description">Define the foreground color for menus.", "display</p> 4209 4210<p>The color is specified using the format described under the <a 4211href="command-line-options.html#fill">-fill</a> option.</p> 4212 4213<p>The default foreground color is black.</p> 4214 4215<div style="margin: auto;"> 4216 <h3><a class="anchor" id="format"></a>-format <var>type</var></h3> 4217</div> 4218 4219<p class="magick-description">the image format type.</p> 4220 4221<p>When used with the <code>mogrify</code> utility, this option converts any 4222image to the image <a href="formats.html">format</a> you specify. 4223For a list of image format types supported by ImageMagick, use <a 4224href="command-line-options.html#list">-list format</a>.</p> 4225 4226<p>By default the file is written to its original name. However, if the 4227filename extension matches a supported format, the extension is replaced with 4228the image format type specified with <a href="command-line-options.html#format">-format</a>. For 4229example, if you specify <var>tiff</var> as the format type and the 4230input image filename is <var>image.gif</var>, the output image 4231filename becomes <var>image.tiff</var>.</p> 4232 4233<div style="margin: auto;"> 4234 <h3><a class="anchor" id="format_identify_"></a>-format <var>string</var></h3> 4235</div> 4236 4237<p class="magick-description">output formatted image characteristics.</p> 4238 4239<p>See <a href="../www/escape.html">Format and Print Image 4240Properties</a> for an explanation on how to specify the argument to this 4241option.</p> 4242 4243<div style="margin: auto;"> 4244 <h3><a class="anchor" id="frame"></a>-frame <var>geometry</var></h3> 4245</div> 4246 4247<p class="magick-description">Surround the image with a border or beveled frame.</p> 4248 4249<p>The color of the border is specified with the <a href="command-line-options.html#mattecolor" 4250>-mattecolor</a> command line option. </p> 4251 4252<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. The <var>size</var> portion of the <var>geometry</var> argument indicates the amount of extra width and 4253height that is added to the dimensions of the image. If no offsets are given 4254in the <var>geometry</var> argument, then the border added is 4255a solid color. Offsets <var>x</var> and <var>y</var>, if present, specify that 4256the width and height of the border is partitioned to form an outer bevel of 4257thickness <var>x</var> pixels and an inner bevel of thickness 4258<var>y</var> pixels. Negative offsets make no sense as frame arguments. 4259</p> 4260 4261<p>The <a href="command-line-options.html#frame">-frame</a> option is affected by the current <a 4262href="command-line-options.html#compose">-compose</a> setting and assumes that this is using the default 4263'<code>Over</code>' composition method. It generates an image of the appropriate 4264size with the current <a href="command-line-options.html#bordercolor">-bordercolor</a> setting, and then 4265draws the frame of four distinct colors close to the current <a 4266href="command-line-options.html#mattecolor">-mattecolor</a>. The original image is then overlaid onto 4267center of this image. This means that with the default compose method of 4268'<code>Over</code>' any transparent parts may be replaced by the current <a 4269href="command-line-options.html#bordercolor">-bordercolor</a> setting.</p> 4270 4271<p>The image composition is not 4272affected by the <a href="command-line-options.html#gravity">-gravity</a> option.</p> 4273 4274 4275<div style="margin: auto;"> 4276 <h3><a class="anchor" id="frame_import_"></a>-frame</h3> 4277</div> 4278 4279<p class="magick-description">include the X window frame in the imported image. </p> 4280<div style="margin: auto;"> 4281 <h3><a class="anchor" id="function"></a>-function <var>function</var> <var>parameters</var></h3> 4282</div> 4283 4284<p class="magick-description">Apply a function to channel values.</p> 4285 4286<p>This operator performs calculations based on the given arguments to modify 4287each of the color values for each previously set <a 4288href="command-line-options.html#channel">-channel</a> in the image. See <a 4289href="command-line-options.html#evaluate">-evaluate</a> for details concerning how the results of the 4290calculations are handled.</p> 4291 4292<p>This is can be considered a multi-argument version of the <a 4293href="command-line-options.html#evaluate">-evaluate</a> operator. (Added in 4294ImageMagick 6.4.8−8.)</p> 4295 4296<p>Here, <var>parameters</var> is a comma-separated list of 4297numerical values. The number of values varies depending on which <var>function</var> is selected. Choose the <var>function</var> from:</p> 4298 4299<pre class="highlight"><code>Polynomial 4300Sinusoid 4301Arcsin 4302Arctan 4303</code></pre> 4304 4305<p>To print a complete list of <a href="command-line-options.html#function">-function</a> operators, 4306use <a href="command-line-options.html#list">-list function</a>. Descriptions follow.</p> 4307 4308<dl class="row"> 4309 <dt class="col-md-4">Polynomial</dt> 4310 <dd class="col-md-8"><p>The <code>Polynomial</code> function takes an arbitrary number of parameters, 4311these being the coefficients of a polynomial, in decreasing order of degree. 4312That is, entering</p> 4313 4314<pre class="highlight"><code>-function Polynomial <var>a</var><sub><var>n</var></sub>,<var>a</var><sub><var>n</var>-1</sub>,...<var>a</var><sub>1</sub>,<var>a</var><sub>0</sub> 4315</code></pre> 4316 4317<p>will invoke a polynomial function given by</p> 4318 4319<pre class="highlight"><code><var>a</var><sub><var>n</var></sub> <b><var>u</var></b><sup><var>n</var></sup> + <var>a</var><sub><var>n</var>-1</sub> <b><var>u</var></b><sup><var>n</var>-1</sup> + ··· <var>a</var><sub>1</sub> <b><var>u</var></b> + <var>a</var><sub>0</sub>, 4320</code></pre> 4321 4322<p>where <b><var>u</var></b> is pixel's original normalized channel value.</p> 4323 4324<p>The <code>Polynomial</code> function can be used in place of <code>Set</code> 4325(the <var>constant</var> polynomial) and <code>Add</code>, <code>Divide</code>, 4326<code>Multiply</code>, and <code>Subtract</code> (some <var>linear</var> 4327polynomials) of the <a href="command-line-options.html#evaluate">-evaluate</a> operator. The <a 4328href="command-line-options.html#level">-level</a> operator also affects channels linearly. Some 4329correspondences follow.</p> 4330 4331<table class="table table-sm table-striped"> 4332 <tr> 4333 <td>-evaluate Set <var>value</var> </td> 4334 <td>-function Polynomial <var>value</var></td> 4335 <td>(Constant functions; set <var>value</var>×100% gray when channels are RGB.)</td> 4336 </tr> 4337 <tr> 4338 <td>-evaluate Add <var>value</var> </td> 4339 <td>-function Polynomial 1,<var>value</var></td> 4340 </tr> 4341 <tr> 4342 <td>-evaluate Subtract <var>value</var> </td> 4343 <td>-function Polynomial 1,−<var>value</var></td> 4344 </tr> 4345 <tr> 4346 <td>-evaluate Multiply <var>value</var> </td> 4347 <td>-function Polynomial <var>value</var>,0</td> 4348 </tr> 4349 <tr> 4350 <td>+level black% x white%</td> 4351 <td>-function Polynomial A,B</td> 4352 <td>(Reduce contrast. Here, A=(white-black)/100 and B=black/100.)</td> 4353 </tr> 4354</table> 4355 4356<p>The <code>Polynomial</code> function gives great versatility, since 4357polynomials can be used to fit any continuous curve to any degree of accuracy 4358desired.</p> 4359 4360</dd> 4361<dt class="col-md-4">Sinusoid</dt> 4362<dd class="col-md-8"> 4363<p>The <code>Sinusoid</code> function can be used to vary the channel values 4364sinusoidally by setting frequency, phase shift, amplitude, and a bias. These 4365values are given as one to four parameters, as follows,</p> 4366 4367<pre class="highlight"><code>-function <code>Sinusoid</code> <var>freq</var>,[<var>phase</var>,[<var>amp</var>,[<var>bias</var>]]] 4368</code></pre> 4369 4370<p>where <var>phase</var> is in degrees. (The domain [0,1] of the function 4371corresponds to 0 through <var>freq</var>×360 degrees.) 4372The result is that if a pixel's normalized channel value is originally 4373<b><var>u</var></b>, its resulting normalized value is given by </p> 4374 4375<pre class="highlight"><code><var>amp</var> * sin(2*π* (<var>freq</var> * <b><var>u</var></b> + <var>phase</var> / 360)) + <var>bias</var> 4376</code></pre> 4377 4378<p> For example, the following generates a curve that starts and ends at 0.9 4379(when <b><var>u</var></b>=0 and 1, resp.), oscillating three times between 4380.7−.2=.5 and .7+.2=.9. </p> 4381 4382<pre class="highlight"><code>-function Sinusoid 3,-90,.2,.7 4383</code></pre> 4384 4385<p>The default values of <var>amp</var> and <var>bias</var> are both .5. The default for <var>phase</var> 4386is 0.</p> 4387 4388<p>The <code>Sinusoid</code> function generalizes <code>Sin</code> and 4389<code>Cos</code> of the <a href="command-line-options.html#evaluate">-evaluate</a> operator by allowing 4390varying amplitude, phase and bias. The correspondence is as follows.</p> 4391 4392<table class="table table-sm table-striped"> 4393 <tr> 4394 <td>-evaluate Sin <var>freq</var> </td> 4395 <td>-function Sinusoid <var>freq</var>,0 </td> 4396 </tr> 4397 <tr> 4398 <td>-evaluate Cos <var>freq</var> </td> 4399 <td>-function Sinusoid <var>freq</var>,90 </td> 4400 </tr> 4401</table> 4402 </dd> 4403<dt class="col-md-4">ArcSin</dt> 4404<dd class="col-md-8"> 4405<p>The <code>ArcSin</code> function generates the inverse curve of a Sinusoid, 4406and can be used to generate cylindrical distortion and displacement maps. 4407The curve can be adjusted relative to both the input values and output range 4408of values.</p> 4409 4410<pre class="highlight"><code>-function <code>ArcSin</code> <var>width</var>,[<var>center</var>,[<var>range</var>,[<var>bias</var>]]] 4411</code></pre> 4412 4413<p>with all values given in terms of normalized color values (0.0 for black, 44141.0 for white). Defaulting to values covering the full range from 0.0 to 1.0 4415for bout input (<var>width</var>), and output (<var>width</var>) values. '<code>1.0,0.5,1.0,0.5</code>' </p> 4416 4417<pre class="highlight"><code><var>range</var>/π * asin( 2/<var>width</var> * ( <b><var>u</var></b> - <var>center</var> ) ) + <var>bias</var> 4418</code></pre> 4419 4420</dd> 4421<dt class="col-md-4">ArcTan</dt> 4422<dd class="col-md-8"> 4423<p>The <code>ArcTan</code> function generates a curve that smooth crosses from 4424limit values at infinities, though a center using the given slope value. 4425All these values can be adjusted via the arguments.</p> 4426 4427<pre class="highlight"><code>-function <code>ArcTan</code> <var>slope</var>,[<var>center</var>,[<var>range</var>,[<var>bias</var>]]] 4428</code></pre> 4429 4430<p>Defaulting to '<code>1.0,0.5,1.0,0.5</code>'. 4431</p> 4432 4433<pre class="highlight"><code><var>range</var>/π * atan( <var>slope</var>*π * ( <b><var>u</var></b> - <var>center</var> ) ) + <var>bias</var> 4434</code></pre> 4435 </dd> 4436</dl> 4437 4438 4439 4440<div style="margin: auto;"> 4441 <h3><a class="anchor" id="fuzz"></a>-fuzz <var>distance</var>{<var>%</var>}</h3> 4442</div> 4443 4444<p class="magick-description">Colors within this <var>distance</var> are considered equal.</p> 4445 4446<p>A number of algorithms search for a target color. By default the color must 4447be exact. Use this option to match colors that are close to the target color 4448in RGB space. For example, if you want to automagically trim the edges of an 4449image with <a href="command-line-options.html#trim">-trim</a> but the image was scanned and the target 4450background color may differ by a small amount. This option can account for 4451these differences.</p> 4452 4453<p>The <var>distance</var> can be in absolute intensity units or, by 4454appending <code>%</code> as a percentage of the maximum possible intensity (255, 445565535, or 4294967295).</p> 4456 4457<p>Use <a href="command-line-options.html#fuzz" >+fuzz</a> to reset the fuzz value to 0.</p> 4458 4459 4460<div style="margin: auto;"> 4461 <h3><a class="anchor" id="fx"></a>-fx <var>expression</var></h3> 4462</div> 4463 4464<p class="magick-description">apply a mathematical expression to an image or image channels.</p> 4465 4466<p>If the first character of <var>expression</var> is <code>@</code>, 4467the expression is read from a file titled by the remaining characters in the 4468string.</p> 4469 4470<p>See <a href="fx.html">FX, 4471The Special Effects Image Operator</a> for a detailed discussion of this 4472option.</p> 4473 4474 4475<div style="margin: auto;"> 4476 <h3><a class="anchor" id="gamma"></a>-gamma <var>value</var></h3> 4477</div> 4478 4479<p class="magick-description">level of gamma correction.</p> 4480 4481<p>The same color image displayed on two different workstations may look 4482different due to differences in the display monitor. Use gamma correction to 4483adjust for this color difference. Reasonable values extend from 4484<code>0.8</code> to <code>2.3</code>. Gamma less than 1.0 darkens the image and 4485gamma greater than 1.0 lightens it. Large adjustments to image gamma may 4486result in the loss of some image information if the pixel quantum size is only 4487eight bits (quantum range 0 to 255).</p> 4488 4489<p>Gamma adjusts the image's channel values pixel-by-pixel according to 4490a power law, namely, pow(pixel,1/gamma) or pixel^(1/gamma), where pixel is the 4491normalized or 0 to 1 color value. For example, using a value of gamma=2 is the 4492same as taking the square root of the image.</p> 4493 4494<p>Use <a href="command-line-options.html#gamma">+gamma <var>value</var></a> to set the 4495image gamma level without actually adjusting the image pixels. This option 4496is useful if the image is of a known gamma but not set as an image attribute 4497(e.g. PNG images). Write the "file gamma" which is the reciprocal of the 4498display gamma; e.g., if your image is sRGB and you want to write a PNG gAMA 4499chunk, use</p> 4500 4501<pre class="highlight"><code>convert input.png +gamma .45455 output.png 4502</code></pre> 4503 4504<p>(0.45455 is 1/2.2)</p> 4505 4506<p>Note that gamma adjustments are also available via the <a href="command-line-options.html#level">-level</a> operator.</p> 4507 4508<div style="margin: auto;"> 4509 <h3><a class="anchor" id="gaussian-blur"></a>-gaussian-blur <var>radius</var><br />-gaussian-blur <var>radius</var>x<var>sigma</var></h3> 4510</div> 4511 4512<p class="magick-description">Blur the image with a Gaussian operator.</p> 4513 4514<p>Convolve the image with a Gaussian or normal distribution using the given 4515<var >Sigma</var> value. The formula is:</p> 4516 4517<p class="text-center"><img class="img-thumbnail" alt="gaussian distribution" width="243px" height="42px" src="../images/gaussian-blur.png"/> </p> 4518 4519<p>The <var >Sigma</var> value is the important argument, and 4520determines the actual amount of blurring that will take place. </p> 4521 4522<p>The <var >Radius</var> is only used to determine the size of the 4523array which will hold the calculated Gaussian distribution. It should be an 4524integer. If not given, or set to zero, IM will calculate the largest possible 4525radius that will provide meaningful results for the Gaussian distribution. 4526</p> 4527 4528<p>The larger the <var >Radius</var> the radius the slower the 4529operation is. However too small a <var >Radius</var>, and severe 4530aliasing effects may result. As a guideline, <var >Radius</var> 4531should be at least twice the <var >Sigma</var> value, though three 4532times will produce a more accurate result. </p> 4533 4534<p>This differs from the faster <a href="command-line-options.html#blur">-blur</a> operator in that a 4535full 2-dimensional convolution is used to generate the weighted average of the 4536neighboring pixels. </p> 4537 4538<p>The <a href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting will determine how 4539pixels which are outside the image proper are blurred into the final result. 4540</p> 4541 4542 4543<div style="margin: auto;"> 4544 <h3><a class="anchor" id="geometry"></a>-geometry <var>geometry</var></h3> 4545</div> 4546 4547<p class="magick-description">Set the preferred size and location of the image.</p> 4548 4549<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 4550 4551<div style="margin: auto;"> 4552 <h3><a class="anchor" id="gravity"></a>-gravity <var>type</var></h3> 4553</div> 4554 4555<p class="magick-description">Sets the current gravity suggestion for various other settings and options.</p> 4556 4557<p>Choices include: <code>NorthWest</code>, <code>North</code>, 4558<code>NorthEast</code>, <code>West</code>, <code>Center</code>, <code>East</code>, 4559<code>SouthWest</code>, <code>South</code>, <code>SouthEast</code>. Use <a 4560href="command-line-options.html#list">-list gravity</a> to get a complete list of <a 4561href="command-line-options.html#gravity">-gravity</a> settings available in your ImageMagick 4562installation.</p> 4563 4564<p>The direction you choose specifies where to position text or subimages. For 4565example, a gravity of <code>Center</code> forces the text to be centered within 4566the image. By default, the image gravity is <code>undefined</code>. See <a 4567href="command-line-options.html#draw">-draw</a> for more details about graphic primitives. Only the 4568text primitive of <a href="command-line-options.html#draw">-draw</a> is affected by the <a 4569href="command-line-options.html#gravity">-gravity</a> option.</p> 4570 4571<p>The <a href="command-line-options.html#gravity">-gravity</a> option is also used in concert with the 4572<a href="command-line-options.html#geometry">-geometry</a> setting and other settings or options that 4573take <var>geometry</var> as an argument, such as the <a 4574href="command-line-options.html#crop">-crop</a> option. </p> 4575 4576<p>If a <a href="command-line-options.html#gravity">-gravity</a> setting occurs before another option 4577or setting having a <var>geometry</var> argument that specifies an 4578offset, the offset is usually applied to the point within the image suggested 4579by the <a href="command-line-options.html#gravity">-gravity</a> argument. Thus, in the following 4580command, for example, suppose the file <code>image.png</code> has dimensions 4581200x100. The offset specified by the argument to <a href="command-line-options.html#region">-region</a> 4582is (−40,+20). The argument to <a href="command-line-options.html#gravity">-gravity</a> is 4583<code>Center</code>, which suggests the midpoint of the image, at the point 4584(100,50). The offset (−40,20) is applied to that point, giving 4585(100−40,50+20)=(60,70), so the specified 10x10 region is located at 4586that point. (In addition, the <a href="command-line-options.html#gravity">-gravity</a> affects the 4587region itself, which is <var>centered</var> at the pixel 4588coordinate (60,70). (See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.)</p> 4589 4590<pre class="highlight"><code>convert image.png -gravity Center -region 10x10-40+20 \ 4591 -negate output.png 4592</code></pre> 4593 4594<p>When used as an option to <a href="composite.html">composite</a>, <a 4595href="command-line-options.html#gravity">-gravity</a> gives the direction that the image gravitates 4596within the composite.</p> 4597 4598<p>When used as an option to <a href="montage.html">montage</a>, <a 4599href="command-line-options.html#gravity">-gravity</a> gives the direction that an image gravitates 4600within a tile. The default gravity is <code>Center</code> for this purpose.</p> 4601 4602<p>Use <a href="command-line-options.html#gravity">+gravity</a> to return gravity to its default value.</p> 4603 4604 4605<div style="margin: auto;"> 4606 <h3><a class="anchor" id="grayscale"></a>-grayscale <var>method</var></h3> 4607</div> 4608 4609<p class="magick-description">convert image to grayscale.</p> 4610 4611<p>This will use one of the <a href="command-line-options.html#intensity" >-intensity</a> methods to 4612convert the given image into a grayscale image. </p> 4613 4614<p>For example, to convert an image to (linear) Rec709Luminance grayscale, type:</p> 4615 4616<pre class="highlight"><code>convert in.png -grayscale Rec709Luminance out.png 4617</code></pre> 4618 4619<p>which is equivalent to:</p> 4620 4621<pre class="highlight"> 4622<code>convert in.png -colorspace RGB -colorspace Gray out.png</code> 4623or 4624<code>convert in.png -colorspace LinearGray out.png</code> 4625</pre> 4626 4627<p>Note that LinearGray is new as of Imagemagick 6.9.9-29 and 7.0.7-17.</p> 4628 4629<p>Similarly, to convert an image to (non-linear) Rec709Luma grayscale, type:</p> 4630 4631<pre class="highlight"><code>convert in.png -grayscale Rec709Luma out.png 4632</code></pre> 4633 4634<p>which is equivalent to:</p> 4635 4636<pre class="highlight"><code>convert in.png -colorspace Gray out.png 4637</code></pre> 4638 4639<p>Note that a 'colorspace' intensity method will produce the same result 4640regardless of the current colorpsace of the image. But a 'mathematical' 4641intensity method depends on the current colorspace the image is currently 4642using. </p> 4643 4644<p>While this operation uses an <a href="command-line-options.html#intensity" >-intensity</a> method, 4645it does not use or set the <a href="command-line-options.html#intensity" >-intensity</a> setting, so 4646will not affect other operations that may use that setting.</p> 4647 4648 4649<div style="margin: auto;"> 4650 <h3><a class="anchor" id="green-primary"></a>-green-primary <var>x,y</var></h3> 4651</div> 4652 4653<p class="magick-description">green chromaticity primary point.</p> 4654 4655 4656<div style="margin: auto;"> 4657 <h3><a class="anchor" id="hald-clut"></a>-hald-clut</h3> 4658</div> 4659 4660<p class="magick-description">apply a Hald color lookup table to the image.</p> 4661 4662<p>A Hald color lookup table is a 3-dimensional color cube mapped to 2 4663dimensions. Create it with the <code>HALD:</code> prefix (e.g. HALD:8). You 4664can apply any color transformation to the Hald image and then use this option 4665to apply the transform to the image. </p> 4666 4667<pre class="highlight"><code>convert image.png hald.png -hald-clut transform.png 4668</code></pre> 4669 4670<p>This option provides a convenient method for you to use Gimp or Photoshop 4671to make color corrections to the Hald CLUT image and subsequently apply them 4672to multiple images using an ImageMagick script. </p> 4673 4674<p>Note that the representation is only of the normal RGB color space and that 4675the whole color value triplet is used for the interpolated lookup of the 4676represented Hald color cube image. Because of this the operation is not <a 4677href="command-line-options.html#channel" >-channel</a> setting affected, nor can it adjust or modify an 4678images transparency or alpha/matte channel.</p> 4679 4680<p>See also <a href="command-line-options.html#clut" >-clut</a> which provides color value replacement 4681of the individual color channels, usually involving a simpler grayscale 4682image. E.g: grayscale to color replacement, or modification by a histogram 4683mapping. </p> 4684 4685 4686<div style="margin: auto;"> 4687 <h3><a class="anchor" id="help"></a>-help</h3> 4688</div> 4689 4690<p class="magick-description">print usage instructions.</p> 4691 4692<div style="margin: auto;"> 4693 <h3><a class="anchor" id="highlight-color"></a>-highlight-color <var>color</var></h3> 4694</div> 4695 4696<p class="magick-description">when comparing images, emphasize pixel differences with this color.</p> 4697 4698<div style="margin: auto;"> 4699 <h3><a class="anchor" id="hough-lines"></a>-hough-lines <var>width</var>x<var>height</var>{<var>+threshold</var>}</h3> 4700</div> 4701 4702<p class="magick-description">identify straight lines in the image (e.g. -hough-lines 9x9+195).</p> 4703 4704<p>Use the Hough line detector with any binary edge extracted image to locate and draw any straight lines that it finds.</p> 4705 4706<p>The process accumulates counts for every white pixel in the binary edge image for every possible orientation (for angles from 0 to 179 in 1 deg increments) and distance from the center of the image to the corners (in 1 px increments). It stores the counts in an accumulator matrix of angle vs distance. The size of the accumulator will be 180x(diagonal/2). Next it searches the accumulator for peaks in counts and converts the locations of the peaks to slope and intercept in the normal x,y input image space. The algorithm uses slope/intercepts to find the endpoints clipped to the bounds of the image. The lines are drawn from the given endpoints. The counts are a measure of the length of the lines.</p>. 4707 4708<p>The WxH arguments specify the filter size for locating the peaks in the Hough accumulator. The threshold excludes lines whose counts are less than the threshold value.</p> 4709 4710<p>Use <code><a href="command-line-options.html#background" >-background</a></code> to specify the color of the background onto which the lines will be drawn. The default is black.</p> 4711 4712<p>Use <code><a href="command-line-options.html#fill" >-fill</a></code> to specify the color of the lines. The default is black.</p> 4713 4714<p>Use <code><a href="command-line-options.html#stroke" >-stroke</a></code> and <code><a href="command-line-options.html#strokewidth" >-strokewidth</a></code> to specify the thickness of the lines. The default is black and no strokewidth.</p> 4715 4716<p>A text file listing the endpoints and counts may be created by using the suffix, .mvg, for the output image.</p> 4717 4718<p>Use <code><a href="command-line-options.html#define" >-define</a> hough-lines:accumulator=true</code> to return the accumulator image in addition to the lines image.</p> 4719 4720<div style="margin: auto;"> 4721 <h3><a class="anchor" id="iconGeometry"></a>-iconGeometry <var>geometry</var></h3> 4722</div> 4723 4724<p class="magick-description">specify the icon geometry.</p> 4725 4726<p>Offsets, if present in the geometry specification, are handled in the same 4727manner as the <a href="command-line-options.html#geometry">-geometry</a> option, using X11 style to 4728handle negative offsets.</p> 4729 4730<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 4731 4732<div style="margin: auto;"> 4733 <h3><a class="anchor" id="iconic"></a>-iconic</h3> 4734</div> 4735 4736<p class="magick-description">start in icon mode in X Windows", 'animate', 'display</p> 4737 4738<div style="margin: auto;"> 4739 <h3><a class="anchor" id="identify"></a>-identify</h3> 4740</div> 4741 4742<p class="magick-description">identify the format and characteristics of the image.</p> 4743 4744<p>This information is printed: image scene number; image name; image size; 4745the image class (<var>DirectClass</var> or <var>PseudoClass</var>); the total number of unique colors; and the 4746number of seconds to read and transform the image. Refer to <a href="miff.html">MIFF</a> for 4747a description of the image class.</p> 4748 4749<p>If <a href="command-line-options.html#colors">-colors</a> is also specified, the total unique colors 4750in the image and color reduction error values are printed. Refer to <a 4751href="../www/quantize.html">color 4752reduction algorithm</a> for a description of these values.</p> 4753 4754<p>If <a href="command-line-options.html#verbose">-verbose</a> precedes this option, copious 4755amounts of image properties are displayed including image statistics, profiles, 4756image histogram, and others.</p> 4757 4758<div style="margin: auto;"> 4759 <h3><a class="anchor" id="ift"></a>-ift</h3> 4760</div> 4761 4762<p class="magick-description">implements the inverse discrete Fourier transform (DFT).</p> 4763 4764<p>This option is new as of ImageMagick 6.5.4-3 (and now working for Windows 4765users in ImageMagick 6.6.0-9). It transforms a pair of magnitude and phase 4766images from the frequency domain to a single image in the normal or spatial 4767domain. See for example, <a 4768href="http://en.wikipedia.org/wiki/Fourier_transform">Fourier Transform</a>, 4769<a href="http://en.wikipedia.org/wiki/DFT">Discrete Fourier Transform</a> and 4770<a href="http://en.wikipedia.org/wiki/FFT">Fast Fourier Transform</a>.</p> 4771 4772<p>For example, depending upon the image format used to store the result of 4773the <a href="command-line-options.html#fft">-fft</a>, one would use either</p> 4774 4775<pre class="highlight"><code>convert fft_image.miff -ift fft_image_ift.png 4776</code></pre> 4777 4778<p>or</p> 4779 4780<pre class="highlight"><code>convert fft_image-0.png fft_image-1.png -ift fft_image_ift.png 4781</code></pre> 4782 4783<p>The resulting image may need to be cropped due to padding introduced when 4784the original image, prior to the <a href="command-line-options.html#fft">-fft</a> or <a 4785href="command-line-options.html#fft">+fft</a>, was not square or even dimensioned. Any padding is at 4786the right and/or bottom sides of the image.</p> 4787 4788<p>The <a href="http://www.fftw.org/">FFTW</a> delegate library is required to 4789use <a href="command-line-options.html#ift">-ift</a>.</p> 4790 4791<p>Use <a href="command-line-options.html#ift">+ift</a> (with HDRI enabled) to transform a pair of real 4792and imaginary images from the frequency domain to a single image in the normal 4793(spatial) domain.</p> 4794 4795<p>By default the IFT is not normalized (and the FFT is). Use "<code><a href="command-line-options.html#define" >-define</a> fourier:normalize=inverse</code> to explicitly normalize the IFT and unnormalize the FFT.</p> 4796 4797<div style="margin: auto;"> 4798 <h3><a class="anchor" id="immutable"></a>-immutable</h3> 4799</div> 4800 4801<p class="magick-description">make image immutable.</p> 4802 4803<div style="margin: auto;"> 4804 <h3><a class="anchor" id="implode"></a>-implode <var>factor</var></h3> 4805</div> 4806 4807<p class="magick-description">implode image pixels about the center.</p> 4808 4809<div style="margin: auto;"> 4810 <h3><a class="anchor" id="insert"></a>-insert <var>index</var></h3> 4811</div> 4812 4813<p class="magick-description">insert the last image into the image sequence.</p> 4814 4815<p>This option takes last image in the current image sequence and inserts it 4816at the given index. If a negative index is used, the insert position is 4817calculated before the last image is removed from the sequence. As such 4818<code>-insert -1</code> will result in no change to the image sequence.</p> 4819 4820<p>The <code>+insert</code> option is equivalent to <code>-insert -1</code>. In 4821other words, insert the last image, at the end of the current image sequence. 4822Consequently this has no effect on the image sequence order.</p> 4823 4824<div style="margin: auto;"> 4825 <h3><a class="anchor" id="intensity"></a>-intensity <var>method</var></h3> 4826</div> 4827 4828<p class="magick-description">method to generate intensity value from pixel.</p> 4829 4830<p>ImageMagick provides a number of methods used in situations where an 4831operator needs to determine a single grayscale value for some purpose, from 4832an image with red, green, and blue pixel components. Typically the 4833<code>Rec709Luma</code> formula is used, which is the same formula used when converting images to <code>-colorspace gray</code>. </p> 4834 4835<p>The following formulas are currently provided, and will first convert 4836the pixel values to linear-RGB or non-linear sRGB colorspace before 4837being applied to calculate the final greyscale value. </p> 4838 4839<dl class="row"> 4840<dt class="col-md-4">Rec601Luma</dt><dd class="col-md-8"> 0.298839R' + 0.586811G'+ 0.114350B'</dd> 4841<dt class="col-md-4">Rec601Luminance</dt><dd class="col-md-8"> 0.298839R + 0.586811G + 0.114350B</dd> 4842<dt class="col-md-4">Rec709Luma</dt><dd class="col-md-8"> 0.212656R' + 0.715158G' + 0.072186B'</dd> 4843<dt class="col-md-4">Rec709Luminance</dt><dd class="col-md-8"> 0.212656R + 0.715158G + 0.072186B</dd> 4844<dt class="col-md-4">Brightness</dt><dd class="col-md-8"> max(R', G', B')</dd> 4845<dt class="col-md-4">Lightness</dt><dd class="col-md-8"> (min(R', G', B') + max(R', G', B')) / 2.0</dd> 4846</dl> 4847 4848<p>Note that the above R,G,B values is the image's linear-RGB values, while 4849R',G',B' are sRGB non-linear values. </p> 4850 4851<p>These intensity methods are mathematical in nature and will use the 4852current value in the images respective R,G,B channel regardless of 4853what that is, or what colorspace the image is currently using.</p> 4854 4855<dl class="row"> 4856<dt class="col-md-4">Average</dt><dd class="col-md-8">(R' + G' + B') / 3.0</dd> 4857<dt class="col-md-4">MS</dt><dd class="col-md-8">(R'^2 + G'^2 + B'^2) / 3.0</dd> 4858<dt class="col-md-4">RMS</dt><dd class="col-md-8">sqrt( (R'^2 + G'^2 + B'^2) / 3.0 )</dd> 4859</dl> 4860 4861<p>These methods are often used for other purposes, such as generating a 4862grayscale difference image between two color images (using <a href="command-line-options.html#compose" 4863>-compose</a> '<code>Difference</code>' composition. </p> 4864 4865<p> For example The 'MS' (Mean Squared) setting is good for minimizing color 4866error comparisions. While... The method 'RMS' (Root Mean Squared) for 4867example is appropriate for calculating color vector distance, from a color 4868difference image. This is equivalent to the color only component of the <a 4869href="command-line-options.html#fuzz" >-fuzz</a> factor color compare setting. </p> 4870 4871<p>See also <a href="command-line-options.html#grayscale" >-grayscale</a> which applies one of the above 4872grayscaling formula directly to an image without setting the <a 4873href="command-line-options.html#intensity" >-intensity</a> setting.</p> 4874 4875<p>The <a href="command-line-options.html#colorspace" >-colorspace gray</a> image conversion also uses 4876the current intensity setting, but will always convert the image to the 4877appropriate sRGB or linear-RGB colorspace before appling the above 4878function.</p> 4879 4880<p>To print a complete list of possible pixel intensity setting methods, use <a href="command-line-options.html#list">-list intensity</a>.</p> 4881 4882<p>Operators affected by the <a href="command-line-options.html#intensity" >-intensity</a> setting include:</p> 4883 4884<pre class="highlight"><code>-adaptive-blur 4885-adaptive-sharpen 4886-black-threshold 4887-clut (when mapping greyscale CLUT image to alpha channel if set by -channels) 4888-colors for gray colorspace 4889-compose {LightenIntensity, DarkenIntensity, CopyOpacity, CopyBlack} 4890-contrast-stretch 4891-distort {ErodeIntensity, DilateIntensity} 4892-normalize 4893-random-threshold 4894-range-threshold 4895-selective-blur 4896-shade 4897-threshold 4898-tint 4899-white-threshold 4900</code></pre> 4901 4902<div style="margin: auto;"> 4903 <h3><a class="anchor" id="intent"></a>-intent <var>type</var></h3> 4904</div> 4905 4906<p class="magick-description">use this type of rendering intent when managing the image color.</p> 4907 4908<p>Use this option to affect the color management operation of an image (see 4909<a href="command-line-options.html#profile">-profile</a>). Choose from these intents: <code>Absolute, 4910Perceptual, Relative, Saturation</code>.</p> 4911 4912<p>The default intent is Perceptual for the sRGB colorspace and undefined for the RGB and gray colorspaces.</p> 4913 4914<p>To print a complete list of rendering intents, use <a href="command-line-options.html#list">-list intent</a>.</p> 4915 4916<div style="margin: auto;"> 4917 <h3><a class="anchor" id="interlace"></a>-interlace <var>type</var></h3> 4918</div> 4919 4920<p class="magick-description">the type of interlacing scheme.</p> 4921 4922<p>Choose from:</p> 4923 4924<pre class="highlight"><code>none 4925line 4926plane 4927partition 4928JPEG 4929GIF 4930PNG 4931</code></pre> 4932 4933<p>This option is used to specify the type of interlacing scheme for raw image 4934formats such as <code>RGB</code> or <code>YUV</code>.</p> 4935 4936<p><code>None</code> means do not interlace (RGBRGBRGBRGBRGBRGB...),</p> 4937 4938<p><code>Line</code> uses scanline interlacing (RRR...GGG...BBB...RRR...GGG...BBB...), and.</p> 4939 4940<p><code>Plane</code> uses plane interlacing (RRRRRR...GGGGGG...BBBBBB...).</p> 4941 4942<p><code>Partition</code> is like plane except the different planes are saved to 4943individual files (e.g. image.R, image.G, and image.B).</p> 4944 4945<p>Use <code>Line</code> or <code>Plane</code> to create an <code>interlaced 4946PNG</code> or <code>GIF</code> or <code>progressive JPEG</code> image.</p> 4947 4948<p>To print a complete list of interlacing schemes, use <a href="command-line-options.html#list">-list 4949interlace</a>.</p> 4950 4951<div style="margin: auto;"> 4952 <h3><a class="anchor" id="interpolate"></a>-interpolate <var>type</var></h3> 4953</div> 4954 4955<p class="magick-description">Set the pixel color interpolation method to use when looking up a color based on a floating point or real value.</p> 4956 4957<p>When looking up the color of a pixel using a non-integer floating point 4958value, you typically fall in between the pixel colors defined by the source 4959image. This setting determines how the color is determined from the colors of 4960the pixels surrounding that point. That is how to determine the color of a 4961point that falls between two, or even four different colored pixels. </p> 4962 4963<dl class="row"> 4964 <dt class="col-md-4">average</dt> 4965 <dd class="col-md-8">The average color of the surrounding four pixels</dd> 4966 <dt class="col-md-4">average4</dt> 4967 <dd class="col-md-8">The average color of the surrounding four pixels</dd> 4968 <dt class="col-md-4">average9</dt> 4969 <dd class="col-md-8">The average color of the surrounding nine pixels</dd> 4970 <dt class="col-md-4">average16</dt> 4971 <dd class="col-md-8">The average color of the surrounding sixteen pixels</dd> 4972 <dt class="col-md-4">background</dt> 4973 <dd class="col-md-8"> </dd> 4974 <dt class="col-md-4">bilinear</dt> 4975 <dd class="col-md-8">A double linear interpolation of pixels (the default)</dd> 4976 <dt class="col-md-4">blend</dt> 4977 <dd class="col-md-8"> </dd> 4978 <dt class="col-md-4">catrom</dt> 4979 <dd class="col-md-8">Fitted bicubic-spines of surrounding 16 pixels</dd> 4980 <dt class="col-md-4">integer</dt> 4981 <dd class="col-md-8">The color of the top-left pixel (floor function)</dd> 4982 <dt class="col-md-4">mesh</dt> 4983 <dd class="col-md-8">Divide area into two flat triangular interpolations</dd> 4984 <dt class="col-md-4">nearest-neighbor</dt> 4985 <dd class="col-md-8">The nearest pixel to the lookup point (rounded function)</dd> 4986 <dt class="col-md-4">spline</dt> 4987 <dd class="col-md-8">Direct spline curves (colors are blurred)</dd> 4988</dl> 4989 4990<p>This most important for distortion operators such as <a href="command-line-options.html#distort" 4991>-distort</a>, <a href="command-line-options.html#implode" >-implode</a>, <a href="command-line-options.html#transform" 4992>-transform</a> and <a href="command-line-options.html#fx" >-fx</a>. </p> 4993 4994<p>To print a complete list of interpolation methods, use <a href="command-line-options.html#list">-list interpolate</a>.</p> 4995 4996<p>See also <a href="command-line-options.html#virtual-pixel" >-virtual-pixel</a>, for control of the 4997lookup for positions outside the boundaries of the image. </p> 4998 4999 5000<div style="margin: auto;"> 5001 <h3><a class="anchor" id="interline-spacing"></a>-interline-spacing <var>value</var></h3> 5002</div> 5003 5004<p class="magick-description">the space between two text lines.</p> 5005 5006<div style="margin: auto;"> 5007 <h3><a class="anchor" id="interword-spacing"></a>-interword-spacing <var>value</var></h3> 5008</div> 5009 5010<p class="magick-description">the space between two words.</p> 5011 5012<div style="margin: auto;"> 5013 <h3><a class="anchor" id="kerning"></a>-kerning <var>value</var></h3> 5014</div> 5015 5016<p class="magick-description">the space between two letters.</p> 5017 5018<div style="margin: auto;"> 5019 <h3><a class="anchor" id="kmeans"></a>-kmeans <var>colors</var>{x<var>iterations</var>}{+<var>tolerance</var>}</h3> 5020</div> 5021 5022<p class="magick-description">Kmeans (iterative) color reduction (e.g. <code>-kmeans 5x100+0.01</code>). Colors is the desired number of colors. Initial colors are found using color quantization. Iterations is the stopping number of iterations (default=100). Convergence is the stopping threshold on the color change between iterations (default=0.01). Processing finishes, if either iterations or tolerance are reached. Use <code>-define kmeans:seed-colors=<var>color-list</var></code> to initialize the colors, where color-list is a semicolon delimited list of seed colors (e.g. <code>-define kmeans:seed-colors="red;sRGB(19,167,254);#00ffff</code>). A color list overrides the color quantization. A non-empty list of colors overrides the number of colors. Any unassigned initial colors are assigned random colors from the image.</p> 5023 5024<div style="margin: auto;"> 5025 <h3><a class="anchor" id="kuwahara"></a>-kuwahara <var>radius</var><br />-kuwahara <var>radius</var>x<var>sigma</var></h3> 5026</div> 5027 5028<p class="magick-description">edge preserving noise reduction filter.</p> 5029 5030<p>The <var >radius</var> is more important than the <var >sigma</var>. If <var >sigma</var> is left off, it will be computed automatically from the <var >radius</var> as <var >sigma</var>=<var >radius</var>-0.5. The <var >sigma</var> provides a bit of additional smoothing control.</p> 5031 5032 5033<div style="margin: auto;"> 5034 <h3><a class="anchor" id="label"></a>-label <var>name</var></h3> 5035</div> 5036 5037<p class="magick-description">assign a label to an image.</p> 5038 5039<p>Use this option to assign a specific label to the image, as it is read in 5040or created. You can use the <a href="command-line-options.html#set" >-set</a> operation to re-assign 5041a the labels of images already read in. Image formats such as TIFF, PNG, 5042MIFF, supports saving the label information with the image.</p> 5043 5044<p>When saving an image to a <var>PostScript</var> file, any label 5045assigned to an image is used as a header string to print above the postscript 5046image. </p> 5047 5048<p>You can include the image filename, type, width, height, or other image 5049attribute by embedding special format character. See <a href="../www/escape.html">Format and Print Image 5050Properties</a> for details of the percent escape codes.</p> 5051 5052<p>For example,</p> 5053 5054<pre class="highlight"><code>-label "%m:%f %wx%h" bird.miff 5055</code></pre> 5056 5057<p>assigns an image label of <code>MIFF:bird.miff 512x480</code> to the 5058"<code>bird.miff</code>" image and whose width is 512 and height is 480, as it 5059is read in. If a <a href="command-line-options.html#label">+label</a> option was used instead, any 5060existing label present in the image would be used. You can remove all labels 5061from an image by assigning the empty string. </p> 5062 5063<p>A label is not drawn on the image, but is embedded in the image datastream 5064via <var>Label</var> tag or similar mechanism. If you want the label to be 5065visible on the image itself, use the <a href="command-line-options.html#draw">-draw</a> option, or 5066during the final processing in the creation of an image montage.</p> 5067 5068<p>If the first character of <var>string</var> is <var>@</var>, the image label is read from a file titled by the 5069remaining characters in the string. Labels in a file are literal, no embedded 5070formatting characters are recognized.</p> 5071 5072 5073<div style="margin: auto;"> 5074 <h3><a class="anchor" id="lat"></a>-lat <var>width</var><br />-lat <var>width</var>x<var>height</var>{<var>+-</var>}<var>offset</var>{<var>%</var>}</h3> 5075</div> 5076 5077<p class="magick-description">perform local adaptive threshold.</p> 5078 5079<p>Adaptively threshold each pixel based on the value of pixels in a 5080surrounding window. If the current pixel is lighter than this average plus 5081the optional <code>offset</code>, then it is made white, otherwise it is made 5082black. Small variations in pixel values such as found in scanned documents 5083can be ignored if offset is positive. A negative offset will make it more 5084sensitive to those small variations. </p> 5085 5086<p>This is commonly used to threshold images with an uneven background. It is 5087based on the assumption that average color of the small window is the 5088the local background color, from which to separate the foreground color. </p> 5089 5090 5091<div style="margin: auto;"> 5092 <h3><a class="anchor" id="layers"></a>-layers <var>method</var></h3> 5093</div> 5094 5095<p class="magick-description">handle multiple images forming a set of image layers or animation frames.</p> 5096 5097<p>Perform various image operation methods to a ordered sequence of images 5098which may represent either a set of overlaid 'image layers', a GIF disposal 5099animation, or a fully-'coalesced' animation sequence. </p> 5100 5101<table class="table table-sm table-striped"> 5102 <tbody> 5103 <tr> 5104 <th style="width: 8%">Method</th> 5105 <th>Description</th> 5106 </tr> 5107 5108 <tr> 5109 <td>compare-any</td> 5110 <td>Crop the second and later frames to the smallest rectangle 5111 that contains all the differences between the two images. No GIF <a 5112 href="command-line-options.html#dispose" >-dispose</a> methods are taken into account. </td> 5113 </tr> 5114 5115 <tr><td></td><td>This exactly the same as the <a href="command-line-options.html#deconstruct" 5116 >-deconstruct</a> operator, and does not preserve animations normal 5117 working, especially when animation used layer disposal methods such as 5118 '<code>Previous</code>' or '<code>Background</code>'. </td> 5119 </tr> 5120 5121 <tr> 5122 <td>compare-clear</td> 5123 <td>As '<code>compare-any</code>' but crop to the bounds of any 5124 opaque pixels which become transparent in the second frame. That is the 5125 smallest image needed to mask or erase pixels for the next frame. </td> 5126 </tr> 5127 5128 <tr> 5129 <td>compare-overlay</td> 5130 <td>As '<code>compare-any</code>' but crop to pixels that add 5131 extra color to the next image, as a result of overlaying color pixels. 5132 That is the smallest single overlaid image to add or change colors. </td> 5133 </tr> 5134 5135 <tr><td></td><td>This can be used with the <a href="command-line-options.html#compose" >-compose</a> alpha 5136 composition method '<code>change-mask</code>', to reduce the image to 5137 just the pixels that need to be overlaid. </td> 5138 </tr> 5139 5140 <tr> 5141 <td>coalesce</td> 5142 <td>Equivalent to a call to the <a href="command-line-options.html#coalesce" 5143 >-coalesce</a> operator. Apply the layer disposal methods set in the 5144 current image sequence to form a fully defined animation sequence, as 5145 it should be displayed. Effectively converting a GIF animation into a 5146 'film strip'-like animation. </td> 5147 </tr> 5148 5149 <tr> 5150 <td>composite</td> 5151 <td>Alpha Composition of two image lists, separated by a 5152 "<code>null:</code>" image, with the destination image list first, and 5153 the source images last. An image from each list are composited 5154 together until one list is finished. The separator image and source 5155 image lists are removed. </td> 5156 </tr> 5157 5158 5159 <tr><td></td> 5160 <td>The <a href="command-line-options.html#geometry" >-geometry</a> offset is adjusted according 5161 to <a href="command-line-options.html#gravity" >-gravity</a> in accordance of the virtual 5162 canvas size of the first image in each list. Unlike a normal <a 5163 href="command-line-options.html#composite" >-composite</a> operation, the canvas offset is also 5164 added to the final composite positioning of each image. </td> </tr> 5165 5166 <tr><td></td> 5167 <td>If one of the image lists only contains one image, that image is 5168 applied to all the images in the other image list, regardless of which 5169 list it is. In this case it is the image meta-data of the list which 5170 preserved. </td> 5171 </tr> 5172 5173 5174 <tr> 5175 <td>dispose</td> 5176 <td>This like '<code>coalesce</code>' but shows the look of 5177 the animation after the layer disposal method has been applied, before 5178 the next sub-frame image is overlaid. That is the 'dispose' image that 5179 results from the application of the GIF <a href="command-line-options.html#dispose" 5180 >-dispose</a> method. This allows you to check what 5181 is going wrong with a particular animation you may be developing. 5182 </td> 5183 </tr> 5184 5185 <tr> 5186 <td>flatten</td> 5187 <td>Create a canvas the size of the first images virtual 5188 canvas using the current <a href="command-line-options.html#background" >-background</a> color, 5189 and <a href="command-line-options.html#compose" >-compose</a> each image in turn onto that 5190 canvas. Images falling outside that canvas is clipped. Final 5191 image will have a zero virtual canvas offset. </td> 5192 </tr> 5193 5194 <tr><td></td> 5195 <td>This usually used as one of the final 'image layering' operations 5196 overlaying all the prepared image layers into a final image. </td> 5197 </tr> 5198 5199 <tr><td></td> 5200 <td>For a single image this method can also be used to fillout a virtual 5201 canvas with real pixels, or to underlay an opaque color to remove 5202 transparency from an image.</td> 5203 </tr> 5204 5205 5206 <tr> 5207 <td>merge</td> 5208 <td>As 'flatten' method but merging all the given image 5209 layers to create a new layer image just large enough to hold all the 5210 image without clipping or extra space. The new images virtual offset 5211 will preserve the position of the new layer, even if this offset is 5212 negative. The virtual canvas size of the first image is preserved. 5213 </td> 5214 </tr> 5215 5216 <tr><td></td><td>Caution is advised when handling image layers with 5217 negative offsets as few image file formats handle them correctly. 5218 Following this operation method with <a href="command-line-options.html#repage" >+repage</a> 5219 will remove the layer offset, and create an image in which all the 5220 overlaid image positions relative to each other is preserved, though 5221 not necessarily exactly where you specified them. 5222 </td> 5223 </tr> 5224 5225 <tr><td></td><td>See also 'trim-bounds' below which is closely related but 5226 without doing the'flatten' to merge the images together. </td> 5227 </tr> 5228 5229 <tr> 5230 <td>mosaic</td> 5231 <td>As 'flatten' method but expanding the initial canvas size 5232 of the first image in a positive direction only so as to hold all the 5233 image layers. However as a virtual canvas is 'locked' to the origin, 5234 by its own definition, image layers with a negative offsets will still 5235 become clipped by the top and left edges. See 'merge' or 'trim-bounds' 5236 if this could be a problem. </td> 5237 5238 </tr> 5239 5240 <tr><td></td><td>This method is commonly used to layout individual image 5241 using various offset but without knowing the final canvas size. The 5242 resulting image will, like 'flatten' not have any virtual offset, so 5243 can be saved to any image file format. </td> 5244 </tr> 5245 5246 5247 <tr> 5248 <td>optimize</td> 5249 <td>Optimize a coalesced animation, into GIF animation using 5250 a number of general techniques. This currently a short cut to 5251 apply both the '<code>optimize-frame</code>', and 5252 '<code>optimize-transparency</code>' methods but may be expanded to 5253 include other optimization methods as they are developed. </td> 5254 </tr> 5255 5256 <tr> 5257 <td>optimize-frame</td> 5258 <td>Optimize a coalesced animation, into GIF animation by 5259 reducing the number of pixels per frame as much as possible by 5260 attempting to pick the best layer disposal method to use, while ensuring 5261 the result will continue to animate properly. </td> 5262 </tr> 5263 5264 <tr><td></td><td> There is no guarantee that the best optimization is found. 5265 But then no reasonably fast GIF optimization algorithm can do this. 5266 However this does seem to do better than most other GIF frame 5267 optimizers seen. </td> 5268 </tr> 5269 5270 <tr> 5271 <td>optimize-plus</td> 5272 <td>As '<code>optimize-frame</code>' but attempt to improve the 5273 overall optimization by adding extra frames to the animation, without 5274 changing the final look or timing of the animation. The frames are 5275 added to attempt to separate the clearing of pixels from the 5276 overlaying of new additional pixels from one animation frame to the 5277 next. If this does not improve the optimization (for the next frame 5278 only), it will fall back to the results of the previous normal 5279 '<code>optimize-frame</code>' technique. </td> 5280 </tr> 5281 5282 <tr><td></td><td>There is the possibility that the change in the disposal 5283 style will result in a worsening in the optimization of later frames, 5284 though this is unlikely. In other words there no guarantee that it is 5285 better than the normal '<code>optimize-frame</code>' technique. For some 5286 animations however you can get a vast improvement in the final 5287 animation size. </td> 5288 </tr> 5289 5290 <tr> 5291 <td>optimize-transparency</td> 5292 <td>Given a GIF animation, replace any pixel in the sub-frame 5293 overlay images with transparency, if it does not change the resulting 5294 animation by more than the current <a href="command-line-options.html#fuzz" >-fuzz</a> factor. 5295 </td> 5296 </tr> 5297 5298 <tr><td></td><td>This should allow a existing frame optimized GIF animation 5299 to compress into a smaller file size due to larger areas of one 5300 (transparent) color rather than a pattern of multiple colors repeating 5301 the current disposed image of the last frame. </td> 5302 </tr> 5303 5304 <tr> 5305 <td>remove-dups</td> 5306 <td>Remove (and merge time delays) of duplicate consecutive 5307 images, so as to simplify layer overlays of coalesced animations. 5308 </td> 5309 </tr> 5310 5311 <tr><td></td><td>Usually this a result of using a constant time delay 5312 across the whole animation, or after a larger animation was split into 5313 smaller sub-animations. The duplicate frames could also have been 5314 used as part of some frame optimization methods. </td> 5315 </tr> 5316 5317 <tr> 5318 <td>remove-zero</td> 5319 <td>Remove any image with a zero time delay, unless ALL the 5320 images have a zero time delay (and is not a proper timed animation, a 5321 warning is then issued). </td> 5322 </tr> 5323 5324 <tr><td></td><td>In a GIF animation, such images are usually frames which 5325 provide partial intermediary updates between the frames that are 5326 actually displayed to users. These frames are usually added for 5327 improved frame optimization in GIF animations. </td> 5328 </tr> 5329 5330 <tr> 5331 <td>trim-bounds</td> 5332 <td>Find the bounds of all the images in the current 5333 image sequence, then adjust the offsets so all images are contained on 5334 a minimal positive canvas. None of the image data is modified or 5335 merged, only the individual image virtual canvas size and offset. 5336 All the images is given the same canvas size, and and will have 5337 a positive offset, but will remain in the same position relative to 5338 each other. As a result of the minimal canvas size at least one image 5339 will touch every edge of that canvas. The image data touching those 5340 edges however may be transparent. </td> 5341 </tr> 5342 5343 <tr><td></td><td>The result is much like if you used 'merge' followed by a 5344 <a href="command-line-options.html#repage" >+repage</a> option, except that all the images 5345 have been kept separate. If 'flatten' is used after using 5346 'trim-bounds' you will get the same result. </td> 5347 </tr> 5348 5349 </tbody> 5350</table> 5351 5352<p>To print a complete list of layer types, use <a href="command-line-options.html#list">-list layers</a>.</p> 5353 5354<p>The operators <a href="command-line-options.html#coalesce" >-coalesce</a>, <a href="command-line-options.html#deconstruct" 5355>-deconstruct</a>, <a href="command-line-options.html#flatten" >-flatten</a>, and <a href="command-line-options.html#mosaic" 5356>-mosaic</a> are only aliases for the above methods and may be depreciated in 5357the future. Also see <a href="command-line-options.html#page" >-page</a>, <a href="command-line-options.html#repage" 5358>-repage</a> operators, the <a href="command-line-options.html#compose" >-compose</a> setting, and the 5359GIF <a href="command-line-options.html#dispose" >-dispose</a> and <a href="command-line-options.html#delay" >-delay</a> 5360settings. </p> 5361 5362 5363<div style="margin: auto;"> 5364 <h3><a class="anchor" id="level"></a>-level <var>black_point</var>{,<var>white_point</var>}{<var>%</var>}{,<var>gamma</var>}</h3> 5365</div> 5366 5367<p class="magick-description">adjust the level of image channels.</p> 5368 5369<p>Given one, two or three values delimited with commas: black-point, 5370white-point, gamma (for example: 10,250,1.0 or 2%,98%,0.5). The black and 5371white points range from 0 to <var>QuantumRange</var>, or from 0 to 5372100%; if the white point is omitted it is set to (<var>QuantumRange</var> - black_point), so as to center contrast changes. 5373If a <code>%</code> sign is present anywhere in the string, both black and white 5374points are percentages of the full color range. Gamma will do a <a 5375href="command-line-options.html#gamma">-gamma</a> adjustment of the values. If it is omitted, the 5376default of 1.0 (no gamma correction) is assumed.</p> 5377 5378<p>In normal usage (<code>-level</code>) the image values are stretched so that 5379the given '<code>black_point</code>' value in the original image is set to zero 5380(or black), while the given '<code>white_point</code>' value is set to <var>QuantumRange</var> (or white). This provides you with direct 5381contrast adjustments to the image. The '<code>gamma</code>' of the resulting 5382image will then be adjusted. </p> 5383 5384<p>From ImageMagick v6.4.1-9 using the plus form of the operator 5385(<code>+level</code>) or adding the special '!' flag anywhere in the argument 5386list, will cause the operator to do the reverse of the level adjustment. That 5387is a zero, or <var>QuantumRange</var> value (black, and white, resp.) 5388in the original image, is adjusted to the given level values, allowing you to 5389de-contrast, or compress the channel values within the image. The 5390'<code>gamma</code>' is adjusted before the level adjustment to de-contrast the 5391image is made. </p> 5392 5393<p>Only the channels defined by the current <a href="command-line-options.html#channel">-channel</a> 5394setting are adjusted (defaults to RGB color channels only), allowing you to 5395limit the effect of this operator. </p> 5396 5397<p>Please note that the transparency channel is treated as 'matte' 5398values (0 is opaque) and not as 'alpha' values (0 is transparent).</p> 5399 5400 5401<div style="margin: auto;"> 5402 <h3><a class="anchor" id="level-colors"></a>-level-colors {<var>black_color</var>}{,}{<var>white_color</var>}</h3> 5403</div> 5404 5405<p class="magick-description">adjust the level of an image using the provided dash separated colors.</p> 5406 5407<p>This function is exactly like <a href="command-line-options.html#level">-level</a>, except that the 5408value value for each color channel is determined by the 5409'<code>black_color</code>' and '<code>white_color</code>' colors given (as 5410described under the <a href="command-line-options.html#fill">-fill</a> option). </p> 5411 5412<p>This effectively means the colors provided to <code>-level-colors</code> 5413is mapped to become 'black' and 'white' respectively, with all the other 5414colors linearly adjusted (or clipped) to match that change. Each channel is 5415adjusted separately using the channel values of the colors specified. </p> 5416 5417<p>On the other hand the plus form of the operator (<code>+level-colors</code>) 5418will map the image color 'black' and 'white' to the given colors 5419respectively, resulting in a gradient (de-contrasting) tint of the image to 5420those colors. This can also be used to convert a plain grayscale image into a 5421one using the gradient of colors specified. </p> 5422 5423<p>By supplying a single color with a comma separator either before or after 5424that color, will just replace the respective 'black' or 'white' point 5425respectively. But if no comma separator is provided, the given color is 5426used for both the black and white color points, making the operator either 5427threshold the images around that color (- form) or set all colors to that 5428color (+ form). </p> 5429 5430 5431<div style="margin: auto;"> 5432 <h3><a class="anchor" id="limit"></a>-limit <var>type value</var></h3> 5433</div> 5434 5435<p class="magick-description">Set the pixel cache resource limit.</p> 5436 5437<p>Choose from: <code>width</code>, <code>height</code>, <code>area</code>, <code>memory</code>, <code>map</code>, <code>disk</code>, <code>file</code>, <code>thread</code>, <code>throttle</code>, or <code>time</code>.</p> 5438 5439<p>The value for <code>file</code> is in number of files. The other limits are 5440in bytes. Define arguments for the memory, map, area, and disk resource limits 5441with SI prefixes (.e.g 100MB).</p> 5442 5443<p>By default the limits are 768 files, 3GB of image area, 1.5GiB memory, 3GiB 5444memory map, and 18.45EB of disk. These limits are adjusted relative to the 5445available resources on your computer if this information is available. When 5446any limit is reached, ImageMagick fails in some fashion but attempts to take 5447compensating actions, if possible. For example, the following limits 5448memory:</p> 5449 5450<pre class="highlight"><code>-limit memory 32MiB -limit map 64MiB 5451</code></pre> 5452 5453<p>Use <a href="command-line-options.html#list">-list resource</a> to list the current limits. For example, our system shows these limits:</p> 5454 5455<pre class="highlight"><code>-> identify -list resource 5456Resource limits: 5457 Width: 100MP 5458 Height: 100MP 5459 Area: 25.181GB 5460 Memory: 11.726GiB 5461 Map: 23.452GiB 5462 Disk: unlimited 5463 File: 768 5464 Thread: 12 5465 Throttle: 0 5466 Time: unlimited 5467</code></pre> 5468 5469<p>Requests for pixel storage to keep intermediate images are satisfied by one 5470of three resource categories: in-memory pool, memory-mapped files pool, and 5471disk pool (in that order) depending on the <a href="command-line-options.html#limit">‑limit</a> settings 5472and whether the system honors a resource request. If the total size of 5473allocated pixel storage in the given pool reaches the corresponding limit, the 5474request is passed to the next pool. Additionally, requests that exceed the 5475<code>area</code> limit automagically are allocated on disk.</p> 5476 5477<p>To illustrate how ImageMagick utilizes resource limits, consider a typical 5478image resource request. First, ImageMagick tries to allocate the pixels in 5479memory. The request might be denied if the resource request exceeds the 5480<code>memory</code> limit or if the system does not honor the request. If 5481a memory request is not honored, the pixels are allocated to disk and the file 5482is memory-mapped. However, if the allocation request exceeds the 5483<code>map</code> limit, the resource allocation goes to disk. In all cases, if 5484the resource request exceeds the <code>area</code> limit, the pixels are 5485automagically cached to disk. If the disk has a hard limit, the program 5486fails.</p> 5487 5488<p>In most cases you simply do not need to concern yourself with resource 5489limits. ImageMagick chooses reasonable defaults and most images do not tax 5490your computer resources. Where limits do come in handy is when you process 5491images that are large or on shared systems where ImageMagick can consume all 5492or most of the available memory. In this case, the ImageMagick workflow slows 5493other processes or, in extreme cases, brings the system to a halt. Under 5494these circumstances, setting limits give some assurances that the ImageMagick 5495workflow will not interfere with other concurrent uses of the computer. For 5496example, assume you have a web interface that processes images uploaded from 5497the Internet. To assure ImageMagick does not exceed 10MiB of memory you can 5498simply set the area limit to 10MiB:</p> 5499 5500<pre class="highlight"><code>-limit area 10MB 5501</code></pre> 5502 5503<p>Now whenever a large image is processed, the pixels are automagically 5504cached to disk instead of memory. This of course implies that large images 5505typically process very slowly, simply because pixel processing in memory can 5506be an order of magnitude faster than on disk. Because your web site users 5507might inadvertently upload a huge image to process, you should set a disk 5508limit as well:</p> 5509 5510<pre class="highlight"><code>-limit area 10MB -limit disk 500MB 5511</code></pre> 5512 5513<p>Here ImageMagick stops processing if an image requires more than 500MB of disk storage.</p> 5514 5515<p>In addition to command-line resource limit option, resources can be set 5516with <a href="resources.html#environment" >environment variables</a>. Set the 5517environment variables <code>MAGICK_AREA_LIMIT</code>, 5518<code>MAGICK_DISK_LIMIT</code>, <code>MAGICK_FILE_LIMIT</code>, 5519<code>MAGICK_MEMORY_LIMIT</code>, <code>MAGICK_MAP_LIMIT</code>, 5520<code>MAGICK_THREAD_LIMIT</code>, <code>MAGICK_TIME_LIMIT</code> for limits of 5521image area, disk space, open files, heap memory, memory map, number of threads 5522of execution, and maximum elapsed time in seconds respectively.</p> 5523 5524<p> Inquisitive users can try adding <a href="command-line-options.html#debug">-debug cache</a> to 5525their commands and then scouring the generated output for references to the 5526pixel cache, in order to determine how the pixel cache was allocated and how 5527resources were consumed. Advanced Unix/Linux users can pipe that output 5528through <code>grep memory|open|destroy|disk</code> for more readable sifting. 5529</p> 5530 5531<p>For more about ImageMagick's use of resources, see the section <b>Cache 5532Storage and Resource Requirements</b> on the <a href="architecture.html#cache 5533">Architecture</a> page. </p> 5534 5535<div style="margin: auto;"> 5536 <h3><a class="anchor" id="linear-stretch"></a>-linear-stretch <var>black-point</var><br />-linear-stretch <var>black-point</var>{x<var>white-point</var>}{<var>%</var>}</h3> 5537</div> 5538 5539<p class="magick-description">Linear with saturation stretch.</p> 5540 5541<p>This is very similar to <a href="command-line-options.html#contrast-stretch" >-contrast-stretch</a>, 5542and uses a 'histogram bin' to determine the range of color values that needs to 5543be stretched. However it then stretches those colors using the <a 5544href="command-line-options.html#level" >-level</a> operator.</p> 5545 5546<p>As such while the initial determination may have 'binning' round off 5547effects, the image colors are stretched mathematically, rather than using the 5548histogram bins. This makes the operator more accurate. </p> 5549 5550<p>note however that a <a href="command-line-options.html#linear-stretch" >-linear-stretch</a> of 5551'<code>0</code>' does nothing, while a value of '<code>1</code>' does a near 5552perfect stretch of the color range. </p> 5553 5554<p>See also <a href="command-line-options.html#auto-level" >-auto-level</a> for a 'perfect' 5555normalization of mathematical images. </p> 5556 5557<p>This operator is under review for re-development. </p> 5558 5559 5560<div style="margin: auto;"> 5561 <h3><a class="anchor" id="linewidth"></a>-linewidth</h3> 5562</div> 5563 5564<p class="magick-description">the line width for subsequent draw operations.</p> 5565 5566<div style="margin: auto;"> 5567 <h3><a class="anchor" id="liquid-rescale"></a>-liquid-rescale <var>geometry</var></h3> 5568</div> 5569 5570<p class="magick-description">rescale image with seam-carving.</p> 5571 5572<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 5573 5574<div style="margin: auto;"> 5575 <h3><a class="anchor" id="list"></a>-list <var>type</var></h3> 5576</div> 5577 5578<p class="magick-description">Print a list of supported arguments for various options or settings. Choose from these list types:</p> 5579 5580<pre class="pre-scrollable"><code> 5581Align 5582Alpha 5583Boolean 5584Cache 5585Channel 5586Class 5587ClipPath 5588Coder 5589Color 5590Colorspace 5591Command 5592Complex 5593Compose 5594Compress 5595Configure 5596DataType 5597Debug 5598Decoration 5599Delegate 5600Direction 5601Dispose 5602Distort 5603Dither 5604Endian 5605Evaluate 5606FillRule 5607Filter 5608Font 5609Format 5610Function 5611Gravity 5612Intensity 5613Intent 5614Interlace 5615Interpolate 5616Kernel 5617Layers 5618LineCap 5619LineJoin 5620List 5621Locale 5622LogEvent 5623Log 5624Magic 5625Method 5626Metric 5627Mime 5628Mode 5629Morphology 5630Module 5631Noise 5632Orientation 5633PixelIntensity 5634Policy 5635PolicyDomain 5636PolicyRights 5637Preview 5638Primitive 5639QuantumFormat 5640Resource 5641SparseColor 5642Statistic 5643Storage 5644Stretch 5645Style 5646Threshold 5647Type 5648Units 5649Validate 5650VirtualPixel 5651</code></pre> 5652 5653<p>These lists vary depending on your version of ImageMagick. Use "<code>-list 5654list</code>" to get a complete listing of all the "<code>-list</code>" arguments 5655available:</p> 5656 5657<pre class="highlight"><code>identify -list list 5658</code></pre> 5659 5660<div style="margin: auto;"> 5661 <h3><a class="anchor" id="log"></a>-log <var>string</var></h3> 5662</div> 5663 5664<p class="magick-description">Specify format for debug log.</p> 5665 5666<p>This option specifies the format for the log printed when the <a 5667href="command-line-options.html#debug">-debug</a> option is active.</p> 5668 5669<p>You can display the following components by embedding special format 5670characters:</p> 5671 5672<dl class="row"> 5673<dt class="col-md-4">%d</dt><dd class="col-md-8">domain</dd> 5674<dt class="col-md-4">%e</dt><dd class="col-md-8">event</dd> 5675<dt class="col-md-4">%f</dt><dd class="col-md-8">function</dd> 5676<dt class="col-md-4">%l</dt><dd class="col-md-8">line</dd> 5677<dt class="col-md-4">%m</dt><dd class="col-md-8">module</dd> 5678<dt class="col-md-4">%p</dt><dd class="col-md-8">process ID</dd> 5679<dt class="col-md-4">%r</dt><dd class="col-md-8">real CPU time</dd> 5680<dt class="col-md-4">%t</dt><dd class="col-md-8">wall clock time</dd> 5681<dt class="col-md-4">%u</dt><dd class="col-md-8">user CPU time</dd> 5682<dt class="col-md-4">%%</dt><dd class="col-md-8">percent sign</dd> 5683<dt class="col-md-4">\n</dt><dd class="col-md-8">newline</dd> 5684<dt class="col-md-4">\r</dt><dd class="col-md-8">carriage return</dd> 5685</dl> 5686 5687<p>For example:</p> 5688 5689<pre class="highlight"><code>convert -debug coder -log "%u %m:%l %e" in.gif out.png 5690</code></pre> 5691 5692<p>The default behavior is to print all of the components.</p> 5693 5694<div style="margin: auto;"> 5695 <h3><a class="anchor" id="loop"></a>-loop <var>iterations</var></h3> 5696</div> 5697 5698<p class="magick-description">add Netscape loop extension to your GIF animation.</p> 5699 5700<p>Set iterations to zero to repeat the animation an infinite number of times, 5701otherwise the animation repeats itself up to <var>iterations</var> 5702times.</p> 5703 5704<div style="margin: auto;"> 5705 <h3><a class="anchor" id="lowlight-color"></a>-lowlight-color <var>color</var></h3> 5706</div> 5707 5708<p class="magick-description">when comparing images, de-emphasize pixel differences with this color.</p> 5709 5710<div style="margin: auto;"> 5711 <h3><a class="anchor" id="magnify"></a>-magnify</h3> 5712</div> 5713 5714<p class="magick-description">double or triple the size of the image with pixel art scaling. Specify an alternative scaling method with <code>-define magnify:method=<var>method</var></code> Choose from these methods: <code>eagle2X, eagle3X, eagle3XB, epb2X, fish2X, hq2X, scale2X, scale3X, xbr2X</code>. The default is scale2X.</p> 5715 5716 5717<div style="margin: auto;"> 5718 <h3><a class="anchor" id="map"></a>-map <var>type</var></h3> 5719</div> 5720 5721<p class="magick-description">Display image using this <var>type</var>.</p> 5722 5723<p>Choose from these <var>Standard Colormap</var> types:</p> 5724 5725<pre class="highlight"><code>best 5726default 5727gray 5728red 5729green 5730blue 5731</code></pre> 5732 5733<p>The <var>X server</var> must support the <var>Standard 5734Colormap</var> you choose, otherwise an error occurs. Use <code>list</code> as 5735the type and <code>display</code> searches the list of colormap types in 5736<code>top-to-bottom</code> order until one is located. See <var>xstdcmap(1)</var> for one way of creating Standard Colormaps.</p> 5737 5738 5739<div style="margin: auto;"> 5740 <h3><a class="anchor" id="map_stream_"></a>-map <var>components</var></h3> 5741</div> 5742 5743<p class="magick-description">pixel map.</p> 5744 5745<p>Here are the valid components of a map:</p> 5746 5747<dl class="row"> 5748<dt class="col-md-4">r</dt><dd class="col-md-8"> red pixel component</dd> 5749<dt class="col-md-4">g</dt><dd class="col-md-8"> green pixel component</dd> 5750<dt class="col-md-4">b</dt><dd class="col-md-8"> blue pixel component</dd> 5751<dt class="col-md-4">a</dt><dd class="col-md-8"> alpha pixel component (0 is transparent)</dd> 5752<dt class="col-md-4">o</dt><dd class="col-md-8"> opacity pixel component (0 is opaque)</dd> 5753<dt class="col-md-4">i</dt><dd class="col-md-8"> grayscale intensity pixel component</dd> 5754<dt class="col-md-4">c</dt><dd class="col-md-8"> cyan pixel component</dd> 5755<dt class="col-md-4">m</dt><dd class="col-md-8"> magenta pixel component</dd> 5756<dt class="col-md-4">y</dt><dd class="col-md-8"> yellow pixel component</dd> 5757<dt class="col-md-4">k</dt><dd class="col-md-8"> black pixel component</dd> 5758<dt class="col-md-4">p</dt><dd class="col-md-8"> pad component (always 0)</dd> 5759</dl> 5760 5761<p>You can specify as many of these components as needed in any order (e.g. 5762bgr). The components can repeat as well (e.g. rgbr).</p> 5763 5764 5765<div style="margin: auto;"> 5766 <h3><a class="anchor" id="mattecolor"></a>-mattecolor <var>color</var></h3> 5767</div> 5768 5769<p class="magick-description">Specify the color to be used with the <a href="command-line-options.html#frame">-frame</a> option.</p> 5770 5771<p>The color is specified using the format described under the <a href="command-line-options.html#fill">-fill</a> option.</p> 5772 5773<p>The default matte color is <code>#BDBDBD</code>, <span 5774style="background-color: #bdbdbd;">this shade of gray</span>.</p> 5775 5776<div style="margin: auto;"> 5777 <h3><a class="anchor" id="maximum"></a>-maximum</h3> 5778</div> 5779 5780<p class="magick-description">return the maximum intensity of an image sequence.</p> 5781 5782<p>Select the 'maximum' value from all the surrounding pixels. </p> 5783 5784<p>This is legacy option from the <a href="command-line-options.html#statistic" >method</a> of the same 5785name. </p> 5786 5787<div style="margin: auto;"> 5788 <h3><a class="anchor" id="median"></a>-median <var>geometry</var></h3> 5789</div> 5790 5791<p class="magick-description">apply a median filter to the image.</p> 5792 5793<p>Select the 'middle' value from all the surrounding pixels. </p> 5794 5795<p>This is legacy option from the <a href="command-line-options.html#statistic" >method</a> of the same 5796name. </p> 5797 5798<div style="margin: auto;"> 5799 <h3><a class="anchor" id="mean-shift"></a>-mean-shift <var>width</var>x<var>height</var>{<var>+distance</var>{%}</h3> 5800</div> 5801 5802<p class="magick-description">image noise removal and color reduction/segmentation (e.g. -mean-shift 7x7+10%).</p> 5803 5804<p><var>width</var>x<var>height</var> is the window size and <var>distance</var> is the color distance measured in the range 0 to 1 or 0 to 100%</p> 5805 5806<p>The mean shift algorithm is iterative and thus slower the larger the window size. For each pixel, it gets all the pixels in the window centered at the pixel and excludes those that are outside the <var>radius=sqrt((width-1)(height-1)/4)</var> surrounding the pixel. From those pixels, it finds which of them are within the specified squared color distance from the current mean. It then computes a new x,y centroid from those coordinates and a new mean. This new x,y centroid is used as the center for a new window. This process is iterated until it converges and the final mean is then used to replace the original pixel value. It repeats this process for the next pixel, etc, until it processes all pixels in the image. Results are better when using other colorspaces rather than RGB. Recommend YIQ, YUV or YCbCr, which seem to give equivalent results.</p> 5807 5808<div style="margin: auto;"> 5809 <h3><a class="anchor" id="metric"></a>-metric <var>type</var></h3> 5810</div> 5811 5812<p class="magick-description">Output to STDERR a measure of the differences between images according to the <var>type</var> given metric.</p> 5813 5814<p>Choose from:</p> 5815 5816<dl class="row"> 5817<dt class="col-md-4">AE</dt><dd class="col-md-8"> absolute error count, number of different pixels (-fuzz affected)</dd> 5818<dt class="col-md-4">DSSIM</dt><dd class="col-md-8"> structural dissimilarity index</dd> 5819<dt class="col-md-4">FUZZ</dt><dd class="col-md-8"> mean color distance</dd> 5820<dt class="col-md-4">MAE</dt><dd class="col-md-8"> mean absolute error (normalized), average channel error distance</dd> 5821<dt class="col-md-4">MEPP</dt><dd class="col-md-8"> mean error per pixel (normalized mean error, normalized peak error)</dd> 5822<dt class="col-md-4">MSE</dt><dd class="col-md-8"> mean error squared, average of the channel error squared</dd> 5823<dt class="col-md-4">NCC</dt><dd class="col-md-8"> normalized cross correlation</dd> 5824<dt class="col-md-4">PAE</dt><dd class="col-md-8"> peak absolute (normalized peak absolute)</dd> 5825<dt class="col-md-4">PHASH</dt><dd class="col-md-8"> perceptual hash for the sRGB and HCLp colorspaces. Specify an alternative colorspace with <code>-define phash:colorspaces=<var>colorspace,colorspace,...</var></code></dd> 5826<dt class="col-md-4">PSNR</dt><dd class="col-md-8"> peak signal to noise ratio</dd> 5827<dt class="col-md-4">RMSE</dt><dd class="col-md-8"> root mean squared (normalized root mean squared)</dd> 5828<dt class="col-md-4">SSIM</dt><dd class="col-md-8"> structural similarity index</dd> 5829</dl> 5830 5831<p>Control the '<code>AE</code>', or absolute count of pixels that are different, 5832with the <a href="command-line-options.html#fuzz" >-fuzz</a> factor (ignore pixels which 5833only changed by a small amount). Use '<code>PAE</code>' to find the 5834size of the <a href="command-line-options.html#fuzz" >-fuzz</a> factor needed to make all pixels 5835'similar', while '<code>MAE</code>' determines the factor needed 5836for about half the pixels to be similar. </p> 5837 5838<p>The <code>MEPP</code> metric returns three different metrics 5839('<code>MAE</code>', '<code>MAE</code>' normalized, and '<code>PAE</code>' 5840normalized) from a single comparison run. </p> 5841 5842<p>The <code>SSIM</code> and <code>DSSIM</code> metrics respect these defines: 5843<code>-define compare:ssim-radius</code>, <code>-define compare:ssim-sigma</code>, 5844<code>-define compare:ssim-k1</code>, and <code>-define compare:ssim-k2</code>.</p> 5845 5846<p>To print a complete list of metrics, use the <a href="command-line-options.html#list">-list 5847metric</a> option.</p> 5848 5849 5850<div style="margin: auto;"> 5851 <h3><a class="anchor" id="minimum"></a>-minimum</h3> 5852</div> 5853 5854<p class="magick-description">return the minimum intensity of an image sequence.</p> 5855 5856<p>Select the 'minimal' value from all the surrounding pixels. </p> 5857 5858<p>This is legacy option from the <a href="command-line-options.html#statistic" >method</a> of the same 5859name. </p> 5860 5861 5862 5863<div style="margin: auto;"> 5864 <h3><a class="anchor" id="mode"></a>-mode <var>geometry</var></h3> 5865</div> 5866 5867<p class="magick-description">make each pixel the \'predominant color\' of the neighborhood.'</p> 5868 5869<div style="margin: auto;"> 5870 <h3>-mode <var>value</var></h3> 5871</div> 5872 5873<p class="magick-description">Mode of operation.</p> 5874 5875<p>Choose the <var>value</var> from these styles: <code>Frame, 5876Unframe, or Concatenate</code></p> 5877 5878<p>Use the <a href="command-line-options.html#list" >-list</a> option with a '<code>Mode</code>' argument 5879for a list of <a href="command-line-options.html#mode" >-mode</a> arguments available in your 5880ImageMagick installation.</p> 5881 5882 5883<div style="margin: auto;"> 5884 <h3><a class="anchor" id="modulate"></a>-modulate <var>brightness</var>[,<var>saturation</var>,<var>hue</var>]</h3> 5885</div> 5886 5887<p class="magick-description">Vary the <var>brightness</var>, <var>saturation</var>, and <var>hue</var> of an image.</p> 5888 5889<p>The arguments are given as a percentages of variation. A value of 100 means 5890no change, and any missing values are taken to mean 100.</p> 5891 5892<p>The <var>brightness</var> is a multiplier of the overall 5893brightness of the image, so 0 means pure black, 50 is half as bright, 200 is 5894twice as bright. To invert its meaning <a href="command-line-options.html#negate">-negate</a> the image 5895before and after. </p> 5896 5897<p>The <var>saturation</var> controls the amount of color in an 5898image. For example, 0 produce a grayscale image, while a large value such as 5899200 produce a very colorful, 'cartoonish' color.</p> 5900 5901<p>The <var>hue</var> argument causes a "rotation" of the colors 5902within the image by the amount specified. For example, 50 results in 5903a counter-clockwise rotation of 90, mapping red shades to purple, and so on. 5904A value of either 0 or 200 results in a complete 180 degree rotation of the 5905image. Using a value of 300 is a 360 degree rotation resulting in no change to 5906the original image. </p> 5907 5908<p>For example, to increase the color brightness by 20% and decrease the color 5909saturation by 10% and leave the hue unchanged, use <a 5910href="command-line-options.html#modulate">-modulate 120,90</a>.</p> 5911 5912<p>Use <a href="command-line-options.html#set">-set</a> attribute of '<code 5913>option:modulate:colorspace</code>' to specify which colorspace to 5914modulate. Choose from <code>HCL</code>, <code>HCLp</code>, <code>HSB</code>, <code>HSI</code>, <code>HSL</code> (the default), <code>HSV</code>, <code>HWB</code>, or <code>LCH</code> (LCHuv). For example,</p> 5915 5916<pre class="highlight"><code>convert image.png -set option:modulate:colorspace hsb -modulate 120,90 modulate.png 5917</code></pre> 5918 5919<div style="margin: auto;"> 5920 <h3><a class="anchor" id="moments"></a>-moments</h3> 5921</div> 5922 5923<p class="magick-description">report image moments and perceptual hash.</p> 5924 5925 5926<div style="margin: auto;"> 5927 <h3><a class="anchor" id="monitor"></a>-monitor</h3> 5928</div> 5929 5930<p class="magick-description">monitor progress.</p> 5931 5932 5933<div style="margin: auto;"> 5934 <h3><a class="anchor" id="monochrome"></a>-monochrome</h3> 5935</div> 5936 5937<p class="magick-description">transform the image to black and white.</p> 5938 5939<div style="margin: auto;"> 5940 <h3><a class="anchor" id="morph"></a>-morph <var>frames</var></h3> 5941</div> 5942 5943<p class="magick-description">morphs an image sequence.</p> 5944 5945<p>Both the image pixels and size are linearly interpolated to give the 5946appearance of a metamorphosis from one image to the next, over all the images 5947in the current image list. The added images are the equivalent of a <a 5948href="command-line-options.html#blend">-blend</a> composition. The <var>frames</var> 5949argument determine how many images to interpolate between each image. </p> 5950 5951 5952<div style="margin: auto;"> 5953 <h3><a class="anchor" id="morphology"></a>-morphology</h3> 5954 <h3>-morphology <var>method</var> <var>kernel</var></h3> 5955</div> 5956 5957<p class="magick-description">apply a morphology method to the image.</p> 5958 5959<p>Until I get around to writing an option summary for this, see <a 5960href="../Usage/morphology/" >IM Usage Examples, 5961Morphology</a>. </p> 5962 5963 5964<div style="margin: auto;"> 5965 <h3><a class="anchor" id="mosaic"></a>-mosaic</h3> 5966</div> 5967 5968<p class="magick-description">an simple alias for the <a href="command-line-options.html#layers" >-layers</a> method "mosaic"</p> 5969 5970 5971<div style="margin: auto;"> 5972 <h3><a class="anchor" id="motion-blur"></a>-motion-blur <var>radius</var><br />-motion-blur <var>radius</var>x<var>sigma</var>+<var>angle</var></h3> 5973</div> 5974 5975<p class="magick-description">simulate motion blur.</p> 5976 5977<p>Blur with the given radius, standard deviation (sigma), and angle. The 5978angle given is the angle toward which the image is blurred. That is the 5979direction people would consider the object is coming from. </p> 5980 5981<p>Note that the blur is not uniform distribution, giving the motion a 5982definite sense of direction of movement. </p> 5983 5984<p>The <a href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting will determine how 5985pixels which are outside the image proper are blurred into the final result. 5986</p> 5987 5988<div style="margin: auto;"> 5989 <h3><a class="anchor" id="name"></a>-name</h3> 5990</div> 5991 5992<p class="magick-description">name an image.</p> 5993<div style="margin: auto;"> 5994 <h3><a class="anchor" id="negate"></a>-negate</h3> 5995</div> 5996 5997<p class="magick-description">replace each pixel with its complementary color.</p> 5998 5999<p>The red, green, and blue intensities of an image are negated. White becomes 6000black, yellow becomes blue, etc. Use <a href="command-line-options.html#negate">+negate</a> to only 6001negate the grayscale pixels of the image.</p> 6002 6003<div style="margin: auto;"> 6004 <h3><a class="anchor" id="noise"></a>-noise <var>geometry</var><br/> 6005 +noise <var>type</var></h3> 6006</div> 6007 6008<p class="magick-description">Add or reduce noise in an image.</p> 6009 6010<p>The principal function of noise peak elimination filter is to smooth the 6011objects within an image without losing edge information and without creating 6012undesired structures. The central idea of the algorithm is to replace a pixel 6013with its next neighbor in value within a pixel window, if this pixel has been 6014found to be noise. A pixel is defined as noise if and only if this pixel is 6015a maximum or minimum within the pixel window.</p> 6016 6017<p>Use <code><a href="command-line-options.html#noise">-noise</a> <var>radius</var></code> to 6018specify the width of the neighborhood when reducing noise. This is equivalent 6019to using a <code><a href="command-line-options.html#statistic" >-statistic</a> NonPeak</code> operation, 6020which should be used in preference.</p> 6021 6022<p>Use <a href="command-line-options.html#noise">+noise</a> followed by a noise <var>type</var> to add noise to an image. Choose from these noise 6023types:</p> 6024 6025<pre class="highlight"><code>Gaussian 6026Impulse 6027Laplacian 6028Multiplicative 6029Poisson 6030Random 6031Uniform 6032</code></pre> 6033 6034<p>The amount of noise added can be controlled by the <code><a 6035href="command-line-options.html#attenuate" >-attenuate</a></code> setting. If unset the value is 6036equivalent to 1.0, or a maximum noise addition.</p> 6037 6038<p>Note that Random will replace the image with noise rather than add noise to the image. Use Uniform, if you wish to add random noise to the image.</p> 6039 6040<p>To print a complete list of noises, use the <a href="command-line-options.html#list">-list noise</a> option.</p> 6041 6042<p>Also see the <a href="command-line-options.html#evaluate">-evaluate</a> noise functions that allows 6043the use of a controlling value to specify the amount of noise that should be 6044added to an image. </p> 6045 6046 6047<div style="margin: auto;"> 6048 <h3><a class="anchor" id="normalize"></a>-normalize</h3> 6049</div> 6050 6051<p class="magick-description">Increase the contrast in an image by <var>stretching</var> the range of intensity values.</p> 6052 6053<p>The intensity values are stretched to cover the entire range of possible 6054values. While doing so, black-out at most <var>2%</var> of the pixels and 6055white-out at most <var>1%</var> of the pixels.</p> 6056 6057<p>Note that as of ImageMagick 6.4.7-0, <a href="command-line-options.html#normalize" >-normalize</a> 6058is equivalent to <a href="command-line-options.html#contrast-stretch" >-contrast-stretch 2%x1%</a>. 6059(Before this version, it was equivalent to <a href="command-line-options.html#contrast-stretch" 6060>-contrast-stretch 2%x99%</a>).</p> 6061 6062<p>All the channels are normalized in concert by the same amount so as to 6063preserve color integrity, when the default <a href="command-line-options.html#channel" >+channel</a> 6064setting is in use. Specifying any other <a href="command-line-options.html#channel" >-channel</a> 6065setting will normalize the RGB channels independently.</p> 6066 6067<p>See <a href="command-line-options.html#contrast-stretch" >-contrast-stretch</a> for more details. 6068Also see <a href="command-line-options.html#auto-level" >-auto-level</a> for a 'perfect' normalization 6069that is better suited to mathematically generated images. </p> 6070 6071<p>This operator is under review for re-development. </p> 6072 6073 6074<div style="margin: auto;"> 6075 <h3><a class="anchor" id="opaque"></a>-opaque <var>color</var></h3> 6076</div> 6077 6078<p class="magick-description">change this color to the fill color within the image.</p> 6079 6080<p>The <var>color</var> argument is defined using the format 6081described under the <a href="command-line-options.html#fill" >-fill</a> option. The <a href="command-line-options.html#fuzz" 6082>-fuzz</a> setting can be used to match and replace colors similar to the one 6083given.</p> 6084 6085<p>Use <a href="command-line-options.html#opaque">+opaque</a> to paint any pixel that does not match 6086the target color. </p> 6087 6088<p>The <a href="command-line-options.html#transparent">-transparent</a> operator is exactly the same 6089as <a href="command-line-options.html#opaque" >-opaque</a> but replaces the matching color with 6090transparency rather than the current <a href="command-line-options.html#fill">-fill</a> color setting. 6091To ensure that it can do this it also ensures that the image has an alpha 6092channel enabled, as per "<code><a href="command-line-options.html#alpha" >-alpha</a> set</code>", for 6093the new transparent colors, and does not require you to modify the <a 6094href="command-line-options.html#channel">-channel</a> to enable alpha channel handling. </p> 6095 6096 6097<div style="margin: auto;"> 6098 <h3><a class="anchor" id="ordered-dither"></a>-ordered-dither <var>threshold_map</var>{,<var>level</var>...}</h3> 6099</div> 6100 6101<p class="magick-description">dither the image using a pre-defined ordered dither <var>threshold map</var> specified, and a uniform color map with the 6102given number of <var>levels</var> per color channel.</p> 6103 6104<p>You can choose from these standard threshold maps:</p> 6105 6106<pre class="pre-scrollable"><code> 6107threshold 1x1 Threshold 1x1 (non-dither) 6108checks 2x1 Checkerboard 2x1 (dither) 6109o2x2 2x2 Ordered 2x2 (dispersed) 6110o3x3 3x3 Ordered 3x3 (dispersed) 6111o4x4 4x4 Ordered 4x4 (dispersed) 6112o8x8 8x8 Ordered 8x8 (dispersed) 6113h3x4a 4x1 Halftone 4x4 (angled) 6114h6x6a 6x1 Halftone 6x6 (angled) 6115h8x8a 8x1 Halftone 8x8 (angled) 6116h3x4o Halftone 4x4 (orthogonal) 6117h6x6o Halftone 6x6 (orthogonal) 6118h8x8o Halftone 8x8 (orthogonal) 6119h36x16o Halftone 16x16 (orthogonal) 6120c5x5b c5x5 Circles 5x5 (black) 6121c5x5w Circles 5x5 (white) 6122c6x6b c6x6 Circles 6x6 (black) 6123c6x6w Circles 6x6 (white) 6124c7x7b c7x7 Circles 7x7 (black) 6125c7x7w Circles 7x7 (white) 6126</code></pre> 6127 6128<p> The <code>threshold</code> generated a simple 50% threshold of the image. 6129This could be used with <var >level</var> to do the equivalent of <a 6130href="command-line-options.html#posterize" >-posterize</a> to reduce an image to basic primary colors. 6131</p> 6132 6133<p>The <code>checks</code> pattern produces a 3 level checkerboard dither 6134pattern. That is a grayscale will become a pattern of solid black, solid 6135white, and mid-tone colors into a checkerboard pattern of black and white. 6136</p> 6137 6138<p>You can define your own <var >threshold map</var> for ordered 6139dithering and halftoning your images, in either personal or system 6140<code>thresholds.xml</code> XML file. See <a href="resources.html" >Resources</a> 6141for more details of configuration files. </p> 6142 6143<p>To print a complete list of the thresholds that have been defined, use the 6144<a href="command-line-options.html#list" >-list threshold</a> option.</p> 6145 6146<p>Note that at this time the same threshold dithering map is used for all 6147color channels, no attempt is made to offset or rotate the map for different 6148channels is made, to create an offset printing effect. Also as the maps are 6149simple threshold levels, the halftone and circle maps will create incomplete 6150circles along the edges of a colored area. Also all the effects are purely 6151on/off boolean effects, without anti-aliasing to make the circles smooth 6152looking. Large dots can be made to look better with a small amount of blurring 6153after being created. </p> 6154 6155 6156<div style="margin: auto;"> 6157 <h3><a class="anchor" id="orient"></a>-orient <var>image orientation</var></h3> 6158</div> 6159 6160<p class="magick-description">specify orientation of a digital camera image.</p> 6161 6162<p>Choose from these orientations:</p> 6163 6164<pre class="highlight"><code>bottom-left right-top 6165bottom-right top-left 6166left-bottom top-right 6167left-top undefined 6168right-bottom 6169</code></pre> 6170 6171<p>To print a complete list of orientations, use the <a href="command-line-options.html#list" >-list 6172orientation</a> option.</p> 6173 6174 6175<div style="margin: auto;"> 6176 <h3><a class="anchor" id="page"></a>-page <var>geometry</var><br/> 6177 -page <var>media</var>[<var>offset</var>][{<var>^!<></var>}]<br/> 6178 +page 6179 </h3> 6180</div> 6181 6182<p class="magick-description">Set the size and location of an image on the larger virtual canvas.</p> 6183 6184<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 6185 6186<p>For convenience you can specify the page size using <var>media</var> (see below). Offsets can then be added as with other 6187<var>geometry</var> arguments (e.g. <a 6188href="command-line-options.html#page">-page</a> <code>Letter+43+43</code>).</p> 6189 6190<p>Use <var>media</var> as shorthand to specify the dimensions (<var>width</var>x<var>height</var>) of the <var>PostScript</var> page in dots per inch or a TEXT page in pixels. 6191The choices for a PostScript page are:</p> 6192 6193<dl class="row"> 6194<dt class="col-md-4"> 11x17 </dt> <dd class="col-md-8"> 792 x 1224</dd> 6195<dt class="col-md-4"> Ledger </dt> <dd class="col-md-8"> 1224 x 792</dd> 6196<dt class="col-md-4"> Legal </dt> <dd class="col-md-8"> 612 x 1008</dd> 6197<dt class="col-md-4"> Letter </dt> <dd class="col-md-8"> 612 x 792</dd> 6198<dt class="col-md-4"> LetterSmall</dt> <dd class="col-md-8"> 612 x 792</dd> 6199<dt class="col-md-4"> ArchE </dt> <dd class="col-md-8"> 2592 x 3456</dd> 6200<dt class="col-md-4"> ArchD </dt> <dd class="col-md-8"> 1728 x 2592</dd> 6201<dt class="col-md-4"> ArchC </dt> <dd class="col-md-8"> 1296 x 1728</dd> 6202<dt class="col-md-4"> ArchB </dt> <dd class="col-md-8"> 864 x 1296</dd> 6203<dt class="col-md-4"> ArchA </dt> <dd class="col-md-8"> 648 x 864</dd> 6204<dt class="col-md-4"> A0 </dt> <dd class="col-md-8"> 2380 x 3368</dd> 6205<dt class="col-md-4"> A1 </dt> <dd class="col-md-8"> 1684 x 2380</dd> 6206<dt class="col-md-4"> A2 </dt> <dd class="col-md-8"> 1190 x 1684</dd> 6207<dt class="col-md-4"> A3 </dt> <dd class="col-md-8"> 842 x 1190</dd> 6208<dt class="col-md-4"> A4 </dt> <dd class="col-md-8"> 595 x 842</dd> 6209<dt class="col-md-4"> A4Small </dt> <dd class="col-md-8"> 595 x 842</dd> 6210<dt class="col-md-4"> A5 </dt> <dd class="col-md-8"> 421 x 595</dd> 6211<dt class="col-md-4"> A6 </dt> <dd class="col-md-8"> 297 x 421</dd> 6212<dt class="col-md-4"> A7 </dt> <dd class="col-md-8"> 210 x 297</dd> 6213<dt class="col-md-4"> A8 </dt> <dd class="col-md-8"> 148 x 210</dd> 6214<dt class="col-md-4"> A9 </dt> <dd class="col-md-8"> 105 x 148</dd> 6215<dt class="col-md-4"> A10 </dt> <dd class="col-md-8"> 74 x 105</dd> 6216<dt class="col-md-4"> B0 </dt> <dd class="col-md-8"> 2836 x 4008</dd> 6217<dt class="col-md-4"> B1 </dt> <dd class="col-md-8"> 2004 x 2836</dd> 6218<dt class="col-md-4"> B2 </dt> <dd class="col-md-8"> 1418 x 2004</dd> 6219<dt class="col-md-4"> B3 </dt> <dd class="col-md-8"> 1002 x 1418</dd> 6220<dt class="col-md-4"> B4 </dt> <dd class="col-md-8"> 709 x 1002</dd> 6221<dt class="col-md-4"> B5 </dt> <dd class="col-md-8"> 501 x 709</dd> 6222<dt class="col-md-4"> C0 </dt> <dd class="col-md-8"> 2600 x 3677</dd> 6223<dt class="col-md-4"> C1 </dt> <dd class="col-md-8"> 1837 x 2600</dd> 6224<dt class="col-md-4"> C2 </dt> <dd class="col-md-8"> 1298 x 1837</dd> 6225<dt class="col-md-4"> C3 </dt> <dd class="col-md-8"> 918 x 1298</dd> 6226<dt class="col-md-4"> C4 </dt> <dd class="col-md-8"> 649 x 918</dd> 6227<dt class="col-md-4"> C5 </dt> <dd class="col-md-8"> 459 x 649</dd> 6228<dt class="col-md-4"> C6 </dt> <dd class="col-md-8"> 323 x 459</dd> 6229<dt class="col-md-4"> Flsa </dt> <dd class="col-md-8"> 612 x 936</dd> 6230<dt class="col-md-4"> Flse </dt> <dd class="col-md-8"> 612 x 936</dd> 6231<dt class="col-md-4"> HalfLetter </dt> <dd class="col-md-8"> 396 x 612</dd> 6232</dl> 6233 6234<p>This option is also used to place subimages when writing to a multi-image 6235format that supports offsets, such as GIF89 and MNG. When used for this 6236purpose the offsets are always measured from the top left corner of the canvas 6237and are not affected by the <a href="command-line-options.html#gravity">-gravity</a> option. To 6238position a GIF or MNG image, use <a href="command-line-options.html#page">-page</a><var>{+-}x{+-}y</var> (e.g. -page +100+200). When writing to a MNG 6239file, a <a href="command-line-options.html#page">-page</a> option appearing ahead of the first image in 6240the sequence with nonzero width and height defines the width and height values 6241that are written in the <code>MHDR</code> chunk. Otherwise, the MNG width and 6242height are computed from the bounding box that contains all images in the 6243sequence. When writing a GIF89 file, only the bounding box method is used to 6244determine its dimensions.</p> 6245 6246<p>For a PostScript page, the image is sized as in <a 6247href="command-line-options.html#geometry">-geometry</a> but positioned relative to the <var>lower 6248left-hand corner</var> of the page by {+-}<code>x</code><var>offset</var>{+-}<code>y</code> <var>offset</var>. Use <a 6249href="command-line-options.html#page">-page 612x792</a>, for example, to center the image within the 6250page. If the image size exceeds the PostScript page, it is reduced to fit the 6251page. The default gravity for the <a href="command-line-options.html#page">-page</a> option is <var>NorthWest</var>, i.e., positive <code>x</code> and <code>y</code> <var>offset</var> are measured rightward and downward from the top left 6252corner of the page, unless the <a href="command-line-options.html#gravity">-gravity</a> option is 6253present with a value other than <var>NorthWest</var>.</p> 6254 6255<p>The default page dimensions for a TEXT image is 612x792.</p> 6256 6257<p>This option is used in concert with <a href="command-line-options.html#density">-density</a>.</p> 6258 6259<p>Use <a href="command-line-options.html#page">+page</a> to remove the page settings for an image.</p> 6260 6261<div style="margin: auto;"> 6262 <h3><a class="anchor" id="paint"></a>-paint <var>radius</var></h3> 6263</div> 6264 6265<p class="magick-description">simulate an oil painting.</p> 6266 6267<p>Each pixel is replaced by the most frequent color in a circular 6268neighborhood whose width is specified with <var>radius</var>.</p> 6269 6270<div style="margin: auto;"> 6271 <h3><a class="anchor" id="path"></a>-path <var>path</var></h3></div> 6272 6273<p class="magick-description">write images to this path on disk.</p> 6274 6275<div style="margin: auto;"> 6276 <h3><a class="anchor" id="pause_animate_"></a>-pause <var>seconds</var></h3> 6277</div> 6278 6279<p class="magick-description">Pause between animation loops</p> 6280 6281<p>Pause for the specified number of seconds before repeating the animation.</p> 6282 6283<div style="margin: auto;"> 6284 <h3><a class="anchor" id="pause_import_"></a>-pause <var>seconds</var></h3> 6285</div> 6286 6287<p class="magick-description">Pause between snapshots.</p> 6288 6289<p>Pause for the specified number of seconds before taking the next snapshot.</p> 6290 6291<div style="margin: auto;"> 6292 <h3><a class="anchor" id="perceptible"></a>-perceptible <var>epsilon</var></h3> 6293</div> 6294 6295<p class="magick-description">set each pixel whose value is less than |<var>epsilon</var>| to <var>-epsilon</var> or <var>epsilon</var> (whichever is closer) otherwise the pixel value remains unchanged.</p> 6296 6297<div style="margin: auto;"> 6298 <h3><a class="anchor" id="ping"></a>-ping</h3> 6299</div> 6300 6301<p class="magick-description">efficiently determine image characteristics.</p> 6302 6303<div style="margin: auto;"> 6304 <h3><a class="anchor" id="pointsize"></a>-pointsize <var>value</var></h3> 6305</div> 6306 6307<p class="magick-description">pointsize of the PostScript, OPTION1, or TrueType font.</p> 6308 6309<div style="margin: auto;"> 6310 <h3><a class="anchor" id="polaroid"></a>-polaroid <var>angle</var></h3> 6311</div> 6312 6313<p class="magick-description">simulate a Polaroid picture.</p> 6314 6315<p>Use <code>+polaroid</code> to rotate the image at a random angle between -15 and +15 degrees.</p> 6316 6317<div style="margin: auto;"> 6318 <h3><a class="anchor" id="poly"></a>-poly <var>"wt,exp ..."</var></h3> 6319</div> 6320 6321<p class="magick-description">combines multiple images according to a weighted sum of polynomials; one floating point weight (coefficient) and one floating point polynomial exponent (power) for each image expressed as comma separated pairs.</p> 6322 6323<p> The weights should typically be fractions between -1 and 1. But the sum of weights should be 1 or at least between 0 and 1 to avoid clamping in non-hdri mode at black and white.</p> 6324 6325<p>The exponents may be positive, negative or zero. A negative exponent is equivalent to 1 divided by the image raised to the corresponding positive exponent. A zero exponent always produces 1 scaled by quantumrange to white, i.e. wt*white, no matter what the image.</p> 6326 6327<p>The format is: <var>output = wt1*image1^exp1 + wt2*image2^exp2 </var>...</p> 6328 6329<p>Some simple uses are:</p> 6330<ul> 6331<li>A weighted sum of each image provided all weights add to unity and all exponents=1. If the the weights are all equal to 1/(number of images), then this is equivalent to <a href="command-line-options.html#profile">-evaluate-sequence</a> <var>mean</var>.</li> 6332<li>The sum of squares of two or more images, provided the weights are equal (and sum to 1 to avoid clamping) and the exponents equal 2.</li> 6333</ul> 6334 6335<p>Note that one may add a constant color to the expression simply by using xc:somecolor for one of the images and specifying the desired weight and exponent equal to 0.</p> 6336 6337<p>Similarly one may add white to the expression by simply using null: (or xc:white) for one of the images with the appropriate weight and exponent equal to 0.</p> 6338 6339 6340<div style="margin: auto;"> 6341 <h3><a class="anchor" id="posterize"></a>-posterize <var>levels</var></h3> 6342</div> 6343 6344<p class="magick-description">reduce the image to a limited number of color levels per channel.</p> 6345 6346<p>Very low values of <var>levels</var>, e.g., 2, 3, 4, have the most 6347visible effect.</p> 6348 6349<div style="margin: auto;"> 6350 <h3><a class="anchor" id="precision"></a>-precision <var>value</var></h3> 6351</div> 6352 6353<p class="magick-description">set the maximum number of significant digits to be printed.</p> 6354 6355<div style="margin: auto;"> 6356 <h3><a class="anchor" id="preview"></a>-preview <var>type</var></h3> 6357</div> 6358 6359<p class="magick-description">image preview type.</p> 6360 6361<p>Use this option to affect the preview operation of an image (e.g. 6362<code>convert file.png -preview Gamma Preview:gamma.png</code>). Choose from 6363these previews:</p> 6364 6365<pre class="pre-scrollable"><code> 6366AddNoise 6367Blur 6368Brightness 6369Charcoal 6370Despeckle 6371Dull 6372EdgeDetect 6373Gamma 6374Grayscale 6375Hue 6376Implode 6377JPEG 6378OilPaint 6379Quantize 6380Raise 6381ReduceNoise 6382Roll 6383Rotate 6384Saturation 6385Segment 6386Shade 6387Sharpen 6388Shear 6389Solarize 6390Spiff 6391Spread 6392Swirl 6393Threshold 6394Wave 6395</code></pre> 6396 6397<p>To print a complete list of previews, use the <a href="command-line-options.html#list">-list preview</a> option.</p> 6398 6399<p>The default preview is <code>JPEG</code>.</p> 6400 6401<div style="margin: auto;"> 6402 <h3><a class="anchor" id="print"></a>-print <var>string</var></h3> 6403</div> 6404 6405<p class="magick-description">interpret string and print to console.</p> 6406 6407<div style="margin: auto;"> 6408 <h3><a class="anchor" id="process"></a>-process <var>command</var></h3> 6409</div> 6410 6411<p class="magick-description">process the image with a custom image filter.</p> 6412 6413<p>The command arguments has the form <code>"module arg1 arg2 arg3 ... 6414argN"</code> where <code>module</code> is the name of the module to invoke (e.g. 6415"Analyze") and arg1 arg2 arg3 ... argN are an arbitrary number of arguments to 6416pass to the process module.</p> 6417 6418<div style="margin: auto;"> 6419 <h3><a class="anchor" id="profile"></a>-profile <var>filename</var><br/> 6420 +profile <var>profile_name</var></h3> 6421</div> 6422 6423<p class="magick-description">Manage ICM, IPTC, or generic profiles in an image.</p> 6424 6425<p>Using <a href="command-line-options.html#profile">-profile</a> <var>filename</var> adds an 6426ICM (ICC color management), IPTC (newswire information), or a generic profile 6427to the image.</p> 6428 6429<p>Use <a href="command-line-options.html#profile">+profile <var>profile_name</var></a> to 6430remove the indicated profile. ImageMagick uses standard filename globbing, so 6431wildcard expressions may be used to remove more than one profile. Here we 6432remove all profiles from the image except for the XMP profile: <code>+profile 6433"!xmp,*"</code>. </p> 6434 6435<p>Use <code>identify -verbose</code> to find out which profiles are in the 6436image file. Use <a href="command-line-options.html#strip">-strip</a> to remove all profiles (and 6437comments).</p> 6438 6439<p>To extract a profile, the <a href="command-line-options.html#profile">-profile</a> option is not 6440used. Instead, simply write the file to an image format such as <var>APP1, 8BIM, ICM,</var> or <var>IPTC</var>.</p> 6441 6442<p>For example, to extract the Exif data (which is stored in JPEG files in the 6443<var>APP1</var> profile), use.</p> 6444 6445<pre class="highlight"><code>convert cockatoo.jpg profile.exif 6446</code></pre> 6447 6448<p>It is important to note that results may depend on whether or not the 6449original image already has an included profile. Also, keep in mind that <a 6450href="command-line-options.html#profile">-profile</a> is an "operator" (as opposed to a "setting") and 6451therefore a conversion is made each time it is encountered, in order, in the 6452command-line. For instance, in the following example, if the original image is 6453CMYK with profile, a CMYK-CMYK-RGB conversion results.</p> 6454 6455<pre class="highlight"><code>convert CMYK.tif -profile "CMYK.icc" -profile "RGB.icc" RGB.tiff 6456</code></pre> 6457 6458<p>Furthermore, since ICC profiles are not necessarily symmetric, extra 6459conversion steps can yield unwanted results. CMYK profiles are often very 6460asymmetric since they involve 3−>4 and 4−>3 channel mapping. 6461</p> 6462 6463<div style="margin: auto;"> 6464 <h3><a class="anchor" id="quality"></a>-quality <var>value</var></h3> 6465</div> 6466 6467<p class="magick-description">JPEG/MIFF/PNG compression level.</p> 6468 6469<p>For the JPEG and MPEG image formats, quality is 1 (lowest image quality and 6470highest compression) to 100 (best quality but least effective compression). 6471The default is to use the estimated quality of your input image if it can 6472be determined, otherwise 92. When the quality is greater than 90, then the 6473chroma channels are not downsampled. 6474Use the <a href="command-line-options.html#sampling-factor">-sampling-factor</a> option to specify the 6475factors for chroma downsampling.</p> 6476 6477<p>For the JPEG-2000 image format, quality is mapped using a non-linear 6478equation to the compression ratio required by the Jasper library. This 6479non-linear equation is intended to loosely approximate the quality provided by 6480the JPEG v1 format. The default quality value 100, a request for non-lossy 6481compression. A quality of 75 results in a request for 16:1 compression.</p> 6482 6483<p>For the MNG and PNG image formats, the quality value sets the zlib 6484compression level (quality / 10) and filter-type (quality % 10). The default 6485PNG "quality" is 75, which means compression level 7 with adaptive PNG 6486filtering, unless the image has a color map, in which case it means 6487compression level 7 with no PNG filtering.</p> 6488 6489<p>For compression level 0 (quality value less than 10), the Huffman-only 6490strategy is used, which is fastest but not necessarily the worst 6491compression.</p> 6492 6493<p>If filter-type is 4 or less, the specified PNG filter-type is used for 6494all scanlines:</p> 6495 6496<dl class="row"> 6497<dt class="col-md-4">0</dt><dd class="col-md-8">none</dd> 6498<dt class="col-md-4">1</dt><dd class="col-md-8">sub</dd> 6499<dt class="col-md-4">2</dt><dd class="col-md-8">up</dd> 6500<dt class="col-md-4">3</dt><dd class="col-md-8">average</dd> 6501<dt class="col-md-4">4</dt><dd class="col-md-8">Paeth</dd> 6502</dl> 6503 6504<p>If filter-type is 5, adaptive filtering is used when quality is greater 6505than 50 and the image does not have a color map, otherwise no filtering is 6506used.</p> 6507 6508<p>If filter-type is 6, adaptive filtering 6509with <var>minimum-sum-of-absolute-values</var> is used.</p> 6510 6511<p>Only if the output is MNG, if filter-type is 7, the LOCO color 6512transformation (intrapixel differencing) and adaptive filtering 6513with <var>minimum-sum-of-absolute-values</var> are used.</p> 6514 6515<p>If the filter-type is 8 the zlib Z_RLE compression strategy (or the 6516Z_HUFFMAN_ONLY strategy, when compression level is 0) is used with 6517adaptive PNG filtering.</p> 6518 6519<p>If the filter-type is 9 the zlib Z_RLE compression strategy (or the 6520Z_HUFFMAN_ONLY strategy, when compression level is 0) is used with 6521no PNG filtering.</p> 6522 6523<p>The quality setting has no effect on the appearance or signature of PNG 6524and MNG images, since the compression is always lossless.</p> 6525 6526<p>Not all combinations of compression level, strategy, and PNG filter type 6527can be obtained using the -quality option. For more precise control, 6528you can use the PNG:compression-level=N, PNG:compression-strategy=N, and 6529PNG:compression-filter=N defines, respectively, instead. 6530See <a href="command-line-options.html#define">-define</a>. Values from the defines take precedence 6531over values from the -quality option.</p> 6532 6533<p>For further information, see 6534the <a href="http://www.w3.org/pub/WWW/TR">PNG</a> specification.</p> 6535 6536<p>For the MIFF and TIFF image formats, quality/10 is the <a href="command-line-options.html#compress">Zip/BZip</a> compression level, which is 0 (worst but fastest compression) to 9 (best but slowest). It has no effect on the image appearance, since the compression is always lossless.</p> 6537 6538<p>For the BPG image format, quality/2 is the actual BPG compression level (range from 0 to 51).</p> 6539 6540<div style="margin: auto;"> 6541 <h3><a class="anchor" id="quantize"></a>-quantize <var>colorspace</var></h3> 6542</div> 6543 6544<p class="magick-description">reduce colors using this colorspace.</p> 6545 6546<p>This setting defines the colorspace used to sort out and reduce the number 6547of colors needed by an image (for later dithering) by operators such as <a 6548href="command-line-options.html#colors" >-colors</a>, Note that color reduction also happens 6549automatically when saving images to color-limited image file formats, such as 6550GIF, and PNG8.</p> 6551 6552 6553<div style="margin: auto;"> 6554 <h3><a class="anchor" id="quiet"></a>-quiet</h3> 6555</div> 6556 6557<p class="magick-description">suppress all warning messages. Error messages are still reported.</p> 6558 6559<div style="margin: auto;"> 6560 <h3><a class="anchor" id="radial-blur"></a>-radial-blur <var>angle</var></h3> 6561</div> 6562 6563<p class="magick-description">Blur around the center of the image.</p> 6564 6565<p>Note that this is actually a rotational blur rather than a radial and as 6566such actually mis-named. </p> 6567 6568<p>The <a href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting will determine how 6569pixels which are outside the image proper are blurred into the final result. 6570</p> 6571 6572 6573<div style="margin: auto;"> 6574 <h3><a class="anchor" id="raise"></a>-raise <var>thickness</var></h3> 6575</div> 6576 6577<p class="magick-description">Lighten or darken image edges.</p> 6578 6579<p>This will create a 3-D effect. Use <a href="command-line-options.html#raise">-raise</a> to create 6580a raised effect, otherwise use <a href="command-line-options.html#raise">+raise</a>. </p> 6581 6582<p>Unlike the similar <a href="command-line-options.html#frame">-frame</a> option, <a 6583href="command-line-options.html#raise">-raise</a> does not alter the dimensions of the image.</p> 6584 6585<div style="margin: auto;"> 6586 <h3><a class="anchor" id="random-threshold"></a>-random-threshold <var>low</var>x<var>high</var></h3> 6587</div> 6588 6589<p class="magick-description">Apply a random threshold to the image.</p> 6590 6591<div style="margin: auto;"> 6592 <h3><a class="anchor" id="range-threshold"></a>-range-threshold <var>low-black</var>,<var>low-white</var>,<var>high-white</var>,<var>high-black</var></h3> 6593</div> 6594 6595<p class="magick-description">Perform either hard or soft thresholding within some range of values in an image.</p> 6596 6597<div style="margin: auto;"> 6598 <h3><a class="anchor" id="read-mask"></a>-read-mask 6599<var>filename</var></h3> 6600</div> 6601 6602<p class="magick-description">Prevent updates to image pixels specified by the mask.</p> 6603 6604<p>This the same as using a mask used for composite masking operations, with 6605grayscale values causing blended updates of the image the mask is attached to. 6606</p> 6607 6608<p>Use <a href="command-line-options.html#read-mask">+read-mask</a> to remove the mask from images.</p> 6609 6610<p>Also see <a href="command-line-options.html#clip-mask">-clip-mask</a> which work in the same way, 6611but with strict boolean masking. </p> 6612 6613<div style="margin: auto;"> 6614 <h3><a class="anchor" id="red-primary"></a>-red-primary <var>x,y</var></h3> 6615</div> 6616 6617<p class="magick-description">Set the red chromaticity primary point.</p> 6618 6619<div style="margin: auto;"> 6620 <h3><a class="anchor" id="regard-warnings"></a>-regard-warnings</h3> 6621</div> 6622 6623<p class="magick-description">Pay attention to warning messages.</p> 6624 6625<p>This option causes some warnings in some image formats to be treated 6626as errors. </p> 6627 6628<div style="margin: auto;"> 6629 <h3><a class="anchor" id="remap"></a>-remap <var>filename</var></h3> 6630</div> 6631 6632<p class="magick-description">Reduce the number of colors in an image to the colors used by this image.</p> 6633 6634<p>If the <a href="command-line-options.html#dither">-dither</a> setting is enabled (the default) then 6635the given colors are dithered over the image as necessary, otherwise the closest 6636color (in RGB colorspace) is selected to replace that pixel in the image. </p> 6637 6638<p>As a side effect of applying a <a href="command-line-options.html#remap">-remap</a> of colors across all 6639images in the current image sequence, all the images will have the same color 6640table. That means that when saved to a file format such as GIF, it will use 6641that color table as a single common or global color table, for all the images, 6642without requiring extra local color tables. </p> 6643 6644<p>Use <a href="command-line-options.html#remap">+remap</a> to reduce all images in the current image 6645sequence to use a common color map over all the images. This equivalent to 6646appending all the images together (without extra background colors) and color 6647reducing those images using <a href="command-line-options.html#colors">-colors</a> with a 256 color 6648limit, then <a href="command-line-options.html#remap">-remap</a> those colors over the original list of 6649images. This ensures all the images follow a single color map. </p> 6650 6651<p>If the number of colors over all the images is less than 256, then <a 6652href="command-line-options.html#remap">+remap</a> should not perform any color reduction or dithering, as 6653no color changes are needed. In that case, its only effect is to force the use 6654of a global color table. This recommended after using either <a 6655href="command-line-options.html#colors">-colors</a> or <a href="command-line-options.html#ordered-dither">-ordered-dither</a> to 6656reduce the number of colors in an animated image sequence. </p> 6657 6658<p>Note, the remap image colormap has at most 8-bits of precision. Deeper color maps are automagically coalesced with other colors to meet this requirement.</p> 6659 6660<div style="margin: auto;"> 6661 <h3><a class="anchor" id="region"></a>-region <var>geometry</var></h3> 6662</div> 6663 6664<p class="magick-description">Set a region in which subsequent operations apply.</p> 6665 6666<p>The <var>x</var> and <var>y</var> offsets are treated 6667in the same manner as in <a href="command-line-options.html#crop">-crop</a>.</p> 6668 6669<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 6670 6671<p>Use <code>+region</code> to remove any previously set regions.</p> 6672 6673<div style="margin: auto;"> 6674 <h3><a class="anchor" id="remote"></a>-remote</h3> 6675</div> 6676 6677<p class="magick-description">perform a remote operation.</p> 6678 6679<p>The only command recognized is the name of an image file to load.</p> 6680 6681<p>If you have more than one <a href="display.html">display</a> application 6682running simultaneously, use the <a href="command-line-options.html#window"> window</a> option to 6683specify which application to control.</p> 6684 6685<div style="margin: auto;"> 6686 <h3><a class="anchor" id="render"></a>-render</h3> 6687</div> 6688 6689<p class="magick-description">render vector operations.</p> 6690 6691<p>Use <a href="command-line-options.html#render">+render</a> to turn off rendering vector operations. 6692This useful when saving the result to vector formats such as MVG or SVG.</p> 6693 6694<div style="margin: auto;"> 6695<h3><a class="anchor" id="repage"></a>-repage <var>geometry</var></h3> 6696</div> 6697 6698<p class="magick-description">Adjust the canvas and offset information of the image.</p> 6699 6700<p>This option is like <a href="command-line-options.html#page">-page</a> but acts as an image operator 6701rather than a setting. You can separately set the canvas size or the offset 6702of the image on that canvas by only providing those components. </p> 6703 6704<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 6705 6706<p>If a <code>!</code> flag is given the offset given is added to the existing 6707offset to move the image relative to its previous position. This useful for 6708animation sequences. </p> 6709 6710<p>A given a canvas size of zero such as '<code>0x0</code>' forces it to 6711recalculate the canvas size so the image (at its current offset) will appear 6712completely on that canvas (unless it has a negative offset).</p> 6713 6714<p>Use <a href="command-line-options.html#repage">+repage</a> to completely remove/reset the virtual 6715canvas meta-data from the images. </p> 6716 6717<p>The <a href="command-line-options.html#set">-set</a> '<code>page</code>' option can be used to 6718directly assign virtual canvas meta-data. </p> 6719 6720 6721<div style="margin: auto;"> 6722 <h3><a class="anchor" id="resample"></a>-resample <var>horizontal</var>x<var>vertical</var></h3> 6723</div> 6724 6725<p class="magick-description">Resample image to specified horizontal and vertical resolution.</p> 6726 6727<p>Resize the image so that its rendered size remains the same as the original 6728at the specified target resolution. For example, if a 300 DPI image renders at 67293 inches by 2 inches on a 300 DPI device, when the image has been resampled to 673072 DPI, it will render at 3 inches by 2 inches on a 72 DPI device. Note that 6731only a small number of image formats (e.g. JPEG, PNG, and TIFF) are capable of 6732storing the image resolution. For formats which do not support an image 6733resolution, the original resolution of the image must be specified via <a 6734href="command-line-options.html#density">-density</a> on the command line prior to specifying the 6735resample resolution.</p> 6736 6737<p>Note that Photoshop stores and obtains image resolution from a proprietary 6738embedded profile. If this profile exists in the image, then Photoshop will 6739continue to treat the image using its former resolution, ignoring the image 6740resolution specified in the standard file header.</p> 6741 6742<div style="margin: auto;"> 6743 <h3><a class="anchor" id="resize"></a>-resize <var>geometry</var></h3> 6744</div> 6745 6746<p class="magick-description">Resize an image.</p> 6747 6748<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. Offsets, if present in the geometry string, are 6749ignored, and the <a href="command-line-options.html#gravity">-gravity</a> option has no effect.</p> 6750 6751<p>If the <a href="command-line-options.html#filter">-filter</a> option 6752or <code>-define filter:option=value</code> precedes the <a 6753href="command-line-options.html#resize">-resize</a> option, the image is resized with the specified 6754filter.</p> 6755 6756<p>Many image processing algorithms assume your image is in a linear-light 6757coding. If your image is gamma-corrected, you can remove the nonlinear gamma 6758correction, apply the transform, then restore it like this:</p> 6759 6760<pre class="highlight"><code>convert portrait.jpg -gamma .45455 -resize 25% -gamma 2.2 \ 6761 -quality 92 passport.jpg 6762</code></pre> 6763 6764<p>Note, some resampling functions are damped oscillations in approximation of a Sinc function. As such, you may get negative lobes if your release of ImageMagick is HDRI-enabled. To eliminate them, add <a href="command-line-options.html#clamp">-clamp</a> to your command-line.</p> 6765 6766<div style="margin: auto;"> 6767 <h3><a class="anchor" id="respect-parentheses"></a>-respect-parentheses</h3> 6768</div> 6769 6770<p class="magick-description">settings remain in effect until parenthesis boundary.</p> 6771 6772<div style="margin: auto;"> 6773 <h3><a class="anchor" id="reverse"></a>-reverse</h3> 6774</div> 6775 6776<p class="magick-description">Reverse the order of images in the current image list.</p> 6777 6778 6779<div style="margin: auto;"> 6780 <h3><a class="anchor" id="roll"></a>-roll {<var>+-</var>}<var>x</var>{<var>+-</var>}<var>y</var></h3> 6781</div> 6782 6783<p class="magick-description">roll an image vertically or horizontally by the amount given.</p> 6784 6785<p>A negative <var>x</var> offset rolls the image right-to-left. 6786A negative <var>y</var> offset rolls the image bottom-to-top.</p> 6787 6788 6789<div style="margin: auto;"> 6790 <h3><a class="anchor" id="rotate"></a>-rotate <var>degrees</var>{<var><</var>}{<var>></var>}</h3> 6791</div> 6792 6793<p class="magick-description">Apply Paeth image rotation (using shear operations) to the image.</p> 6794 6795<p>Use <code>></code> to rotate the image only if its width exceeds the 6796height. <code><</code> rotates the image <var>only</var> if its width is less 6797than the height. For example, if you specify <code>-rotate "-90>"</code> and 6798the image size is 480x640, the image is not rotated. However, if the image is 6799640x480, it is rotated by -90 degrees. If you use <code>></code> or 6800<code><</code>, enclose it in quotation marks to prevent it from being 6801misinterpreted as a file redirection.</p> 6802 6803<p>Empty triangles in the corners, left over from rotating the image, are 6804filled with the <code>background</code> color. </p> 6805 6806<p>See also the <a href="command-line-options.html#distort">-distort</a> operator and specifically the 6807'<code>ScaleRotateTranslate</code>' distort method. </p> 6808 6809 6810<div style="margin: auto;"> 6811 <h3><a class="anchor" id="sample"></a>-sample <var>geometry</var></h3> 6812</div> 6813 6814<p class="magick-description">minify / magnify the image with pixel subsampling and pixel replication, respectively.</p> 6815 6816<p>Change the image size simply by directly sampling the pixels original 6817from the image. When magnifying, pixels are replicated in blocks. When 6818minifying, pixels are sub-sampled (i.e., some rows and columns are skipped 6819over). </p> 6820 6821<p>The results are thus equivalent to using <a href="command-line-options.html#resize">-resize</a> with 6822a <a href="command-line-options.html#filter">-filter</a> setting of <code>point</code> (nearest 6823neighbor), though <a href="command-line-options.html#sample">-sample</a> is a lot faster, as it 6824avoids all the filter processing of the image. As such it completely ignores 6825the current <a href="command-line-options.html#filter">-filter</a> setting. </p> 6826 6827<p>The key feature of the <a href="command-line-options.html#sample">-sample</a> is that no new colors 6828will be added to the resulting image, though some colors may disappear. </p> 6829 6830<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. Offsets, if present in the geometry string, are 6831ignored, unlike <a href="command-line-options.html#resize">-resize</a>. </p> 6832 6833 6834<p>The actual sampling point is the middle of the sub-region being sampled. 6835As such a single pixel sampling of an image will take the middle pixel, (or 6836top-left-middle if image has even dimensions). However the <a 6837href="command-line-options.html#define">-define</a> '<code>sample:offset</code>' can be set to modify 6838this position some other location within each sub-region being sampled, as 6839a percentage offset.</p> 6840 6841<p>By default this value is '<code>50</code>' for the midpoint, but could be set 6842to '<code>0</code>' for top-left, '<code>100</code>' for bottom-right, or with 6843separate X and Y offsets such as '<code>0x50</code>' for left-middle edge of 6844sampling sub-region.</p> 6845 6846 6847<div style="margin: auto;"> 6848 <h3><a class="anchor" id="sampling-factor"></a>-sampling-factor <var>horizontal-factor</var>x<var>vertical-factor</var></h3> 6849</div> 6850 6851<p class="magick-description">sampling factors used by JPEG or MPEG-2 encoder and YUV decoder/encoder.</p> 6852 6853<p>This option specifies the sampling factors to be used by the JPEG encoder 6854for chroma downsampling. If this option is omitted, the JPEG library will use 6855its own default values. When reading or writing the YUV format and when 6856writing the M2V (MPEG-2) format, use <a 6857href="command-line-options.html#sampling-factor">-sampling-factor 2x1</a> or <a 6858href="command-line-options.html#sampling-factor">-sampling-factor 4:2:2</a> to specify the 4:2:2 6859downsampling method.</p> 6860 6861<div style="margin: auto;"> 6862 <h3><a class="anchor" id="scale"></a>-scale <var>geometry</var></h3> 6863</div> 6864 6865<p class="magick-description">minify / magnify the image with pixel block averaging and pixel replication, respectively.</p> 6866 6867<p>Change the image size simply by replacing pixels by averaging pixels 6868together when minifying, or replacing pixels when magnifying. </p> 6869 6870<p>The results are thus equivalent to using <a href="command-line-options.html#resize">-resize</a> with 6871a <a href="command-line-options.html#filter">-filter</a> setting of <code>box</code>. Though it is a lot 6872faster, as it avoids all the filter processing of the image. As such it 6873completely ignores the current <a href="command-line-options.html#filter">-filter</a> setting. </p> 6874 6875<p>If when shrinking (minifying) images the original image is some integer 6876multiple of the new image size, the number of pixels averaged together to 6877produce the new pixel color is the same across the whole image. This is 6878a special case known as 'binning' and is often used as a method of reducing 6879noise in image such as those generated by digital cameras, especially in low 6880light conditions. </p> 6881 6882 6883<div style="margin: auto;"> 6884 <h3><a class="anchor" id="scene"></a>-scene <var>value</var></h3> 6885</div> 6886 6887<p class="magick-description">set scene number.</p> 6888 6889<p>This option sets the scene number of an image or the first image in an image sequence.</p> 6890 6891<div style="margin: auto;"> 6892 <h3><a class="anchor" id="screen"></a>-screen</h3> 6893</div> 6894 6895<p class="magick-description">specify the screen to capture.</p> 6896 6897<p>This option indicates that the GetImage request used to obtain the image 6898should be done on the root window, rather than directly on the specified 6899window. In this way, you can obtain pieces of other windows that overlap the 6900specified window, and more importantly, you can capture menus or other popups 6901that are independent windows but appear over the specified window.</p> 6902 6903<div style="margin: auto;"> 6904 <h3><a class="anchor" id="seed"></a>-seed</h3> 6905</div> 6906 6907<p class="magick-description">seed a new sequence of pseudo-random numbers</p> 6908 6909<div style="margin: auto;"> 6910 <h3><a class="anchor" id="segment"></a>-segment <var>cluster-threshold</var>x<var>smoothing-threshold</var></h3> 6911</div> 6912 6913<p class="magick-description">segment the colors of an image.</p> 6914 6915<p>Segment an image by analyzing the histograms of the color components and 6916identifying units that are homogeneous with the fuzzy c-means technique. This 6917is part of the ImageMagick color quantization routines. </p> 6918 6919<p>Specify <var>cluster threshold</var> as the number of pixels in 6920each cluster that must exceed the cluster threshold to be considered valid. 6921<var>Smoothing threshold</var> eliminates noise in the second 6922derivative of the histogram. As the value is increased, you can expect 6923a smoother second derivative. The default is 1.5.</p> 6924 6925<p>If the <a href="command-line-options.html#verbose">-verbose</a> setting is defined, a detailed report 6926of the color clusters is returned.</p> 6927 6928 6929<div style="margin: auto;"> 6930 <h3><a class="anchor" id="selective-blur"></a>-selective-blur <var>radius</var><br />-selective-blur <var>radius</var>x<var>sigma</var>{<var>+threshold</var>}</h3> 6931</div> 6932 6933<p class="magick-description">Selectively blur pixels within a contrast threshold.</p> 6934 6935<p>Blurs those pixels that are less than or equal to the threshold in 6936contrast. The threshold may be expressed as a fraction of <var>QuantumRange</var> or as a percentage.</p> 6937 6938<div style="margin: auto;"> 6939 <h3><a class="anchor" id="separate"></a>-separate</h3> 6940</div> 6941 6942<p class="magick-description">separate an image channel into a grayscale image. Specify the channel with <a href="command-line-options.html#channel">-channel</a>.</p> 6943 6944<div style="margin: auto;"> 6945 <h3><a class="anchor" id="sepia-tone"></a>-sepia-tone <var>percent-threshold</var></h3> 6946</div> 6947 6948<p class="magick-description">simulate a sepia-toned photo.</p> 6949 6950<p>Specify <var>threshold</var> as the percent threshold of the intensity (0 - 99.9%).</p> 6951 6952<p>This option applies a special effect to the image, similar to the effect 6953achieved in a photo darkroom by sepia toning. Threshold ranges from 0 to <var>QuantumRange</var> and is a measure of the extent of the sepia 6954toning. A threshold of 80% is a good starting point for a reasonable 6955tone.</p> 6956 6957 6958 6959<div style="margin: auto;"> 6960 <h3><a class="anchor" id="set"></a>-set <var>key value</var></h3> 6961 <h3>+set <var>key</var></h3> 6962</div> 6963 6964<p class="magick-description">sets image attributes and properties for images in the current image sequence.</p> 6965 6966<p>This will assign (or modify) specific settings attached to all the images 6967in the current image sequence. Using the <a href="command-line-options.html#set">+set</a> form of the 6968option will either remove, or reset that setting to a default state, as 6969appropriate. </p> 6970 6971<p>For example, it will modify specific well known image meta-data 6972'attributes' such as those normally overridden by: the options <a 6973href="command-line-options.html#delay" >-delay</a>, <a href="command-line-options.html#dispose" >-dispose</a>, and <a 6974href="command-line-options.html#page" >-page</a>, <a href="command-line-options.html#colorspace" >-colorspace</a>; generally 6975assigned before the image is read in, by using a <var>key</var> of 6976the same name. </p> 6977 6978<p>If the given <var>key</var> does not match a specific known 6979'attribute ', such as shown above, the setting is stored as a free form 6980'property' string. Such settings are listed in <a href="command-line-options.html#verbose" 6981>-verbose</a> information ("<code>info:</code>" output format) as "Properties". 6982</p> 6983 6984<p>This includes string 'properties' that are set by and assigned to images 6985using the options <a href="command-line-options.html#comment" >-comment</a>, <a href="command-line-options.html#label" 6986>-label</a>, <a href="command-line-options.html#caption" >-caption</a>. These options actually assign 6987a global 'artifact' which are automatically assigned (and any <a href="../www/escape.html" >Format Percent 6988Escapes</a> expanded) to images as they are read in. For example:</p> 6989 6990<pre class="highlight"><code>-> convert rose: -set comment 'Rose is a rose is a rose is a rose' rose.png 6991identify -format %c rose.png 6992Rose is a rose is a rose is a rose 6993</code></pre> 6994 6995<p>The set value can also make use of <a href="../www/escape.html" >Format and Print Image 6996Properties</a> in the defined value. For example:</p> 6997 6998<pre class="highlight"><code>-> convert rose: -set origsize '%wx%h' -resize 50% \ 6999 -format 'Old size = %[origsize] New size = %wx%h' info: 7000Old size = 70x46 New size = 35x23 7001</code></pre> 7002 7003<p>Other well known 'properties' that are available include: 7004'<code>date:create</code>' and '<code>date:modify</code>' and 7005'<code>signature</code>'. </p> 7006 7007<p>The <a href="command-line-options.html#repage">-repage</a> operator will also allow you to modify 7008the '<code>page</code>' attribute of an image for images already in memory (also 7009see <a href="command-line-options.html#repage">-page</a>). However it is designed to provide a finer 7010control of the sub-parts of this 'attribute'. The <a href="command-line-options.html#set">-set page</a> 7011option will only provide a direct, unmodified assignment of '<code>page</code>' 7012attribute. </p> 7013 7014<p>This option can also associate a colorspace or profile with your image. 7015For example,</p> 7016 7017<pre class="highlight"><code>convert image.psd -set profile ISOcoated_v2_eci.icc image-icc.psd 7018</code></pre> 7019 7020<p>Some 'properties' must be defined in a specific way to be used. For 7021example only 'properties' prefixed with "<code>filename:</code>" can be used to 7022modify the output filename of an image. For example</p> 7023 7024<pre class="highlight"><code>convert rose: -set filename:mysize '%wx%h' 'rose_%[filename:mysize].png' 7025</code></pre> 7026 7027<p>If the setting value is prefixed with "<code>option:</code>" the setting will 7028be saved as a global "Artifact" exactly as if it was set using the <a 7029href="command-line-options.html#define" >-define</a> option. As such settings are global in scope, they 7030can be used to pass 'attributes' and 'properties' of one specific image, 7031in a way that allows you to use them in a completely different image, even if 7032the original image has long since been modified or destroyed. For example: </p> 7033 7034<pre class="highlight"><code>convert rose: -set option:rosesize '%wx%h' -delete 0 \ 7035 label:'%[rosesize]' label_size_of_rose.gif" 7036</code></pre> 7037 7038<p>Note that <a href="../www/escape.html" >Format Percent Escapes</a> will only match 7039a 'artifact' if the given <var>key</var> does not match an existing 7040'attribute' or 'property'. </p> 7041 7042<p>You can set the attributes of the image registry by prefixing the value 7043with <code>registry:</code>.</p> 7044 7045<p>The <a href="command-line-options.html#set">-set profile</a> option can also be used to inject 7046previously-formatted ancillary chunks into the output PNG file, using 7047the commandline option as shown below or by setting the profile via a 7048programming interface:</p> 7049 7050<pre class="highlight"><code>convert in.png -set profile PNG-chunk-x:<filename> out.png 7051</code></pre> 7052 7053<p>where <var>x</var> is a location flag and 7054<var>filename</var> is a file containing the chunk 7055name in the first 4 bytes, then a colon (":"), followed by the chunk data. 7056This encoder will compute the chunk length and CRC, so those must not 7057be included in the file.</p> 7058 7059<p>"x" can be "b" (before PLTE), "m" (middle, i.e., between PLTE and IDAT), 7060or "e" (end, i.e., after IDAT). If you want to write multiple chunks 7061of the same type, then add a short unique string after the "x" to prevent 7062subsequent profiles from overwriting the preceding ones, e.g.,</p> 7063 7064 7065<pre class="highlight"><code>convert in.png -set profile PNG-chunk-b01:file01 \ 7066 -profile PNG-chunk-b02:file02 out.png 7067</code></pre> 7068 7069<div style="margin: auto;"> 7070 <h3><a class="anchor" id="shade"></a>-shade <var>azimuth</var>x<var>elevation</var></h3> 7071</div> 7072 7073<p class="magick-description">shade the image using a distant light source.</p> 7074 7075<p>Specify <var>azimuth</var> and <var>elevation</var> as 7076the position of the light source. Use <a href="command-line-options.html#shade">+shade</a> to return 7077the shading results as a grayscale image.</p> 7078 7079<div style="margin: auto;"> 7080 <h3><a class="anchor" id="shadow"></a>-shadow <var>percent-opacity</var>{x<var>sigma</var>}{<var>+-</var>}<var>x</var>{<var>+-</var>}<var>y</var>{<var>%</var>}</h3> 7081</div> 7082 7083<p class="magick-description">simulate an image shadow.</p> 7084 7085<div style="margin: auto;"> 7086 <h3><a 7087id="shared-memory"></a>-shared-memory</h3> 7088</div> 7089 7090<p class="magick-description">use shared memory.</p> 7091 7092<p>This option specifies whether the utility should attempt to use shared 7093memory for pixmaps. ImageMagick must be compiled with shared memory support, 7094and the display must support the <var>MIT-SHM</var> extension. 7095Otherwise, this option is ignored. The default is <code>True</code>.</p> 7096 7097<div style="margin: auto;"> 7098 <h3><a class="anchor" id="sharpen"></a>-sharpen <var>radius</var><br />-sharpen <var>radius</var>x<var>sigma</var></h3> 7099</div> 7100 7101<p class="magick-description">sharpen the image.</p> 7102 7103<p>Use a Gaussian operator of the given radius and standard deviation (sigma).</p> 7104 7105<div style="margin: auto;"> 7106 <h3><a class="anchor" id="shave"></a>-shave <var>geometry</var></h3> 7107</div> 7108 7109<p class="magick-description">Shave pixels from the image edges.</p> 7110 7111<p>The <var>size</var> portion of the <var>geometry</var> 7112argument specifies the width of the region to be removed from both sides of 7113the image and the height of the regions to be removed from top and bottom. 7114Offsets are ignored.</p> 7115 7116<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 7117 7118<div style="margin: auto;"> 7119 <h3><a class="anchor" id="shear"></a>-shear <var>Xdegrees</var>[x<var>Ydegrees</var>]</h3> 7120</div> 7121 7122<p class="magick-description">Shear the image along the x-axis and/or y-axis.</p> 7123 7124<p>The shear angles may be positive, negative, or zero. When <var>Ydegrees</var> is omitted it defaults to <var>Xdegrees</var>. When both angles are 7125given, the horizontal component of the shear is performed before the vertical 7126component.</p> 7127 7128<p>Shearing slides one edge of an image along the x-axis or y-axis (i.e., 7129horizontally or vertically, respectively),creating a parallelogram. The amount 7130of each is controlled by the respective shear angle. For horizontal shears, 7131<var>Xdegrees</var> is measured clockwise relative to "up" (the 7132negative y-axis), sliding the top edge to the right when 0°<<var>Xdegrees</var><90° and to the left when 90°<<var>Xdegrees</var><180°. For vertical shears <var>Ydegrees</var> is measured clockwise relative to "right" (the 7133positive x-axis), sliding the right edge down when 0°<<var>Ydegrees</var><90° and up when 90°<<var>Ydegrees</var><180°.</p> 7134 7135<p>Empty triangles left over from shearing the image are filled with the color 7136defined by the <a href="command-line-options.html#fill">-background</a> option. The color is specified 7137using the format described under the <a href="command-line-options.html#fill">-fill</a> option.</p> 7138 7139<p>The horizontal shear is performed before the vertical part. This is 7140important to note, since horizontal and vertical shears do not 7141<var>commute</var>, i.e., the order matters in a sequence of shears. For 7142example, the following two commands are not equivalent.</p> 7143 7144<pre class="highlight"><code>convert logo: -shear 20x0 -shear 0x60 logo-sheared.png 7145convert logo: -shear 0x60 -shear 20x0 logo-sheared.png 7146</code></pre> 7147 7148<p>The first of the two commands above is equivalent to the following, except 7149for the amount of empty space created; the command that follows generates 7150a smaller image, and so is a better choice in terms of time and space.</p> 7151 7152<pre class="highlight"><code>convert logo: -shear 20x60 logo-sheared.png 7153</code></pre> 7154 7155<div style="margin: auto;"> 7156 <h3><a class="anchor" id="sigmoidal-contrast"></a>-sigmoidal-contrast <var>contrast</var>x<var>mid-point</var></h3> 7157</div> 7158 7159<p class="magick-description">increase the contrast without saturating highlights or shadows.</p> 7160 7161<p>Increase the contrast of the image using a sigmoidal transfer function 7162without saturating highlights or shadows. <var>Contrast</var> 7163indicates how much to increase the contrast. For example, 0 is none, 3 is 7164typical and 20 is a lot. 7165</p> 7166 7167<p>The <var>mid-point</var> indicates where the maximum change 7168'slope' in contrast should fall in the resultant image (0 is white; 50% is 7169middle-gray; 100% is black). </p> 7170 7171<p>By default the image contrast is increased, use <var>+sigmoidal-contrast</var> to decrease the contrast.</p> 7172 7173<p>To achieve the equivalent of a sigmoidal brightness change (similar to 7174a gamma adjustment), you would use <var>-sigmoidal-contrast 7175{brightness}x0%</var> to increase brightness and <var>+sigmoidal-contrast {brightness}x0%</var> to decrease brightness. 7176Note the use of '0' fo rthe mid-point of the sigmoidal curve. </p> 7177 7178<p>Using a very high <var>contrast</var> will produce a sort of 7179'smoothed thresholding' of the image. Not as sharp (with high aliasing 7180effects) of a true threshold, but with tapered gray-levels around the threshold 7181<var>mid-point</var>. </p> 7182 7183<div style="margin: auto;"> 7184 <h3><a class="anchor" id="silent"></a>-silent</h3> 7185 7186 7187</div> 7188 7189<p class="magick-description">operate silently. This option is only used 7190by the <a href="import.html">import</a> tool.</p> 7191 7192<div style="margin: auto;"> 7193 <h3><a class="anchor" id="similarity-threshold"></a>-similarity-threshold <var>value</var></h3> 7194</div> 7195 7196<p class="magick-description">minimum RMSE for subimage match.</p> 7197 7198<p>If this setting is used, then the search will stop as soon as it finds a match whose metric is less than or equal to the value. A partially filled second output image will result. Using a value of zero, will cause the search to stop at the first perfect match it finds. If this setting is left off, then the search will proceed to completion or as limited by <var>-dissimilarity-threshold</var>.</p> 7199 7200<div style="margin: auto;"> 7201 <h3><a class="anchor" id="size"></a>-size <var>width</var>[x<var>height</var>][<var>+offset</var>]</h3> 7202</div> 7203 7204<p class="magick-description">set the width and height of the image.</p> 7205 7206<p>Use this option to specify the width and height of raw images whose 7207dimensions are unknown such as <code>GRAY</code>, <code>RGB</code>, or 7208<code>CMYK</code>. In addition to width and height, use <a 7209href="command-line-options.html#size">-size</a> with an offset to skip any header information in the 7210image or tell the number of colors in a <code>MAP</code> image file, (e.g. -size 7211640x512+256).</p> 7212 7213<p>For Photo CD images, choose from these sizes:</p> 7214 7215<pre class="highlight"><code>192x128 7216384x256 7217768x512 72181536x1024 72193072x2048 7220</code></pre> 7221 7222<div style="margin: auto;"> 7223 <h3><a class="anchor" id="sketch"></a>-sketch <var>radius</var><br />-sketch <var>radius</var>x<var>sigma</var>+<var>angle</var></h3> 7224</div> 7225 7226<p class="magick-description">simulate a pencil sketch.</p> 7227 7228<p>Sketch with the given radius, standard deviation (sigma), and angle. The 7229angle given is the angle toward which the image is sketched. That is the 7230direction people would consider the object is coming from. </p> 7231 7232<div style="margin: auto;"> 7233 <h3><a class="anchor" id="smush"></a>-smush <var>offset</var></h3> 7234</div> 7235 7236<p class="magick-description">appends an image sequence together ignoring transparency.</p> 7237 7238<p>Smush is a more flexible version of <a href="command-line-options.html#append">-append</a>, joining the images in the sequence top-to-bottom (<a href="command-line-options.html#smush">-smush</a>) or left-to-right (<a href="command-line-options.html#smush">+smush</a>), with a gap between images according to the specified offset.</p> 7239 7240<p>If the offset is negative, images will overlap by that amount.</p> 7241 7242<p><a href="command-line-options.html#smush">-smush</a> respects <a href="command-line-options.html#gravity">-gravity</a>. Any empty space will be filled with the <a href="command-line-options.html#background">-background</a> color.</p> 7243 7244<p>For zero offset and transparent images, the non-transparent parts of the two images will be aligned as close as possible without overlapping.</p> 7245 7246<div style="margin: auto;"> 7247 <h3><a class="anchor" id="snaps"></a>-snaps <var>value</var></h3> 7248</div> 7249 7250<p class="magick-description">Set the number of screen snapshots.</p> 7251 7252<p>Use this option to grab more than one image from the X server screen, to create an animation sequence.</p> 7253 7254<div style="margin: auto;"> 7255 <h3><a class="anchor" id="solarize"></a>-solarize <var>percent-threshold</var></h3> 7256</div> 7257 7258<p class="magick-description">negate all pixels above the threshold level.</p> 7259 7260<p>Specify <var>factor</var> as the percent threshold of the intensity (0 - 99.9%).</p> 7261 7262<p>This option produces a <var>solarization</var> effect seen when 7263exposing a photographic film to light during the development process.</p> 7264 7265<div style="margin: auto;"> 7266 <h3><a class="anchor" id="sparse-color"></a>-sparse-color <var>method</var> '<var>x</var>,<var>y</var> <var>color</var> ...'</h3> 7267</div> 7268 7269<p class="magick-description"> color the given image using the specified points of color, and filling the other intervening colors using the given methods. </p> 7270 7271 7272<dl class="row"> 7273 <dt class="col-md-4">barycentric</dt> 7274 <dd class="col-md-8">three point triangle of color given 3 points. 7275 Giving only 2 points will form a linear gradient between those points. 7276 The gradient generated extends beyond the triangle created by those 7277 3 points. </dd> 7278 <dt class="col-md-4">bilinear</dt> 7279 <dd class="col-md-8">Like barycentric but for 4 points. Less than 4 points 7280 fall back to barycentric. </dd> 7281 <dt class="col-md-4">voronoi</dt> 7282 <dd class="col-md-8">Simply map each pixel to the to nearest color point 7283 given. The result are polygonal 'cells' of solid color. </dd> 7284 <dt class="col-md-4">manhattan</dt> 7285 <dd class="col-md-8">Like voronoi, but resulting polygonal 'cells' are mapped to a fixed coordinate system.</dd> 7286 <dt class="col-md-4">shepards</dt> 7287 <dd class="col-md-8">Colors points biased on the ratio of inverse distance 7288 squared. Generating spots of color in a sea of the average of 7289 colors. </dd> 7290 <dt class="col-md-4">inverse</dt> 7291 <dd class="col-md-8">Colors points biased on the ratio of inverse distance. 7292 This generates sharper points of color rather than rounded spots of 7293 '<code>shepards</code>' Generating spots of color in a sea of the 7294 average of colors. </dd> 7295</dl> 7296 7297<p>The points are placed according to the images location on the virtual 7298canvas (<a href="command-line-options.html#page" >-page</a> or <a href="command-line-options.html#repage" >-repage</a> 7299offset), and do not actually have to exist on the given image, but may be 7300some point beyond the edge of the image. All points are floating point values. 7301</p> 7302 7303<p>Only the color channels defined by the <a href="command-line-options.html#channel" >-channel</a> are 7304modified, which means that by default matte/alpha transparency channel is not 7305affected. Typically transparency channel is turned off either before or after 7306the operation. </p> 7307 7308<p>Of course if some color points are transparent to generate a transparent 7309gradient, then the image also requires transparency enabled to store the 7310values. </p> 7311 7312<p>All the above methods when given a single point of color will replace all 7313the colors in the image with the color given, regardless of the point. This is 7314logical, and provides an alternative technique to recolor an image to some 7315default value. </p> 7316 7317 7318<div style="margin: auto;"> 7319 <h3><a class="anchor" id="splice"></a>-splice <var>geometry</var></h3> 7320</div> 7321 7322<p class="magick-description">Splice the current background color into the image.</p> 7323 7324<p>This will add rows and columns of the current <a 7325href="command-line-options.html#background">-background</a> color into the given image according to the 7326given <a href="command-line-options.html#gravity">-gravity</a> geometry setting. See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. Essentially <a href="command-line-options.html#splice">-splice</a> will divide the 7327image into four quadrants, separating them by the inserted rows and columns. 7328</p> 7329 7330<p>If a dimension of geometry is zero no rows or columns will be added for that 7331dimension. Similarly using a zero offset with the appropriate <a 7332href="command-line-options.html#gravity">-gravity</a> setting will add rows and columns to the edges of 7333the image, padding the image only along that one edge. Edge padding is what <a 7334href="command-line-options.html#splice">-splice</a> is most commonly used for. </p> 7335 7336<p>If the exact same <var>geometry</var> and <a 7337href="command-line-options.html#gravity">-gravity</a> is later used with <a href="command-line-options.html#chop">-chop</a> the 7338added added all splices removed. </p> 7339 7340<div style="margin: auto;"> 7341 <h3><a class="anchor" id="spread"></a>-spread <var>amount</var></h3> 7342</div> 7343 7344<p class="magick-description">displace image pixels by a random amount.</p> 7345 7346<p>The argument <var>amount</var> defines the size of the 7347neighborhood around each pixel from which to choose a candidate pixel to 7348blend.</p> 7349 7350<p>The lookup is controlled by the <a href="command-line-options.html#interpolate">-interpolate</a> setting.</p> 7351 7352<div style="margin: auto;"> 7353 <h3><a class="anchor" id="statistic"></a>-statistic <var>type</var> <var>geometry</var></h3> 7354</div> 7355 7356<p class="magick-description">replace each pixel with corresponding statistic from the neighborhood.</p> 7357 7358<p>Choose from these statistic types:</p> 7359<dl class="row"> 7360<dt class="col-md-4">Gradient</dt><dd class="col-md-8">maximum difference (max - min) value in neighborhood</dd> 7361<dt class="col-md-4">Maximum</dt><dd class="col-md-8">maximum value per channel in neighborhood</dd> 7362<dt class="col-md-4">Minimum</dt><dd class="col-md-8">minimum value per channel in neighborhood</dd> 7363<dt class="col-md-4">Mean</dt><dd class="col-md-8">average value per channel in neighborhood</dd> 7364<dt class="col-md-4">Median</dt><dd class="col-md-8">median value per channel in neighborhood</dd> 7365<dt class="col-md-4">Mode</dt><dd class="col-md-8">mode (most frequent) value per channel in neighborhood</dd> 7366<dt class="col-md-4">Nonpeak</dt><dd class="col-md-8">value just before or after the median value per channel in neighborhood</dd> 7367<dt class="col-md-4">RMS</dt><dd class="col-md-8">root mean square value per channel in neighborhood</dd> 7368<dt class="col-md-4">StandardDeviation</dt><dd class="col-md-8"> standard deviation value per channel in neighborhood</dd> 7369</dl> 7370 7371<div style="margin: auto;"> 7372 <h3><a class="anchor" id="stegano"></a>-stegano <var>offset</var></h3> 7373</div> 7374 7375<p class="magick-description">hide watermark within an image.</p> 7376 7377<p>Use an offset to start the image hiding some number of pixels from the 7378beginning of the image. Note this offset and the image size. You will need 7379this information to recover the steganographic image (e.g. display -size 7380320x256+35 stegano:image.png).</p> 7381 7382<div style="margin: auto;"> 7383 <h3><a class="anchor" id="stereo"></a>-stereo <var>+x</var>{<var>+y</var>}</h3> 7384</div> 7385 7386<p class="magick-description">composite two images to create a red / cyan stereo anaglyph.</p> 7387 7388<p>The left side of the stereo pair (second image) is saved as the red channel of the output image. The right side (first image) is saved as the green and blue channels. Red-green stereo glasses are required to properly view the stereo image.</p> 7389 7390<div style="margin: auto;"> 7391 <h3><a class="anchor" id="storage-type"></a>-storage-type <var>type</var></h3> 7392</div> 7393 7394<p class="magick-description">pixel storage type. Here are the valid types:</p> 7395 7396<dl class="row"> 7397<dt class="col-md-4">char</dt><dd class="col-md-8">unsigned characters</dd> 7398<dt class="col-md-4">double</dt><dd class="col-md-8">doubles</dd> 7399<dt class="col-md-4">float</dt><dd class="col-md-8">floats</dd> 7400<dt class="col-md-4">integer</dt><dd class="col-md-8">integers</dd> 7401<dt class="col-md-4">long</dt><dd class="col-md-8">longs</dd> 7402<dt class="col-md-4">quantum</dt><dd class="col-md-8">pixels in the native depth of your ImageMagick distribution</dd> 7403<dt class="col-md-4">short</dt><dd class="col-md-8">unsigned shorts</dd> 7404</dl> 7405 7406<p>Float and double types are normalized from 0.0 to 1.0 otherwise the pixels 7407values range from 0 to the maximum value the storage type can support.</p> 7408 7409<div style="margin: auto;"> 7410 <h3><a class="anchor" id="stretch"></a>-stretch <var>fontStretch</var></h3> 7411</div> 7412 7413<p class="magick-description">Set a type of stretch style for fonts.</p> 7414 7415<p>This setting suggests a type of stretch that ImageMagick should try to 7416apply to the currently selected font family. Select <var>fontStretch</var> from the following.</p> 7417 7418<pre class="highlight"><code>Any 7419Condensed 7420Expanded 7421ExtraCondensed 7422ExtraExpanded 7423Normal 7424SemiCondensed 7425SemiExpanded 7426UltraCondensed 7427UltraExpanded 7428</code></pre> 7429 7430<p>To print a complete list of stretch types, use <a href="command-line-options.html#list">-list 7431stretch</a>.</p> 7432 7433<p>For other settings that affect fonts, see the options <a 7434href="command-line-options.html#font">-font</a>, <a href="command-line-options.html#family">-family</a>, <a 7435href="command-line-options.html#style">-style</a>, and <a href="command-line-options.html#weight">-weight</a>. </p> 7436 7437<div style="margin: auto;"> 7438 <h3><a class="anchor" id="strip"></a>-strip</h3> 7439</div> 7440 7441<p class="magick-description">strip the image of any profiles, comments or these PNG chunks: bKGD,cHRM,EXIF,gAMA,iCCP,iTXt,sRGB,tEXt,zCCP,zTXt,date.</p> 7442 7443<div style="margin: auto;"> 7444 <h3><a class="anchor" id="stroke"></a>-stroke <var>color</var></h3> 7445</div> 7446 7447<p class="magick-description">color to use when stroking a graphic primitive.</p> 7448 7449<p>The color is specified using the format described under the <a href="command-line-options.html#fill">-fill</a> option.</p> 7450 7451<p>See <a href="command-line-options.html#draw">-draw</a> for further details.</p> 7452 7453<div style="margin: auto;"> 7454 <h3><a class="anchor" id="strokewidth"></a>-strokewidth <var>value</var></h3> 7455</div> 7456 7457<p class="magick-description">set the stroke width.</p> 7458 7459<p>See <a href="command-line-options.html#draw">-draw</a> for further details.</p> 7460 7461<div style="margin: auto;"> 7462 <h3><a class="anchor" id="style"></a>-style <var>fontStyle</var></h3> 7463</div> 7464 7465<p class="magick-description">Set a font style for text.</p> 7466 7467<p>This setting suggests a font style that ImageMagick should try to apply to 7468the currently selected font family. Select <var>fontStyle</var> from 7469the following.</p> 7470 7471<pre class="highlight"><code>Any 7472Italic 7473Normal 7474Oblique 7475</code></pre> 7476 7477<p>For other settings that affect fonts, see the options <a 7478href="command-line-options.html#font">-font</a>, <a href="command-line-options.html#family">-family</a>, <a 7479href="command-line-options.html#stretch">-stretch</a>, and <a href="command-line-options.html#weight">-weight</a>. </p> 7480 7481<div style="margin: auto;"> 7482 <h3><a class="anchor" id="subimage-search"></a>-subimage-search</h3> 7483</div> 7484 7485<p class="magick-description">search for subimage.</p> 7486 7487<p>This option is required to have compare search for the best match location 7488of a small image within a larger image. This search will produce two images 7489(or two frames). The first is the "difference" image and the second will 7490be the "match score" image.</p> 7491 7492<p>The "match-score" image is smaller containing a pixel for ever possible 7493position of the top-left corner of the given sub-image. that is its size will 7494be the size of the larger_image - sub_image + 1. The brightest location in 7495this image is the location s the locate on the best match that is also 7496reported. Note that this may or may not be a perfect match, and the actual 7497brightness will reflect this. Other bright 'peaks' can be used to locate other 7498possible matching locations. </p> 7499 7500<p>Note that the search will try to compare the sub-image at every possible 7501location in the larger image, as such it can be very slow. The smaller the 7502sub-image the faster this search is. </p> 7503 7504 7505<div style="margin: auto;"> 7506 <h3><a class="anchor" id="swap"></a>-swap <var>index,index</var></h3> 7507</div> 7508 7509<p class="magick-description">Swap the positions of two images in the image sequence.</p> 7510 7511<p>For example, <a href="command-line-options.html#swap">-swap 0,2</a> swaps the first and the third 7512images in the current image sequence. Use <a href="command-line-options.html#swap">+swap</a> to switch 7513the last two images in the sequence.</p> 7514 7515<div style="margin: auto;"> 7516 <h3><a class="anchor" id="swirl"></a>-swirl <var>degrees</var></h3> 7517</div> 7518 7519<p class="magick-description">swirl image pixels about the center.</p> 7520 7521<p><var>Degrees</var> defines the tightness of the swirl.</p> 7522 7523<div style="margin: auto;"> 7524 <h3><a class="anchor" id="synchronize"></a>-synchronize</h3> 7525</div> 7526 7527<p class="magick-description">synchronize image to storage device.</p> 7528 7529<p>Set to "true" to ensure all image data is fully flushed and synchronized 7530to disk. There is a performance penalty, but the benefits include ensuring a 7531valid image file in the event of a system crash and early reporting if there 7532is not enough disk space for the image pixel cache.</p> 7533 7534<div style="margin: auto;"> 7535 <h3><a class="anchor" id="taint"></a>-taint</h3> 7536</div> 7537 7538<p class="magick-description">Mark the image as modified.</p> 7539 7540<div style="margin: auto;"> 7541 <h3><a class="anchor" id="text-font"></a>-text-font <var>name</var></h3> 7542</div> 7543 7544<p class="magick-description">font for writing fixed-width text.</p> 7545 7546<p>Specifies the name of the preferred font to use in fixed (typewriter style) 7547formatted text. The default is 14 point <var>Courier</var>.</p> 7548 7549<p>You can tag a font to specify whether it is a PostScript, TrueType, or 7550OPTION1 font. For example, <code>Courier.ttf</code> is a TrueType font and 7551<code>x:fixed</code> is OPTION1.</p> 7552 7553<div style="margin: auto;"> 7554 <h3><a class="anchor" id="texture"></a>-texture <var>filename</var></h3> 7555</div> 7556 7557<p class="magick-description">name of texture to tile onto the image background.</p> 7558 7559<div style="margin: auto;"> 7560 <h3><a class="anchor" id="threshold"></a>-threshold <var>value</var>{<var>%</var>}</h3> 7561</div> 7562 7563<!-- {<var>green,blue,opacity</var>} 7564<p>If the green or blue value is omitted, these channels use the same value as 7565the first one provided. If all three color values are the same, the result is 7566a bi-level image. If the opacity threshold is omitted, OpaqueOpacity is used 7567and any partially transparent pixel becomes fully transparent.</p> 7568--> 7569 7570<p class="magick-description">Apply simultaneous black/white threshold to the image.</p> 7571 7572<p>Any pixel values (more specifically, those channels set using <a href="command-line-options.html#channel">‑channel</a>) that exceed the specified threshold are reassigned the 7573maximum channel value, while all other values are assigned the minimum.</p> 7574 7575<p> The threshold value can be given as a percentage or as an absolute integer 7576value corresponding to the desired channel value. When given as an integer, 7577the minimum attainable value is 0 (corresponding to black when all channels 7578are affected), but the maximum value (corresponding to white) is that of the 7579<code>quantum depth</code> of the particular build of ImageMagick, and is 7580therefore dependent on the installation. For that reason, a reasonable 7581recommendation for most applications is to specify the threshold values as 7582a percentage. </p> 7583 7584<p> The following would force pixels with red values above 50% to have 100% 7585red values, while those at or below 50% red would be set to 0 in the red 7586channel. The green, blue, and alpha channels (if present) would be unchanged. 7587</p> 7588 7589<pre class="highlight"><code>convert in.png -channel red -threshold 50% out.png 7590</code></pre> 7591 7592<p>As (possibly) impractical but instructive examples, the following would 7593generate an all-black and an all-white image with the same dimensions as the 7594input image.</p> 7595 7596 7597<pre class="highlight"><code>convert in.png -channel RGB -threshold 100% black.png 7598convert in.png -channel RGB -threshold -1 white.png 7599</code></pre> 7600 7601<p> See also <a href="command-line-options.html#black-threshold">‑black‑threshold</a> and <a href="command-line-options.html#white-threshold">‑white‑threshold</a>. 7602</p> 7603 7604<div style="margin: auto;"> 7605 <h3><a class="anchor" id="thumbnail"></a>-thumbnail <var>geometry</var></h3> 7606</div> 7607 7608<p class="magick-description">Create a thumbnail of the image.</p> 7609 7610<p>This is similar to <a href="command-line-options.html#resize">-resize</a>, except it is optimized 7611for speed and any image profile, other than a color profile, is removed to 7612reduce the thumbnail size. To strip the color profiles as well, add <a 7613href="command-line-options.html#strip">-strip</a> just before of after this option.</p> 7614 7615<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 7616 7617<div style="margin: auto;"> 7618 <h3><a class="anchor" id="tile"></a>-tile <var>filename</var></h3> 7619</div> 7620 7621<p class="magick-description">Set the tile image used for filling a subsequent graphic primitive.</p> 7622 7623<div style="margin: auto;"> 7624 <h3>-tile <var>geometry</var></h3> 7625</div> 7626 7627<p class="magick-description">Specify the layout of images.</p> 7628 7629<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 7630 7631<div style="margin: auto;"> 7632 <h3>-tile</h3> 7633</div> 7634 7635<p class="magick-description">Specifies that a subsequent composite operation is repeated across and down image.</p> 7636 7637<div style="margin: auto;"> 7638 <h3><a class="anchor" id="tile-offset"></a>-tile-offset {<var>+-</var>}<var>x</var>{<var>+-</var>}<var>y</var></h3> 7639</div> 7640 7641<p class="magick-description">Specify the offset for tile images, relative to the background image it is tiled on.</p> 7642 7643<p>This should be set before the tiling image is set by <a href="command-line-options.html#tile" 7644>-tile</a> or <a href="command-line-options.html#texture" >-texture</a>, or directly applied for 7645creating a tiled canvas using <code>TILE:</code> or <code>PATTERN:</code> input 7646formats. </p> 7647 7648<p>Internally ImageMagick does a <a href="command-line-options.html#roll" >-roll</a> of the tile image 7649by the arguments given when the tile image is set. </p> 7650 7651<div style="margin: auto;"> 7652 <h3><a class="anchor" id="tint"></a>-tint <var>value</var></h3> 7653</div> 7654 7655<p class="magick-description">Tint the image with the fill color.</p> 7656 7657<p>Tint the image with the fill color.</p> 7658 7659<p>Specify the amount of tinting as a percentage. Pure colors like black, 7660white red, yellow, will not be affected by -tint. Only mid-range colors such 7661as the various shades of grey.</p> 7662 7663<div style="margin: auto;"> 7664 <h3><a class="anchor" id="title"></a>-title <var>string</var></h3> 7665</div> 7666 7667<p class="magick-description">Assign a title to displayed image.", "animate", "display", "montage</p> 7668 7669<p>Use this option to assign a specific title to the image. This assigned to 7670the image window and is typically displayed in the window title bar. 7671Optionally you can include the image filename, type, width, height, Exif data, 7672or other image attribute by embedding special format characters described 7673under the <a href="command-line-options.html#format">-format</a> option.</p> 7674 7675<p>For example,</p> 7676 7677<pre class="highlight"><code>-title "%m:%f %wx%h" 7678</code></pre> 7679 7680<p>produces an image title of <code>MIFF:bird.miff 512x480</code> for an image 7681titled <code>bird.miff</code> and whose width is 512 and height is 480.</p> 7682 7683 7684<div style="margin: auto;"> 7685 <h3><a class="anchor" id="transform"></a>-transform</h3> 7686</div> 7687 7688<p class="magick-description">transform the image.</p> 7689 7690<p>This option applies the transformation matrix from a previous <a href="command-line-options.html#affine">-affine</a> option.</p> 7691 7692<pre class="highlight"><code>convert -affine 2,2,-2,2,0,0 -transform bird.ppm bird.jpg 7693</code></pre> 7694 7695 7696<p>This operator has been now been superseded by the <a 7697href="command-line-options.html#distort">-distort</a> '<code>AffineProjection</code>' method. </p> 7698 7699 7700<div style="margin: auto;"> 7701 <h3><a class="anchor" id="transparent"></a>-transparent <var>color</var></h3> 7702</div> 7703 7704<p class="magick-description">Make this color transparent within the image.</p> 7705 7706<p>The <var>color</var> argument is defined using the format 7707described under the <a href="command-line-options.html#fill">-fill</a> option. The <a href="command-line-options.html#fuzz" 7708>-fuzz</a> setting can be used to match and replace colors similar to the one 7709given. </p> 7710 7711<p>Use <a href="command-line-options.html#transparent" >+transparent</a> to invert the pixels matched. 7712that is make all non-matching colors transparent. </p> 7713 7714<p>The <a href="command-line-options.html#opaque">-opaque</a> operator is exactly the same as <a 7715href="command-line-options.html#transparent" >-transparent</a> but replaces the matching color with the 7716current <a href="command-line-options.html#fill">-fill</a> color setting, rather than transparent. 7717However the <a href="command-line-options.html#transparent" >-transparent</a> operator also ensures 7718that the image has an alpha channel enabled, as per "<code><a href="command-line-options.html#alpha" 7719>-alpha</a> set</code>", and does not require you to modify the <a 7720href="command-line-options.html#channel">-channel</a> to enable alpha channel handling. </p> 7721 7722<p>Note that this does not define the color as being the 'transparency color' 7723used for color-mapped image formats, such as GIF. For that use <a 7724href="command-line-options.html#transparent-color" >-transparent-color</a> </p> 7725 7726 7727<div style="margin: auto;"> 7728 <h3><a class="anchor" id="transparent-color"></a>-transparent-color <var>color</var></h3> 7729</div> 7730 7731<p class="magick-description">Set the transparent color.</p> 7732 7733<p>Sometimes this is used for saving to image formats such as 7734GIF and PNG8 which uses this color to represent boolean transparency. This 7735does not make a color transparent, it only defines what color the transparent 7736color is in the color palette of the saved image. Use <a 7737href="command-line-options.html#transparent">-transparent</a> to make an opaque color transparent.</p> 7738 7739<p>This option allows you to have both an opaque visible color, as well as a 7740transparent color of the same color value without conflict. That is, you can 7741use the same color for both the transparent and opaque color areas within an 7742image. This, in turn, frees to you to select a transparent color that is 7743appropriate when an image is displayed by an application that does not handle a 7744transparent color index, while allowing ImageMagick to correctly handle images of this 7745type. </p> 7746 7747<p>The default transparent color is <code>#00000000</code>, which is fully transparent black.</p> 7748 7749<div style="margin: auto;"> 7750 <h3><a class="anchor" id="transpose"></a>-transpose</h3> 7751</div> 7752 7753<p class="magick-description">Mirror the image along the top-left to bottom-right diagonal.</p> 7754 7755<p> This option mathematically transposes the pixel array. It is equivalent to the sequence <code>-flip -rotate 90</code>. 7756</p> 7757 7758<div style="margin: auto;"> 7759 <h3><a class="anchor" id="transverse"></a>-transverse</h3> 7760</div> 7761 7762<p class="magick-description">Mirror the image along the images bottom-left top-right diagonal. Equivalent to the operations <code>-flop -rotate 90</code>.</p> 7763 7764 7765<div style="margin: auto;"> 7766 <h3><a class="anchor" id="treedepth"></a>-treedepth <var>value</var></h3> 7767</div> 7768 7769<p class="magick-description">tree depth for the color reduction algorithm.</p> 7770 7771<p>Normally, this integer value is zero or one. A value of zero or one causes 7772the use of an optimal tree depth for the color reduction algorithm.</p> 7773 7774<p>An optimal depth generally allows the best representation of the source 7775image with the fastest computational speed and the least amount of memory. 7776However, the default depth is inappropriate for some images. To assure the 7777best representation, try values between 2 and 8 for this parameter. Refer to 7778the <a href="../www/quantize.html" 7779>color reduction algorithm</a> for more details.</p> 7780 7781<p>The <a href="command-line-options.html#colors">-colors</a> or <a href="command-line-options.html#monochrome">-monochrome</a> 7782option, or writing to an image format which requires color reduction, is 7783required for this option to take effect.</p> 7784 7785<div style="margin: auto;"> 7786 <h3><a class="anchor" id="trim"></a>-trim</h3> 7787</div> 7788 7789<p class="magick-description">trim an image.</p> 7790 7791<p>This option removes any edges that are exactly the same color as the corner 7792pixels. Use <a href="command-line-options.html#fuzz">-fuzz</a> to make <a href="command-line-options.html#trim">-trim</a> remove 7793edges that are nearly the same color as the corner pixels.</p> 7794 7795<p>The page or virtual canvas information of the image is preserved allowing 7796you to extract the result of the <a href="command-line-options.html#trim">-trim</a> operation from the 7797image. Use a <a href="command-line-options.html#repage">+repage</a> to remove the virtual canvas page 7798information if it is unwanted.</p> 7799 7800<p>If the trimmed image 'disappears' an warning is produced, and a special 7801single pixel transparent 'missed' image is returned, in the same way as when a 7802<a href="command-line-options.html#crop">-crop</a> operation 'misses' the image proper. </p> 7803 7804<p>Use <code><a href="command-line-options.html#define">-define</a> trim:percent-background=0%</code> to remove all the background from the image. The amount of background that is tolerated in an edge specified as a percent. 0% means no background is tolerated. 50% means an edge can contain up to 50% pixels that are background per the fuzz-factor.</p> 7805 7806<p>Use <code><a href="command-line-options.html#define">-define</a> trim:background-color=<em>color</em></code> to identify background color surrounding the region of interest.</p> 7807 7808<div style="margin: auto;"> 7809 <h3><a class="anchor" id="type"></a>-type <var>type</var></h3> 7810</div> 7811 7812<p class="magick-description">the image type.</p> <p>Choose from: <code>Bilevel</code>, 7813<code>Grayscale</code>, <code>GrayscaleAlpha</code>, <code>Palette</code>, 7814<code>PaletteAlpha</code>, <code>TrueColor</code>, <code>TrueColorAlpha</code>, 7815<code>ColorSeparation</code>, or <code>ColorSeparationAlpha</code>.</p> 7816 7817<p>Normally, when a format supports different subformats such as grayscale and 7818truecolor, the encoder will try to choose an efficient subformat. The <a 7819href="command-line-options.html#type">-type</a> option can be used to override this behavior. For 7820example, to prevent a JPEG from being written in grayscale format even though 7821only gray pixels are present, use.</p> 7822 7823<pre class="highlight"><code>convert bird.png -type TrueColor bird.jpg 7824</code></pre> 7825 7826<p>Similarly, use <a href="command-line-options.html#type">-type TrueColorAlpha</a> to force the 7827encoder to write an alpha channel even though the image is opaque, if the 7828output format supports transparency.</p> 7829 7830<p>Use <a href="command-line-options.html#type">-type optimize</a> to ensure the image is written in the smallest possible file size.</p> 7831 7832<div style="margin: auto;"> 7833 <h3><a class="anchor" id="undercolor"></a>-undercolor <var>color</var></h3> 7834</div> 7835 7836<p class="magick-description">set the color of the annotation bounding box.</p> 7837 7838<p>The color is specified using the format described under the <a href="command-line-options.html#fill">-fill</a> option.</p> 7839 7840<p>See <a href="command-line-options.html#draw">-draw</a> for further details.</p> 7841 7842 7843<div style="margin: auto;"> 7844 <h3><a class="anchor" id="update"></a>-update <var>seconds</var></h3> 7845</div> 7846 7847<p class="magick-description">detect when image file is modified and redisplay.</p> 7848 7849<p>Suppose that while you are displaying an image the file that is currently 7850displayed is over-written. <code>display</code> will automagically detect that 7851the input file has been changed and update the displayed image 7852accordingly.</p> 7853 7854 7855<div style="margin: auto;"> 7856 <h3><a class="anchor" id="unique-colors"></a>-unique-colors</h3> 7857</div> 7858 7859<p class="magick-description">discard all but one of any pixel color.</p> 7860 7861 7862<div style="margin: auto;"> 7863 <h3><a class="anchor" id="units"></a>-units <var>type</var></h3> 7864</div> 7865 7866<p class="magick-description">the units of image resolution.</p> 7867 7868<p>Choose from: <code>Undefined</code>, <code>PixelsPerInch</code>, or 7869<code>PixelsPerCentimeter</code>. This option is normally used in conjunction 7870with the <a href="command-line-options.html#density">-density</a> option.</p> 7871 7872 7873<div style="margin: auto;"> 7874 <h3><a class="anchor" id="unsharp"></a>-unsharp <var>radius</var><br />-unsharp <var>radius</var>x<var>sigma</var>{<var>+gain</var>}{<var>+threshold</var>}</h3> 7875</div> 7876 7877<p class="magick-description">sharpen the image with an unsharp mask operator.</p> 7878 7879<p>The <a href="command-line-options.html#unsharp">-unsharp</a> option sharpens an image. The image is 7880convolved with a Gaussian operator of the given radius and standard deviation 7881(sigma). For reasonable results, radius should be larger than sigma. Use 7882a radius of 0 to have the method select a suitable radius.</p> 7883 7884<p>The parameters are:</p> 7885 7886<dl class="row"> 7887<dt class="col-md-4">radius</dt> 7888<dd class="col-md-8">The radius of the Gaussian, in pixels, not counting the center pixel (default 0).</dd> 7889<dt class="col-md-4">sigma</dt> 7890<dd class="col-md-8">The standard deviation of the Gaussian, in pixels (default 1.0).</dd> 7891<dt class="col-md-4">gain</dt> 7892<dd class="col-md-8">The fraction of the difference between the original and the blur image that is added back into the original (default 1.0).</dd> 7893<dt class="col-md-4">threshold</dt> 7894<dd class="col-md-8">The threshold, as a fraction of <var>QuantumRange</var>, needed to apply the difference amount (default 0.05).</dd> 7895</dl> 7896 7897<div style="margin: auto;"> 7898 <h3><a class="anchor" id="verbose"></a>-verbose</h3> 7899</div> 7900 7901<p class="magick-description">print detailed information about the image when this option precedes the <a href="command-line-options.html#identify">-identify</a> option or <code>info:</code>.</p> 7902 7903 7904<div style="margin: auto;"> 7905 <h3><a class="anchor" id="version"></a>-version</h3> 7906</div> 7907 7908<p class="magick-description">print ImageMagick version string and exit.</p> 7909 7910 7911<div style="margin: auto;"> 7912 <h3><a class="anchor" id="view"></a>-view <var>string</var></h3> 7913</div> 7914 7915<p class="magick-description">FlashPix viewing parameters.</p> 7916 7917 7918<div style="margin: auto;"> 7919 <h3><a class="anchor" id="vignette"></a>-vignette <var>radius</var>{x<var>sigma</var>}{<var>+-</var>}<var>x</var>{<var>+-</var>}<var>y</var>{<var>%</var>}</h3> 7920</div> 7921 7922<p class="magick-description">soften the edges of the image in vignette style.</p> 7923 7924<p>The vignette effect rolloff is controlled by radiusxsigma. For nominal rolloff, this would be set to 0xsigma. A value of 0x0 will produce a circle/ellipse with no rolloff. The arguments x and y control the size of the circle. Larger values decrease the radii and smaller values increase the radii. Values of +0+0 will generate a circle/ellipse the same size as the image. The default values for x and y are 10% of the corresponding image dimension. Thus, the radii will be decreased by 10%, i.e., the diameters of the circle/ellipse will be 80% of the corresponding image dimension.</p> 7925 7926<div style="margin: auto;"> 7927 <h3><a class="anchor" id="virtual-pixel"></a>-virtual-pixel <var>method</var></h3> 7928</div> 7929 7930<p class="magick-description">Specify contents of <var>virtual pixels</var>.</p> 7931 7932<p>This option defines what color source should be used if and when a color 7933lookup completely 'misses' the source image. The color(s) that appear to 7934surround the source image. Generally this color is derived from the source 7935image, but could also be set to a specify background color. </p> 7936 7937<p>Choose from these methods:</p> 7938 7939<dl class="row"> 7940<dt class="col-md-4">background</dt><dd class="col-md-8">the area surrounding the image is the background color</dd> 7941<dt class="col-md-4">black</dt><dd class="col-md-8">the area surrounding the image is black</dd> 7942<dt class="col-md-4">checker-tile</dt><dd class="col-md-8">alternate squares with image and background color</dd> 7943<dt class="col-md-4">dither</dt><dd class="col-md-8">non-random 32x32 dithered pattern</dd> 7944<dt class="col-md-4">edge</dt><dd class="col-md-8">extend the edge pixel toward infinity</dd> 7945<dt class="col-md-4">gray</dt><dd class="col-md-8">the area surrounding the image is gray</dd> 7946<dt class="col-md-4">horizontal-tile</dt><dd class="col-md-8">horizontally tile the image, background color above/below</dd> 7947<dt class="col-md-4">horizontal-tile-edge</dt><dd class="col-md-8">horizontally tile the image and replicate the side edge pixels</dd> 7948<dt class="col-md-4">mirror</dt><dd class="col-md-8">mirror tile the image</dd> 7949<dt class="col-md-4">random</dt><dd class="col-md-8">choose a random pixel from the image</dd> 7950<dt class="col-md-4">tile</dt><dd class="col-md-8">tile the image (default)</dd> 7951<dt class="col-md-4">transparent</dt><dd class="col-md-8">the area surrounding the image is transparent blackness</dd> 7952<dt class="col-md-4">vertical-tile</dt><dd class="col-md-8">vertically tile the image, sides are background color</dd> 7953<dt class="col-md-4">vertical-tile-edge</dt><dd class="col-md-8">vertically tile the image and replicate the side edge pixels</dd> 7954<dt class="col-md-4">white</dt><dd class="col-md-8">the area surrounding the image is white</dd> 7955</dl> 7956 7957<p>The default value is "edge".</p> 7958 7959<p>This most important for distortion operators such as <a href="command-line-options.html#distort" 7960>-distort</a>, <a href="command-line-options.html#implode" >-implode</a>, and <a href="command-line-options.html#fx" >-fx</a>. 7961However it also affects operations that may access pixels just outside the 7962image proper, such as <a href="command-line-options.html#convolve">-convolve</a>, <a 7963href="command-line-options.html#blur">-blur</a>, and <a href="command-line-options.html#sharpen">-sharpen</a>. </p> 7964 7965<p>To print a complete list of virtual pixel types, use the <a 7966href="command-line-options.html#list">-list virtual-pixel</a> option.</p> 7967 7968 7969<div style="margin: auto;"> 7970 <h3><a class="anchor" id="visual"></a>-visual <var>type</var></h3> 7971</div> 7972 7973<p class="magick-description">Animate images using this X visual type.", 'animate', 'display'</p> 7974 7975<p>Choose from these visual classes:</p> 7976 7977<pre class="highlight"><code>StaticGray TrueColor 7978GrayScale DirectColor 7979StaticColor default 7980PseudoColor visual id 7981</code></pre> 7982 7983<p>The X server must support the visual you choose, otherwise an error occurs. 7984If a visual is not specified, the visual class that can display the most 7985simultaneous colors on the default screen is chosen.</p> 7986 7987 7988<div style="margin: auto;"> 7989 <h3><a class="anchor" id="watermark"></a>-watermark <var>brightness</var>x<var>saturation</var></h3> 7990</div> 7991 7992<p class="magick-description">Watermark an image using the given percentages of brightness and saturation.</p> 7993 7994<p>Take a grayscale image (with alpha mask) and modify the destination image's 7995brightness according to watermark image's grayscale value and the 7996<var>brightness</var> percentage. The destinations color saturation 7997attribute is just direct modified by the <var>saturation</var> 7998percentage, which defaults to 100 percent (no color change). </p> 7999 8000 8001<div style="margin: auto;"> 8002 <h3><a class="anchor" id="wave"></a>-wave <var>amplitude</var><br />-wave <var>amplitude</var>x<var>wavelength</var></h3> 8003</div> 8004 8005<p class="magick-description">Shear the columns of an image into a sine wave.</p> 8006 8007<div style="margin: auto;"> 8008 <h3><a class="anchor" id="wavelet-denoise"></a>-wavelet-denoise <var>threshold</var><br />-wavelet-denoise <var>threshold</var>x<var>softness</var></h3> 8009</div> 8010 8011<p class="magick-description">removes noise from the image using a wavelet transform. The threshold is the value below which everything is considered noise and ranges from 0.0 (none) to QuantumRange or use percent (e.g. 5%). Softness attenuates the threshold and typically ranges from 0.0 (none) to 1.0. The higher the value the more noise that remains in the image.</p> 8012 8013<div style="margin: auto;"> 8014 <h3><a class="anchor" id="weight"></a>-weight <var>fontWeight</var></h3> 8015</div> 8016 8017<p class="magick-description">Set a font weight for text.</p> 8018 8019<p>This setting suggests a font weight that ImageMagick should try to apply to 8020the currently selected font family. Use a positive integer for 8021<var>fontWeight</var> or select from the following.</p> 8022 8023<dl class="row"> 8024<dt class="col-md-4">Thin </dt> 8025<dd class="col-md-8">Same as <var>fontWeight</var> = 100.</dd> 8026<dt class="col-md-4">ExtraLight </dt> 8027<dd class="col-md-8">Same as <var>fontWeight</var> = 200.</dd> 8028<dt class="col-md-4">Light </dt> 8029<dd class="col-md-8">Same as <var>fontWeight</var> = 300.</dd> 8030<dt class="col-md-4">Normal </dt> 8031<dd class="col-md-8">Same as <var>fontWeight</var> = 400.</dd> 8032<dt class="col-md-4">Medium </dt> 8033<dd class="col-md-8">Same as <var>fontWeight</var> = 500.</dd> 8034<dt class="col-md-4">DemiBold </dt> 8035<dd class="col-md-8">Same as <var>fontWeight</var> = 600.</dd> 8036<dt class="col-md-4">Bold </dt> 8037<dd class="col-md-8">Same as <var>fontWeight</var> = 700.</dd> 8038<dt class="col-md-4">ExtraBold </dt> 8039<dd class="col-md-8">Same as <var>fontWeight</var> = 800.</dd> 8040<dt class="col-md-4">Heavy </dt> 8041<dd class="col-md-8">Same as <var>fontWeight</var> = 900.</dd> 8042</dl> 8043<br/> 8044 8045<p>To print a complete list of weight types, use <a href="command-line-options.html#list">-list weight</a>.</p> 8046 8047<p>For other settings that affect fonts, see the options <a 8048href="command-line-options.html#font">-font</a>, <a href="command-line-options.html#family">-family</a>, <a 8049href="command-line-options.html#stretch">-stretch</a>, and <a href="command-line-options.html#style">-style</a>. </p> 8050 8051<div style="margin: auto;"> 8052 <h3><a class="anchor" id="white-point"></a>-white-point <var>x,y</var></h3> 8053</div> 8054 8055<p class="magick-description">chromaticity white point.</p> 8056 8057<div style="margin: auto;"> 8058 <h3><a class="anchor" id="white-threshold"></a>-white-threshold <var>value</var>{<var>%</var>}</h3> 8059</div> 8060 8061<p class="magick-description">Force to white all pixels above the threshold while leaving all pixels at or below the threshold unchanged.</p> 8062 8063<p> The threshold value can be given as a percentage or as an absolute integer 8064value within [0, <var>QuantumRange</var>] corresponding to the 8065desired <a href="command-line-options.html#channel">‑channel</a> value. See <a href="command-line-options.html#threshold">‑threshold</a>for more details on thresholds and resulting values. </p> 8066 8067<div style="margin: auto;"> 8068 <h3><a class="anchor" id="window"></a>-window <var>id</var></h3> 8069</div> 8070 8071<p class="magick-description">Make the image the background of a window.", 'animate', 'display'</p> 8072 8073<p><var>id</var> can be a window id or name. Specify <code>root</code> 8074to select X's root window as the target window.</p> 8075 8076<p>By default the image is tiled onto the background of the target window. If 8077<code>backdrop</code> or <a href="command-line-options.html#geometry">-resize</a> are specified, the 8078image is surrounded by the background color. Refer to <code>X RESOURCES</code> 8079for details.</p> 8080 8081<p>The image will not display on the root window if the image has more unique 8082colors than the target window colormap allows. Use <a 8083href="command-line-options.html#colors">-colors</a> to reduce the number of colors.</p> 8084 8085<div style="margin: auto;"> 8086 <h3><a class="anchor" id="window-group"></a>-window-group</h3> 8087</div> 8088 8089<p class="magick-description">specify the window group.</p> 8090 8091<div style="margin: auto;"> 8092 <h3><a class="anchor" id="write"></a>-write <var>filename</var></h3> 8093</div> 8094 8095<p class="magick-description">write an image sequence.</p> 8096 8097<p>The image sequence preceding the <a href="command-line-options.html#write">-write</a> <var>filename</var> option is written out, and processing continues with the same image in its current state if there are additional options. To restore the image to its original state after writing it, use the <a href="command-line-options.html#write">+write</a> <var>filename</var> option.</p> 8098 8099<p>Use <a href="command-line-options.html#compress">-compress</a> to specify the type of image compression.</p> 8100 8101<div style="margin: auto;"> 8102 <h3><a class="anchor" id="write-mask"></a>-write-mask <var>filename</var></h3> 8103</div> 8104 8105<p class="magick-description">Prevent updates to image pixels specified by the mask.</p> 8106 8107<p>This the same as using a mask used for composite masking operations, with 8108grayscale values causing blended updates of the image the mask is attached to. 8109</p> 8110 8111<p>Use <a href="command-line-options.html#write-mask">+write-mask</a> to remove the mask from images.</p> 8112 8113<p>Also see <a href="command-line-options.html#clip-mask">-clip-mask</a> which work in the same way, 8114but with strict boolean masking. </p> 8115</div> 8116</div> 8117 </div> 8118 </main><!-- /.container --> 8119 <footer class="magick-footer"> 8120 <p><a href="security-policy.html">Security</a> • 8121 <a href="architecture.html">Architecture</a> 8122 8123 <a href="command-line-options.html#"><img class="d-inline" id="wand" alt="And Now a Touch of Magick" width="16" height="16" src="../images/wand.ico"/></a> 8124 8125 <a href="links.html">Related</a> • 8126 <a href="sitemap.html">Sitemap</a> 8127 <br/> 8128 <a href="support.html">Donate</a> • 8129 <a href="http://pgp.mit.edu/pks/lookup?op=get&search=0x89AB63D48277377A">Public Key</a> • 8130 <a href="https://imagemagick.org/script/contact.php">Contact Us</a> 8131 <br/> 8132 <small>© 1999-2020 ImageMagick Studio LLC</small></p> 8133 </footer> 8134 8135 <!-- Javascript assets --> 8136 <script src="assets/magick.js" crossorigin="anonymous"></script> 8137 <script>window.jQuery || document.write('<script src="https://localhost/ajax/libs/jquery/3.4.1/jquery.min.js"><\/script>')</script> 8138</body> 8139</html> 8140<!-- Magick Cache 5th January 2020 11:16 -->
