20
24
<meta name="Author" content="ImageMagick Studio LLC"/>
21
25
<meta name="Revisit-after" content="2 DAYS"/>
22
26
<meta name="Resource-type" content="document"/>
23
<meta name="Copyright" content="Copyright (c) 1999-2008 ImageMagick Studio LLC"/>
27
<meta name="Copyright" content="Copyright (c) 1999-2009 ImageMagick Studio LLC"/>
24
28
<meta name="Distribution" content="Global"/>
25
29
<link rel="shortcut icon" href="../images/wand.ico" type="images/vnd.microsoft.icon"/>
28
32
<body id="www-imagemagick-org">
29
<table id="titlebar" style="width: 100%;background-color: #f5f5f5" cellpadding="0" cellspacing="0" border="0" summary="ImageMagick">
32
<td align="left"><a href="../index.html"><img id="titlebar-west" src="../images/script.png" alt="[ImageMagick]" width="350" height="60" vspace="28" name="titlebar-west"/></a></td>
33
<td align="left"><a href="http://www.networkredux.com" target="1705984078"><img id="titlebar-west" src="../images/networkredux.png" alt="[sponsor]" border="0" vspace="45" name="titlebar-west"/></a></td>
34
<td width="99%"><br /> </td>
35
<td style="background-color: white" align="right"><a href="../index.html"><img src="../images/sprite.jpg" alt="" width="114" height="118" border="0" name="titlebar-east"/></a></td>
36
<td style="background-color: white" align="right"><a href="http://www.imagemagick.org/discourse-server/" target="178329759"><img id="titlebar-east" src="../images/logo.jpg" alt="" width="114" height="118" border="0" name="titlebar-east"/></a></td>
41
<table style="width: 100%" border="0" cellpadding="0" cellspacing="0" summary="">
44
<tr valign="top" style="height: 100%;">
45
<td id="menu" width="1%" height="100%">
46
<p><a href="#main">Skip to page contents</a></p>
49
<a href="../index.html">About ImageMagick</a>
50
<span>]</span><br /><span>[</span>
51
<a href="../www/command-line-tools.html">Command-line Tools</a>
52
<a href="../www/command-line-processing.html" class="sub">Processing</a>
53
<a href="../www/command-line-options.html" class="sub">Options</a>
54
<a href="http://www.imagemagick.org/Usage/" target="552806409" class="sub">Usage</a>
33
<div class="titlebar">
34
<a href="../index.html">
35
<img src="../images/script.png" alt="[ImageMagick]"
36
style="width: 350px; height: 60px; margin: 28px auto; float: left;" /></a>
37
<a href="http://www.networkredux.com">
38
<img src="../images/networkredux.png" alt="[sponsor]"
39
style="margin: 45px auto; border: 0px; float: left;" /></a>
40
<a href="http://www.imagemagick.org/discourse-server/">
41
<img src="../images/logo.jpg" alt=""
42
style="width: 114px; height: 118px; border: 0px; float: right;" /></a>
43
<a href="../index.html">
44
<img src="../images/sprite.jpg" alt=""
45
style="width: 114px; height: 118px; border: 0px; float: right;" /></a>
51
<a href="../index.html">About ImageMagick</a>
53
<div class="sep"></div>
55
<a href="../www/command-line-tools.html">Command-line Tools</a>
58
<a href="../www/command-line-processing.html">Processing</a>
61
<a href="../www/command-line-options.html">Options</a>
64
<a href="http://www.imagemagick.org/Usage/">Usage</a>
55
67
<a href="../www/api.html">Program Interfaces</a>
56
<a href="../www/magick-wand.html" class="sub">MagickWand</a>
57
<a href="../www/magick-core.html" class="sub">MagickCore</a>
58
<a href="../www/perl-magick.html" class="sub">PerlMagick</a>
59
<a href="../www/Magick++/" target="594677443" class="sub">Magick++</a>
60
<a href="../www/architecture.html">Architecture</a>
61
<span>]</span><br /><span>[</span>
70
<a href="../www/magick-wand.html">MagickWand</a>
73
<a href="../www/magick-core.html">MagickCore</a>
76
<a href="../www/perl-magick.html">PerlMagick</a>
79
<a href="../Magick++/">Magick++</a>
82
<a href="../www/architecture.html">Architecture</a>
84
<div class="sep"></div>
62
86
<a href="../www/install-source.html">Install from Source</a>
63
<a href="../www/install-source.html#unix" class="sub">Unix</a>
64
<a href="../www/install-source.html#windows" class="sub">Windows</a>
89
<a href="../www/install-source.html#unix">Unix</a>
92
<a href="../www/install-source.html#windows">Windows</a>
65
95
<a href="../www/binary-releases.html">Binary Releases</a>
66
<a href="../www/binary-releases.html#unix" class="sub">Unix</a>
67
<a href="../www/binary-releases.html#macosx" class="sub">Mac OS X</a>
68
<a href="../www/binary-releases.html#windows" class="sub">Windows</a>
98
<a href="../www/binary-releases.html#unix">Unix</a>
101
<a href="../www/binary-releases.html#macosx">Mac OS X</a>
104
<a href="../www/binary-releases.html#windows">Windows</a>
69
107
<a href="../www/resources.html">Resources</a>
70
<span>]</span><br /><span>[</span>
109
<div class="sep"></div>
71
111
<a href="../www/download.html">Download</a>
72
<span>]</span><br /><span>[</span>
73
<a href="../www/sitemap.html">Site Map</a>
74
<a href="../www/links.html" class="sub">Links</a>
75
<span>]</span><br /><span>[</span>
76
<a href="../www/sponsors.html">Sponsors:</a>
78
<a href="http://www.17things.com/" class="sponsor" target="sponsor">Answers to Questions</a><!-- 200904010200 -->
80
<a href="http://meta-preisvergleich.de" class="sponsor" target="sponsor">Preisvergleich</a><!-- 200901010120 -->
82
<a href="http://www.checkcost.co.uk" class="sponsor" target="sponsor">Compare</a><!-- 200902010720 -->
84
<a href="http://www.ecostsoftware.com" class="sponsor" target="sponsor">Software</a><!-- 200902010720 -->
86
<a href="http://www.callerbase.com" class="sponsor" target="sponsor">Phone Number<br />Search</a><!-- 200812010040 -->
88
<a href="http://www.online-kredit-index.de" class="sponsor" target="sponsor">Kredit</a><!-- 200903010120 -->
90
<a href="http://www.posters555.com" class="sponsor" target="sponsor">Poster</a><!-- 200903010800 -->
92
<a href="http://www.iceposter.com" class="sponsor" target="sponsor">Posters</a><!-- 200812010200 -->
94
<a href="http://www.imade-art.de"><img src="../images/imade_art2.jpg" alt="[Kunst bei imade-art]" width="116" height="28" border="0" name="Kunst bei imade-art"/></a> <!-- 200811010160 -->
100
<td id="main" valign="top">
101
<p class="navigation-index">[<a href="#adaptive-blur">-adaptive-blur</a> • <a href="#adaptive-resize">-adaptive-resize</a> • <a href="#adaptive-sharpen">-adaptive-sharpen</a> • <a href="#adjoin">-adjoin</a> • <a href="#affine">-affine</a> • <a href="#alpha">-alpha</a> • <a href="#annotate">-annotate</a> • <a href="#antialias">-antialias</a> • <a href="#append">-append</a> • <a href="#attenuate">-attenuate</a> • <a href="#authenticate">-authenticate</a> • <a href="#auto-orient">-auto-orient</a> • <a href="#average">-average</a> • <a href="#backdrop">-backdrop</a> • <a href="#background">-background</a> • <a href="#bench">-bench</a> • <a href="#bias">-bias</a> • <a href="#blackpoint-compensation">-blackpoint-compensation</a> • <a href="#black-threshold">-black-threshold</a> • <a href="#blue-primary">-blue-primary</a> • <a href="#blur">-blur</a> • <a href="#border">-border</a> • <a href="#bordercolor">-bordercolor</a> • <a href="#borderwidth">-borderwidth</a> • <a href="#cache">-cache</a> • <a href="#caption">-caption</a> • <a href="#channel">-channel</a> • <a href="#charcoal">-charcoal</a> • <a href="#chop">-chop</a> • <a href="#clip">-clip</a> • <a href="#clip-mask">-clip-mask</a> • <a href="#clip-path">-clip-path</a> • <a href="#clone">-clone</a> • <a href="#clut">-clut</a> • <a href="#coalesce">-coalesce</a> • <a href="#colorize">-colorize</a> • <a href="#colormap">-colormap</a> • <a href="#colors">-colors</a> • <a href="#colorspace">-colorspace</a> • <a href="#combine">-combine</a> • <a href="#comment">-comment</a> • <a href="#compose">-compose</a> • <a href="#composite">-composite</a> • <a href="#compress">-compress</a> • <a href="#contrast">-contrast</a> • <a href="#contrast-stretch">-contrast-stretch</a> • <a href="#convolve">-convolve</a> • <a href="#crop">-crop</a> • <a href="#cycle">-cycle</a> • <a href="#decipher">-decipher</a> • <a href="#debug">-debug</a> • <a href="#deconstruct">-deconstruct</a> • <a href="#define">-define</a> • <a href="#delay">-delay</a> • <a href="#delete">-delete</a> • <a href="#density">-density</a> • <a href="#depth">-depth</a> • <a href="#descend">-descend</a> • <a href="#deskew">-deskew</a> • <a href="#despeckle">-despeckle</a> • <a href="#displace">-displace</a> • <a href="#display">-display</a> • <a href="#dispose">-dispose</a> • <a href="#dissolve">-dissolve</a> • <a href="#distort">-distort</a> • <a href="#dither">-dither</a> • <a href="#draw">-draw</a> • <a href="#edge">-edge</a> • <a href="#emboss">-emboss</a> • <a href="#encipher">-encipher</a> • <a href="#encoding">-encoding</a> • <a href="#endian">-endian</a> • <a href="#enhance">-enhance</a> • <a href="#equalize">-equalize</a> • <a href="#evaluate">-evaluate</a> • <a href="#extent">-extent</a> • <a href="#extract">-extract</a> • <a href="#fill">-fill</a> • <a href="#filter">-filter</a> • <a href="#flatten">-flatten</a> • <a href="#flip">-flip</a> • <a href="#floodfill">-floodfill</a> • <a href="#flop">-flop</a> • <a href="#font">-font</a> • <a href="#foreground">-foreground</a> • <a href="#format">-format</a> • <a href="#frame">-frame</a> • <a href="#frame">-frame</a> • <a href="#fuzz">-fuzz</a> • <a href="#fx">-fx</a> • <a href="#gamma">-gamma</a> • <a href="#gaussian-blur">-gaussian-blur</a> • <a href="#geometry">-geometry</a> • <a href="#gravity">-gravity</a> • <a href="#green-primary">-green-primary</a> • <a href="#help">-help</a> • <a href="#highlight-color">-highlight-color</a> • <a href="#iconGeometry">-iconGeometry</a> • <a href="#iconic">-iconic</a> • <a href="#identify">- identify</a> • <a href="#immutable">-immutable</a> • <a href="#implode">-implode</a> • <a href="#insert">-insert</a> • <a href="#intent">-intent</a> • <a href="#interlace">-interlace</a> • <a href="#interpolate">-interpolate</a> • <a href="#label">-label</a> • <a href="#lat">-lat</a> • <a href="#layers">-layers</a> • <a href="#level">-level</a> • <a href="#level-colors">-level-colors</a> • <a href="#limit">-limit</a> • <a href="#linear-stretch">-linear-stretch</a> • <a href="#linewidth">-linewidth</a> • <a href="#liquid-rescale">-liquid-rescale</a> • <a href="#list">-list</a> • <a href="#log">-log</a> • <a href="#loop">-loop</a> • <a href="#lowlight-color">-lightcolor</a> • <a href="#magnify">-magnify</a> • <a href="#mask">-mask</a> • <a href="#mattecolor">-mattecolor</a> • <a href="#mask">-mask</a> • <a href="#median">-median</a> • <a href="#metric">-metric</a> • <a href="#mode">-mode</a> • <a href="#modulate">-modulate</a> • <a href="#monitor">-monitor</a> • <a href="#monochrome">-monochrome</a> • <a href="#morph">-morph</a> • <a href="#mosaic">-mosaic</a> • <a href="#motion-blur">-motion-blur</a> • <a href="#name">-name</a> • <a href="#negate">-negate</a> • <a href="#noise">-noise</a> • <a href="#normalize">-normalize</a> • <a href="#opaque">-opaque</a> • <a href="#ordered-dither">-ordered-dither</a> • <a href="#orient">-orient</a> • <a href="#page">-page</a> • <a href="#paint">-paint</a> • <a href="#path">-path</a> • <a href="#pause">-pause</a> • <a href="#pause">-pause</a> • <a href="#pen">-pen</a> • <a href="#ping">-ping</a> • <a href="#pointsize">-pointsize</a> • <a href="#polaroid">-polaroid</a> • <a href="#posterize">-posterize</a> • <a href="#preview">-preview</a> • <a href="#print">-print</a> • <a href="#process">-process</a> • <a href="#profile">-profile</a> • <a href="#quality">-quality</a> • <a href="#quantize">-quantize</a> • <a href="#quiet">-quiet</a> • <a href="#radial-blur">-radial-blur</a> • <a href="#raise">-raise</a> • <a href="#random-thresold">-random-thresold</a> • <a href="#recolor">-recolor</a> • <a href="#red-primary">-red-primary</a> • <a href="#regard-warnings">-regard-warnings</a> • <a href="#region">-region</a> • <a href="#remap">-remap</a> • <a href="#remote">-remote</a> • <a href="#render">-render</a> • <a href="#repage">-repage</a> • <a href="#resample">-resample</a> • <a href="#resize">-resize</a> • <a href="#respect-parenthesis">-respect-parenthesis</a> • <a href="#reverse">-reverse</a> • <a href="#roll">-roll</a> • <a href="#rotate">-rotate</a> • <a href="#sample">-sample</a> • <a href="#sampling-factor">-sampling-factor</a> • <a href="#scale">-scale</a> • <a href="#scene">-scene</a> • <a href="#screen">-screen</a> • <a href="#seed">-seed</a> • <a href="#segment">-segment</a> • <a href="#separate">-separate</a> • <a href="#sepia-tone">-sepia-tone</a> • <a href="#set">-set</a> • <a href="#shade">-shade</a> • <a href="#shadow">-shadow</a> • <a href="#shared-memory">-shared-memory</a> • <a href="#sharpen">-sharpen</a> • <a href="#shave">-shave</a> • <a href="#shear">-shear</a> • <a href="#sigmoidal-contrast">-sigmoidal-contrast</a> • <a href="#silent">-silent</a> • <a href="#size">-size</a> • <a href="#sketch">-sketch</a> • <a href="#snaps">-snaps</a> • <a href="#solarize">-solarize</a> • <a href="#sparse-color">-sparse-color</a> • <a href="#splice">-splice</a> • <a href="#spread">-spread</a> • <a href="#stegano">-stegano</a> • <a href="#stereo">-stereo</a> • <a href="#strip">-strip</a> • <a href="#stroke">-stroke</a> • <a href="#strokewidth">-strokewidth</a> • <a href="#swap">-swap</a> • <a href="#swirl">-swirl</a> • <a href="#taint">-taint</a> • <a href="#text-font">-text-font</a> • <a href="#texture">-texture</a> • <a href="#threshold">-threshold</a> • <a href="#thumbnail">-thumbnail</a> • <a href="#tile">-tile</a> • <a href="#tile-offset">-tile-offset</a> • <a href="#tint">-tint</a> • <a href="#title">-title</a> • <a href="#transform">-transform</a> • <a href="#transparent">-transparent</a> • <a href="#transparent-color">-transparent-color</a> • <a href="#transpose">-transpose</a> • <a href="#transverse">-transverse</a> • <a href="#treedepth">-treedepth</a> • <a href="#trim">-trim</a> • <a href="#type">-type</a> • <a href="#undercolor">-undercolor</a> • <a href="#unique-colors">-unique-colors</a> • <a href="#units">-units</a> • <a href="#unsharp">-unsharp</a> • <a href="#update">-update</a> • <a href="#verbose">-verbose</a> • <a href="#version">-version</a> • <a href="#view">-view</a> • <a href="#vignette">-vignette</a> • <a href="#virtual-pixel">-virtual-pixel</a> • <a href="#visual">-visual</a> • <a href="#watermark">-watermark</a> • <a href="#wave">-wave</a> • <a href="#white-point">-white-point</a> • <a href="#white-threshold">-white-threshold</a> • <a href="#window">-window</a> • <a href="#window-group">-window-group</a> • <a href="#write">-write</a>]</p>
103
<p>Below is list of command-line options recognized by the ImageMagick <a href="../www/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.</p>
105
<div style="margin: auto;">
106
<h4><a name="adaptive-blur" id="adaptive-blur"></a>-adaptive-blur <em class="option">radius</em>{x<em class="option">sigma</em>}</h4>
109
<p>adaptively blur pixels; descreasing its effect near edges.</p>
111
<p>Use a Gaussian operator of the given radius and standard deviation (sigma).</p>
113
<div style="margin: auto;">
114
<h4><a name="adaptive-resize" id="adaptive-resize"></a>-adaptive-resize <em class="option">geometry</em></h4>
117
<p>resize image with data dependent triangulation.</p>
119
<p>See <a href="#resize">-resize</a> for details about the geometry specification. The <a href="#adaptive-resize">-adaptive-resize</a> option defaults to data dependent triangulation. Use the <a href="#filter">-filter</a> to choose a different resampling algorithm. Offsets, if present in the geometry string, are ignored, and the <a href="#gravity">-gravity</a> option has no effect.</p>
121
<div style="margin: auto;">
122
<h4><a name="adaptive-sharpen" id="adaptive-sharpen"></a>-adaptive-sharpen <em class="option">radius</em>{x<em class="option">sigma</em>}</h4>
125
<p>adaptively sharpen pixels; increasng its effect near edges.</p>
127
<p>Use a Gaussian operator of the given radius and standard deviation (sigma).</p>
113
<div class="sep"></div>
115
<a href="http://www.imagemagick.org/script/search.php">Search</a>
116
</div><div class="sep"></div>
118
<a href="../www/sitemap.html">Site Map</a>
121
<a href="../www/links.html">Links</a>
123
<div class="sep"></div>
125
<a href="../www/sponsors.html">Sponsors:</a>
127
<div class="sponsbox">
128
<div class="sponsor">
129
<a href="http://www.fernstudium-vergleich.de">Fernstudium</a><!-- 200908070325 -->
131
<div class="sponsor">
132
<a href="http://www.who-sells-it.com/">Free Catalogs</a><!-- 201002010000 -->
134
<div class="sponsor">
135
<a href="http://www.online-kredit-index.de">Kredit</a><!-- 200908010120 -->
147
<p class="navigation-index">
148
[ <a href="../www/command-line-options.html#adaptive-blur">‑adaptive‑blur</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#adaptive-resize">‑adaptive‑resize</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#adaptive-sharpen">‑adaptive‑sharpen</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#adjoin">‑adjoin</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#affine">‑affine</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#alpha">‑alpha</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#annotate">‑annotate</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#antialias">‑antialias</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#append">‑append</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#attenuate">‑attenuate</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#authenticate">‑authenticate</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#auto-orient">‑auto‑orient</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#average">‑average</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#backdrop">‑backdrop</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#background">‑background</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#bench">‑bench</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#bias">‑bias</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#blackpoint-compensation">‑blackpoint‑compensation</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#black-threshold">‑black‑threshold</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#blend">‑blend</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#blue-primary">‑blue‑primary</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#blur">‑blur</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#border">‑border</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#bordercolor">‑bordercolor</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#borderwidth">‑borderwidth</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#cache">‑cache</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#caption">‑caption</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#channel">‑channel</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#charcoal">‑charcoal</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#chop">‑chop</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#clip">‑clip</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#clip-mask">‑clip‑mask</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#clip-path">‑clip‑path</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#clone">‑clone</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#clut">‑clut</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#coalesce">‑coalesce</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#colorize">‑colorize</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#colormap">‑colormap</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#colors">‑colors</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#colorspace">‑colorspace</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#combine">‑combine</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#comment">‑comment</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#compose">‑compose</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#composite">‑composite</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#compress">‑compress</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#contrast">‑contrast</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#contrast-stretch">‑contrast‑stretch</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#convolve">‑convolve</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#crop">‑crop</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#cycle">‑cycle</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#debug">‑debug</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#decipher">‑decipher</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#deconstruct">‑deconstruct</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#define">‑define</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#delay">‑delay</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#delete">‑delete</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#density">‑density</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#depth">‑depth</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#descend">‑descend</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#deskew">‑deskew</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#despeckle">‑despeckle</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#displace">‑displace</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#display">‑display</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#dispose">‑dispose</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#dissolve">‑dissolve</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#distort">‑distort</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#dither">‑dither</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#draw">‑draw</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#edge">‑edge</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#emboss">‑emboss</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#encipher">‑encipher</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#encoding">‑encoding</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#endian">‑endian</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#enhance">‑enhance</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#equalize">‑equalize</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#evaluate">‑evaluate</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#extent">‑extent</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#extract">‑extract</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#family">‑family</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#fill">‑fill</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#filter">‑filter</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#flatten">‑flatten</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#flip">‑flip</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#floodfill">‑floodfill</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#flop">‑flop</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#font">‑font</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#foreground">‑foreground</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#format">‑format</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#format_identify_">‑format[identify]</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#frame">‑frame</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#frame_import_">‑frame[import]</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#function">‑function</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#fuzz">‑fuzz</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#fx">‑fx</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#gamma">‑gamma</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#gaussian-blur">‑gaussian‑blur</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#geometry">‑geometry</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#gravity">‑gravity</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#green-primary">‑green‑primary</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#help">‑help</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#highlight-color">‑highlight‑color</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#iconGeometry">‑iconGeometry</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#iconic">‑iconic</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#identify">‑identify</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#immutable">‑immutable</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#implode">‑implode</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#insert">‑insert</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#intent">‑intent</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#interlace">‑interlace</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#interpolate">‑interpolate</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#interword-spacing">‑interword‑spacing</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#kerning">‑kerning</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#label">‑label</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#lat">‑lat</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#layers">‑layers</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#level">‑level</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#level-colors">‑level‑colors</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#limit">‑limit</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#linear-stretch">‑linear‑stretch</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#linewidth">‑linewidth</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#liquid-rescale">‑liquid‑rescale</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#list">‑list</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#log">‑log</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#loop">‑loop</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#lowlight-color">‑lowlight‑color</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#magnify">‑magnify</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#map">‑map</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#map_stream_">‑map[stream]</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#mask">‑mask</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#mattecolor">‑mattecolor</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#median">‑median</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#metric">‑metric</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#mode">‑mode</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#modulate">‑modulate</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#monitor">‑monitor</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#monochrome">‑monochrome</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#morph">‑morph</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#mosaic">‑mosaic</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#motion-blur">‑motion‑blur</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#name">‑name</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#negate">‑negate</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#noise">‑noise</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#normalize">‑normalize</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#opaque">‑opaque</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#ordered-dither">‑ordered‑dither</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#orient">‑orient</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#page">‑page</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#paint">‑paint</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#path">‑path</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#pause_animate_">‑pause[animate]</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#pause_import_">‑pause[import]</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#pen">‑pen</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#ping">‑ping</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#pointsize">‑pointsize</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#polaroid">‑polaroid</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#posterize">‑posterize</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#preview">‑preview</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#print">‑print</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#process">‑process</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#profile">‑profile</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#quality">‑quality</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#quantize">‑quantize</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#quiet">‑quiet</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#radial-blur">‑radial‑blur</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#raise">‑raise</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#random-threshold">‑random‑threshold</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#recolor">‑recolor</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#red-primary">‑red‑primary</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#regard-warnings">‑regard‑warnings</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#region">‑region</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#remap">‑remap</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#remote">‑remote</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#render">‑render</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#repage">‑repage</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#resample">‑resample</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#resize">‑resize</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#respect-parentheses">‑respect‑parentheses</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#reverse">‑reverse</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#roll">‑roll</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#rotate">‑rotate</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#sample">‑sample</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#sampling-factor">‑sampling‑factor</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#scale">‑scale</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#scene">‑scene</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#screen">‑screen</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#seed">‑seed</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#segment">‑segment</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#selective-blur">‑selective‑blur</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#separate">‑separate</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#sepia-tone">‑sepia‑tone</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#set">‑set</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#shade">‑shade</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#shadow">‑shadow</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#shared-memory">‑shared‑memory</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#sharpen">‑sharpen</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#shave">‑shave</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#shear">‑shear</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#sigmoidal-contrast">‑sigmoidal‑contrast</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#silent">‑silent</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#size">‑size</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#sketch">‑sketch</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#snaps">‑snaps</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#solarize">‑solarize</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#sparse-color">‑sparse‑color</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#splice">‑splice</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#spread">‑spread</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#stegano">‑stegano</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#stereo">‑stereo</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#stretch">‑stretch</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#strip">‑strip</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#stroke">‑stroke</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#strokewidth">‑strokewidth</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#style">‑style</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#swap">‑swap</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#swirl">‑swirl</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#taint">‑taint</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#text-font">‑text‑font</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#texture">‑texture</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#threshold">‑threshold</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#thumbnail">‑thumbnail</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#tile">‑tile</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#tile-offset">‑tile‑offset</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#tint">‑tint</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#title">‑title</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#transform">‑transform</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#transparent">‑transparent</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#transparent-color">‑transparent‑color</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#transpose">‑transpose</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#transverse">‑transverse</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#treedepth">‑treedepth</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#trim">‑trim</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#type">‑type</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#undercolor">‑undercolor</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#unique-colors">‑unique‑colors</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#units">‑units</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#unsharp">‑unsharp</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#update">‑update</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#verbose">‑verbose</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#version">‑version</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#view">‑view</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#vignette">‑vignette</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#virtual-pixel">‑virtual‑pixel</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#visual">‑visual</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#watermark">‑watermark</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#wave">‑wave</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#weight">‑weight</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#white-point">‑white‑point</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#white-threshold">‑white‑threshold</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#window">‑window</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#window-group">‑window‑group</a> <span class='bull'> • </span> <a href="../www/command-line-options.html#write">‑write</a> ]
151
<p>Below is list of command-line options recognized by the ImageMagick <a href="../www/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
152
<a href="../www/convert.html">convert</a>, <a href="../www/mogrify.html">mogrify</a>, and .... </p>
154
<div style="margin: auto;">
155
<h4><a name="adaptive-blur" id="adaptive-blur"></a>-adaptive-blur <em class="arg">radius</em>[x<em class="arg">sigma</em>]</h4>
158
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Adaptively blur pixels, with decreasing effect near edges.</td><td style='text-align:right;'></td></tr></table>
160
<p>A Gaussian operator of the given radius and standard deviation (<em class="arg">sigma</em>) is used. If <em class="arg">sigma</em> is not given it defaults to 1.</p>
162
<div style="margin: auto;">
163
<h4><a name="adaptive-resize" id="adaptive-resize"></a>-adaptive-resize <em class="arg">geometry</em></h4>
166
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Resize the image using data-dependent triangulation.</td><td style='text-align:right;'></td></tr></table>
168
<p>See <a href="../www/command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. The <a href="#adaptive-resize">-adaptive-resize</a> option defaults to data-dependent triangulation. Use the <a href="#filter">-filter</a> to choose a different resampling algorithm. Offsets, if present in the geometry string, are ignored, and the <a href="#gravity">-gravity</a> option has no effect.</p>
170
<div style="margin: auto;">
171
<h4><a name="adaptive-sharpen" id="adaptive-sharpen"></a>-adaptive-sharpen <em class="arg">radius</em>[x<em class="arg">sigma</em>]</h4>
174
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Adaptively sharpen pixels, with increasing effect near edges.</td><td style='text-align:right;'></td></tr></table>
176
<p>A Gaussian operator of the given radius and standard deviation (<em class="arg">sigma</em>) is used. If <em class="arg">sigma</em> is not given it defaults to 1.</p>
129
178
<div style="margin: auto;">
130
179
<h4><a name="adjoin" id="adjoin"></a>-adjoin</h4>
133
<p>join images into a single multi-image file.</p>
135
<p>Enabled by default. <a href="#adjoin">-adjoin</a> will try to save all
136
images of an image sequence in the same file. </p>
138
<p>However, some formats, such as JPEG, and PNG, do not support more than one
139
image per file and IM is forced to write each image into separate files. As
140
such if more than one image needs to be written, the filename given will be
141
modified with a <A HREF="#scene" >-scene</A> number added before the
142
suffix, to made multiple filenames, one for each image. </p>
144
<p>You can use <a href="#adjoin">+adjoin</a> to force each image to be written
145
into separate files regardless of if the file format allows multiple images
146
per file (for example GIF, MIFF, and TIFF). </p>
148
<p>Adding a '<kbd>%d</kbd>' (as per the <kbd>printf()</kbd>' library function)
149
to the output filename, defining the placement of the <A HREF="#scene"
150
>-scene</A> number, will also automatically enable saving images to one image
153
<p>In summary, ImageMagick trys to write all images to one file, but will use
154
multiple files if either: image file format does not allow multi-image files,
155
a <a href="#adjoin">+adjoin</a> setting is given, or a '<kbd>%d</kbd>' is
182
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Join images into a single multi-image file.</td><td style='text-align:right;'></td></tr></table>
184
<p>This option is enabled by default. An attempt will be made to save all
185
images of an image sequence into the given output file.
186
However, some formats, such as JPEG and PNG, do not support more than one
187
image per file, and in that case IM is forced to write each image as a separate file. As
188
such, if more than one image needs to be written, the filename given will be
189
modified by adding a <a href="#scene">-scene</a> number before the
190
suffix, in order to make distinct names for each image. </p>
192
<p>Use <a href="#adjoin">+adjoin</a> to force each image to be written
193
to separate files, whether or not the file format allows multiple images
194
per file (for example, GIF, MIFF, and TIFF). </p>
196
<p>Including a C-style integer format string in the output filename will automatically enable <a href="#adjoin">+adjoin</a> and are used to specify where the <a href="#scene">-scene</a> number is placed in the filenames. These strings, such as '<kbd>%d</kbd>' or '<kbd>%03d</kbd>', are familiar to those who have used the standard <kbd>printf()</kbd>' C-library function. As an example, the command</p>
198
<p class='crt'><span class="crtprompt"> $magick> </span><span class='crtin'>convert logo: rose: -morph 15 my%02dmorph.jpg</span></p>
199
<p>will create a sequence of 17 images named my00morph.jpg, my01morph.jpg, my02morph.jpg, ..., my16morph.jpg.
202
<p>In summary, ImageMagick tries to write all images to one file, but will use
203
multiple files if either (1) the output image's file format does not allow multi-image files,
204
(2) the <a href="#adjoin">+adjoin</a> option is given, or (3) a C-style integer format string is
156
205
present in the output filename. </p>
159
208
<div style="margin: auto;">
160
<h4><a name="affine" id="affine"></a>-affine <em class="option">matrix</em></h4>
163
<p>Set the drawing transformation matrix.</p>
165
<p>This option provides a transformation matrix {<em class="option">s<sub>x</sub></em>, <em class="option">r<sub>x</sub></em>, <em class="option">r<sub>y</sub></em>, <em class="option">s<sub>y</sub></em>, <em class="option">t<sub>x</sub></em>, <em class="option">t<sub>y</sub></em>} for use by subsequent <a href="#draw">-draw</a> or <a href="#transform">-transform</a> options.</p>
167
<p>The transformation matrix has 3x3 elements, but three of them are omitted from the input because they are constant. The new coordinate { <em class="option">x<sup>'</sup></em>, <em class="option">y<sup>'</sup></em> } of a pixel {<em class="option">x</em>, <em class="option">y</em>} in the transformed image is calculated using the following matrix equation:</p>
170
| s<sub>x</sub> r<sub>x</sub> 0 |
171
{ x<sup>'</sup> y<sup>'</sup> 1 } = { x y 1 } * | r<sub>y</sub> s<sub>y</sub> 0 |
172
| t<sub>x</sub> t<sub>y</sub> 1 |
175
<p>The size of the resulting image is set so that the rotated and scaled source image is exactly contained within the new image area. The <em class="option">t<sub>x</sub></em> and <em class="option">t<sub>y</sub></em> parameters subsequently shift the image pixels so that those that are moved out of the image areare cut off.</p>
177
<p>As do the pixel coordinates, the transform matrix uses a left-handed coordinate system (positive direction is rightward resp. downward; positive rotation is clockwise).</p>
179
<p>Scaling by the factor <em class="option">s</em> is accomplished with the matrix:</p>
185
<p>Translation by a displacement {<em class="option">d<sub>x</sub></em>, <em class="option">d<sub>y</sub></em>} is accomplished with the matrix:</p>
188
{1, 0, 0, 1, d<sub>x</sub>, d<sub>y</sub>}
191
<p>Rotation clockwise about the origin by an angle <em class="option">a</em> is accomplished with the matrix:</p>
194
{cos(a), sin(a), -sin(a), cos(a), 0, 0}
197
<p>A series of operations can be accomplished by using a matrix that is the multiple of the matrices for each operation.</p>
209
<h4><a name="affine" id="affine"></a>-affine <em class="arg">s<sub>x</sub></em>,<em class="arg">r<sub>x</sub></em>,<em class="arg">r<sub>y</sub></em>,<em class="arg">s<sub>y</sub></em>,<em class="arg">t<sub>x</sub></em>,<em class="arg">t<sub>y</sub></em><br/>
210
-affine <em class="arg">s<sub>x</sub></em>,<em class="arg">r<sub>x</sub></em>,<em class="arg">r<sub>y</sub></em>,<em class="arg">s<sub>y</sub></em></h4>
213
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the drawing transformation matrix for combined rotating and scaling.</td><td style='text-align:right;'></td></tr></table>
215
<p>This option sets a transformation matrix, encoded as (<em class="arg">s<sub>x</sub></em>, <em class="arg">r<sub>x</sub></em>, <em class="arg">r<sub>y</sub></em>, <em class="arg">s<sub>y</sub></em>, <em class="arg">t<sub>x</sub></em>, <em class="arg">t<sub>y</sub></em>), for use by subsequent <a href="#draw">-draw</a> or <a href="#transform">-transform</a> options.</p>
217
<p>The matrix entries are entered as comma-separated numeric values <i>with no spaces</i>. </p>
219
<p>Internally, the transformation matrix has 3x3 elements, but three of them are omitted from the input because they are constant. The new (transformed) coordinates (<em class="arg">x'</em>, <em class="arg">y'</em>) of a pixel at position (<em class="arg">x</em>, <em class="arg">y</em>) in the original image are calculated using the following matrix equation.</p>
222
<img alt="affine transformation" src="../images/affine.png"/>
226
The size of the resulting image is that of the smallest rectangle that contains the transformed source image. The parameters <em class="arg">t<sub>x</sub></em> and <em class="arg">t<sub>y</sub></em> subsequently shift the image pixels so that those that are moved out of the image area are cut off.</p>
228
<p>The transformation matrix complies with the left-handed pixel coordinate system: positive <em class="arg">x</em> and <em class="arg">y</em> directions are rightward and downward, resp.; positive rotation is clockwise.</p>
230
<p> If the translation coefficients <em class="arg">t<sub>x</sub></em> and <em class="arg">t<sub>y</sub></em> are omotted they default to 0,0. Therefore, four parameters suffice for rotation and scaling without translation.</p>
232
<p>Scaling by the factors <em class="arg">s<sub>x</sub></em> and <em class="arg">s<sub>y</sub></em> in the <em>x</em> and <em>y</em> directions, respectively, is accomplished with the following.</p>
235
-affine <em class="arg">s<sub>x</sub></em>,0,0,<em class="arg">s<sub>y</sub></em>
238
<p>Translation by a displacement (<em class="arg">t<sub>x</sub></em>, <em class="arg">t<sub>y</sub></em>) is accomplished like so:</p>
241
-affine 1,0,0,1,<em class="arg">t<sub>x</sub></em>,<em class="arg">t<sub>y</sub></em>
244
<p>Rotate clockwise about the origin (the upper left-hand corner) by an angle <em>a</em> by letting
245
<em>c</em> = cos(<em>a</em>), <em>s</em> = sin(<em>a</em>), and using the following.</p>
248
-affine <em>c</em>,<em>s</em>,-<em>s</em>,<em>c</em>
251
<p>The cumulative effect of a sequence of <a href="#affine" >-affine</a> transformations can be accomplished by instead by a single <a href="#affine" >-affine</a> operation using the matrix equal to the product of the matrices of the individual transformations.</p>
253
<p>An attempt is made to detect near-singular transformation matrices. If the matrix determinant has a sufficiently small absolute value it is rejected.</p>
199
255
<div style="margin: auto;">
200
<h4><a name="alpha" id="alpha"></a>-alpha <em class="option">type</em></h4>
256
<h4><a name="alpha" id="alpha"></a>-alpha <em class="arg">type</em></h4>
203
<p>control of and special operations involving the alpha/matte channel of an
206
<p>Alpha sets a flag on an image indicating whether or not to use alpha
207
channel data. But also will perform other operations specific to the control
208
of the alpha or transparency channel. Choose from these options:</p>
211
<table id="table" cellpadding="2" cellspacing="0" style="width: 93%">
259
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Gives control of the alpha/matte channel of an image.</td><td style='text-align:right;'></td></tr></table>
261
<p>Used to set a flag on an image indicating whether or not to use existing alpha
262
channel data, to create an alpha channel, or to perform other operations on the alpha channel. Choose the argument <em class="arg">type</em> from the list below.</p>
213
267
<tr valign="top">
214
268
<th align="left" style="width: 8%">type</th>
283
<p>Note that while <a href="#matte" >+matte</a> operation is the same as a
336
<p>Note that while the <a href="#matte" >+matte</a> operation is the same as
284
337
"<kbd><a href="#alpha" >-alpha</a> off</kbd>", the <a href="#matte"
285
>-matte</a> operation is as "<kbd><a href="#alpha" >-alpha</a> set</kbd>" and
286
not "<kbd><a href="#alpha" >-alpha</a> on</kbd>". That is it will ensure the
287
image remains '<kbd>opaque</kbd>' if the given image had no transparency
288
channel enabled, regardless if old existing transparency data is present. </p>
338
>-matte</a> operation is the same as "<kbd><a href="#alpha" >-alpha</a> set</kbd>" and
339
not "<kbd><a href="#alpha" >-alpha</a> on</kbd>".
340
That is, "<kbd><a href="#alpha" >-alpha</a> set</kbd>" will ensure that the
341
written image is opaque if the original image had no transparency
342
channel enabled, regardless if transparency data is already present. </p>
291
345
<div style="margin: auto;">
292
<h4><a name="annotate" id="annotate"></a>-annotate <em class="option">x-rotate</em> <em class="option">text</em><br />-annotate <em class="option">x-rotate</em>x<em class="option">y-rotate</em>{+-}<em class="option">x</em>{+-}<em class="option">y text</em></h4>
346
<h4><a name="annotate" id="annotate"></a>
347
-annotate <em class="arg">degrees</em> <em class="arg">text</em><br />
348
-annotate <em class="arg">Xdegrees</em>x<em class="arg">Ydegrees</em> <em class="arg">text</em><br />
349
-annotate <em class="arg">Xdegrees</em>x<em class="arg">Ydegrees</em> {+-}<em class="arg">t<sub>x</sub></em>{+-}<em class="arg">t<sub>y</sub></em> <em class="arg">text</em></h4>
295
<p>annotate an image with text.</p>
297
<p>This a convenience option for annotating your image with text. For more precise control over your text annotations, use <a href="#draw">-draw</a>.</p>
299
<p><em class="option">X-rotate</em> and <em class="option">Y-rotate</em> give the angle of the text and <em class="option">x</em> and <em class="option">y</em> are offsets that give the location of the text relative to the upper left corner of the image.</p>
301
<p>If the first character of <em class="option">text</em> is <kbd>@</kbd>, the text is read from a file titled by the remaining characters in the string. Text in a file are literal, no embedded formatting characters are recognized.</p>
352
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Annotate an image with text.</td><td style='text-align:right;'></td></tr></table>
354
<p>This is a convenience for annotating an image with text. For more precise control over text annotations, use <a href="#draw">-draw</a>.</p>
357
<p>The values <em class="arg">Xdegrees</em> and <em class="arg">Ydegrees</em> control the shears with respect to the , respectively, applied to the text, while <em class="arg">t<sub>x</sub></em> and <em class="arg">t<sub>y</sub></em> are offsets that give the location of the text relative to the upper left corner of the image.</p>
359
<p>Using <a href="#annotate">-annotate</a> <em class="arg">degrees</em> or <a href="#annotate">-annotate</a> <em class="arg">degrees</em>x<em class="arg">degrees</em> produces an unsheared rotation of the text. The direction of the rotation is positive, which means a clockwise rotation if <em class="arg">degrees</em> is positive. (This conforms to the usual mathematical convention once it is realized that the positive <em>y</em>–direction is conventionally considered to be <em>downward</em> for images.)</p>
361
<p>The new (transformed) coordinates (<em class="arg">x'</em>, <em class="arg">y'</em>) of a pixel at position (<em class="arg">x</em>, <em class="arg">y</em>) in the image are calculated using the following matrix equation.</p>
362
<div class="eqn"><img alt="annotate transformation" src="../images/annotate.png"/></div>
364
<p>If <em class="arg">t<sub>x</sub></em> and <em class="arg">t<sub>y</sub></em> are omitted, they default to 0. This makes the bottom-left of the text becomes the upper-left corner of the image, which is probably undesirable. Adding a <a href="#gravity" >-gravity</a> option in this case leads to nice results.</p>
366
<p>If <em class="arg">text</em> is of the form '@mytext.txt', the text is read from the file 'mytext.txt'. Text in a file is taken literally; no embedded formatting characters are recognized.</p>
303
368
<div style="margin: auto;">
304
369
<h4><a name="antialias" id="antialias"></a>-antialias</h4>
307
<p>remove pixel aliasing.</p>
372
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Remove pixel aliasing.</td><td style='text-align:right;'></td></tr></table>
309
<p>By default, objects are antialiased when drawn (e.g. lines, polygon, etc.). Use <a href="#antialias">+antialias</a> to disable antialiasing. Without antialiasing, you can avoid increasing the unique colors in an image, draw fixed width lines, or improve the rendering speed.</p>
374
<p>By default, objects (e.g. lines, polygon, etc.) are antialiased when drawn. Use <a href="#antialias">+antialias</a> to disable antialiasing. By disabling antialiasing, an increase in the number of unique colors in an image can be avoided, fixed-width lines can be drawn, and rendering speed can be improved.</p>
311
376
<div style="margin: auto;">
312
377
<h4><a name="append" id="append"></a>-append</h4>
315
<p>append a set of images.</p>
317
<p>This option creates a single image where the images in the original set are stacked top-to-bottom. If they are not of the same width, any narrow images will be expanded to fit using the current <a href="#background">-background</a> color setting. Use <a href="#append">+append</a> to stack images left-to-right. The set of images is terminated by the appearance of any option. If the <a href="#append">-append</a> option appears after all of the input images, all images are appended.</p>
319
<div style="margin: auto;">
320
<h4><a name="attenuate" id="attenuate"></a>-attenuate <em class="option">value</em></h4>
323
<p>lessen (or intensify) when adding noise to an image.</p>
325
<div style="margin: auto;">
326
<h4><a name="authenticate" id="authenticate"></a>-authenticate <em class="option">password</em></h4>
329
<p>decipher image with this password.</p>
331
<p>Use this option to supply a password for decipher an image or an image sequence, if it is being read from a format such as PDF that supports enciphering. Enciphering images being written is not supported.</p>
380
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Stack a set of images.</td><td style='text-align:right;'></td></tr></table>
382
<p>This option creates a single image where the images in the original set are stacked top-to-bottom. If they are not of the same width, narrower images will be padded with the current <a href="#background">-background</a> color setting. Use <a href="#append">+append</a> to stack images left-to-right. The set of images is terminated by the appearance of any option. If the <a href="#append">-append</a> option appears after all of the input images, all images are stacked.</p>
384
<div style="margin: auto;">
385
<h4><a name="attenuate" id="attenuate"></a>-attenuate <em class="arg">value</em></h4>
388
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Lessen (or intensify) when adding noise to an image.</td><td style='text-align:right;'></td></tr></table>
390
<div style="margin: auto;">
391
<h4><a name="authenticate" id="authenticate"></a>-authenticate <em class="arg">password</em></h4>
394
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Decrypt a PDF with a password.</td><td style='text-align:right;'></td></tr></table>
396
<p>Use this option to supply a <em class="arg">password</em> for decrypting a PDF that has been encrypted using Microsoft Crypto API (MSC API). The encrypting using the MSC API is not supported.</p>
398
<p>For a different encryption method, see <a href="#encipher">-encipher</a> and <a href="#decipher">-decipher</a>. </p>
333
400
<div style="margin: auto;">
334
401
<h4><a name="auto-orient" id="auto-orient"></a>-auto-orient</h4>
337
<p>automatically orient (rotate) image from a digital camera.</p>
404
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Automatically orient (rotate) an image created by a digital camera.</td><td style='text-align:right;'></td></tr></table>
339
406
<div style="margin: auto;">
340
407
<h4><a name="average" id="average"></a>-average</h4>
343
<p>average a set of images.</p>
345
<p>The set of images is terminated by the appearance of any option. If the <a href="#average">-average</a> option appears after all of the input images, all images are averaged.</p>
410
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Average a set of images.</td><td style='text-align:right;'></td></tr></table>
412
<p>An error results if the images are not identically sized.</p>
414
<p>The sequence of images is terminated by the appearance of any option. If the <a href="#average">-average</a> option appears after all of the input images, all images are averaged.</p>
347
416
<div style="margin: auto;">
348
<h4><a name="backdrop" id="backdrop"></a>-backdrop <em class="option">color</em></h4>
417
<h4><a name="backdrop" id="backdrop"></a>-backdrop <em class="arg">color</em></h4>
351
<p>display the image centered on a backdrop.</p>
420
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Display the image centered on a backdrop.</td><td style='text-align:right;'>[<a href="../www/animate.html">animate</a>, <a href="../www/display.html">display</a>]</td></tr></table>
353
422
<p>This backdrop covers the entire workstation screen and is useful for hiding other X window activity while viewing the image. The color of the backdrop is specified as the background color. The color is specified using the format described under the <a href="#fill">-fill</a> option.</p>
355
424
<div style="margin: auto;">
356
<h4><a name="background" id="background"></a>-background <em class="option">color</em></h4>
359
<p>the background color.</p>
361
<p>The color is specified using the format described under the <a href="#fill">-fill</a> option.</p>
364
<div style="margin: auto;">
365
<div style="margin: auto;">
366
<h4><a name="bench" id="bench"></a>-bench <em class="option">iterations</em></h4>
369
<p>measure performance.</p>
371
<h4><a name="bias" id="bias"></a>-bias <em class="option">value</em>{<em class="option">%</em>}</h4>
374
<p>add bias when convolving an image.</p>
425
<h4><a name="background" id="background"></a>-background <em class="arg">color</em></h4>
428
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the background color.</td><td style='text-align:right;'></td></tr></table>
430
<p>The color is specified using the format described under the <a href="#fill">-fill</a> option. The default background color (if none is specified or found in the image) is white.</p>
432
<div style="margin: auto;">
433
<h4><a name="bench" id="bench"></a>-bench <em class="arg">iterations</em></h4>
436
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Measure performance.</td><td style='text-align:right;'></td></tr></table>
438
<p>Repeat the entire command for the given number of <em class="arg">iterations</em> and report the user-time and elapsed time. For instance, consider the following command and its output.</p>
440
<p class='crt'><span class="crtprompt"> $magick> </span><span class='crtin'>convert logo: -resize 1000% -bench 5 biglogo.png</span><span class='crtout'>Performance: 5i 0.0539724ips 91.750u 2:33</span></p>
441
<p>In this example, 5 iterations were completed at 0.0539724 iterations per second, using 91.750 seconds of the user's allotted time, for a total elapsed time of 2 minutes and 33 seconds.</p>
443
<div style="margin: auto;">
444
<h4><a name="bias" id="bias"></a>-bias <em class="arg">value</em>{<em class="arg">%</em>}</h4>
447
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Add bias when convolving an image.</td><td style='text-align:right;'></td></tr></table>
449
<p>This option shifts the output of <a href="../www/command-line-options.html#convolve">‑convolve</a> so that positive and negative results are relative to the specified bias value. </p>
451
<p>This is important for non-HDRI compilations of ImageMagick when dealing with convolutions that contain negative as well as positive values. This is especially the case with convolutions involving high pass filters or edge detection. Without an output bias, the negative values will be clipped at zero.</p>
453
<p>When using an IM with the HDRI compile-time setting, <a href="../www/command-line-options.html#bias">‑bias</a> is not needed,
454
as IM will be able to store/handle any negative results without
455
clipping to the color value range (0..QuantumRange).</p>
457
<p>See the discussion on HDRI implementations of ImageMagick on the page
458
<a href="/www/high-dynamic-range.html">High Dynamic-Range Images</a>. For more about HDRI go the ImageMagick <a href="http://www.imagemagick.org/Usage/basics/#hdri">Usage</a> pages or this <a href="http://en.wikipedia.org/wiki/High_dynamic_range_imaging">Wikipedia</a> entry.
376
461
<div style="margin: auto;">
377
462
<h4><a name="black-point-compensation" id="black-point-compensation"></a>-black-point-compensation</h4>
380
<p>use black point compensation.</p>
382
<div style="margin: auto;">
383
<h4><a name="black-threshold" id="black-threshold"></a>-black-threshold <em class="option">threshold</em></h4>
386
<p>force all pixels at or below the threshold into black while leaving all pixels above the threshold unchanged.</p>
388
<div style="margin: auto;">
389
<h4><a name="blue-primary" id="blue-primary"></a>-blue-primary <em class="option">x</em>,<em class="option">y</em></h4>
392
<p>blue chromaticity primary point.</p>
394
<div style="margin: auto;">
395
<h4><a name="blur" id="blur"></a>-blur <em class="option">radius</em><br />-blur <em class="option">radius</em>x<em class="option">sigma</em></h4>
398
<p>reduce image noise and reduce detail levels.</p>
465
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Use black point compensation.</td><td style='text-align:right;'></td></tr></table>
467
<div style="margin: auto;">
468
<h4><a name="black-threshold" id="black-threshold"></a>-black-threshold <em class="arg">threshold</em></h4>
471
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Force to black all pixels at or below the threshold while leaving all pixels above the threshold unchanged.</td><td style='text-align:right;'></td></tr></table>
474
<div style="margin: auto;">
475
<h4><a name="blend" id="blend"></a>-blend <em class="arg">percent</em></h4>
478
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>blend an image into another by the given percent.</td><td style='text-align:right;'>[<a href="../www/composite.html">composite</a>]</td></tr></table>
480
<p>If only a single percentage value is given, it is used as the dissolve percentage for the overlay, while the background image is dissolved by the exact opposite amount. That is a <kbd>-blend 30</kbd> dissolves the overlay by 30%, and the background by 70% before the two images are added together. thus it is equivalent to <kbd>-blend 30x70</kbd>.</p>
482
<div style="margin: auto;">
483
<h4><a name="blue-primary" id="blue-primary"></a>-blue-primary <em class="arg">x</em>,<em class="arg">y</em></h4>
486
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the blue chromaticity primary point.</td><td style='text-align:right;'></td></tr></table>
488
<div style="margin: auto;">
489
<h4><a name="blur" id="blur"></a>-blur <em class="arg">radius</em><br />-blur <em class="arg">radius</em>x<em class="arg">sigma</em></h4>
492
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Reduce image noise and reduce detail levels.</td><td style='text-align:right;'></td></tr></table>
400
494
<p>Convolve the image with a Gaussian or normal distribution. The formula is:</p>
401
<ul><dd><img alt="gaussian distribution" width="243px" height="42px" src="../images/gaussian-blur.png"/></dd></ul>
402
<p>where <i>r</i> is the blur radius (<i>r</i><sup>2</sup> = <i>u</i><sup>2</sup> + <i>v</i><sup>2</sup>), and σ is the standard deviation of the Gaussian distribution. As a guideline, set <i>r</i> to approximately 3σ. Specify a radius of 0 and ImageMagick selects a suitable radius for you.</p>
404
<p>This option differs from <a href="#gaussian-blur">-gaussian-blur</a> simply by taking advantage of the linear separable properties of the distribution. Here we apply a single-dimensional Gaussian matrix in the horizontal direction, then repeat the process in the vertical direction.</p>
406
<div style="margin: auto;">
407
<h4><a name="border" id="border"></a>-border <em class="option">width</em><br />-border <em class="option">width</em>x<em class="option">height</em></h4>
410
<p>surround the image with a border of color.</p>
412
<p>See <a href="#resize">-resize</a> for details about the geometry specification.</p>
414
<div style="margin: auto;">
415
<h4><a name="bordercolor" id="bordercolor"></a>-bordercolor <em class="option">color</em></h4>
418
<p>the border color.</p>
496
<div class="eqn"><img alt="gaussian distribution" width="243px" height="42px" src="../images/gaussian-blur.png"/>
499
<p>where <i>r</i> is the blur radius (<i>r</i><sup>2</sup> = <i>u</i><sup>2</sup> + <i>v</i><sup>2</sup>), and σ is the standard deviation of the Gaussian distribution. As a guideline, set <i>r</i> to approximately 3σ. If a radius of 0 is specified, ImageMagick selects a suitable radius for you.</p>
501
<p>This option differs from <a href="#gaussian-blur">-gaussian-blur</a> simply by taking advantage of the separability properties of the distribution. Here we apply a single-dimensional Gaussian matrix in the horizontal direction, then repeat the process in the vertical direction.</p>
503
<div style="margin: auto;">
504
<h4><a name="border" id="border"></a>-border <em class="arg">geometry</em></h4>
507
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Surround the image with a border of color. </td><td style='text-align:right;'></td></tr></table>
509
<p>Set the width and height using the <em class="arg">size</em> portion of the <em class="arg">gravity</em> argument. See <a href="../www/command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. Offsets are ignored. </p>
511
<p>Set the border color by preceding with the <a href="#bordercolor">-bordercolor</a> setting.</p>
513
<p>See also the <a href="#frame">-frame</a> option, which has more functionality.</p>
515
<div style="margin: auto;">
516
<h4><a name="bordercolor" id="bordercolor"></a>-bordercolor <em class="arg">color</em></h4>
519
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the border color.</td><td style='text-align:right;'>[<a href="../www/import.html">import</a>]</td></tr></table>
420
521
<p>The color is specified using the format described under the <a href="#fill">-fill</a> option.</p>
422
<div style="margin: auto;">
423
<h4><a name="borderwidth" id="borderwidth"></a>-borderwidth <em class="option">geometry</em></h4>
426
<p>the border width.</p>
428
<div style="margin: auto;">
429
<h4><a name="cache" id="cache"></a>-cache <em class="option">threshold</em></h4>
432
<p>(This option has been replaced by the <a href="#limit">-limit</a> option).</p>
434
<div style="margin: auto;">
435
<h4><a name="caption" id="caption"></a>-caption <em class="option">string</em></h4>
438
<p>assign a caption to an image.</p>
440
<div style="margin: auto;">
441
<h4><a name="channel" id="channel"></a>-channel <em class="option">type</em></h4>
444
<p>define the image color channels later operators may be limited to.</p>
523
<p>The default border color is <kbd>#DFDFDF</kbd>, <span style="background-color: #dfdfdf;">this shade of gray</span>.</p>
525
<div style="margin: auto;">
526
<h4><a name="borderwidth" id="borderwidth"></a>-borderwidth <em class="arg">geometry</em> </h4>
529
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the border width.</td><td style='text-align:right;'>[<a href="../www/animate.html">animate</a>, <a href="../www/display.html">display</a>]</td></tr></table>
531
<div style="margin: auto;">
532
<h4><a name="cache" id="cache"></a>-cache <em class="arg">threshold</em></h4>
535
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>(This option has been replaced by the <a href='#limit'>-limit</a> option.)</td><td style='text-align:right;'></td></tr></table>
537
<div style="margin: auto;">
538
<h4><a name="caption" id="caption"></a>-caption <em class="arg">string</em></h4>
541
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Assign a caption to an image.</td><td style='text-align:right;'></td></tr></table>
543
<div style="margin: auto;">
544
<h4><a name="channel" id="channel"></a>-channel <em class="arg">type</em></h4>
547
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Specify those image color channels to which subsequent operators will be limited.</td><td style='text-align:right;'></td></tr></table>
446
549
<p>Choose from: <kbd>Red</kbd>, <kbd>Green</kbd>, <kbd>Blue</kbd>, <kbd>Alpha</kbd>, <kbd>Cyan</kbd>, <kbd>Magenta</kbd>, <kbd>Yellow</kbd>, <kbd>Black</kbd>, <kbd>Opacity</kbd>, <kbd>Index</kbd>, <kbd>RGB</kbd>, <kbd>RGBA</kbd>, <kbd>CMYK</kbd>, or <kbd>CMYKA</kbd>.</p>
448
<p>To print a complete list of channel types, use the <a href="#list">-list channel</a> option.</p>
551
<p>To print a complete list of channel types, use <a href="#list">-list channel</a>.</p>
450
<p>You can specify the above as a comma separated list of channels, or
451
concatenate the letters '<kbd>R</kbd>', '<kbd>G</kbd>', '<kbd>B</kbd>',
553
<p>The channels above can be specified as a comma-separated list or can be abbreviated as a
554
concatenation of the letters '<kbd>R</kbd>', '<kbd>G</kbd>', '<kbd>B</kbd>',
452
555
'<kbd>A</kbd>', '<kbd>O</kbd>', '<kbd>C</kbd>', '<kbd>M</kbd>', '<kbd>Y</kbd>',
453
'<kbd>K</kbd>', to specify specific multiple channels for later operators to be
456
For example to only negate the alpha channel of an image, use</p>
558
For example, to negate only the alpha channel of an image, use</p>
458
560
-channel Alpha -negate
461
<p>By default, ImageMagick sets <a href="#channel" >"-channel</a> to the value
462
'<kbd>RGB</kbd>' to limit channel affected operators to all channels, except
463
the opacity channel, in an image. Using the option <a href="#channel" >"+channel</a> will reset the value back to this default. </p>
465
<p>Operators that are affected by the <a href="#channel" >"-channel</a>
467
<a href="#blur" >"-blur</a>,
468
<a href="#combine" >"-combine</a>,
469
<a href="#contrast-stretch" >"-contrast-stretch</a>,
470
<a href="#evaluate" >"-evaluate</a>,
471
<a href="#fx" >"-fx</a>,
472
<a href="#gaussian-blur" >"-gaussian-blur</a>,
473
<a href="#motion-blur" >"-motion-blur</a>,
474
<a href="#negate" >"-negate</a>,
475
<a href="#normalize" >"-normalize</a>,
476
<a href="#ordered-dither" >"-ordered-dither</a>,
477
<a href="#radial-blur" >"-radial-blur</a>,
478
<a href="#random-threshold" >"-random-threshold</a>,
479
<a href="#separate" >"-separate</a>,
480
and <a href="#threshold" >-threshold</a>. </p>
483
<div style="margin: auto;">
484
<h4><a name="charcoal" id="charcoal"></a>-charcoal <em class="option">factor</em></h4>
487
<p>simulate a charcoal drawing.</p>
489
<div style="margin: auto;">
490
<h4><a name="chop" id="chop"></a>-chop <em class="option">width</em>x<em class="option">height</em>{<em class="option">+-</em>}<em class="option">x</em>{<em class="option">+-</em>}<em class="option">y</em>{<em class="option">%</em>}</h4>
493
<p>remove pixels from the interior of an image.</p>
495
<p><em class="option">Width</em> and <em class="option">height</em> give the number of columns and rows to remove, and <em class="option">x</em> and <em class="option">y</em> are offsets that give the location of the leftmost column and topmost row to remove.</p>
497
<p>The <kbd class="option">x</kbd> offset normally specifies the leftmost column to remove. If the <a href="#gravity">-gravity</a> option is present with <kbd>NorthEast</kbd>, <kbd>East</kbd>, or <kbd>SouthEast</kbd> gravity, it gives the distance leftward from the right edge of the image to the rightmost column to remove. Similarly, the <kbd class="option">y</kbd> offset normally specifies the topmost row to remove, but if the <a href="#gravity">-gravity</a> option is present with <kbd>SouthWest</kbd>, <kbd>South</kbd>, or <kbd>SouthEast</kbd> gravity, it specifies the distance upward from the bottom edge of the image to the bottom row to remove.</p>
499
<p>The <a href="#chop">-chop</a>option removes entire rows and columns, and moves the remaining corner blocks leftward and upward to close the gaps.</p>
563
<p>By default, ImageMagick sets <a href="#channel">-channel</a> to the value
564
'<kbd>RGB</kbd>', which specifies that operators act on all channels except
565
the opacity channel. Using the option <a href="#channel" >+channel</a> will reset the value back to this default. </p>
567
<p>Operators that are affected by the <a href="#channel" >-channel</a>
568
setting include the following.
569
<a href="#black-threshold">-black-threshold</a>,
570
<a href="#blur">-blur</a>,
571
<a href="#clut">-clut</a>,
572
<a href="#combine">-combine</a>,
573
<a href="#contrast-stretch">-contrast-stretch</a>,
574
<a href="#evaluate">-evaluate</a>,
575
<a href="#function">-function</a>,
576
<a href="#fx">-fx</a>,
577
<a href="#gaussian-blur">-gaussian-blur</a>,
578
<a href="#motion-blur">-motion-blur</a>,
579
<a href="#negate">-negate</a>,
580
<a href="#normalize">-normalize</a>,
581
<a href="#ordered-dither">-ordered-dither</a>,
582
<a href="#radial-blur">-radial-blur</a>,
583
<a href="#random-threshold">-random-threshold</a>,
584
<a href="#separate">-separate</a>, and
585
<a href="#white-threshold">-white-threshold</a>.
589
<div style="margin: auto;">
590
<h4><a name="charcoal" id="charcoal"></a>-charcoal <em class="arg">factor</em></h4>
593
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Simulate a charcoal drawing.</td><td style='text-align:right;'></td></tr></table>
595
<div style="margin: auto;">
596
<h4><a name="chop" id="chop"></a>-chop <em class="arg">geometry</em></h4>
599
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Remove pixels from the interior of an image.</td><td style='text-align:right;'></td></tr></table>
601
<p>See <a href="../www/command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. The <em class="arg">width</em> and <em class="arg">height</em> given in the of the <em class="arg">size</em> portion of the <em class="arg">geometry</em> argument give the number of columns and rows to remove. The <em class="arg">offset</em> portion of the <em class="arg">geometry</em> argument is influenced by a <a href="#gravity">-gravity</a> setting, if present.</p>
603
<p>The <a href="#chop">-chop</a> option removes entire rows and columns, and moves the remaining corner blocks leftward and upward to close the gaps.</p>
501
605
<div style="margin: auto;">
502
606
<h4><a name="clip" id="clip"></a>-clip</h4>
505
<p>apply the clipping path, if one is present.</p>
609
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Apply the clipping path if one is present.</td><td style='text-align:right;'></td></tr></table>
507
611
<p>If a clipping path is present, it will be applied to subsequent operations.</p>
509
<p>For example, if you type the following command:</p>
512
convert -clip -negate cockatoo.tif negated.tif
613
<p>For example, in the command</p>
615
<p class='crt'><span class="crtprompt"> $magick> </span><span class='crtin'>convert -clip -negate cockatoo.tif negated.tif</span></p>
515
616
<p>only the pixels within the clipping path are negated.</p>
517
618
<p>The <a href="#clip">-clip</a> feature requires the XML library. If the XML library is not present, the option is ignored.</p>
719
819
<tr><th align="left" valign="middle">YCC</th></tr>
720
820
<tr><td align="left" valign="middle">Y=(0.29900*R+0.58700*G+0.11400*B) (with complicated scaling); <em>intensity-like</em></td></tr>
721
<tr><td align="left" valign="middle">C1=(-0.29900*R-0.58700*G+0.88600*B) (with complicated scaling)</td></tr>
722
<tr><td align="left" valign="middle">C2=(0.70100*R-0.58700*G-0.11400*B) (with complicated scaling)</td></tr>
821
<tr><td align="left" valign="middle">C1=(−0.29900*R−0.58700*G+0.88600*B) (with complicated scaling)</td></tr>
822
<tr><td align="left" valign="middle">C2=(0.70100*R−0.58700*G−0.11400*B) (with complicated scaling)</td></tr>
724
824
<tr><th align="left" valign="middle">YCbCr</th></tr>
725
825
<tr><td align="left" valign="middle">Y=0.299000*R+0.587000*G+0.114000*B; <em>intensity-like</em></td></tr>
726
<tr><td align="left" valign="middle">Cb=(-0.168736*R-0.331264*G+0.500000*B)*(QuantumRange+1)/2</td></tr>
727
<tr><td align="left" valign="middle">Cr=(0.500000*R-0.418688*G-0.081312*B)*(QuantumRange+1)/2</td></tr>
826
<tr><td align="left" valign="middle">Cb=(−0.168736*R−0.331264*G+0.500000*B)*(<em class="QR">QuantumRange</em>+1)/2</td></tr>
827
<tr><td align="left" valign="middle">Cr=(0.500000*R−0.418688*G−0.081312*B)*(<em class="QR">QuantumRange</em>+1)/2</td></tr>
729
829
<tr><th align="left" valign="middle">YIQ</th></tr>
730
830
<tr><td align="left" valign="middle">Y=0.29900*R+0.58700*G+0.11400*B; <em>intensity-like</em></td></tr>
731
<tr><td align="left" valign="middle">I=(0.59600*R-0.27400*G-0.32200*B)*(QuantumRange+1)/2</td></tr>
732
<tr><td align="left" valign="middle">Q=(0.21100*R-0.52300*G+0.31200*B)*(QuantumRange+1)/2</td></tr>
831
<tr><td align="left" valign="middle">I=(0.59600*R−0.27400*G−0.32200*B)*(<em class="QR">QuantumRange</em>+1)/2</td></tr>
832
<tr><td align="left" valign="middle">Q=(0.21100*R−0.52300*G+0.31200*B)*(<em class="QR">QuantumRange</em>+1)/2</td></tr>
734
834
<tr><th align="left" valign="middle">YPbPr</th></tr>
735
835
<tr><td align="left" valign="middle">Y=0.299000*R+0.587000*G+0.114000*B; <em>intensity-like</em></td></tr>
736
<tr><td align="left" valign="middle">Pb=(-0.168736*R-0.331264*G+0.500000*B)*(QuantumRange+1)/2</td></tr>
737
<tr><td align="left" valign="middle">Pr=(0.500000*R-0.418688*G-0.081312*B)*(QuantumRange+1)/2</td></tr>
836
<tr><td align="left" valign="middle">Pb=(−0.168736*R−0.331264*G+0.500000*B)*(<em class="QR">QuantumRange</em>+1)/2</td></tr>
837
<tr><td align="left" valign="middle">Pr=(0.500000*R−0.418688*G−0.081312*B)*(<em class="QR">QuantumRange</em>+1)/2</td></tr>
739
839
<tr><th align="left" valign="middle">YUV</th></tr>
740
840
<tr><td align="left" valign="middle">Y=0.29900*R+0.58700*G+0.11400*B; <em>intensity-like</em></td></tr>
741
<tr><td align="left" valign="middle">U=(-0.14740*R-0.28950*G+0.43690*B)*(QuantumRange+1)/2</td></tr>
742
<tr><td align="left" valign="middle">V=(0.61500*R-0.51500*G-0.10000*B)*(QuantumRange+1)/2</td></tr>
841
<tr><td align="left" valign="middle">U=(−0.14740*R−0.28950*G+0.43690*B)*(<em class="QR">QuantumRange</em>+1)/2</td></tr>
842
<tr><td align="left" valign="middle">V=(0.61500*R−0.51500*G−0.10000*B)*(<em class="QR">QuantumRange</em>+1)/2</td></tr>
747
845
<div style="margin: auto;">
748
846
<h4><a name="combine" id="combine"></a>-combine</h4>
751
<p>combine one or more images into a single image.</p>
753
<p>The grayscale value of the pixels of each image in the sequence is assigned in order to the specified channels of the combined image. The typical ordering would be image 1 = Red, 2 = Green, 3 = Blue, etc.</p>
849
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Combine one or more images into a single image.</td><td style='text-align:right;'></td></tr></table>
851
<p>The channels (previously set by <a href="#channel">-channel</a>) of the combined image are taken from the grayscale values of each image in the sequence, in order. For the default -channel setting of <kbd>RGB</kbd>, this means the first image is assigned to the <kbd>Red</kbd> channel, the second to the <kbd>Green</kbd> channel, the third to the <kbd>Blue</kbd>.</p>
853
<p>This option can be thought of as the inverse to <a href="#separate">-separate</a>, so long as the channel settings are the same. Thus, in the following example, the final image should be a copy of the original.
856
<p class='crt'><span class="crtprompt"> $magick> </span><span class='crtin'>convert original.png -channel RGB -separate sepimage.png</span><span class='crtout'></span><span class="crtprompt"> $magick> </span><span class='crtin'>convert sepimage-0.png sepimage-1.png sepimage-2.png -channel RGB -combine imagecopy.png</span></p>
755
857
<div style="margin: auto;">
756
<h4><a name="comment" id="comment"></a>-comment<em class="option">string</em></h4>
858
<h4><a name="comment" id="comment"></a>-comment <em class="arg">string</em></h4>
759
<p>annotate an image with a comment.</p>
761
<p>Use this option to assign a specific comment to the image, when writing to an image format that supports comments. You can include the image filename, type, width, height, or other image attribute by embedding special format characters listed under the <a href="#format">-format</a> option. The comment is not drawn on the image, but is embedded in the image datastream via "Comment" tag or similar mechanism. If you want the comment to be visible on the image itself, use the <a href="#draw">-draw</a> option.</p>
861
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Embed a comment in an image.</td><td style='text-align:right;'></td></tr></table>
863
<p>This option places comments in a non-pixel portion of the image file. For a comment to be visibly written on the image itself, use the <a href="#annotate">-annotate</a> or <a href="#draw">-draw</a> options.</p>
865
<p>Use this option to assign a specific comment to the image, when writing to an image format that supports comments. You can include the image filename, type, width, height, or other image attribute by embedding special format characters listed under the <a href="#format">-format</a> option. The comment is not drawn on the image, but is embedded in the image datastream via "Comment" tag or similar mechanism. </p>
763
867
<p>For example,</p>
766
870
-comment "%m:%f %wx%h"
768
873
<p>produces an image comment of <kbd>MIFF:bird.miff 512x480</kbd> for an image titled <kbd>bird.miff</kbd> and whose width is 512 and height is 480.</p>
770
<p>If the first character of <em class="option">string</em> is <em class="option">@</em>, the image comment is read from a file titled by the remaining characters in the string. Comments in a file are literal, no embedded formatting characters are recognized.</p>
875
<p>If the first character of <em class="arg">string</em> is <em class="arg">@</em>, the image comment is read from a file titled by the remaining characters in the string. Comments in a file are literal; no embedded formatting characters are recognized.</p>
772
877
<div style="margin: auto;">
773
<h4><a name="compose" id="compose"></a>-compose <em class="option">operator</em></h4>
878
<h4><a name="compose" id="compose"></a>-compose <em class="arg">operator</em></h4>
776
<p>the type of image composition.</p>
778
<p>The description of composition uses abstract terminology in order to allow the description to be more clear, while avoiding constant values which are specific to a particular build configuration. Each image pixel is represented by red, green, and blue levels (which are equal for a gray pixel). QuantumRange is the maximum integral value which may be stored in the red, green, or blue channels of the image. Each image pixel may also optionally (if the image matte channel is enabled) have an associated level of opacity (ranging from opaque to transparent), which may be used to determine the influence of the pixel color when compositing the pixel with another image pixel. If the image matte channel is disabled, then all pixels in the image are treated as opaque. The color of an <em>opaque</em> pixel is fully visible while the color of a <em>transparent</em> pixel color is entirely absent (pixel color is ignored).</p>
780
<p>By definition, raster images have a rectangular shape. All image rows are of equal length, and all image columns have the same number of rows. By treating the alpha channel as a visual "mask" the rectangular image may be given a "shape" by treating the alpha channel as a cookie-cutter for the image. Pixels within the shape are opaque, while pixels outside the shape are transparent. Pixels on the boundary of the shape may be between opaque and transparent in order to provide antialiasing (visually smooth edges). The description of the composition operators use this concept of image "shape" in order to make the description of the operators easier to understand. While it is convenient to describe the operators in terms of "shapes" they are by no means limited to mask-style operations since they are based on continuous floating-point mathematics rather than simple boolean operations.</p>
881
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the type of image composition.</td><td style='text-align:right;'></td></tr></table>
883
<p>The description of composition uses abstract terminology in order to allow the description to be more precise, while avoiding constant values which are specific to a particular build configuration. Each image pixel is represented by red, green, and blue levels (which are equal for a gray pixel). The build-dependent value <em class="QR">QuantumRange</em> is the maximum integral value which may be stored, per pixel, in the red, green, or blue channels of the image. Each image pixel may also optionally (if the image matte channel is enabled) have an associated level of opacity, ranging from <em>opaque</em> to <em>transparent</em>, which may be used to determine the influence of the pixel color when compositing the pixel with another image pixel. If the image matte channel is disabled, then all pixels in the image are treated as opaque. The color of an opaque pixel is fully visible while the color of a transparent pixel color is entirely absent (pixel color is ignored).</p>
885
<p>By definition, raster images have a rectangular shape. All image rows are of equal length, as are all image columns. By treating the alpha channel as a visual "mask" the rectangular image may be given a "shape" by treating the alpha channel as a cookie-cutter for the image. This is done by setting the pixels within the shape to be opaque, with pixels outside the shape set as transparent. Pixels on the boundary of the shape may be between opaque and transparent in order to provide antialiasing (visually smooth edges). The description of the composition operators use this concept of image "shape" in order to make the description of the operators easier to understand. While it is convenient to describe the operators in terms of "shapes" they are by no means limited to mask-style operations since they are based on continuous floating-point mathematics rather than simple boolean operations.</p>
782
887
<p>The following composite methods are available:</p>
784
<table id="table" cellpadding="2" cellspacing="0" style="width: 93%">
787
892
<th align="left" style="width: 8%">Method</th>
788
893
<th align="left">Description</th>
792
897
<td valign="top">clear</td>
793
898
<td valign="top">Both the color and the alpha of the destination are cleared. Neither the source nor the destination are used as input.</td>
797
902
<td valign="top">src</td>
798
903
<td valign="top">The source is copied to the destination. The destination is not used as input.</td>
802
907
<td valign="top">dst</td>
803
908
<td valign="top">The destination is left untouched.</td>
807
<td valign="top"><b>src-over</b></td>
912
<td valign="top">src-over</td>
808
913
<td valign="top">The source is composited over the destination.</td>
812
917
<td valign="top">dst-over</td>
813
918
<td valign="top">The destination is composited over the source and the result replaces the destination.</td>
817
922
<td valign="top">src-in</td>
818
923
<td valign="top">The part of the source lying inside of the destination replaces the destination.</td>
822
927
<td valign="top">dst-in</td>
823
928
<td valign="top">The part of the destination lying inside of the source replaces the destination.</td>
827
932
<td valign="top">src-out</td>
828
933
<td valign="top">The part of the source lying outside of the destination replaces the destination.</td>
832
937
<td valign="top">dst-out</td>
833
938
<td valign="top">The part of the destination lying outside of the source replaces the destination.</td>
837
942
<td valign="top">src-atop</td>
838
943
<td valign="top">The part of the source lying inside of the destination is composited onto the destination.</td>
842
947
<td valign="top">dst-atop</td>
843
948
<td valign="top">The part of the destination lying inside of the source is composited over the source and replaces the destination.</td>
847
952
<td valign="top">multiply</td>
848
953
<td valign="top">The source is multiplied by the destination and replaces the destination. The resultant color is always at least as dark as either of the two constituent colors. Multiplying any color with black produces black. Multiplying any color with white leaves the original color unchanged.</td>
852
957
<td valign="top">screen</td>
853
958
<td valign="top">The source and destination are complemented and then multiplied and then replace the destination. The resultant color is always at least as light as either of the two constituent colors. Screening any color with white produces white. Screening any color with black leaves the original color unchanged.</td>
857
962
<td valign="top">overlay</td>
858
963
<td valign="top">Multiplies or screens the colors, dependent on the destination color. Source colors overlay the destination whilst preserving its highlights and shadows. The destination color is not replaced, but is mixed with the source color to reflect the lightness or darkness of the destination.</td>
862
967
<td valign="top">darken</td>
863
968
<td valign="top">Selects the darker of the destination and source colors. The destination is replaced with the source when the source is darker, otherwise it is left unchanged.</td>
867
972
<td valign="top">lighten</td>
868
973
<td valign="top">Selects the lighter of the destination and source colors. The destination is replaced with the source when the source is lighter, otherwise it is left unchanged.</td>
872
977
<td valign="top">linear-light</td>
873
978
<td valign="top">Increase contrast slightly with an impact on the foreground's tonal values.</td>
877
982
<td valign="top">color-dodge</td>
878
983
<td valign="top">Brightens the destination color to reflect the source color. Painting with black produces no change.</td>
882
987
<td valign="top">color-burn</td>
883
988
<td valign="top">Darkens the destination color to reflect the source color. Painting with white produces no change.</td>
887
992
<td valign="top">hard-light</td>
888
993
<td valign="top">Multiplies or screens the colors, dependent on the source color value. If the source color is lighter than 0.5, the destination is lightened as if it were screened. If the source color is darker than 0.5, the destination is darkened, as if it were multiplied. The degree of lightening or darkening is proportional to the difference between the source color and 0.5. If it is equal to 0.5 the destination is unchanged. Painting with pure black or white produces black or white.</td>
892
997
<td valign="top">soft-light</td>
893
998
<td valign="top">Darkens or lightens the colors, dependent on the source color value. If the source color is lighter than 0.5, the destination is lightened. If the source color is darker than 0.5, the destination is darkened, as if it were burned in. The degree of darkening or lightening is proportional to the difference between the source color and 0.5. If it is equal to 0.5, the destination is unchanged. Painting with pure black or white produces a distinctly darker or lighter area, but does not result in pure black or white.</td>
897
1002
<td valign="top">plus</td>
898
1003
<td valign="top">The source is added to the destination and replaces the destination. This operator is useful for animating a dissolve between two images.</td>
902
1007
<td valign="top">add</td>
903
1008
<td valign="top">As per 'plus' but transparency data is treated as matte
904
1009
values. As such any transparent areas in either image remain
905
1010
transparent. </td>
909
1014
<td valign="top">minus</td>
910
1015
<td valign="top">Subtract the colors in the source image from the
911
destination image. When transparency is involved, Opaque areas will be
1016
destination image. When transparency is involved, opaque areas will be
912
1017
subtracted from any destination opaque areas. </td>
916
1021
<td valign="top">subtract</td>
917
1022
<td valign="top">Subtract the colors in the source image from the
918
1023
destination image. When transparency is involved transparent areas are
991
1096
<h4><a name="contrast" id="contrast"></a>-contrast</h4>
994
<p>enhance or reduce the image contrast.</p>
1099
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Enhance or reduce the image contrast.</td><td style='text-align:right;'></td></tr></table>
996
1101
<p>This option enhances the intensity differences between the lighter and darker elements of the image. Use <a href="#contrast">-contrast</a> to enhance the image or <a href="#contrast">+contrast</a> to reduce the image contrast.</p>
998
1103
<p>For a more pronounced effect you can repeat the option:</p>
1001
convert rose: -contrast -contrast rose_c2.png
1105
<p class='crt'><span class="crtprompt"> $magick> </span><span class='crtin'>convert rose: -contrast -contrast rose_c2.png</span></p>
1004
1106
<div style="margin: auto;">
1005
<h4><a name="contrast-stretch" id="contrast-stretch"></a>-contrast-stretch <em class="option">black-point</em><br />-contrast-stretch <em class="option">black-point</em>{x<em class="option">white-point</em>}{<em class="option">%</em>}}</h4>
1107
<h4><a name="contrast-stretch" id="contrast-stretch"></a>-contrast-stretch <em class="arg">black-point</em><br />-contrast-stretch <em class="arg">black-point</em>{x<em class="arg">white-point</em>}{<em class="arg">%</em>}}</h4>
1008
<p>Increase the contrast in an image by <em>stretching</em> the range of intensity values. While doing so black-out at most <em>black-point</em> pixels and white-out at most <em>white-point</em> pixels. Or, if percent is used, black-out at most <em>black-point %</em> pixels and white-out at most <em>white-point %</em> pixels.</p>
1010
<p>Prior to IM 6.4.5-9, -contrast-stretch will black-out at most <em>black-point</em> pixels and white-out at most <em>total pixels minus white-point</em> pixels. Or, if percent is used, black-out at most <em>black-point %</em> pixels and white-out at most <em>100% minus white-point %</em> pixels.</p>
1012
<p>Note that -contrast-stretch 0 will modify the image such that the image's
1013
min and max values are stretched to 0 and QuantumRange, respectively, without any loss of data due to burn-out at either end. This is not the same as <a href="#normalize">-normalize</a>, which is equivalent to -contrast-stretch 2%x1% (or prior to IM 6.4.5-9, -contrast-stretch 2%x99%).</p>
1110
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Increase the contrast in an image by <em>stretching</em> the range of intensity values.</td><td style='text-align:right;'></td></tr></table>
1112
<p>While performing the stretch, black-out at most <em class="arg">black-point</em> pixels and white-out at most <em class="arg">white-point</em> pixels. Or, if percent is used, black-out at most <em class="arg">black-point %</em> pixels and white-out at most <em class="arg">white-point %</em> pixels.</p>
1114
<p>Prior to IM 6.4.7-0, <a href="#contrast-stretch">-contrast-stretch</a> will black-out at most <em class="arg">black-point</em> pixels and white-out at most <em class="arg">total pixels minus white-point</em> pixels. Or, if percent is used, black-out at most <em class="arg">black-point %</em> pixels and white-out at most <em class="arg">100% minus white-point %</em> pixels.</p>
1116
<p>Note that <kbd>-contrast-stretch 0</kbd> will modify the image such that the image's
1117
min and max values are stretched to 0 and <em class="QR">QuantumRange</em>, respectively, without any loss of data due to burn-out at either end. This is not the same as <a href="#normalize">-normalize</a>, which is equivalent to <kbd>-contrast-stretch 2%x1%</kbd> (or prior to IM 6.4.7-0, <kbd>-contrast-stretch 2%x99%</kbd>).</p>
1015
1119
<p>The channels are stretched in concert. Specify <a href="#channel">-channel</a> to normalize the RGB channels individually.</p>
1018
1122
<div style="margin: auto;">
1019
<h4><a name="convolve" id="convolve"></a>-convolve <em class="option">kernel</em></h4>
1123
<h4><a name="convolve" id="convolve"></a>-convolve <em class="arg">kernel</em></h4>
1022
<p>convolve image with the specified convolution kernel.</p>
1024
<p>The kernel is specified as a comma-separated list of integers, ordered left-to right, starting with the top row. The order of the kernel is determined by the square root of the number of entries. Presently only square kernels are supported.</p>
1126
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Convolve an image with a user-supplied convolution kernel.</td><td style='text-align:right;'></td></tr></table>
1128
<p>The <em class="arg">kernel</em> is a square matrix specified as a comma-separated list of integers (with no spaces), ordered left-to right, starting with the top row. Presently, only odd-dimensioned kernels are supported, and therefore the number of entries in the specified <em class="arg">kernel</em> must be 3<sup>2</sup>=9, 5<sup>2</sup>=25, 7<sup>2</sup>=49, etc. </p>
1130
<p>Note that the <a href="../www/command-line-options.html#convolve">‑convolve</a> operator supports the <a href="../www/command-line-options.html#bias">‑bias</a> setting. This option shifts the convolution so that positive and negative results are relative to a user-specified bias value. This is important for non-HDRI compilations of ImageMagick when dealing with convolutions that contain negative as well as positive values. This is especially the case with convolutions involving high pass filters or edge detection. Without an output bias, the negative values will be clipped at zero.
1133
<p>When using an IM with the HDRI compile-time setting, <a href="../www/command-line-options.html#bias">‑bias</a> is not needed,
1134
as IM will be able to store/handle any negative results without
1135
clipping to the color value range (0..QuantumRange).</p>
1137
<p>See the discussion on HDRI implementations of ImageMagick on the page
1138
<a href="/www/high-dynamic-range.html">High Dynamic-Range Images</a>. For more about HDRI go the ImageMagick <a href="http://www.imagemagick.org/Usage/basics/#hdri">Usage</a> pages or this <a href="http://en.wikipedia.org/wiki/High_dynamic_range_imaging">Wikipedia</a> entry.
1027
1141
<div style="margin: auto;">
1028
<h4><a name="crop" id="crop"></a>-crop <em class="option">width</em>{%}<br />-crop <em class="option">width</em>x<em class="option">height</em>{<em class="option">+-</em>}<em class="option">x</em>{<em class="option">+-</em>}<em class="option">y</em>{<em class="option">%</em>}{<em class="option">!</em>}</h4>
1142
<h4><a name="crop" id="crop"></a>-crop <em class="arg">geometry</em></h4>
1031
<p>cut out a rectangular region of the image.</p>
1033
<p>See <a href="#resize">-resize</a> for details about the geometry specification.</p>
1035
<p>The width and height give the size of the image that remains after cropping, and <em class="option">x</em> and <em class="option">y</em> are offsets that give the location of the top left corner of the cropped image with respect to the original image. To specify the amount to be removed, use <a href="#shave">-shave</a> instead.</p>
1037
<p>If the <em class="option">x</em> and <em class="option">y</em> offsets are present, a single image is generated, consisting of the pixels from the cropping region. The offsets specify the location of the upper left corner of the cropping region measured downward and rightward with respect to the upper left corner of the image. If the <a href="#gravity">-gravity</a> option is present with <kbd>NorthEast</kbd>, <kbd>East</kbd>, or <kbd>SouthEast</kbd> gravity, it gives the distance leftward from the right edge of the image to the right edge of the cropping region. Similarly, if the <a href="#gravity">-gravity</a> option is present with <kbd>SouthWest</kbd>, <kbd>South</kbd>, or <kbd>SouthEast</kbd> gravity, the distance is measured upward between the bottom edges.</p>
1039
<p>If the <em class="option">x</em> and <em class="option">y</em> offsets are omitted, a set of tiles of the specified geometry, covering the entire input image, is generated. The rightmost tiles and the bottom tiles are smaller if the specified geometry extends beyond the dimensions of the input image.</p>
1145
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Cut out one or more rectangular regions of the image.</td><td style='text-align:right;'></td></tr></table>
1147
<p>See <a href="../www/command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
1149
<p>The <em class="arg">width</em> and <em class="arg">height</em> of the <em class="arg">geometry</em> argument give the size of the image that remains after cropping, and <em class="arg">x</em> and <em class="arg">y</em> in the <em class="arg">offset</em> (if present) gives the location of the top left corner of the cropped image with respect to the original image. To specify the amount to be removed, use <a href="#shave">-shave</a> instead.</p>
1151
<p>If the <em class="arg">x</em> and <em class="arg">y</em> offsets are present, a single image is generated, consisting of the pixels from the cropping region. The offsets specify the location of the upper left corner of the cropping region measured downward and rightward with respect to the upper left corner of the image. If the <a href="#gravity">-gravity</a> option is present with <kbd>NorthEast</kbd>, <kbd>East</kbd>, or <kbd>SouthEast</kbd> gravity, it gives the distance leftward from the right edge of the image to the right edge of the cropping region. Similarly, if the <a href="#gravity">-gravity</a> option is present with <kbd>SouthWest</kbd>, <kbd>South</kbd>, or <kbd>SouthEast</kbd> gravity, the distance is measured upward between the bottom edges.</p>
1153
<p>If the <em class="arg">x</em> and <em class="arg">y</em> offsets are omitted, a set of tiles of the specified geometry, covering the entire input image, is generated. The rightmost tiles and the bottom tiles are smaller if the specified geometry extends beyond the dimensions of the input image.</p>
1041
1155
<p>By adding a exclamation character flag to the geometry argument, the
1042
1156
cropped images virtual canvas page size and offset will be set as if the
1517
1633
<td valign="top"><kbd>Shepards</kbd></td>
1518
1634
<td valign="top">
1519
1635
Distort the given list control points (any number) using an Inverse
1520
Squared Distance Interpolation Method (<A
1521
HREF="http://www.ems-i.com/smshelp/Data_Module/Interpolation/Inverse_Distance_Weighted.htm"
1522
>Shepards Method</A>). The control points in effect do 'localized'
1636
Squared Distance Interpolation Method (<a
1637
href="http://www.ems-i.com/smshelp/Data_Module/Interpolation/Inverse_Distance_Weighted.htm"
1638
>Shepards Method</a>). The control points in effect do 'localized'
1523
1639
distortions of the image around the given control point. For best
1524
1640
results extra control points should be added to 'lock' the positions of
1525
the corners and other unchanging parts of the image. <br>
1641
the corners and other unchanging parts of the image. <br/>
1527
1643
The distortion has been likened to 'taffy pulling' using nails, pins or
1528
sticks. It basically uses the <A HREF="#sparse-color"
1529
>-sparse-color</A> method of the same name to generate separate X and Y
1530
displacement maps (see <A HREF="#displace" >-displace</A>) for source
1644
sticks. It basically uses the <a href="#sparse-color"
1645
>-sparse-color</a> method of the same name to generate separate X and Y
1646
displacement maps (see <a href="#displace" >-displace</a>) for source
1531
1647
image color look-up. </td>
1538
<p>To print a complete list of distortion methods, use the <a href="#list">-list distort</a> option.</p>
1653
<p>To print a complete list of distortion methods, use <a href="#list">-list distort</a>.</p>
1540
1655
<p>Many of the above distortion methods such as '<kbd>Affine</kbd>',
1541
1656
'<kbd>Perspective</kbd>', and '<kbd>Shepards</kbd>' use a list control points
1542
1657
defining how these points in the given image should be distorted in the
1543
1658
destination image. Each set of four floating point values represent a source
1544
1659
image coordinate, followed immediately by the destination image coordinate.
1545
This produces a list of values such as...
1546
<div align=center><em>
1660
This produces a list of values such as...</p>
1661
<div style="text-align: center"><em>
1547
1662
U<sub>1</sub>,V<sub>1</sub> X<sub>1</sub>,Y<sub>1</sub>
1548
1663
U<sub>2</sub>,V<sub>2</sub> X<sub>2</sub>,Y<sub>2</sub>
1549
1664
U<sub>3</sub>,V<sub>3</sub> X<sub>3</sub>,Y<sub>3</sub>
1551
1666
U<sub>n</sub>,V<sub>n</sub> X<sub>n</sub>,Y<sub>n</sub>
1553
where <em>U,V</em> on the source image is mapped to <em>X,Y</em> on the
1668
<p>where <em>U,V</em> on the source image is mapped to <em>X,Y</em> on the
1554
1669
destination image. </p>
1556
1671
<p>For example, to warp an image using '<kbd>perspective</kbd>' distortion,
1557
1672
needs a list of at least 4 sets of coordinates, or 16 numbers. Here is the
1558
1673
perspective distortion of the built-in "rose:" image. Note how spaces were
1559
1674
used to group the 4 sets of coordinate pairs, to make it easier to read and
1562
convert rose: -virtual-pixel black \
1563
-distort Perspective '0,0,0,0 0,45,0,45 69,0,60,10 69,45,60,35' \
1677
<p class='crt'><span class="crtprompt"> $magick> </span><span class='crtin'>
1678
convert rose: -virtual-pixel black \ <br/>
1679
-distort Perspective '0,0,0,0 0,45,0,45 69,0,60,10 69,45,60,35' \ <br/>
1680
rose_3d_rotated.gif</span></p>
1567
1681
<p>If more that the required number of coordinate pairs are given for a
1568
1682
distortion, then the distortion method will be 'least squares' fitted to
1569
1683
produce the best result for all the coordinate pairs given. If less than the
1707
<p>The pixel operation primitives are.</p>
1819
<p>The pixel operation primitives:</p>
1709
1821
<pre class="text">
1710
1822
color x0,y0 method
1711
1823
matte x0,y0 method
1714
<p>The shape primitives are drawn in the color specified in the preceding <a href="#fill">-fill</a> option. For unfilled shapes, use <a href="#fill">-fill none</a>. You can optionally control the stroke with the <a href="#stroke">-stroke</a> and <a href="#strokewidth">-strokewidth</a> options.</p>
1716
<p><kbd>Point</kbd> requires a single coordinate.</p>
1718
<p><kbd>Line</kbd> requires a start and end coordinate.</p>
1720
<p><kbd>Rectangle</kbd> expects an upper left and lower right coordinate.</p>
1722
<p><kbd>RoundRectangle</kbd> has the upper left and lower right coordinates and the width and height of the corners.</p>
1724
<p><kbd>Circle</kbd> has a center coordinate and a coordinate for the outer edge.</p>
1726
<p>Use <kbd>Arc</kbd> to inscribe an elliptical arc within a rectangle. Arcs require a start and end point as well as the degree of rotation (e.g. 130,30 200,100 45,90).</p>
1728
<p>Use <kbd>Ellipse</kbd> to draw a partial ellipse centered at the given point with the x-axis and y-axis radius and start and end of arc in degrees (e.g. 100,100 100,150 0,360).</p>
1730
<p><kbd>Polyline</kbd> and
1731
<kbd>polygon</kbd> require three or more coordinates to define its boundaries. Coordinates are integers separated by an optional comma. For example, to define a circle centered at 100,100 that extends to 150,150 use:</p>
1826
<p>The shape primitives are drawn in the color specified by the preceding <a href="#fill">-fill</a> setting. For unfilled shapes, use <a href="#fill">-fill none</a>. You can optionally control the stroke (the "outline" of a shape) with the <a href="#stroke">-stroke</a> and <a href="#strokewidth">-strokewidth</a> settings.</p>
1828
<p>A <kbd>point</kbd> primitive is specified by a single <em>point</em> in the pixel plane, that is, by an ordered pair of integer coordinates, <em>x</em>,<em>y</em>. (As it involves only a single pixel, a <kbd>point</kbd> primitive is not affected by <a href="#stroke">-stroke</a> or <a href="#strokewidth">-strokewidth</a>.)</p>
1830
<p>A <kbd>line</kbd> primitive requires a start point and end point.</p>
1832
<p>A <kbd>rectangle</kbd> primitive is specified by the pair of points at the upper left and lower right corners.</p>
1834
<p>A <kbd>roundRectangle</kbd> primitive takes the same corner points as a <kbd>rectangle</kbd> followed by the width and height of the rounded corners to be removed.</p>
1836
<p>The <kbd>circle</kbd> primitive makes a disk (filled) or circle (unfilled). Give the center and any point on the perimeter (boundary).</p>
1838
<p>The <kbd>arc</kbd> primitive is used to inscribe an elliptical segment in to a given rectangle. An <kbd>arc</kbd> requires the two corners used for <kbd>rectangle</kbd> (see above) followed by the start and end angles of the arc of the segment segment (e.g. 130,30 200,100 45,90). The start and end points produced are then joined with a line segment and the resulting segment of an ellipse is filled.</p>
1840
<p>Use <kbd>ellipse</kbd> to draw a partial (or whole) ellipse. Give the center point, the horizontal and vertical "radii" (the <em>semi-axes</em> of the ellipse) and start and end angles in degrees (e.g. 100,100 100,150 0,360).</p>
1842
<p>The <kbd>polyline</kbd> and <kbd>polygon</kbd> primitives require three or more points to define their perimeters. A <kbd>polyline</kbd> is simply a <kbd>polygon</kbd> in which the final point is not stroked to the start point. When unfilled, this is a <em>polygonal line</em>. If the <a href="#stroke">-stroke</a> setting is <kbd>none</kbd> (the default), then a <kbd>polyline</kbd> is identical to a <kbd>polygon</kbd>.
1845
<p>A <em>coordinate</em> is a pair of integers separated by a space or optional comma. </p>
1847
<p>As an example, to define a circle centered at 100,100 that extends to 150,150 use:</p>
1734
1850
-draw 'circle 100,100 150,150'
1737
<p><kbd>Bezier</kbd> (spline) requires three or more x,y coordinates to define its shape. The first and last points are the knots (preserved coordinates) and any intermediate coordinates are the control points. If two control points are specified, the line between each end knot and its sequentially respective control point determines the tangent direction of the curve at that end. If one control point is specified, the lines from the end knots to the one control point determines the tangent directions of the curve at each end. If more than two control points are specified, then the additional control points act in combination to determine the intermediate shape of the curve. In order to
1738
draw complex curves, it is highly recommended either to use the <kbd>Path</kbd> primitive or to draw multiple four-point bezier segments with the start and end knots of each successive segment repeated. For example:</p>
1853
<p>The <kbd>Bezier</kbd> primitive creates a spline curve and requires three or points to define its shape. The first and last points are the <em>knots</em> and these points are attained by the curve, while any intermediate coordinates are <em>control points</em>. If two control points are specified, the line between each end knot and its sequentially respective control point determines the tangent direction of the curve at that end. If one control point is specified, the lines from the end knots to the one control point determines the tangent directions of the curve at each end. If more than two control points are specified, then the additional control points act in combination to determine the intermediate shape of the curve. In order to
1854
draw complex curves, it is highly recommended either to use the <kbd>path</kbd> primitive or to draw multiple four-point bezier segments with the start and end knots of each successive segment repeated. For example:</p>
1741
1857
-draw 'bezier 20,50 45,100 45,0 70,50'
1742
1860
-draw 'bezier 70,50 95,100 95,0 120,50'
1746
<p><kbd>Paths</kbd> (See <a href="http://www.w3.org/TR/SVG/paths.html">Paths</a>) represent an outline of an object which is defined in terms of moveto (set a new current point), lineto (draw a straight line), curveto (draw a curve using a cubic Bezier), arc (elliptical or circular arc) and closepath (close the current shape by drawing a line to the last moveto) elements. Compound paths (i.e., a path with subpaths, each consisting of a single moveto followed by one or more line or curve operations) are possible to allow effects such as <em>donut holes</em> in objects.</p>
1864
<p>A <kbd>path</kbd> represents an outline of an object, defined in terms of moveto (set a new current point), lineto (draw a straight line), curveto (draw a Bezier curve), arc (elliptical or circular arc) and closepath (close the current shape by drawing a line to the last moveto) elements. Compound paths (i.e., a path with subpaths, each consisting of a single moveto followed by one or more line or curve operations) are possible to allow effects such as <em>donut holes</em> in objects. (See <a href="http://www.w3.org/TR/SVG/paths.html">Paths</a>.)</p>
1748
1866
<p>Use <kbd>image</kbd> to composite an image with another image. Follow the image keyword with the composite operator, image location, image size, and filename:</p>
1751
-draw 'image Over 100,100 225,225 image.jpg'
1869
-draw 'image SrcOver 100,100 225,225 image.jpg'
1754
1872
<p>You can use 0,0 for the image size, which means to use the actual dimensions found in the image header. Otherwise, it will be scaled to the given dimensions. See <a href="#compose">-compose</a> for a description of the composite operators.</p>
1756
1874
<p>Use <kbd>text</kbd> to annotate an image with text. Follow the text coordinates with a string. If the string has embedded spaces, enclose it in single or double quotes.</p>
1876
<p>For example, the following annotates the image with <kbd>Works like magick!</kbd> for an image titled <kbd>bird.miff</kbd>. </p>
1761
1879
-draw 'text 100,100 "Works like magick!"'
1764
<p>annotates the image with <kbd>Works like magick!</kbd> for an image titled <kbd>bird.miff</kbd>. See the <a href="#annotate">-annotate</a> option for another convenient way to annotate an image with text.</p>
1766
<p><kbd>Rotate</kbd> rotates subsequent shape primitives and text primitives about the origin of the main image. If the <a href="#region">-region</a> option precedes the <a href="#draw">-draw</a> option, the origin for transformations is the upper left corner of the region.</p>
1768
<p><kbd>Translate</kbd> translates them.</p>
1770
<p><kbd>Scale</kbd> scales them.</p>
1772
<p><kbd>SkewX</kbd> and <kbd>SkewY</kbd> skew them with respect to the origin of the main image or the region.</p>
1774
<p>The transformations modify the current affine matrix, which is initialized from the initial affine matrix defined by the <a href="#affine">-affine</a> option. Transformations are cumulative within the <a href="#draw">-draw</a> option. The initial affine matrix is not affected; that matrix is only changed by the appearance of another <a href="#affine">-affine</a>option. If another <a href="#draw">-draw</a> option appears, the current affine matrix is reinitialized from the initial affine
1882
<p>See the <a href="#annotate">-annotate</a> option for another convenient way to annotate an image with text.</p>
1884
<p>The <kbd>rotate</kbd> primitive rotates subsequent shape primitives and text primitives about the origin of the main image. If the <a href="#region">-region</a> option precedes the <a href="#draw">-draw</a> option, the origin for transformations is the upper left corner of the region.</p>
1886
<p>The <kbd>translate</kbd> primitive translates subsequent shape and text primitives.</p>
1888
<p>The <kbd>scale</kbd> primitive scales them.</p>
1890
<p>The <kbd>skewX</kbd> and <kbd>skewY</kbd> primitives skew them with respect to the origin of the main image or the region.</p>
1892
<p>The transformations modify the current affine matrix, which is initialized from the initial affine matrix defined by the <a href="#affine">-affine</a> option. Transformations are cumulative within the <a href="#draw">-draw</a> option. The initial affine matrix is not affected; that matrix is only changed by the appearance of another <a href="#affine">-affine</a> option. If another <a href="#draw">-draw</a> option appears, the current affine matrix is reinitialized from the initial affine
1777
<p>Use <kbd>color</kbd> to change the color of a pixel to the fill color (see <a href="#fill">-fill</a>). Follow the pixel coordinate with a method:</p>
1895
<p>Use the <kbd>color</kbd> primitive to change the color of a pixel to the fill color (see <a href="#fill">-fill</a>). Follow the pixel coordinate with a method:</p>
1779
1897
<pre class="text">
1852
1974
<p>For YIQ, YUV and OHTA use the red channel. For example, OHTA is a principal components transformation that puts most of the information in the first channel. Here we have ... <kbd>-colorspace OHTA -channel red -equalize -colorspace RGB</kbd> ...</p>
1854
1976
<div style="margin: auto;">
1855
<h4><a name="evaluate" id="evaluate"></a>-evaluate <em class="option">operator constant</em></h4>
1977
<h4><a name="evaluate" id="evaluate"></a>-evaluate <em class="arg">operator value</em></h4>
1858
<p>evaluate an arithmetic, relational, or logical expression.</p> <p>Choose
1872
Multiplicative-noise
1887
<p>The function will modify each of the color values for the specified <a
1888
href="#channel" >-channel</a> in the image. The values are not normalized, but
1889
are modified as 0 to QuantumRange. The transparency channel of the image is
1890
represented as a 'alpha' values (0 - fully transparent), so divide an alpha
1891
channel value by 2 will make the image semi-transparent. Percentage
1892
'<kbd>%</kbd>' can be used to specify a value as a percentage of the
1895
<p>To print a complete list of evaluate operators, use the <a href="#list">-list evaluate</a> option.</p>
1980
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Alter channel pixels by evaluating an arithmetic, relational, or logical expression.</td><td style='text-align:right;'></td></tr></table>
1982
<p>(See the <a href="#function" >-function</a> operator for some multi-parameter functions. See the <a href="#fx" >-fx</a> operator if more elaborate calculations are needed.)</p>
1984
<p>The behaviors of each <em class="arg">operator</em> are summarized in the following list. For brevity, the numerical value of a "pixel" referred to below is the value of the corresponding channel of that pixel, while a "normalized pixel" is that number divided by the maximum (installation-dependent) value <em class="QR">QuantumRange</em>. (If normalized pixels are used, they are restored, following the other calculations, to the full range by multiplying by <em class="QR">QuantumRange</em>.)</p>
1991
<th><em class="arg">operator</em></th>
1992
<th>Summary (see further below for details)</th>
1997
<tr><td>Add </td> <td>Add <em class="arg">value</em> to pixels. </td></tr>
1998
<tr><td>AddModulus </td> <td>Add <em class="arg">value</em> to pixels modulo <em class="QR">QuantumRange</em>.</td></tr>
1999
<tr><td>And </td> <td>Binary AND of pixels with <em class="arg">value</em>.</td></tr>
2000
<tr><td>Cos, Cosine </td> <td>Apply cosine to pixels with frequency <em class="arg">value</em> with 50% bias added.</td></tr>
2001
<tr><td>Divide </td> <td>Divide pixels by <em class="arg">value</em>.</td></tr>
2002
<tr><td>LeftShift </td> <td>Shift the pixel values left by <em class="arg">value</em> bits (i.e., multiply pixels by 2<sup><em class="arg">value</em></sup>).</td></tr>
2003
<tr><td>Log </td> <td>Apply scaled logarithm to normalized pixels.</td></tr>
2004
<tr><td>Max </td> <td>Clip pixels at lower bound <em class="arg">value</em>.</td></tr>
2005
<tr><td>Min </td> <td>Clip pixels at upper bound <em class="arg">value</em>.</td></tr>
2006
<tr><td>Multiply </td> <td>Multiply pixels by <em class="arg">value</em>.</td></tr>
2007
<tr><td>Or </td> <td>Binary OR of pixels with <em class="arg">value</em>.</td></tr>
2008
<tr><td>Pow </td> <td>Raise normalized pixels to the power <em class="arg">value</em>.</td></tr>
2009
<tr><td>RightShift </td> <td>Shift the pixel values right by <em class="arg">value</em> bits (i.e., divide pixels by 2<sup><em class="arg">value</em></sup>).</td></tr>
2010
<tr><td>Set </td> <td>Set pixel equal to <em class="arg">value</em>.</td></tr>
2011
<tr><td>Sin, Sine </td> <td>Apply sine to pixels with frequency <em class="arg">value</em> with 50% bias added.</td></tr>
2012
<tr><td>Subtract </td> <td>Subtract <em class="arg">value</em> from pixels.</td></tr>
2013
<tr><td>Xor </td> <td>Binary XOR of pixels with <em class="arg">value.</em></td></tr>
2015
<tr><td> </td></tr>
2018
<tr><td>Gaussian-noise</td></tr>
2019
<tr><td>Impulse-noise</td></tr>
2020
<tr><td>Laplacian-noise</td></tr>
2021
<tr><td>Multiplicative-noise</td> <td>(These are equivalent to the corresponding <a href="#noise" >-noise</a> operators.)</td></tr>
2022
<tr><td>PoissonNoise</td></tr>
2023
<tr><td>Uniform-noise</td></tr>
2025
<tr><td> </td></tr>
2027
<tr><td>Threshold </td> <td>Threshold pixels larger than <em class="arg">value</em>.</td></tr>
2028
<tr><td>ThresholdBlack </td> <td>Threshold pixels to zero values equal to or below <em class="arg">value</em>.</td></tr>
2029
<tr><td>ThresholdWhite </td> <td>Threshold pixels to maximum values above <em class="arg">value</em>. </td></tr>
2033
<p>The specified functions are applied only to each previously set <a
2034
href="#channel" >-channel</a> in the image. If necessary, the results of the calculations are truncated (clipped) to fit in the interval [0, <em class="QR">QuantumRange</em>]. The transparency channel of the image is
2035
represented as a 'alpha' values (0 = fully transparent), so, for example, a <kbd>Divide</kbd> by 2 of the alpha channel will make the image semi-transparent. Append the percent symbol
2036
'<kbd>%</kbd>' to specify a value as a percentage of the <em class="QR">QuantumRange</em>.</p>
2038
<p>To print a complete list of <a href="#evaluate">-evaluate</a> operators, use <a href="#list">-list evaluate</a>.</p>
2040
<p>The results of the <kbd>Add</kbd>, <kbd>Subtract</kbd> and <kbd>Multiply</kbd> methods can
2041
also be achieved using either the <a href="#level"
2042
>-level</a> or the <a href="#level" >+level</a> operator, with appropriate
2043
argument, to linearly modify the overall range of color values. Please note,
2044
however, that <a href="#level" >-level</a> treats transparency as 'matte'
2045
values (0 = opaque), while <a href="#level" >-evaluate</a> works with 'alpha'
2048
<p><kbd>AddModulus</kbd> has been added as of IM 6.4.8-4 and provides addition modulo the <em class="QR">QuantumRange</em>. It is therefore equivalent to <kbd>Add</kbd> unless the resulting pixel value is outside the interval [0, <em class="QR">QuantumRange</em>]. </p>
2050
<p><kbd>Cos</kbd> has been added as of IM 6.4.8-4 (along with <kbd>Sin</kbd>) and provides a <em>scaled</em> cosine function as follows. (The synonyms <kbd>Cosine</kbd> and <kbd>Sine</kbd> may also be used.) The <em class="arg">value</em> used with <kbd>Cos</kbd> provides a scaling of the <em>period</em> of the usual cosine function (a frequency), allowing compression or stretching of the color range, with repetition. For example, if the <em class="arg">value</em> is 1, the effective period is simply the <em class="QR">QuantumRange</em>; but if the <em class="arg">value</em> is 2, then the effective period is the <em>half</em> the <em class="QR">QuantumRange</em>. All the values are <em>centered</em> about the value <em class="QR">QuantumRange</em>/2. The formula on a normalized pixel value <b><em>u</em></b> is </p>
2052
<div style="text-align:center;">
2053
0.5 + 0.5 × cos(2 π <b><em>u</em></b> × <em class="arg">value</em>).
2056
<p><kbd>Log</kbd> has been added as of IM 6.4.2-1 and works on normalized pixel values. This a <em>scaled</em> log function. The <em class="arg">value</em> used with <kbd>Log</kbd> provides a <em>scaling factor</em> that adjusts the curvature in the graph of the log function. The formula applied to a normalized value <b><em>u</em></b> is below. </p>
2058
<div style="text-align:center;">
2059
log(<em class="arg">value</em> × <b><em>u</em></b> + 1) / log(<em class="arg">value</em> + 1)
1897
2062
<p><kbd>Pow</kbd> has been added as of IM 6.4.1-9, and works on normalized
1898
color values. Note that <kbd>Pow</kbd> is equivalent to the <a href="#gamma"
1899
>-gamma</A> operator. For example <a href="#gamma">-gamma 2</a> would be
1900
equivalent to <b>-evaluate pow 0.5</b> or a 'square root' function. The value
1901
used with <a href="#gamma" >-gamma</A> is just the inverse of the value used
2063
pixel values. Note that <kbd>Pow</kbd> is related to the <a href="#gamma"
2064
>-gamma</a> operator. For example, <b>-gamma 2</b> is
2065
equivalent to <b>-evaluate pow 0.5</b>, i.e., a 'square root' function. The value
2066
used with <a href="#gamma" >-gamma</a> is simply the reciprocal of the value used
1902
2067
with <kbd>Pow</kbd>.</p>
1904
<p><kbd>Log</kbd> has been added as of IM 6.4.2-1 and works on normalize color values. This a <em>scaled</em> log function. The constant used with <kbd>Log</kbd> provides a <em>scaling factor</em> that adjusts the curvature in the graph of the log function. The formula on normalize values is <b>log(constant*value)/log(constant+1)</b>. </p>
1906
<p>The <kbd>Add</kbd>, <kbd>Subtract</kbd> and <kbd>Multiply</kbd> methods can
1907
also be achieved sing either the <a href="#level"
1908
>-level</a> or the <a href="#level" >+level</a> operator with appropriate
1909
argument to linearly modify the overall range of color values. Please note
1910
however that <a href="#level" >-level</a> treats transparency as 'matte'
1911
values (0 = opaque), while <a href="#level" >-evaluate</a> works with 'alpha'
1916
<div style="margin: auto;">
1917
<h4><a name="extent" id="extent"></a>-extent <em class="option">width</em><br />-extent <em class="option">width</em>x<em class="option">height</em></h4>
1920
<p>set the image size and offset. If the image is enlarged, unfilled areas are set to the background color.</p>
1922
<p>See <a href="#resize">-resize</a> for details about the geometry specification.</p>
1924
<div style="margin: auto;">
1925
<h4><a name="extract" id="extract"></a>-extract <em class="option">width</em><br />-extract <em class="option">width</em>x<em class="option">height</em>{{+-}<em class="option">offset</em>}</h4>
1928
<p>extract the specified area from image. The option is most useful for extracting a subregion of a very large raw image. Note, these two command are equivalent:</p>
1931
convert -size 16000x16000 -depth 8 -extract 640x480+1280+960 image.rgb image.png
1932
convert -size 16000x16000 -depth 8 image.rgb[640x480+1280+960]' image.rgb image.png
1935
<div style="margin: auto;">
1936
<h4><a name="fill" id="fill"></a>-fill <em class="option">color</em></h4>
1939
<p>color to use when filling a graphic primitive.</p>
2069
<p><kbd>Sin</kbd> has been added as of IM 6.4.8-4 (along with <kbd>Cos</kbd>) and provides a scaled and centered sine function. (See <kbd>Cos</kbd>, above, for those details.) <em>centered</em> about the value <em class="QR">QuantumRange</em>/2. The formula on a normalized pixel <b><em>u</em></b> is </p>
2071
<div style="text-align:center;">
2072
0.5 + 0.5 × sin(2 π <b><em>u</em></b> × <em class="arg">value</em>).
2075
<div style="margin: auto;">
2076
<h4><a name="extent" id="extent"></a>-extent <em class="arg">geometry</em></h4>
2079
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the image size and offset.</td><td style='text-align:right;'></td></tr></table>
2081
<p>If the image is enlarged, unfilled areas are set to the background color. To position the image, use offsets in the <em class="arg">geometry</em> specification or precede with a <a href="#gravity">-gravity</a> setting.</p>
2083
<p>See <a href="../www/command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
2085
<div style="margin: auto;">
2086
<h4><a name="extract" id="extract"></a>-extract <em class="arg">geometry</em></h4>
2089
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Extract the specified area from image.</td><td style='text-align:right;'></td></tr></table>
2091
<p>This option is most useful for extracting a subregion of a very large raw image. Note that these two commands are equivalent:</p>
2093
<p class='crt'><span class="crtprompt"> $magick> </span><span class='crtin'>convert -size 16000x16000 -depth 8 -extract 640x480+1280+960 image.rgb image.png</span><span class='crtout'></span><span class="crtprompt"> $magick> </span><span class='crtin'>convert -size 16000x16000 -depth 8 image.rgb[640x480+1280+960]' image.rgb image.png</span></p>
2094
<p>See <a href="../www/command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
2096
<div style="margin: auto;">
2097
<h4><a name="family" id="family"></a>-family <em class="arg">fontFamily</em></h4>
2100
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set a font family for text.</td><td style='text-align:right;'></td></tr></table>
2102
<p>This setting suggests a font family that ImageMagick should try to use for rendering text. If the family can be found it will be used; if not, a default font (e.g., "Arial") or a family known to be similar will be substituted (e.g., "Courier" might be used if "System" is requested but not found).
2105
<p>For other settings that affect fonts, see the options <a href="#font">-font</a>, <a href="#stretch">-stretch</a>, <a href="#style">-style</a>, and <a href="#weight">-weight</a>.
2108
<div style="margin: auto;">
2109
<h4><a name="fill" id="fill"></a>-fill <em class="arg">color</em></h4>
2112
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>color to use when filling a graphic primitive.</td><td style='text-align:right;'></td></tr></table>
1941
2114
<p>This option accepts a color name, a hex color, or a numerical RGB, RGBA, HSL, HSLA, CMYK, or CMYKA specification. See <a href="../www/color.html">Color Names</a> for a description of how to properly specify the color argument.</p>
1986
2163
<kbd>Lagrange</kbd>, which will automatically re-adjust its function depending
1987
2164
on the current 'support' or 'lobes' expert settings (see below).</p>
1989
<p>If you do not select a filter with this option, the filter defaults to <kbd>Mitchell</kbd> for a colormapped image, a image with a matte channel, or if the image is enlarged. Otherwise the filter default to <kbd>Lanczos</kbd>.
2166
<p>If you do not select a filter with this option, the filter defaults to <kbd>Mitchell</kbd> for a colormapped image, a image with a matte channel, or if the image is enlarged. Otherwise the filter default to <kbd>Lanczos</kbd>.</p>
1991
2168
<p>To print a complete list of resize filters, use the <a href="#list">-list filter</a> option.</p>
1993
2170
<p>You can modify how the filter behaves as it scales your image through the
1994
use of these expert settings:<p>
1997
<dt>-set filter:blur=<em>factor</em></dt>
1998
<dd>Scale the X axis of the filter (and its window). Use > 1.0 for blurry or < 1.0 for sharp.</dd><br />
2000
<dt>-set filter:filter=<em>filter</em></dt>
2001
<dt>-set filter:support=<em>radius</em></dt>
2002
<dd>Set the filter support radius.</dd><br />
2004
<dt>-set filter:lobes=<em>count</em></dt>
2005
<dd>Set the number of lobes to use for the Sinc/Bessel filter. This an alturntive way of specifying the 'support' range of the filter.</dd><br />
2007
<dt>-set filter:b=<em>b-spline_factor</em></dt>
2008
<dt>-set filter:c=<em>keys_alpha_factor</em></dt>
2009
<dd>Redefine the values used for cubic filters such as <kbd>Cubic</kbd>, <kbd>Catrom</kbd>, <kbd>Mitchel</kbd>, and <kbd>Hermite</kbd>, as well as the <kbd>Parzen</kbd> Sinc windowing function. If only one of the values are defined, the other will be set so as to generate a 'Keys' type cubic filter.</dd><br />
2011
<dd>Use this function directly as the scaling filter. This will allow you to
2012
directly use a 'windowing filter' such as <kbd>blackman</kbd>, rather than as
2013
its normal usage as a windowing function for 'Sinc' or 'Bessel'. If defined, no
2014
windowing function will be used, unless the following expert setting is also
2017
<dt>-set filter:window=<em>filter</em></dt> <dd>The IIR (infinite impulse
2018
response) filters <kbd>bessel</kbd> and <kbd>sinc</kbd> are windowed (brought
2019
down to zero over the defined support range) with the given filter. This
2020
allows you to use a filter that is not normally used as a windowing function,
2021
such as <kbd>box</kbd>, (which effectivally turns off the windowing function). </dd>
2171
use of these expert settings:</p>
2174
<dt>-set filter:blur=<em>factor</em></dt>
2175
<dd>Scale the X axis of the filter (and its window). Use > 1.0 for blurry or < 1.0 for sharp.</dd>
2177
<dt>-set filter:filter=<em>filter</em></dt>
2178
<dt>-set filter:support=<em>radius</em></dt>
2179
<dd>Set the filter support radius.</dd>
2181
<dt>-set filter:lobes=<em>count</em></dt>
2182
<dd>Set the number of lobes to use for the Sinc/Bessel filter. This an alternative way of specifying the 'support' range of the filter.</dd>
2184
<dt>-set filter:b=<em>b-spline_factor</em></dt>
2185
<dt>-set filter:c=<em>keys_alpha_factor</em></dt>
2186
<dd>Redefine the values used for cubic filters such as <kbd>Cubic</kbd>, <kbd>Catrom</kbd>, <kbd>Mitchel</kbd>, and <kbd>Hermite</kbd>, as well as the <kbd>Parzen</kbd> Sinc windowing function. If only one of the values are defined, the other will be set so as to generate a 'Keys' type cubic filter.</dd>
2188
<dd>Use this function directly as the scaling filter. This will allow you to
2189
directly use a 'windowing filter' such as <kbd>blackman</kbd>, rather than as
2190
its normal usage as a windowing function for 'Sinc' or 'Bessel'. If defined, no
2191
windowing function will be used, unless the following expert setting is also
2194
<dt>-set filter:window=<em>filter</em></dt> <dd>The IIR (infinite impulse
2195
response) filters <kbd>bessel</kbd> and <kbd>sinc</kbd> are windowed (brought
2196
down to zero over the defined support range) with the given filter. This
2197
allows you to use a filter that is not normally used as a windowing function,
2198
such as <kbd>box</kbd>, (which effectivally turns off the windowing function). </dd>
2024
2201
<p>For example, to get a 8 lobe Lanczos-Bessel filter:</p>
2026
convert image.png -filter bessel \
2027
-set filter:window=bessel -set filter:lobes=8 \
2028
-resize 150% image.jpg
2203
<p class='crt'><span class="crtprompt"> $magick> </span><span class='crtin'>convert image.png -filter bessel \ <br/>
2204
-set filter:window=bessel -set filter:lobes=8 \ <br/>
2205
-resize 150% image.jpg</span></p>
2030
2206
<p>Or a raw un-windowed Sinc filter with 4 lobes:</p>
2032
convert image.png -set filter:filter=sinc -set filter:lobes=4 \
2033
-resize 150% image.jpg
2208
<p class='crt'><span class="crtprompt"> $magick> </span><span class='crtin'>convert image.png -set filter:filter=sinc -set filter:lobes=4 \ <br/>
2209
-resize 150% image.jpg</span></p>
2036
2210
<p>Note that the use of expert options (except for 'blur' with simple resize
2037
2211
filters), are provided for image processing experts who have studied and
2038
2212
understood how resize filters work. Without this knowledge, and an
2083
2257
is a TrueType font file, <kbd>ps:helvetica</kbd> is PostScript font, and
2084
2258
<kbd>x:fixed</kbd> is X11 font.</p>
2260
<p>For other settings that affect fonts, see the options <a href="#family">-family</a>, <a href="#stretch">-stretch</a>, <a href="#style">-style</a>, and <a href="#weight">-weight</a>. </p>
2086
2263
<div style="margin: auto;">
2087
<h4><a name="foreground" id="foreground"></a>-foreground <em class="option">color</em></h4>
2264
<h4><a name="foreground" id="foreground"></a>-foreground <em class="arg">color</em></h4>
2090
<p>define the foreground color.</p>
2267
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Define the foreground color.</td><td style='text-align:right;'></td></tr></table>
2092
2269
<p>The color is specified using the format described under the <a href="#fill">-fill</a> option.</p>
2094
<div style="margin: auto;">
2095
<h4><a name="format" id="format"></a>-format <em class="option">type</em></h4>
2098
<p>the image format type.</p>
2100
<p>When used with the <kbd>mogrify</kbd> utility, this option converts any image to the image <a href="/www/formats.html">format</a> you specify. For a list of image format types supported by ImageMagick, see the output of this command: <kbd>identify -list format</kbd>.</p>
2102
<p>By default the file is written to its original name. However, if the filename extension matches a supported format, the extension is replaced with the image format type specified with <a href="#format">-format</a>. For example, if you specify <em class="option">tiff</em> as the format type and the input image filename is <em class="option">image.gif</em>, the output image filename becomes <em class="option">image.tiff</em>.</p>
2104
<div style="margin: auto;">
2105
<h4><a name="format" id="format"></a>-format <em class="option">string</em></h4>
2108
<p>output formatted image characteristics.</p>
2271
<p>The default foreground color is black.</p>
2273
<div style="margin: auto;">
2274
<h4><a name="format" id="format"></a>-format <em class="arg">type</em></h4>
2277
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>the image format type.</td><td style='text-align:right;'></td></tr></table>
2279
<p>When used with the <kbd>mogrify</kbd> utility, this option converts any image to the image <a href="/www/formats.html">format</a> you specify. For a list of image format types supported by ImageMagick, use <a href="#list">-list format</a>.</p>
2281
<p>By default the file is written to its original name. However, if the filename extension matches a supported format, the extension is replaced with the image format type specified with <a href="#format">-format</a>. For example, if you specify <em class="arg">tiff</em> as the format type and the input image filename is <em class="arg">image.gif</em>, the output image filename becomes <em class="arg">image.tiff</em>.</p>
2283
<div style="margin: auto;">
2284
<h4><a name="format_identify_" id="format_identify_"></a>-format <em class="arg">string</em></h4>
2287
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>output formatted image characteristics.</td><td style='text-align:right;'>[<a href="../www/identify.html">identify</a>]</td></tr></table>
2110
2289
<p>See <a href="../www/escape.html">Format and Print Image Properties</a> for an explanation on how to specify the argument to this option.</p>
2112
2291
<div style="margin: auto;">
2113
<h4><a name="frame" id="frame"></a>-frame <em class="option">width</em><br />-frame <em class="option">width</em>x<em class="option">height</em>{+-}<em class="option">outer-bevel-width</em>{+-}<em class="option">inner-bevel-width</em></h4>
2116
<p>surround the image with an ornamental border.</p>
2118
<p>See <a href="#resize">-resize</a>for details about the geometry specification. The <a href="#frame">-frame</a> option is not affected by the <a href="#gravity">-gravity</a> option.</p>
2120
<p>The color of the border is specified with the <a href="#mattecolor">-mattecolor</a> command line option.</p>
2122
<div style="margin: auto;">
2123
<h4><a name="frame" id="frame"></a>-frame</h4>
2126
<p>include the X window frame in the imported image.</p>
2128
<div style="margin: auto;">
2129
<h4><a name="fuzz" id="fuzz"></a>-fuzz <em class="option">distance</em>{<em class="option">%</em>}</h4>
2132
<p>colors within this distance are considered equal.</p>
2292
<h4><a name="frame" id="frame"></a>-frame <em class="arg">geometry</em></h4>
2295
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Surround the image with a border or beveled frame.</td><td style='text-align:right;'></td></tr></table>
2297
<p>The color of the border is specified with the <a href="#mattecolor">-mattecolor</a> command line option. </p>
2299
<p>See <a href="../www/command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. The <em class="arg">size</em> portion of the <em class="arg">geometry</em> argument indicates the amount of extra width and height that will be added to the dimensions of the image. If no offsets are given in the <em class="arg">geometry</em> argument, then the border added is a solid color. Offsets <em>x</em> and <em>y</em>, if present, specify that the width and height of the border is partitioned to form an outer bevel of thickness <em>x</em> pixels and an inner bevel of thickness <em>y</em> pixels. (Negative offsets make no sense here.) The <a href="#frame">-frame</a> option is not affected by the <a href="#gravity">-gravity</a> option.</p>
2302
<div style="margin: auto;">
2303
<h4><a name="frame_import_" id="frame_import_"></a>-frame</h4>
2306
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>include the X window frame in the imported image.</td><td style='text-align:right;'>[<a href="../www/import.html">import</a>]</td></tr></table>
2308
<div style="margin: auto;">
2309
<h4><a name="function" id="function"></a>-function <em class="arg">function</em> <em class="arg">parameters</em></h4>
2312
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Apply a function to channel values.</td><td style='text-align:right;'></td></tr></table>
2314
<p>This operator performs calculations based on the given arguments to modify each of the color values for each previously set <a href="#channel">-channel</a> in the image. See <a href="#evaluate">-evaluate</a> for details concerning how the results of the calculations are handled.</p>
2316
<p>This is can be considered a multi-argument version of the <a href="#evaluate">-evaluate</a> operator. (Added in IM 6.4.8−8.)</p>
2318
<p>Here, <em class="arg">parameters</em> is a comma-separated list of numerical values. The number of values varies depending on which <em class="arg">function</em> is selected. Choose the <em class="arg">function</em> from:</p>
2325
<p>To print a complete list of <a href="#function">-function</a> operators, use <a href="#list">-list function</a>. Descriptions follow.</p>
2328
<dt><kbd>Sinusoid</kbd></dt>
2330
<p>The <kbd>Sinusoid</kbd> function can be used to vary the channel values sinusoidally by setting frequency, phase shift, amplitude, and a bias. These values are given as one to four parameters, as follows,</p>
2332
<div style="text-align: center">
2333
-function <kbd>Sinusoid</kbd> <em class="arg">freq</em>,[<em class="arg">phase</em>,[<em class="arg">amp</em>,[<em class="arg">bias</em>]]]
2336
<p>where <em>phase</em> is in degrees. (The domain [0,1] of the function corresponds to 0 through <em class="arg">freq</em>×360 degrees.) The result is that if a pixel's normalized channel value is originally <b><em>u</em></b>, its resulting normalized value will be given by </p>
2338
<div style="text-align: center">
2339
<em class="arg">bias</em> + <em class="arg">amp</em> * sin(2π (<em class="arg">freq</em> * <b><em>u</em></b> + <em class="arg">phase</em> / 360) ).
2342
<p> For example, the following generates a curve that starts and ends at 0.9 (when <b><em>u</em></b>=0 and 1, resp.), oscillating three times between .7−.2=.5 and .7+.2=.9. </p>
2345
-function Sinusoid 3,-90,.2,.7
2348
<p>The default values of <em class="arg">amp</em> and <em class="arg">bias</em> are both .5. The default for <em class="arg">phase</em> is 0.</p>
2350
<p>The <kbd>Sinusoid</kbd> function generalizes <kbd>Sin</kbd> and <kbd>Cos</kbd> of the <a href="#evaluate">-evaluate</a> operator by allowing varying amplitude, phase and bias. The correspondence is as follows.</p>
2354
<td>-evaluate Sin <em class="arg">freq</em> </td>
2355
<td>-function Sinusoid <em class="arg">freq</em>,0 </td>
2358
<td>-evaluate Cos <em class="arg">freq</em> </td>
2359
<td>-function Sinusoid <em class="arg">freq</em>,90 </td>
2365
<dt><kbd>Polynomial</kbd></dt>
2367
<p>The <kbd>Polynomial</kbd> function takes an arbitrary number of parameters, these being the coefficients of a polynomial, in decreasing order of degree. That is, entering</p>
2369
<div style="text-align: center">
2370
-function Polynomial <em>a</em><sub><em>n</em></sub>,<em>a</em><sub><em>n</em>-1</sub>,...<em>a</em><sub>1</sub>,<em>a</em><sub>0</sub>
2373
<p>will invoke a polynomial function given by</p>
2375
<div style="text-align: center">
2376
<em>a</em><sub><em>n</em></sub> <b><em>u</em></b><sup><em>n</em></sup> +
2377
<em>a</em><sub><em>n</em>-1</sub> <b><em>u</em></b><sup><em>n</em>-1</sup> +
2378
··· <em>a</em><sub>1</sub> <b><em>u</em></b> + <em>a</em><sub>0</sub>,
2381
<p>where <b><em>u</em></b> is pixel's original normalized channel value.</p>
2383
<p>The <kbd>Polynomial</kbd> function can be used in place of <kbd>Set</kbd> (the <em>constant</em> polynomial) and <kbd>Add</kbd>, <kbd>Divide</kbd>, <kbd>Multiply</kbd>, and <kbd>Subtract</kbd> (some <em>linear</em> polynomials) of the <a href="#evaluate">-evaluate</a> operator. The <a href="#level">-level</a> operator also affects channels linearly. Some correspondences follow.</p>
2390
<td>-evaluate Set <em class="arg">value</em> </td>
2391
<td>-function Polynomial <em class="arg">value</em></td>
2392
<td>(Constant functions; set <em class="arg">value</em>×100% gray when channels are RGB.)</td>
2395
<td>-evaluate Add <em class="arg">value</em> </td>
2396
<td>-function Polynomial 1,<em class="arg">value</em></td>
2399
<td>-evaluate Subtract <em class="arg">value</em> </td>
2400
<td>-function Polynomial 1,−<em class="arg">value</em></td>
2403
<td>-evaluate Multiply <em class="arg">value</em> </td>
2404
<td>-function Polynomial <em class="arg">value</em>,0</td>
2407
<td>+level black% x white%</td>
2408
<td>-function Polynomial A,B</td>
2409
<td>(Reduce contrast. Here, A=(white-black)/100 and B=black/100.)</td>
2413
<p>The <kbd>Polynomial</kbd> function gives great versatility, since polynomials can be used to fit any continuous curve to any degree of accuracy desired.</p>
2418
<div style="margin: auto;">
2419
<h4><a name="fuzz" id="fuzz"></a>-fuzz <em class="arg">distance</em>{<em class="arg">%</em>}</h4>
2422
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Colors within this <em class="arg">distance</em> are considered equal.</td><td style='text-align:right;'></td></tr></table>
2134
2424
<p>A number of algorithms search for a target color. By default the color must be exact. Use this option to match colors that are close to the target color in RGB space. For example, if you want to automatically trim the edges of an image with <a href="#trim">-trim</a> but the image was scanned and the target background color may differ by a small amount. This option can account for these differences.</p>
2136
<p>The <em class="option">distance</em> can be in absolute intensity units or, by appending <kbd>%</kbd> as a percentage of the maximum possible intensity (255, 65535, or 4294967295).</p>
2426
<p>The <em class="arg">distance</em> can be in absolute intensity units or, by appending <kbd>%</kbd> as a percentage of the maximum possible intensity (255, 65535, or 4294967295).</p>
2139
2429
<div style="margin: auto;">
2140
<h4><a name="fx" id="fx"></a>-fx <em class="option">expression</em></h4>
2430
<h4><a name="fx" id="fx"></a>-fx <em class="arg">expression</em></h4>
2143
<p>apply a mathematical expression to an image or image channels.</p>
2433
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>apply a mathematical expression to an image or image channels.</td><td style='text-align:right;'></td></tr></table>
2145
<p>If the first character of <em class="option">expression</em> is <kbd>@</kbd>, the expression is read from a file titled by the remaining characters in the string.</p>
2435
<p>If the first character of <em class="arg">expression</em> is <kbd>@</kbd>, the expression is read from a file titled by the remaining characters in the string.</p>
2147
2437
<p>See <a href="../www/fx.html">FX, The Special Effects Image Operator</a> for a detailed discussion of this option.</p>
2150
2440
<div style="margin: auto;">
2151
<h4><a name="gamma" id="gamma"></a>-gamma <em class="option">value</em></h4>
2441
<h4><a name="gamma" id="gamma"></a>-gamma <em class="arg">value</em></h4>
2154
<p>level of gamma correction.</p>
2444
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>level of gamma correction.</td><td style='text-align:right;'></td></tr></table>
2156
2446
<p>The same color image displayed on two different workstations may look different due to differences in the display monitor. Use gamma correction to adjust for this color difference. Reasonable values extend from <kbd>0.8</kbd> to <kbd>2.3</kbd>. Gamma less than 1.0 darkens the image and gamma greater than 1.0 lightens it. Large adjustments to image gamma may result in the loss of some image information if the pixel quantum size is only eight bits (quantum range 0 to 255).</p>
2158
<p>Gammadjusts the image's channel values pixel-by-pixel according to a power law, namely, pow(pixel,1/gamma) or pixel^(1/gamma), where pixel is the normalized or 0 to 1 color value. For example, using a value of gamma=2 will be the same as taking the square root of the image.</p>
2448
<p>Gamma adjusts the image's channel values pixel-by-pixel according to a power law, namely, pow(pixel,1/gamma) or pixel^(1/gamma), where pixel is the normalized or 0 to 1 color value. For example, using a value of gamma=2 will be the same as taking the square root of the image.</p>
2160
2450
<p>You can apply separate gamma values to the red, green, and blue channels of the image with a gamma value list delimited with commas (e.g., <kbd>1.7,2.3,1.2</kbd>).</p>
2162
<p>Use <a href="#gamma">+gamma <em class="option">value</em></a> to set the image gamma level without actually adjusting the image pixels. This option is useful if the image is of a known gamma but not set as an image attribute (e.g. PNG images).</p>
2452
<p>Use <a href="#gamma">+gamma <em class="arg">value</em></a> to set the image gamma level without actually adjusting the image pixels. This option is useful if the image is of a known gamma but not set as an image attribute (e.g. PNG images).</p>
2164
<p>Note that gammadjustments is also available via the <a href="#level">-level</a> operator
2454
<p>Note that gamma adjustments are also available via the <a href="#level">-level</a> operator.</p>
2166
2456
<div style="margin: auto;">
2167
<h4><a name="gaussian-blur" id="gaussian-blur"></a>-gaussian-blur <em class="option">radius</em><br />-gaussian-blur <em class="option">radius</em>x<em class="option">sigma</em></h4>
2457
<h4><a name="gaussian-blur" id="gaussian-blur"></a>-gaussian-blur <em class="arg">radius</em><br />-gaussian-blur <em class="arg">radius</em>x<em class="arg">sigma</em></h4>
2170
<p>blur the image with a Gaussian operator.</p>
2460
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Blur the image with a Gaussian operator.</td><td style='text-align:right;'></td></tr></table>
2172
2462
<p>Convolve the image with a Gaussian or normal distribution. The formula is:</p>
2173
<ul><dd><img alt="gaussian distribution" width="243px" height="42px" src="../images/gaussian-blur.png"/></dd></ul>
2174
<p>where <i>r</i> is the blur radius (<i>r</i><sup>2</sup> = <i>u</i><sup>2</sup> + <i>v</i><sup>2</sup>), and σ is the standard deviation of the Gaussian distribution. As a guideline, set <i>r</i> to approximately 3σ. Specify a radius of 0 and ImageMagick selects a suitable radius for you.</p>
2177
<div style="margin: auto;">
2178
<h4><a name="geometry" id="geometry"></a>-geometry <em class="option">width</em><br />-geometry <em class="option">width</em>x<em class="option">height</em>{<em class="option">+-</em>}<em class="option">x</em>{<em class="option">+-</em>}<em class="option">y</em></h4>
2181
<p>preferred size and location of the image.</p>
2183
<p>If the <em class="option">x</em> is negative, the offset is measured leftward from the right edge of the screen to the right edge of the image being displayed. Similarly, negative <em class="option">y</em> is measured between the bottom edges. The offsets are not affected by <kbd>%</kbd>; they are always measured in pixels.</p>
2185
<div style="margin: auto;">
2186
<h4><a name="gravity" id="gravity"></a>-gravity <em class="option">type</em></h4>
2189
<p>direction primitive gravitates to when annotating the image.</p>
2191
<p>Choices are: <kbd>NorthWest</kbd>, <kbd>North</kbd>, <kbd>NorthEast</kbd>,
2464
<div class="eqn"><img alt="gaussian distribution" width="243px" height="42px" src="../images/gaussian-blur.png"/>
2467
<p>where <i>r</i> is the blur radius (<i>r</i><sup>2</sup> = <i>u</i><sup>2</sup> + <i>v</i><sup>2</sup>), and σ is the standard deviation of the Gaussian distribution. As a guideline, set <i>r</i> to approximately 3σ. Specify a radius of 0 and ImageMagick selects a suitable radius for you.</p>
2470
<div style="margin: auto;">
2471
<h4><a name="geometry" id="geometry"></a>-geometry <em class="arg">geometry</em></h4>
2474
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the preferred size and location of the image.</td><td style='text-align:right;'></td></tr></table>
2476
<p>See <a href="../www/command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
2478
<div style="margin: auto;">
2479
<h4><a name="gravity" id="gravity"></a>-gravity <em class="arg">type</em></h4>
2482
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Sets the current gravity suggestion for various other settings and options.</td><td style='text-align:right;'></td></tr></table>
2484
<p>Choices include: <kbd>NorthWest</kbd>, <kbd>North</kbd>, <kbd>NorthEast</kbd>,
2192
2485
<kbd>West</kbd>, <kbd>Center</kbd>, <kbd>East</kbd>, <kbd>SouthWest</kbd>,
2193
<kbd>South</kbd>, <kbd>SouthEast</kbd>. Or you can use <a
2194
href="#list">-list</a> with a '<kbd>Gravity</kbd>' option to get a complete
2486
<kbd>South</kbd>, <kbd>SouthEast</kbd>. Use <a href="#list">-list gravity</a> to get a complete
2195
2487
list of <a href="#gravity">-gravity</a> settings available in your ImageMagick
2196
2488
installation.</p>
2198
<p>The direction you choose specifies where to position the text when annotating the image. For example, a gravity of <kbd>Center</kbd> forces the text to be centered within the image. By default, the image gravity is <kbd>NorthWest</kbd>. See <a href="#draw">-draw</a> for more details about graphic primitives. Only the text primitive is affected by the <a href="#gravity">-gravity</a> option.</p>
2200
<p>The <a href="#gravity">-gravity</a> option is also used in concert with the <a href="#geometry">-geometry</a> option and other options that take <em class="option">geometry</em> as a parameter, such as the <a href="#crop">-crop</a> option. See <a href="#geometry">-geometry</a> for details of how the <a href="#gravity">-gravity</a> option interacts with the <kbd>x</kbd> and <kbd>y</kbd> parameters of a geometry specification.</p>
2490
<p>The direction you choose specifies where to position text or subimages. For example, a gravity of <kbd>Center</kbd> forces the text to be centered within the image. By default, the image gravity is <kbd>NorthWest</kbd>. See <a href="#draw">-draw</a> for more details about graphic primitives. Only the text primitive of <a href="#draw">-draw</a> affected by the <a href="#gravity">-gravity</a> option.</p>
2492
<p>The <a href="#gravity">-gravity</a> option is also used in concert with the <a href="#geometry">-geometry</a> setting and other settings or options that take <em class="arg">geometry</em> as an argument, such as the <a href="#crop">-crop</a> option. </p>
2494
<p>If a <a href="#gravity">-gravity</a> setting occurs before another option or setting having a <em class="arg">geometry</em> argument that specifies an offset, the offset is usually applied to the point within the image suggested by the <a href="#gravity">-gravity</a> argument. Thus, in the following command, for example, suppose the file <kbd>image.png</kbd> has dimensions 200x100. The offset specified by the argument to <a href="#region">-region</a> is (−40,+20). The argument to <a href="#gravity">-gravity</a> is <kbd>Center</kbd>, which suggests the midpoint of the image, at the point (100,50). The offset (−40,20) is applied to that point, giving (100−40,50+20)=(60,70), so the specified 10x10 region is located at that point. (In addition, the <a href="#gravity">-gravity</a> affects the region itself, which will be <em>centered</em> at the pixel coordinate (60,70). (See <a href="../www/command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.)</p>
2496
<p class='crt'><span class="crtprompt"> $magick> </span><span class='crtin'>convert image.png -gravity Center -region 10x10-40+20 -negate output.png</span></p>
2202
2497
<p>When used as an option to <a href="../www/composite.html">composite</a>, <a href="#gravity">-gravity</a> gives the direction that the image gravitates within the composite.</p>
2204
2499
<p>When used as an option to <a href="../www/montage.html">montage</a>, <a href="#gravity">-gravity</a> gives the direction that an image gravitates within a tile. The default gravity is <kbd>Center</kbd> for this purpose.</p>
2206
2501
<div style="margin: auto;">
2207
<h4><a name="green-primary" id="green-primary"></a>-green-primary <em class="option">x,y</em></h4>
2502
<h4><a name="green-primary" id="green-primary"></a>-green-primary <em class="arg">x,y</em></h4>
2210
<p>green chromaticity primary point.</p>
2505
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>green chromaticity primary point.</td><td style='text-align:right;'></td></tr></table>
2212
2507
<div style="margin: auto;">
2213
2508
<h4><a name="help" id="help"></a>-help</h4>
2216
<p>print usage instructions.</p>
2218
<div style="margin: auto;">
2219
<h4><a name="highlight-color" id="highlight-color"></a>-highlight-color <em class="option">color</em></h4>
2222
<p>when comparing images, emphasize pixel differences with this color.</p>
2224
<div style="margin: auto;">
2225
<h4><a name="iconGeometry" id="iconGeometry"></a>-iconGeometry <em class="option">geometry</em></h4>
2228
<p>specify the icon geometry.</p>
2511
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>print usage instructions.</td><td style='text-align:right;'></td></tr></table>
2513
<div style="margin: auto;">
2514
<h4><a name="highlight-color" id="highlight-color"></a>-highlight-color <em class="arg">color</em></h4>
2517
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>when comparing images, emphasize pixel differences with this color.</td><td style='text-align:right;'></td></tr></table>
2519
<div style="margin: auto;">
2520
<h4><a name="iconGeometry" id="iconGeometry"></a>-iconGeometry <em class="arg">geometry</em></h4>
2523
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>specify the icon geometry.</td><td style='text-align:right;'></td></tr></table>
2230
2525
<p>Offsets, if present in the geometry specification, are handled in the same manner as the <a href="#geometry">-geometry</a> option, using X11 style to handle negative offsets.</p>
2527
<p>See <a href="../www/command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
2232
2529
<div style="margin: auto;">
2233
2530
<h4><a name="iconic" id="iconic"></a>-iconic</h4>
2236
<p>iconic animation.</p>
2533
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>iconic animation.</td><td style='text-align:right;'></td></tr></table>
2238
2535
<div style="margin: auto;">
2239
2536
<h4><a name="identify" id="identify"></a>-identify</h4>
2242
<p>identify the format and characteristics of the image.</p>
2539
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>identify the format and characteristics of the image.</td><td style='text-align:right;'></td></tr></table>
2244
<p>This information is printed: image scene number; image name; image size; the image class (<em class="option">DirectClass</em> or <em class="option">PseudoClass</em>); the total number of unique colors; and the number of seconds to read and transform the image. Refer to <a href="../www/miff.html">MIFF</a> for a description of the image class.</p>
2541
<p>This information is printed: image scene number; image name; image size; the image class (<em class="arg">DirectClass</em> or <em class="arg">PseudoClass</em>); the total number of unique colors; and the number of seconds to read and transform the image. Refer to <a href="../www/miff.html">MIFF</a> for a description of the image class.</p>
2246
2543
<p>If <a href="#colors">-colors</a> is also specified, the total unique colors in the image and color reduction error values are printed. Refer to <a href="/www/quantize.html">color reduction algorithm</a> for a description of these values.</p>
2400
2708
<div style="margin: auto;">
2401
<h4><a name="layers" id="layers"></a>-layers <em class="option">method</em></h4>
2709
<h4><a name="layers" id="layers"></a>-layers <em class="arg">method</em></h4>
2404
<p>handle multiple images forming a set of image layers or animation frames.</p>
2712
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>handle multiple images forming a set of image layers or animation frames.</td><td style='text-align:right;'></td></tr></table>
2406
2714
<p>Perform various image operation methods to a ordered sequence of images
2407
2715
which may represent either a set of overlaid 'image layers', a GIF disposal
2408
2716
animation, or a fully-'coalesced' animation sequence. </p>
2410
<table id="table" cellpadding="2" cellspacing="0" style="width: 93%">
2413
2721
<th align="left" style="width: 8%">Method</th>
2414
2722
<th align="left">Description</th>
2418
2726
<td valign="top">compare-any</td>
2419
2727
<td valign="top">Crop the second and later frames to the smallest rectangle
2420
2728
that contains all the differences between the two images. No GIF <a
2421
href="#dispose" >-dispose</A> methods are taken into account. <p>
2729
href="#dispose" >-dispose</a> methods are taken into account. </td>
2423
This exactly the same as the <a href="#deconstruct"
2732
<tr><td></td><td>This exactly the same as the <a href="#deconstruct"
2424
2733
>-deconstruct</a> operator, and does not preserve animations normal
2425
2734
working, especially when animation used layer disposal methods such as
2426
2735
'<kbd>Previous</kbd>' or '<kbd>Background</kbd>'. </td>
2430
2739
<td valign="top">compare-clear</td>
2431
2740
<td valign="top">As '<kbd>compare-any</kbd>' but crop to the bounds of any
2432
2741
opaque pixels which become transparent in the second frame. That is the
2433
2742
smallest image needed to mask or erase pixels for the next frame. </td>
2437
2746
<td valign="top">compare-overlay</td>
2438
2747
<td valign="top">As '<kbd>compare-any</kbd>' but crop to pixels that add
2439
2748
extra color to the next image, as a result of overlaying color pixels.
2440
That is the smallest single overlaid image to add or change colors. <p>
2749
That is the smallest single overlaid image to add or change colors. </td>
2442
This can, be used with the <a href="#compose" >-compose</A> alpha
2752
<tr><td></td><td>This can be used with the <a href="#compose" >-compose</a> alpha
2443
2753
composition method '<kbd>change-mask</kbd>', to reduce the image to
2444
2754
just the pixels that need to be overlaid. </td>
2448
2758
<td valign="top">coalesce</td>
2449
2759
<td valign="top">Equivalent to a call to the <a href="#coalesce"
2450
2760
>-coalesce</a> operator. Apply the layer disposal methods set in the
2451
2761
current image sequence to form a fully defined animation sequence, as
2452
2762
it should be displayed. Effectively converting a GIF animation into a
2453
'film strip' like animation. </td>
2763
'film strip'-like animation. </td>
2457
2767
<td valign="top">composite</td>
2458
2768
<td valign="top">Alpha Composition of two image lists, separated by a
2459
2769
"<kbd>null:</kbd>" image, with the destination image list first, and
2460
2770
the source images last. An image from each list are composited
2461
2771
together until one list is finished. The separator image and source
2462
image lists are removed. <p>
2464
The <a href="#geometry" >-geometry</a> offset is adjusted according to
2772
image lists are removed. </td>
2776
<tr><td></td><td>The <a href="#geometry" >-geometry</a> offset is adjusted according to
2465
2777
<a href="#gravity" >-gravity</a> in accordance of the virtual canvas
2466
2778
size of the first image in each list. Unlike a normal <a
2467
2779
href="#composite" >-composite</a> operation, the canvas offset is also
2468
added to the final composite positioning of each image. <p>
2780
added to the final composite positioning of each image. </td>
2470
If one of the image lists only contains one image, that image is
2783
<tr><td></td><td>If one of the image lists only contains one image, that image is
2471
2784
applied to all the images in the other image list, regardless of which
2472
2785
list it is. In this case it is the image meta-data of the list which
2473
2786
preserved. </td>
2477
2791
<td valign="top">dispose</td>
2478
2792
<td valign="top">This like '<kbd>coalesce</kbd>' but shows the look of
2479
2793
the animation after the layer disposal method has been applied, before
2705
3026
<div style="margin: auto;">
2706
<h4><a name="limit" id="limit"></a>-limit <em class="option">type value</em></h4>
3027
<h4><a name="limit" id="limit"></a>-limit <em class="arg">type value</em></h4>
2709
<p>pixel cache resource limit.</p>
2711
<p>Choose from: <kbd>Area</kbd>, <kbd>Disk</kbd>, <kbd>File</kbd>, <kbd>Map</kbd>, <kbd>or Memory.</kbd></p>
2713
<p>The value for <kbd>File</kbd> is in number of files. The other limits are in bytes. By default the limits are 768 files, 1024MB memory, 4096MB map, and unlimited disk, but these are adjusted at startup time on platforms that can provide information about available resources. When the limit is reached, ImageMagick will fail in some fashion, or take compensating actions if possible. For example,</p>
3030
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the pixel cache resource limit.</td><td style='text-align:right;'></td></tr></table>
3032
<p>Choose from: <kbd>area</kbd>, <kbd>disk</kbd>, <kbd>file</kbd>, <kbd>map</kbd>, or <kbd>memory</kbd>.</p>
3034
<p>The value for <kbd>file</kbd> is in number of files. The other limits are in bytes. By default the limits are 768 files, 2gb of image area, 1.5gb memory, 8gb memory map, and 16tb of disk. These limits are adjusted relative to the available resources on your computer if this information is available. When any limit is reached, ImageMagick fails in some fashion but attempts to take compensating actions, if possible. For example, the following limits memory:</p>
2716
3037
-limit memory 32mb -limit map 64mb
2719
<p>limits memory. When the pixel cache reaches the memory limit it uses memory mapping. When that limit is reached it goes to disk. If disk has a hard limit, the program fails.</p>
2721
<p>Resource limits may also be set using <a href="../www/resources.html#environment">environment variables</a>. Set the environment variables <kbd>MAGICK_AREA_LIMIT</kbd>, <kbd>MAGICK_DISK_LIMIT</kbd>, <kbd>MAGICK_FILE_LIMIT</kbd>, <kbd>MAGICK_MEMORY_LIMIT</kbd>, and <kbd>MAGICK_MAP_LIMIT</kbd> limits for image area, disk space, open files, heap memory, and memory map respectively.</p> <p>You can use the option <a href="#list">-list resource</a> to list the current limits.</p>
3040
<p>Use <a href="#list">-list resource</a> to list the current limits. For example, our system shows these limits:</p>
3042
<p class='crt'><span class="crtprompt"> $magick> </span><span class='crtin'>identify -list resource</span><span class='crtout'><pre>File Area Memory Map Disk
3043
------------------------------------------------
3044
768 3.8187gb 2.864gb 7.6375gb 16eb </pre>
3046
<p>Requests for pixel storage to keep intermediate images are satisfied by one of three resource categories: in-memory pool, memory-mapped files pool, and disk pool (in that order) depending on the <a href="../www/command-line-options.html#limit">‑limit</a> settings and whether the system honors a resource request. If the total size of allocated pixel storage in the given pool reaches the corresponding limit, the request is passed to the next pool. Additionally, requests that exceed the <kbd>area</kbd> limit automatically are allocated on disk.</p>
3048
<p>To illustrate how ImageMagick utilizes resource limits, consider a typical image resource request. First, ImageMagick tries to allocate the pixels in memory. The request might be denied if the resource request exceeds the <kbd>memory</kbd> limit or if the system does not honor the request. If a memory request is not honored, the pixels are allocated to disk and the file is memory-mapped. However, if the allocation request exceeds the <kbd>map</kbd> limit, the resource allocation goes to disk. In all cases, if the resource request exceeds the <kbd>area</kbd> limit, the pixels are automatically cached to disk. If the disk has a hard limit, the program fails.</p>
3050
<p>In most cases you simply do not need to concern yourself with resource limits. ImageMagick chooses reasonable defaults and most images do not tax your computer resources. Where limits do come in handy is when you process images that are large or on shared systems where ImageMagick can consume all or most of the available memory. In this case, the ImageMagick workflow slows other processes or, in extreme cases, brings the system to a halt. Under these circumstances, setting limits give some assurances that the ImageMagick workflow will not interfere with other concurrent uses of the computer. For example, assume you have a web interface that processes images uploaded from the Internet. To assure ImageMagick does not exceed 10mb of memory you can simply set the area limit to 10mb:</p>
3056
<p>Now whenever a large image is processed, the pixels are automatically cached to disk instead of memory. This of course implies that large images will process very slowly, simply because pixel processing in memory can be an order of magnitude faster than on disk. Because your web site users might inadvertedly upload a huge image to process, you should set a disk limit as well:</p>
3059
-limit area 10mb -limit disk 500mb
3062
<p>Here ImageMagick stops processing if an image requires more than 500MB of disk storage.</p>
3064
<p>In addition to command-line resource limit option, resources can be set with <a href="../www/resources.html#environment">environment variables</a>. Set the environment variables <kbd>MAGICK_AREA_LIMIT</kbd>, <kbd>MAGICK_DISK_LIMIT</kbd>, <kbd>MAGICK_FILE_LIMIT</kbd>, <kbd>MAGICK_MEMORY_LIMIT</kbd>, and <kbd>MAGICK_MAP_LIMIT</kbd> for limits of image area, disk space, open files, heap memory, and memory map, respectively.</p>
3066
<p> Inquisitive users can try adding <a href="#debug">-debug cache</a> to their commands and then scouring the generated output for references to the pixel cache, in order to determine how the pixel cache was allocated and how resources were consumed. Advanced Unix/Linux users can pipe that output through <kbd>grep memory|open|destroy|disk</kbd> for more readable sifting.
3069
<p>For more about ImageMagick's use of resources, see the section <b>Cache Storage and Resource Requirements</b> on the <a href="../www/architecture.html#cache">Architecture</a> page.
2723
3072
<div style="margin: auto;">
2724
<h4><a name="linear-stretch" id="linear-stretch"></a>-linear-stretch <em class="option">black-point</em><br />-linear-stretch <em class="option">black-point</em>{x<em class="option">white-point</em>}{<em class="option">%</em>}}</h4>
3073
<h4><a name="linear-stretch" id="linear-stretch"></a>-linear-stretch <em class="arg">black-point</em><br />-linear-stretch <em class="arg">black-point</em>{x<em class="arg">white-point</em>}{<em class="arg">%</em>}}</h4>
2727
<p>Linear with saturation stretch.</p>
3076
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Linear with saturation stretch.</td><td style='text-align:right;'></td></tr></table>
2729
3078
<div style="margin: auto;">
2730
3079
<h4><a name="linewidth" id="linewidth"></a>-linewidth</h4>
2733
<p>the line width for subsequent draw operations.</p>
2735
<div style="margin: auto;">
2736
<h4><a name="liquid-rescale" id="liquid-rescale"></a>-liquid-rescale <em class="option">geometry</em></h4>
2739
<p>rescale image with seam-carving.</p>
2741
<div style="margin: auto;">
2742
<h4><a name="list" id="list"></a>-list <em class="option">type</em></h4>
2745
<p>print a list of supported option arguments. Choose from these list types:</p>
3082
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>the line width for subsequent draw operations.</td><td style='text-align:right;'></td></tr></table>
3084
<div style="margin: auto;">
3085
<h4><a name="liquid-rescale" id="liquid-rescale"></a>-liquid-rescale <em class="arg">geometry</em></h4>
3088
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>rescale image with seam-carving.</td><td style='text-align:right;'></td></tr></table>
3090
<p>See <a href="../www/command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
3092
<div style="margin: auto;">
3093
<h4><a name="list" id="list"></a>-list <em class="arg">type</em></h4>
3096
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Print a list of supported arguments for various options or settings. Choose from these list types:</td><td style='text-align:right;'></td></tr></table>
2747
3098
<pre class="text">
3131
3481
<div style="margin: auto;">
3132
<h4><a name="page" id="page"></a>-page <em class="option">width</em>x<em class="option">height</em>{<em class="option">+-</em>}<em class="option">x</em>{<em class="option">+-</em>}<em class="option"> y</em>{<em class="option">%</em>}{<em class="option">!</em>}{<em class="option"></em>}{<em class="option"></em>}</h4> </div>
3134
<p>size and location of an image on the larger virtual canvas.</p>
3136
<p>Use this option to specify the dimensions of the <em class="option">PostScript</em> page in dots per inch or a TEXT page in pixels. The choices for a PostScript page are:</p>
3179
<p>For convenience you can specify the page size by media (e.g. A4, Ledger, etc.). Otherwise, <a href="#page">-page</a> behaves much like <a href="#geometry">-geometry</a> (e.g. <a href="#page">-page letter+43+43</a>).</p>
3181
<p>This option is also used to place subimages when writing to a multi-image format that supports offsets, such as GIF89 and MNG. When used for this purpose the offsets are always measured from the top left corner of the canvas and are not affected by the <a href="#gravity">-gravity</a> option. To position a GIF or MNG image, use <a href="#page">-page</a><em class="option">{+-}x{+-}y</em> (e.g. -page +100+200). When writing to a MNG file, a <a href="#page">-page</a> option appearing ahead of the first image in the sequence with nonzero width and height defines the width and height values that are written in the <kbd>MHDR</kbd> chunk. Otherwise, the MNG width and height are computed from the bounding box that contains all images in the sequence. When writing a GIF89 file, only the bounding box method is used to determine its dimensions.</p>
3183
<p>For a PostScript page, the image is sized as in <a href="#geometry">-geometry</a> and positioned relative to the lower left hand corner of the page by {+-}<kbd>x</kbd><em class="option">offset</em>{+-}<kbd>y</kbd> <em class="option">offset</em>. Use <a href="#page">-page 612x792</a>, for example, to center the image within the page. If the image size exceeds the PostScript page, it is reduced to fit the page. The default gravity for the <a href="#page">-page</a> option is <em class="option">NorthWest</em>, i.e., positive <kbd>x</kbd> and <kbd>y</kbd> <em class="option">offset</em> are measured rightward and downward from the top left corner of the page, unless the <a href="#gravity">-gravity</a> option is present with a value other than <em class="option">NorthWest</em>.</p>
3482
<h4><a name="page" id="page"></a>-page <em class="arg">geometry</em><br/>
3483
-page <em class="arg">media</em>[<em class="arg">offset</em>][{<em class="arg">^!<></em>}]<br/>
3488
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the size and location of an image on the larger virtual canvas.</td><td style='text-align:right;'></td></tr></table>
3490
<p>See <a href="../www/command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
3492
<p>For convenience you can specify the page size using <em class="arg">media</em> (see below). Offsets can then be added as with other <em class="arg">geometry</em> arguments (e.g. <a href="#page">-page</a> <kbd>Letter+43+43</kbd>).</p>
3494
<p>Use <em class="arg">media</em> as shorthand to specify the dimensions (<em class="arg">width</em>x<em class="arg">height</em>) of the <em class="arg">PostScript</em> page in dots per inch or a TEXT page in pixels. The choices for a PostScript page are:</p>
3495
<table id="geometryTable" cellpadding="2" cellspacing="0" border="1" width="50%" style="margin-left: auto; margin-right: auto;">
3498
<th align="center"><em class="arg">media</em></th>
3499
<th align="center"><em class="arg">width</em></th>
3500
<th align="center"><em class="arg">height</em></th>
3504
<tr><td align="left"> 11x17 </td> <td align="right"> 792</td> <td align="right"> 1224</td> </tr>
3505
<tr><td align="left"> Ledger </td> <td align="right"> 1224</td> <td align="right"> 792</td> </tr>
3506
<tr><td align="left"> Legal </td> <td align="right"> 612</td> <td align="right"> 1008</td> </tr>
3507
<tr><td align="left"> Letter </td> <td align="right"> 612</td> <td align="right"> 792</td> </tr>
3508
<tr><td align="left"> LetterSmall</td> <td align="right"> 612</td> <td align="right"> 792</td> </tr>
3509
<tr><td align="left"> ArchE </td> <td align="right"> 2592</td> <td align="right"> 3456</td> </tr>
3510
<tr><td align="left"> ArchD </td> <td align="right"> 1728</td> <td align="right"> 2592</td> </tr>
3511
<tr><td align="left"> ArchC </td> <td align="right"> 1296</td> <td align="right"> 1728</td> </tr>
3512
<tr><td align="left"> ArchB </td> <td align="right"> 864</td> <td align="right"> 1296</td> </tr>
3513
<tr><td align="left"> ArchA </td> <td align="right"> 648</td> <td align="right"> 864</td> </tr>
3514
<tr><td align="left"> A0 </td> <td align="right"> 2380</td> <td align="right"> 3368</td> </tr>
3515
<tr><td align="left"> A1 </td> <td align="right"> 1684</td> <td align="right"> 2380</td> </tr>
3516
<tr><td align="left"> A2 </td> <td align="right"> 1190</td> <td align="right"> 1684</td> </tr>
3517
<tr><td align="left"> A3 </td> <td align="right"> 842</td> <td align="right"> 1190</td> </tr>
3518
<tr><td align="left"> A4 </td> <td align="right"> 595</td> <td align="right"> 842</td> </tr>
3519
<tr><td align="left"> A4Small </td> <td align="right"> 595</td> <td align="right"> 842</td> </tr>
3520
<tr><td align="left"> A5 </td> <td align="right"> 421</td> <td align="right"> 595</td> </tr>
3521
<tr><td align="left"> A6 </td> <td align="right"> 297</td> <td align="right"> 421</td> </tr>
3522
<tr><td align="left"> A7 </td> <td align="right"> 210</td> <td align="right"> 297</td> </tr>
3523
<tr><td align="left"> A8 </td> <td align="right"> 148</td> <td align="right"> 210</td> </tr>
3524
<tr><td align="left"> A9 </td> <td align="right"> 105</td> <td align="right"> 148</td> </tr>
3525
<tr><td align="left"> A10 </td> <td align="right"> 74</td> <td align="right"> 105</td> </tr>
3526
<tr><td align="left"> B0 </td> <td align="right"> 2836</td> <td align="right"> 4008</td> </tr>
3527
<tr><td align="left"> B1 </td> <td align="right"> 2004</td> <td align="right"> 2836</td> </tr>
3528
<tr><td align="left"> B2 </td> <td align="right"> 1418</td> <td align="right"> 2004</td> </tr>
3529
<tr><td align="left"> B3 </td> <td align="right"> 1002</td> <td align="right"> 1418</td> </tr>
3530
<tr><td align="left"> B4 </td> <td align="right"> 709</td> <td align="right"> 1002</td> </tr>
3531
<tr><td align="left"> B5 </td> <td align="right"> 501</td> <td align="right"> 709</td> </tr>
3532
<tr><td align="left"> C0 </td> <td align="right"> 2600</td> <td align="right"> 3677</td> </tr>
3533
<tr><td align="left"> C1 </td> <td align="right"> 1837</td> <td align="right"> 2600</td> </tr>
3534
<tr><td align="left"> C2 </td> <td align="right"> 1298</td> <td align="right"> 1837</td> </tr>
3535
<tr><td align="left"> C3 </td> <td align="right"> 918</td> <td align="right"> 1298</td> </tr>
3536
<tr><td align="left"> C4 </td> <td align="right"> 649</td> <td align="right"> 918</td> </tr>
3537
<tr><td align="left"> C5 </td> <td align="right"> 459</td> <td align="right"> 649</td> </tr>
3538
<tr><td align="left"> C6 </td> <td align="right"> 323</td> <td align="right"> 459</td> </tr>
3539
<tr><td align="left"> Flsa </td> <td align="right"> 612</td> <td align="right"> 936</td> </tr>
3540
<tr><td align="left"> Flse </td> <td align="right"> 612</td> <td align="right"> 936</td> </tr>
3541
<tr><td align="left"> HalfLetter </td> <td align="right"> 396</td> <td align="right"> 612</td> </tr>
3548
<p>This option is also used to place subimages when writing to a multi-image format that supports offsets, such as GIF89 and MNG. When used for this purpose the offsets are always measured from the top left corner of the canvas and are not affected by the <a href="#gravity">-gravity</a> option. To position a GIF or MNG image, use <a href="#page">-page</a><em class="arg">{+-}x{+-}y</em> (e.g. -page +100+200). When writing to a MNG file, a <a href="#page">-page</a> option appearing ahead of the first image in the sequence with nonzero width and height defines the width and height values that are written in the <kbd>MHDR</kbd> chunk. Otherwise, the MNG width and height are computed from the bounding box that contains all images in the sequence. When writing a GIF89 file, only the bounding box method is used to determine its dimensions.</p>
3550
<p>For a PostScript page, the image is sized as in <a href="#geometry">-geometry</a> but positioned relative to the <em>lower left-hand corner</em> of the page by {+-}<kbd>x</kbd><em class="arg">offset</em>{+-}<kbd>y</kbd> <em class="arg">offset</em>. Use <a href="#page">-page 612x792</a>, for example, to center the image within the page. If the image size exceeds the PostScript page, it is reduced to fit the page. The default gravity for the <a href="#page">-page</a> option is <em class="arg">NorthWest</em>, i.e., positive <kbd>x</kbd> and <kbd>y</kbd> <em class="arg">offset</em> are measured rightward and downward from the top left corner of the page, unless the <a href="#gravity">-gravity</a> option is present with a value other than <em class="arg">NorthWest</em>.</p>
3185
3552
<p>The default page dimensions for a TEXT image is 612x792.</p>
3485
3869
<p>Use <a href="#repage">+repage</a> to completely remove/reset the virtual
3486
3870
canvas meta-data from the images. </p>
3488
<p>The <a href="#set">-set</a> '<kbd>page</kbd>' option can be used to just
3872
<p>The <a href="#set">-set</a> '<kbd>page</kbd>' option can be used to
3489
3873
directly assign virtual canvas meta-data. </p>
3492
3876
<div style="margin: auto;">
3493
<h4><a name="resample" id="resample"></a>-resample <em class="option">horizontalxvertical</em></h4>
3877
<h4><a name="resample" id="resample"></a>-resample <em class="arg">horizontal</em>x<em class="arg">vertical</em></h4>
3496
<p>Resample image to specified horizontal and vertical resolution.</p>
3880
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Resample image to specified horizontal and vertical resolution.</td><td style='text-align:right;'></td></tr></table>
3498
3882
<p>Resize the image so that its rendered size remains the same as the original at the specified target resolution. For example, if a 300 DPI image renders at 3 inches by 2 inches on a 300 DPI device, when the image has been resampled to 72 DPI, it will render at 3 inches by 2 inches on a 72 DPI device. Note that only a small number of image formats (e.g. JPEG, PNG, and TIFF) are capable of storing the image resolution. For formats which do not support an image resolution, the original resolution of the image must be specified via <a href="#density">-density</a> on the command line prior to specifying the resample resolution.</p>
3500
3884
<p>Note that Photoshop stores and obtains image resolution from a proprietary embedded profile. If this profile exists in the image, then Photoshop will continue to treat the image using its former resolution, ignoring the image resolution specified in the standard file header.</p>
3502
3886
<div style="margin: auto;">
3503
<h4><a name="resize" id="resize"></a>-resize <em class="option">width</em><br />-resize <em class="option">width</em>x<em class="option">height</em>{<em class="option">%</em>} {<em class="option">@</em>} {<em class="option">!</em>} {<em class="option"><</em>} {<em class="option">></em>} {<em class="option">^</em>}</h4>
3887
<h4><a name="resize" id="resize"></a>-resize <em class="arg">geometry</em></h4>
3506
<p>resize an image.</p>
3508
<p>By default, the width and height are maximum values. That is, the image is expanded or contracted to fit the width and height value while maintaining the aspect ratio of the image. Append an exclamation point to the geometry to force the image size to exactly the size you specify. For example, if you specify <kbd>640x480!</kbd> the image width is set to 640 pixels and height to 480.</p>
3510
<p>If only the width is specified, the width assumes the value and the height is chosen to maintain the aspect ratio of the image. Similarly, if only the height is specified (e.g., <kbd>-resize x256</kbd>, the width is chosen to maintain the aspect ratio.</p>
3512
<p>To specify a percentage width or height instead, append %. The image size is multiplied by the width and height percentages to obtain the final image dimensions. To increase the size of an image, use a value greater than 100 (e.g. 125%). To decrease an image's size, use a percentage less than 100.</p>
3514
<p>Use <kbd>@</kbd> to specify the maximum area in pixels of an image.</p>
3516
<p>Use <kbd>></kbd> to change the dimensions of the image <em>only</em> if its width or height exceeds the geometry specification. <kbd><</kbd> resizes the image <em>only</em> if both of its dimensions are less than the geometry specification. For example, if you specify <kbd>640x480></kbd> and the image size is 256x256, the image size does not change. However, if the image is 512x512 or 1024x1024, it is resized to 480x480. Enclose the geometry specification in quotation marks to prevent the <kbd><</kbd> or <kbd>></kbd> from being interpreted by your shell as a file redirection.</p>
3518
<p>Use <kbd>^</kbd> to set a minimum image size limit. The geometry <kbd>640x480^</kbd>, for example, means the image width will not be less than 640 and the image height will not be less than 480 pixels after the resize. One of those dimensions will match the requested size, but the image will likely overflow the space requested to preserve its aspect ratio. The <kbd>^</kbd> feature is new as of IM 6.3.8-2</p>
3890
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Resize an image.</td><td style='text-align:right;'></td></tr></table>
3892
<p>See <a href="../www/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 ignored, and the <a href="#gravity">-gravity</a> option has no effect.</p>
3520
3894
<p>If the <a href="#filter">-filter</a> option precedes the <a href="#resize">-resize</a> option, the image is resized with the specified filter.</p>
3522
3896
<div style="margin: auto;">
3523
<h4><a name="respect-parenthesis" id="respect-parenthesis"></a>-respect-parenthesis</h4>
3897
<h4><a name="respect-parentheses" id="respect-parentheses"></a>-respect-parentheses</h4>
3526
<p>settings remain in effect until parenthesis boundary.</p>
3900
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>settings remain in effect until parenthesis boundary.</td><td style='text-align:right;'></td></tr></table>
3528
3902
<div style="margin: auto;">
3529
3903
<h4><a name="reverse" id="reverse"></a>-reverse</h4>
3532
<p>Reverse the order of images in the current image list.</p>
3535
<div style="margin: auto;">
3536
<h4><a name="roll" id="roll"></a>-roll {<em class="option">+-</em>}<em class="option">x</em>{<em class="option">+-</em>}<em class="option">y</em></h4>
3539
<p>roll an image vertically or horizontally by the amount given.</p>
3541
<p>A negative <em class="option">x</em> offset rolls the image left-to-right. A negative <em class="option">y</em> offset rolls the image top-to-bottom.</p>
3544
<div style="margin: auto;">
3545
<h4><a name="rotate" id="rotate"></a>-rotate <em class="option">degrees</em>{<em class="option"><</em>}{<em class="option">></em>}</h4>
3548
<p>Apply Paeth image rotation (using shear operations) to the image.</p>
3906
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Reverse the order of images in the current image list.</td><td style='text-align:right;'></td></tr></table>
3909
<div style="margin: auto;">
3910
<h4><a name="roll" id="roll"></a>-roll {<em class="arg">+-</em>}<em class="arg">x</em>{<em class="arg">+-</em>}<em class="arg">y</em></h4>
3913
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>roll an image vertically or horizontally by the amount given.</td><td style='text-align:right;'></td></tr></table>
3915
<p>A negative <em class="arg">x</em> offset rolls the image left-to-right. A negative <em class="arg">y</em> offset rolls the image top-to-bottom.</p>
3918
<div style="margin: auto;">
3919
<h4><a name="rotate" id="rotate"></a>-rotate <em class="arg">degrees</em>{<em class="arg"><</em>}{<em class="arg">></em>}</h4>
3922
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Apply Paeth image rotation (using shear operations) to the image.</td><td style='text-align:right;'></td></tr></table>
3550
3924
<p>Use <kbd>></kbd> to rotate the image only if its width exceeds the height. <kbd><</kbd> rotates the image <em>only</em> if its width is less than the height. For example, if you specify <kbd>-rotate "-90>"</kbd> and the image size is 480x640, the image is not rotated. However, if the image is 640x480, it is rotated by -90 degrees. If you use <kbd>></kbd> or <kbd><</kbd>, enclose it in quotation marks to prevent it from being misinterpreted as a file redirection.</p>
3595
3969
<h4><a name="screen" id="screen"></a>-screen</h4>
3598
<p>specify the screen to capture.</p>
3972
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>specify the screen to capture.</td><td style='text-align:right;'></td></tr></table>
3600
3974
<p>This option indicates that the GetImage request used to obtain the image should be done on the root window, rather than directly on the specified window. In this way, you can obtain pieces of other windows that overlap the specified window, and more importantly, you can capture menus or other popups that are independent windows but appear over the specified window.</p>
3602
3976
<div style="margin: auto;">
3603
<h4><a name="segment" id="segment"></a>-segment <em class="option">cluster-threshold</em>x<em class="option">smoothing-threshold</em></h4>
3606
<p>segment the colors of an image.</p>
3608
<p>Segment an image by analyzing the histograms of the color components and identifying units that are homogeneous with the fuzzy c-means technique. This part of the ImageMagick color quantization routines. </p>
3610
<p>Specify <em class="option">cluster threshold</em> as the number of pixels in each cluster that must exceed the cluster threshold to be considered valid. <em class="option">Smoothing threshold</em> eliminates noise in the second derivative of the histogram. As the value is increased, you can expect a smoother second derivative. The default is 1.5.</p>
3977
<h4><a name="seed" id="seed"></a>-seed</h4>
3980
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>seed a new sequence of pseudo-random numbers</td><td style='text-align:right;'></td></tr></table>
3982
<div style="margin: auto;">
3983
<h4><a name="segment" id="segment"></a>-segment <em class="arg">cluster-threshold</em>x<em class="arg">smoothing-threshold</em></h4>
3986
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>segment the colors of an image.</td><td style='text-align:right;'></td></tr></table>
3988
<p>Segment an image by analyzing the histograms of the color components and identifying units that are homogeneous with the fuzzy c-means technique. This is part of the ImageMagick color quantization routines. </p>
3990
<p>Specify <em class="arg">cluster threshold</em> as the number of pixels in each cluster that must exceed the cluster threshold to be considered valid. <em class="arg">Smoothing threshold</em> eliminates noise in the second derivative of the histogram. As the value is increased, you can expect a smoother second derivative. The default is 1.5.</p>
3612
3992
<p>If the <a href="#verbose">-verbose</a> setting is defined, a detailed report
3613
3993
of the color clusters is returned.</p>
3616
3996
<div style="margin: auto;">
3617
<h4><a name="seed" id="seed"></a>-seed</h4>
3997
<h4><a name="selective-blur" id="selective-blur"></a>-selective-blur <em class="arg">geometry</em></h4>
3620
<p>seed a new sequence of pseudo-random numbers</p>
4000
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Selectively blur pixels within a contrast threshold.</td><td style='text-align:right;'></td></tr></table>
3622
4002
<div style="margin: auto;">
3623
4003
<h4><a name="separate" id="separate"></a>-separate</h4>
3626
<p>separate an image channel into a grayscale image. Specify the channel with <a href="#channel">-channel</a>.</p>
3628
<div style="margin: auto;">
3629
<h4><a name="sepia-tone" id="sepia-tone"></a>-sepia-tone <em class="option">threshold</em></h4>
3632
<p>simulate a sepia-toned photo.</p>
3634
<p>Specify <em class="option">threshold</em> as the percent threshold of the intensity (0 - 99.9%).</p>
3636
<p>This option applies a special effect to the image, similar to the effect achieved in a photo darkroom by sepia toning. Threshold ranges from 0 to QuantumRange and is a measure of the extent of the sepia toning. A threshold of 80% is a good starting point for a reasonable tone.</p>
3638
<div style="margin: auto;">
3639
<h4><a name="set" id="set"></a>-set <em class="option">attribute value</em></h4>
3642
<p>set an image attribute for all images in the current image sequence, after they have been created or read in. </p>
4006
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>separate an image channel into a grayscale image. Specify the channel with <a href="#channel">-channel</a>.</td><td style='text-align:right;'></td></tr></table>
4008
<div style="margin: auto;">
4009
<h4><a name="sepia-tone" id="sepia-tone"></a>-sepia-tone <em class="arg">threshold</em></h4>
4012
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>simulate a sepia-toned photo.</td><td style='text-align:right;'></td></tr></table>
4014
<p>Specify <em class="arg">threshold</em> as the percent threshold of the intensity (0 - 99.9%).</p>
4016
<p>This option applies a special effect to the image, similar to the effect achieved in a photo darkroom by sepia toning. Threshold ranges from 0 to <em class="QR">QuantumRange</em> and is a measure of the extent of the sepia toning. A threshold of 80% is a good starting point for a reasonable tone.</p>
4018
<div style="margin: auto;">
4019
<h4><a name="set" id="set"></a>-set <em class="arg">attribute value</em></h4>
4022
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>set an image attribute for all images in the current image sequence, after they have been created or read in. </td><td style='text-align:right;'></td></tr></table>
3644
4024
<p>Attributes of interest include <a href="#comment">-comment</a>, <a href="#delay">-delay</a>, <a href="#dispose">-dispose</a>, and <a href="#page">-page</a>. For example:</p>
3647
-> convert rose: -set comment 'Rose is a rose is a rose is a rose' rose.png
3649
-> identify -format %c rose.png
3650
Rose is a rose is a rose is a rose
4026
<p class='crt'><span class="crtprompt"> $magick> </span><span class='crtin'>convert rose: -set comment 'Rose is a rose is a rose is a rose' rose.png</span><span class='crtout'></span><span class="crtprompt"> $magick> </span><span class='crtin'>identify -format %c rose.png</span><span class='crtout'>Rose is a rose is a rose is a rose</span></p>
3653
4027
<p>The <a href="#repage">-repage</a> operator will also set the
3654
4028
'<kbd>page</kbd>' attribute of images already in memory, but allows you to
3655
4029
separately set the virtual canvas's size and offset components, and also allows
3660
4034
<p>Set image options by prefixing the value with <kbd>option:</kbd>. Set attributes of the image registry by prefixing the value with <kbd>registry:</kbd>.</p>
3662
4036
<div style="margin: auto;">
3663
<h4><a name="shade" id="shade"></a>-shade <em class="option">azimuth</em>x<em class="option">elevation</em></h4>
4037
<h4><a name="shade" id="shade"></a>-shade <em class="arg">azimuth</em>x<em class="arg">elevation</em></h4>
3666
<p>shade the image using a distant light source.</p>
4040
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>shade the image using a distant light source.</td><td style='text-align:right;'></td></tr></table>
3668
<p>Specify <em class="option">azimuth</em> and <em class="option">elevation</em> as the position of the light source. Use <a href="#shade">+shade</a> to return the shading results as a grayscale image.</p>
4042
<p>Specify <em class="arg">azimuth</em> and <em class="arg">elevation</em> as the position of the light source. Use <a href="#shade">+shade</a> to return the shading results as a grayscale image.</p>
3670
4044
<div style="margin: auto;">
3671
<h4><a name="shadow" id="shadow"></a>-shadow <em class="option">percent-opacity</em>{x<em class="option">sigma</em>}{<em class="option">+-</em>}<em class="option">x</em>{<em class="option">+-</em>}<em class="option">y</em>{<em class="option">%</em>}</h4>
4045
<h4><a name="shadow" id="shadow"></a>-shadow <em class="arg">percent-opacity</em>{x<em class="arg">sigma</em>}{<em class="arg">+-</em>}<em class="arg">x</em>{<em class="arg">+-</em>}<em class="arg">y</em>{<em class="arg">%</em>}</h4>
3674
<p>simulate an image shadow.</p>
4048
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>simulate an image shadow.</td><td style='text-align:right;'></td></tr></table>
3676
4050
<div style="margin: auto;">
3677
4051
<h4><a name="shared-memory"
3678
4052
id="shared-memory"></a>-shared-memory</h4>
3681
<p>use shared memory.</p>
4055
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>use shared memory.</td><td style='text-align:right;'></td></tr></table>
3683
<p>This option specifies whether the utility should attempt to use shared memory for pixmaps. ImageMagick must be compiled with shared memory support, and the display must support the <em class="option">MIT-SHM</em> extension. Otherwise, this option is ignored. The default is <kbd>True</kbd>.</p>
4057
<p>This option specifies whether the utility should attempt to use shared memory for pixmaps. ImageMagick must be compiled with shared memory support, and the display must support the <em class="arg">MIT-SHM</em> extension. Otherwise, this option is ignored. The default is <kbd>True</kbd>.</p>
3685
4059
<div style="margin: auto;">
3686
<h4><a name="sharpen" id="sharpen"></a>-sharpen <em class="option">radius</em>{x<em class="option">sigma</em>}</h4>
4060
<h4><a name="sharpen" id="sharpen"></a>-sharpen <em class="arg">radius</em>{x<em class="arg">sigma</em>}</h4>
3689
<p>sharpen the image.</p>
4063
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>sharpen the image.</td><td style='text-align:right;'></td></tr></table>
3691
4065
<p>Use a Gaussian operator of the given radius and standard deviation (sigma).</p>
3693
4067
<div style="margin: auto;">
3694
<h4><a name="shave" id="shave"></a>-shave <em class="option">widthxheight</em>{<em class="option">%</em>}</h4>
3697
<p>shave pixels from the image edges.</p>
3699
<p>Specify the width of the region to be removed from both sides of the image and the height of the regions to be removed from top and bottom.</p>
3701
<div style="margin: auto;">
3702
<h4><a name="shear" id="shear"></a>-shear <em class="option">x-degrees</em>x<em class="option">y-degrees</em></h4>
3705
<p>shear the image along the X or Y axis.</p>
3707
<p>Use the specified positive or negative shear angle.</p>
3709
<p>Shearing slides one edge of an image along the X or Y axis, creating a parallelogram. An X direction shear slides an edge along the X axis, while a Y direction shear slides an edge along the Y axis. The amount of the shear is controlled by a shear angle. For X direction shears, <em class="option">x-degrees</em> is measured relative to the Y axis, and similarly, for Y direction shears <em class="option">y-degrees</em> is measured relative to the X axis.</p>
3711
<p>Empty triangles left over from shearing the image are filled with the color defined with the <a href="#fill">-background</a> options. The color is specified using the format described under the <a href="#fill">-fill</a> option.</p>
3713
<div style="margin: auto;">
3714
<h4><a name="sigmoidal" id="sigmoidal-contrast"></a>-sigmoidal-contrast <em class="option">contrast</em>x<em class="option">mid-point</em></h4>
3717
<p>increase the contrast without saturating highlights or shadows.</p>
3719
<p>Increase the contrast of the image using a sigmoidal transfer function without saturating highlights or shadows. <em class="option">Contrast</em> indicates how much to increase the contrast (0 is none; 3 is typical; 20 is a lot); <em class="option">mid-point</em> indicates where midtones fall in the resultant image (0 is white; 50% is middle-gray; 100% is black). By default the image contrast is increased, use <em class="option">+sigmoidal-contrast</em> to decrease the contrast.</p>
4068
<h4><a name="shave" id="shave"></a>-shave <em class="arg">geometry</em></h4>
4071
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Shave pixels from the image edges.</td><td style='text-align:right;'></td></tr></table>
4073
<p>The <em class="arg">size</em> portion of the <em class="arg">geometry</em> argument specifies the width of the region to be removed from both sides of the image and the height of the regions to be removed from top and bottom. Offsets are ignored.</p>
4075
<p>See <a href="../www/command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
4077
<div style="margin: auto;">
4078
<h4><a name="shear" id="shear"></a>-shear <em class="arg">Xdegrees</em>[x<em class="arg">Ydegrees</em>]</h4>
4081
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Shear the image along the x-axis and/or y-axis.</td><td style='text-align:right;'></td></tr></table>
4083
<p>The shear angles may be positive, negative, or zero. When <em class="arg">Ydegrees</em> is omitted it defaults to 0. When both angles are given, the horizontal component of the shear is performed before the vertical component.</p>
4085
<p>Shearing slides one edge of an image along the x-axis or y-axis (i.e., horizontally or vertically, respectively),creating a parallelogram. The amount of each is controlled by the respective shear angle. For horizontal shears, <em class="arg">Xdegrees</em> is measured clockwise relative to "up" (the negative y-axis), sliding the top edge to the right when 0°<<em class="arg">Xdegrees</em><90° and to the left when 90°<<em class="arg">Xdegrees</em><180°. For vertical shears <em class="arg">Ydegrees</em> is measured clockwise relative to "right" (the positive x-axis), sliding the right edge down when 0°<<em class="arg">Ydegrees</em><90° and up when 90°<<em class="arg">Ydegrees</em><180°.</p>
4087
<p>Empty triangles left over from shearing the image are filled with the color defined by the <a href="#fill">-background</a> option. The color is specified using the format described under the <a href="#fill">-fill</a> option.</p>
4089
<p>The horizontal shear is performed before the vertical part. This is important to note, since horizontal and vertical shears do not <em>commute</em>, i.e., the order matters in a sequence of shears. For example, the following two commands are not equivalent.</p>
4091
<p class='crt'><span class="crtprompt"> $magick> </span><span class='crtin'>convert logo: -shear 20x0 -shear 0x60 logo-sheared.png</span><span class='crtout'></span><span class="crtprompt"> $magick> </span><span class='crtin'>convert logo: -shear 0x60 -shear 20x0 logo-sheared.png</span></p>
4092
<p>The first of the two commands above is equivalent to the following, except for the amount of empty space created; the command that follows generates a smaller image, and so is a better choice in terms of time and space.</p>
4094
<p class='crt'><span class="crtprompt"> $magick> </span><span class='crtin'>convert logo: -shear 20x60 logo-sheared.png</span></p>
4095
<div style="margin: auto;">
4096
<h4><a name="sigmoidal" id="sigmoidal-contrast"></a>-sigmoidal-contrast <em class="arg">contrast</em>x<em class="arg">mid-point</em></h4>
4099
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>increase the contrast without saturating highlights or shadows.</td><td style='text-align:right;'></td></tr></table>
4101
<p>Increase the contrast of the image using a sigmoidal transfer function without saturating highlights or shadows. <em class="arg">Contrast</em> indicates how much to increase the contrast (0 is none; 3 is typical; 20 is a lot); <em class="arg">mid-point</em> indicates where midtones fall in the resultant image (0 is white; 50% is middle-gray; 100% is black). By default the image contrast is increased, use <em class="arg">+sigmoidal-contrast</em> to decrease the contrast.</p>
3721
4103
<div style="margin: auto;">
3722
4104
<h4><a name="silent" id="silent"></a>-silent</h4>
3725
<p>operate silently.</p>
4107
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>operate silently.</td><td style='text-align:right;'></td></tr></table>
3727
4109
<div style="margin: auto;">
3728
<h4><a name="size" id="size"></a>-size <em class="option">width</em>{x<em class="option">height</em>}{<em class="option">+offset</em>}</h4>
4110
<h4><a name="size" id="size"></a>-size <em class="arg">width</em>[x<em class="arg">height</em>][<em class="arg">+offset</em>]</h4>
3731
<p>width and height of the image.</p>
4113
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the width and height of the image.</td><td style='text-align:right;'></td></tr></table>
3733
4115
<p>Use this option to specify the width and height of raw images whose dimensions are unknown such as <kbd>GRAY</kbd>, <kbd>RGB</kbd>, or <kbd>CMYK</kbd>. In addition to width and height, use <a href="#size">-size</a> with an offset to skip any header information in the image or tell the number of colors in a <kbd>MAP</kbd> image file, (e.g. -size 640x512+256).</p>
3883
4265
<p>Float and double types are normalized from 0.0 to 1.0 otherwise the pixels
3884
values range from 0 to the maximum value the storage type can support.
4266
values range from 0 to the maximum value the storage type can support.</p>
4268
<div style="margin: auto;">
4269
<h4><a name="stretch" id="stretch"></a>-stretch <em class="arg">fontStretch</em></h4>
4272
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set a type of stretch style for fonts.</td><td style='text-align:right;'></td></tr></table>
4274
<p>This setting suggests a type of stretch that ImageMagick should try to apply to the currently selected font family. Select <em class="arg">fontStretch</em> from the following.</p>
4289
<p>To print a complete list of stretch types, use <a href="#list">-list stretch</a>.</p>
4291
<p>For other settings that affect fonts, see the options <a href="#font">-font</a>, <a href="#family">-family</a>, <a href="#style">-style</a>, and <a href="#weight">-weight</a>. </p>
3886
4293
<div style="margin: auto;">
3887
4294
<h4><a name="strip" id="strip"></a>-strip</h4>
3890
<p>strip the image of any profiles or comments.</p>
4297
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>strip the image of any profiles or comments.</td><td style='text-align:right;'></td></tr></table>
3892
4299
<div style="margin: auto;">
3893
<h4><a name="stroke" id="stroke"></a>-stroke <em class="option">color</em></h4>
4300
<h4><a name="stroke" id="stroke"></a>-stroke <em class="arg">color</em></h4>
3896
<p>color to use when stroking a graphic primitive.</p>
4303
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>color to use when stroking a graphic primitive.</td><td style='text-align:right;'></td></tr></table>
3898
4305
<p>The color is specified using the format described under the <a href="#fill">-fill</a> option.</p>
3900
4307
<p>See <a href="#draw">-draw</a> for further details.</p>
3902
4309
<div style="margin: auto;">
3903
<h4><a name="strokewidth" id="strokewidth"></a>-strokewidth <em class="option">value</em></h4>
4310
<h4><a name="strokewidth" id="strokewidth"></a>-strokewidth <em class="arg">value</em></h4>
3906
<p>set the stroke width.</p>
4313
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>set the stroke width.</td><td style='text-align:right;'></td></tr></table>
3908
4315
<p>See <a href="#draw">-draw</a> for further details.</p>
3910
4317
<div style="margin: auto;">
3911
<h4><a name="swap" id="swap"></a>-swap <em class="option">index,index</em></h4>
3914
<p>swap the positions of two images in the image sequence.</p>
3916
<p>For example, <a href="#swap">-swap 0,2</a> swaps the first and the third images in the current image sequence. Whereas, <a href="#swap">+swap</a> swaps the last two image.</p>
3918
<div style="margin: auto;">
3919
<h4><a name="swirl" id="swirl"></a>-swirl <em class="option">degrees</em></h4>
3922
<p>swirl image pixels about the center.</p>
3924
<p><em class="option">Degrees</em> defines the tightness of the swirl.</p>
4318
<h4><a name="style" id="style"></a>-style <em class="arg">fontStyle</em></h4>
4321
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set a font style for text.</td><td style='text-align:right;'></td></tr></table>
4323
<p>This setting suggests a font style that ImageMagick should try to apply to the currently selected font family. Select <em class="arg">fontStyle</em> from the following.</p>
4332
<p>For other settings that affect fonts, see the options <a href="#font">-font</a>, <a href="#family">-family</a>, <a href="#stretch">-stretch</a>, and <a href="#weight">-weight</a>. </p>
4334
<div style="margin: auto;">
4335
<h4><a name="swap" id="swap"></a>-swap <em class="arg">index,index</em></h4>
4338
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Swap the positions of two images in the image sequence.</td><td style='text-align:right;'></td></tr></table>
4340
<p>For example, <a href="#swap">-swap 0,2</a> swaps the first and the third images in the current image sequence. Use <a href="#swap">+swap</a> to switch the last two images in the sequence.</p>
4342
<div style="margin: auto;">
4343
<h4><a name="swirl" id="swirl"></a>-swirl <em class="arg">degrees</em></h4>
4346
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>swirl image pixels about the center.</td><td style='text-align:right;'></td></tr></table>
4348
<p><em class="arg">Degrees</em> defines the tightness of the swirl.</p>
3926
4350
<div style="margin: auto;">
3927
4351
<h4><a name="taint" id="taint"></a>-taint</h4>
3930
<p>Mark the image as modified even if it isn't.</p>
4354
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Mark the image as modified even if it isn't.</td><td style='text-align:right;'></td></tr></table>
3932
4356
<div style="margin: auto;">
3933
<h4><a name="text-font" id="text-font"></a>-text-font <em class="option">name</em></h4>
4357
<h4><a name="text-font" id="text-font"></a>-text-font <em class="arg">name</em></h4>
3936
<p>font for writing fixed-width text.</p>
4360
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>font for writing fixed-width text.</td><td style='text-align:right;'></td></tr></table>
3938
<p>Specifies the name of the preferred font to use in fixed (typewriter style) formatted text. The default is 14 point <em class="option">Courier</em>.</p>
4362
<p>Specifies the name of the preferred font to use in fixed (typewriter style) formatted text. The default is 14 point <em class="arg">Courier</em>.</p>
3940
4364
<p>You can tag a font to specify whether it is a PostScript, TrueType, or OPTION1 font. For example, <kbd>Courier.ttf</kbd> is a TrueType font and <kbd>x:fixed</kbd> is OPTION1.</p>
3942
4366
<div style="margin: auto;">
3943
<h4><a name="texture" id="texture"></a>-texture <em class="option">filename</em></h4>
4367
<h4><a name="texture" id="texture"></a>-texture <em class="arg">filename</em></h4>
3946
<p>name of texture to tile onto the image background.</p>
4370
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>name of texture to tile onto the image background.</td><td style='text-align:right;'></td></tr></table>
3948
4372
<div style="margin: auto;">
3949
<h4><a name="threshold" id="threshold"></a>-threshold <em class="option">value</em>{<em class="option">green,blue,opacity</em>}{<em class="option"> %</em>}</h4>
4373
<h4><a name="threshold" id="threshold"></a>-threshold <em class="arg">value</em>{<em class="arg">%</em>}</h4>
3952
<p>threshold the image.</p>
3954
<p>Create an image such that any pixel sample that is equal to, or exceeds the threshold, is reassigned the maximum intensity otherwise the minimum intensity.</p>
4376
<!-- {<em class="arg">green,blue,opacity</em>}
3956
4377
<p>If the green or blue value is omitted, these channels use the same value as the first one provided. If all three color values are the same, the result is a bi-level image. If the opacity threshold is omitted, OpaqueOpacity will be used and any partially transparent pixel will become fully transparent.</p>
3958
<p>To generate an all-black or all-white image with the same dimensions as the input image, you can use.</p>
3961
convert -threshold 65535 in.png black.png
3962
convert -threshold 0,0,0 in.png white.png
3965
<p>Please note that the transparency channel will be treated as 'matte'
4380
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Apply simultaneous black/white threshold to the image.</td><td style='text-align:right;'></td></tr></table>
4382
<p>Any pixel values (more specifically, those channels set using <a href="../www/command-line-options.html#channel">‑channel</a>) that exceed the specified threshold are reassigned the maximum channel value, while all other values are assigned the minimum.</p>
4384
<p> The threshold value can be given as a percentage or as an absolute integer value corresponding to the desired channel value. When given as an integer, the minimum attainable value is 0 (corresponding to black when all channels are affected), but the maximum value (corresponding to white) is that of the <kbd>quantum depth</kbd> of the particular build of ImageMagick, and is therefore dependent on the installation. For that reason, a reasonable recommendation for most applications is to specify the threshold values as a percentage.
4387
<p> The following would force pixels with red values above 50% to have 100% red values, while those at or below 50% red would be set to 0 in the red channel. The green, blue, and alpha channels (if present) would be unchanged. </p>
4389
<p class='crt'><span class="crtprompt"> $magick> </span><span class='crtin'>convert in.png -channel red -threshold 50% out.png</span></p>
4390
<p>As (possibly) impractical but instructive examples, the following would generate an all-black and an all-white image with the same dimensions as the input image.</p>
4393
<p class='crt'><span class="crtprompt"> $magick> </span><span class='crtin'>convert in.png -threshold 100% black.png</span><span class='crtout'></span><span class="crtprompt"> $magick> </span><span class='crtin'>convert in.png -threshold -1 white.png</span></p>
4394
<p>Note that the values of the transparency channel will be treated as 'matte'
3966
4395
values (0 is opaque) and not as 'alpha' values (0 is transparent).</p>
4397
<p> See also <a href="../www/command-line-options.html#black-threshold">‑black‑threshold</a> and <a href="../www/command-line-options.html#white-threshold">‑white‑threshold</a>.
3969
4400
<div style="margin: auto;">
3970
<h4><a name="thumbnail" id="thumbnail"></a>-thumbnail <em class="option">width</em><br />-thumbnail <em class="option">width</em>x<em class="option">height</em>{<em class="option">%</em>} {<em class="option">@</em>} {<em class="option">!</em>} {<em class="option"><</em>} {<em class="option">></em>}</h4>
4401
<h4><a name="thumbnail" id="thumbnail"></a>-thumbnail <em class="arg">geometry</em></h4>
3973
<p>create a thumbnail of the image.</p>
4404
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Create a thumbnail of the image.</td><td style='text-align:right;'></td></tr></table>
3975
4406
<p>This exactly like <a href="#resize">-resize</a>, except that any image profiles present are also removed as they are of little importance to small image thumbnails.</p>
3977
<div style="margin: auto;">
3978
<h4><a name="tile" id="tile"></a>-tile <em class="option">filename</em></h4>
3981
<p>tile image when filling a graphic primitive.</p>
3983
<div style="margin: auto;">
3984
<h4>-tile <em class="option">geometry</em></h4>
3987
<p>layout of images [<em class="option">montage</em>].</p>
4408
<p>See <a href="../www/command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
4410
<div style="margin: auto;">
4411
<h4><a name="tile" id="tile"></a>-tile <em class="arg">filename</em></h4>
4414
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the tile image used for filling a subsequent graphic primitive.</td><td style='text-align:right;'></td></tr></table>
4416
<div style="margin: auto;">
4417
<h4>-tile <em class="arg">geometry</em></h4>
4420
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Specify the layout of images .</td><td style='text-align:right;'>[<a href="../www/montage.html">montage</a>]</td></tr></table>
4422
<p>See <a href="../www/command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
3989
4424
<div style="margin: auto;">
3993
<p>repeat composite operation across and down image [<em class="option">composite</em>].</p>
4428
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Specifies that a subsequent composite operation is repeated across and down image.</td><td style='text-align:right;'>[<a href="../www/composite.html">composite</a>]</td></tr></table>
3995
4430
<div style="margin: auto;">
3996
<h4><a name="tile-offset" id="tile-offset"></a>-tile-offset <em class="option">+-</em>}<em class="option">x</em>{<em class="option">+-</em>}<em class="option"> y</em></h4>
4431
<h4><a name="tile-offset" id="tile-offset"></a>-tile-offset {<em class="arg">+-</em>}<em class="arg">x</em>{<em class="arg">+-</em>}<em class="arg">y</em></h4>
3999
<p>specify the offset for tile images, relative to the background image it will be tiled on.</p>
4434
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Specify the offset for tile images, relative to the background image it will be tiled on.</td><td style='text-align:right;'></td></tr></table>
4001
<p>This should be set before the tiling image is defined using <a href="#tile" >-tile</a> or <a href="#texture" >-texture</a>, or directly applied for create a tiled canvas using <kbd>TILE:</kbd> or <kbd>PATTERN</kbd> input formats. </p>
4436
<p>This should be set before the tiling image is set by <a href="#tile" >-tile</a> or <a href="#texture" >-texture</a>, or directly applied for creating a tiled canvas using <kbd>TILE:</kbd> or <kbd>PATTERN:</kbd> input formats. </p>
4003
4438
<p>Internally ImageMagick does a <a href="#roll" >-roll</a> of the tile image by the arguments given when the tile image is set. </p>
4005
4440
<div style="margin: auto;">
4006
<h4><a name="tint" id="tint"></a>-tint <em class="option">value</em></h4>
4441
<h4><a name="tint" id="tint"></a>-tint <em class="arg">value</em></h4>
4009
<p>tint the image with the fill color.</p>
4444
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Tint the image with the fill color.</td><td style='text-align:right;'></td></tr></table>
4446
<p>Tint the image with the fill color.</p>
4011
4448
<p>Specify the amount of tinting as a percentage. Pure colors like black, white red, yellow, will not be affected by -tint. Only mid-range colors such as the various shades of grey.</p>
4013
4450
<div style="margin: auto;">
4014
<h4><a name="title" id="title"></a>-title <em class="option">string</em></h4>
4451
<h4><a name="title" id="title"></a>-title <em class="arg">string</em></h4>
4017
<p>assign title to displayed image [<em class="option">animate, display, montage</em>].</p>
4454
<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Assign a title to displayed image.</td><td style='text-align:right;'>[<a href="../www/animate.html">animate</a>, <a href="../www/display.html">display</a>, <a href="../www/montage.html">montage</a>]</td></tr></table>
4019
4456
<p>Use this option to assign a specific title to the image. This assigned to the image window and is typically displayed in the window title bar. Optionally you can include the image filename, type, width, height, Exif data, or other image attribute by embedding special format characters described under the <a href="#format">-format</a> option.</p>
4021
4458
<p>For example,</p>
4024
4461
-title "%m:%f %wx%h"
4027
4464
<p>produces an image title of <kbd>MIFF:bird.miff 512x480</kbd> for an image titled <kbd>bird.miff</kbd> and whose width is 512 and height is 480.</p>