granicus.if.org Git - imagemagick/blob - www/perl-magick.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" \r
   2   "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">\r
   3 <html version="-//W3C//DTD XHTML 1.1//EN"\r
   4       xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"\r
   5       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"\r
   6       xsi:schemaLocation="http://www.w3.org/1999/xhtml\r
   7                           http://www.w3.org/MarkUp/SCHEMA/xhtml11.xsd">\r
   8 <head>\r
   9   <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>\r
  10   <meta name="verify-v1" content="g222frIIxcQTrvDR3NBRUSKP3AnMNoqxOkIniCEkV7U="/>\r
  11   <title>ImageMagick: PerlMagick, Perl API for ImageMagick</title>
  12   <meta http-equiv="Content-Language" content="en-US"/>
  13   <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
  14   <meta http-equiv="Reply-to" content="magick-users@imagemagick.org"/>
  15   <meta name="Application-name" content="ImageMagick"/>
  16   <meta name="Description" content="Use ImageMagick to convert, edit, or compose bitmap images in a variety of formats.  In addition resize, rotate, shear, distort and transform images."/>
  17   <meta name="Application-url" content="http://www.imagemagick.org"/>
  18   <meta name="Generator" content="PHP"/>
  19   <meta name="Keywords" content="perlmagick, perl, api, for, imagemagick, ImageMagick, ImageMagic, MagickCore, MagickWand, PerlMagick, Magick++, RMagick, PythonMagick, JMagick, TclMagick, Image, Magick, Magic, Wand, ImageMagickObject, Swiss, Army, Knife, Image, Processing"/>
  20   <meta name="Rating" content="GENERAL"/>
  21   <meta name="Robots" content="INDEX, FOLLOW"/>
  22   <meta name="Generator" content="ImageMagick Studio LLC"/>
  23   <meta name="Author" content="ImageMagick Studio LLC"/>
  24   <meta name="Revisit-after" content="2 DAYS"/>
  25   <meta name="Resource-type" content="document"/>
  26   <meta name="Copyright" content="Copyright (c) 1999-2011 ImageMagick Studio LLC"/>
  27   <meta name="Distribution" content="Global"/>
  28   <link rel="icon" href="../images/wand.png"/>
  29   <link rel="shortcut icon" href="../images/wand.ico"  type="images/x-icon"/>
  30   <link rel="meta" type="application/rdf+xml" title="ICI" href="http://imagemagick.org/ici.rdf"/>\r
  31   <link rel="stylesheet" href="http://www.google.com/cse/style/look/default.css" type="text/css" />\r
  32   <style type="text/css" media="all">\r
  33     @import url("../www/magick.css");\r
  34   </style>\r
  35   <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js"></script>\r
  36   <script type="text/javascript" src="../fancybox/jquery.fancybox-1.3.4.pack.js"></script>\r
  37   <link rel="stylesheet" type="text/css" href="../fancybox/jquery.fancybox-1.3.4.css" media="screen" />\r
  38   <script type="text/javascript">\r
  39     $(document).ready(function() {\r
  40       $("a[href$=.jpg],a[href$=.png],a[href$=.gif]").fancybox({\r
  41         'transitionIn'  : 'elastic',\r
  42         'transitionOut' : 'elastic',\r
  43         'overlayShow'   : false,\r
  44         'opacity'       : true\r
  45       });\r
  46     });\r
  47   </script>\r
  48 </head>\r
  49 \r
  50 <body id="www-imagemagick-org">\r
  51 <div class="titlebar">\r
  52 <div style="margin: 17px auto; float: left;">\r
  53   <script type="text/javascript">\r
  54   <!--\r
  55     google_ad_client = "pub-3129977114552745";\r
  56     google_ad_slot = "5439289906";\r
  57     google_ad_width = 728;\r
  58     google_ad_height = 90;\r
  59   //-->\r
  60   </script>\r
  61   <script type="text/javascript"\r
  62     src="http://pagead2.googlesyndication.com/pagead/show_ads.js">\r
  63   </script>\r
  64 </div>\r
  65 <a href="http://www.imagemagick.org/discourse-server/">\r
  66   <img src="../images/logo.jpg"\r
  67   alt="ImageMagick Logo"\r
  68   style="width: 123px; height: 118px; border: 0px; float: right;" /></a>\r
  69 <a href="../index.html">\r
  70   <img src="../images/sprite.jpg"\r
  71   alt="ImageMagick Sprite"\r
  72   style="width: 114px; height: 118px; border: 0px; float: right;" /></a>\r
  73 </div>\r
  74 \r
  75 <div class="westbar">\r
  76 \r
  77 <div class="menu">
  78   <a title="About ImageMagick" href="../index.html">About ImageMagick</a>
  79 </div>
  80 <div class="sep"></div>\r
  81 <div class="menu">
  82   <a title="Binary Releases" href="../www/binary-releases.html">Binary Releases</a>
  83 </div>
  84 <div class="sub">
  85     <a title="Binary Release: Unix" href="../www/binary-releases.html#unix">Unix</a>
  86 </div>
  87 <div class="sub">
  88     <a title="Binary Release: MacOS X" href="../www/binary-releases.html#macosx">Mac OS X</a>
  89 </div>
  90 <div class="sub">
  91     <a title="Binary Release: iPhone" href="../www/binary-releases.html#iPhone">iPhone</a>
  92 </div>
  93 <div class="sub">
  94     <a title="Binary Release: Windows" href="../www/binary-releases.html#windows">Windows</a>
  95 </div>
  96 <div class="sep"></div>\r
  97 <div class="menu">
  98   <a title="Command-line Tools" href="../www/command-line-tools.html">Command-line Tools</a>
  99 </div>
 100 <div class="sub">
 101     <a title="Command-line Tools: Processing" href="../www/command-line-processing.html">Processing</a>
 102 </div>
 103 <div class="sub">
 104     <a title="Command-line Tools: Options" href="../www/command-line-options.html">Options</a>
 105 </div>
 106 <div class="sub">
 107     <a title="Command-line Tools: Usage" href="http://www.imagemagick.org/Usage/">Usage</a>
 108 </div>
 109 <div class="menu">
 110   <a title="Program Interfaces" href="../www/api.html">Program Interfaces</a>
 111 </div>
 112 <div class="sub">
 113     <a title="Program Interface: MagickWand" href="../www/magick-wand.html">MagickWand</a>
 114 </div>
 115 <div class="sub">
 116     <a title="Program Interface: MagickCore" href="../www/magick-core.html">MagickCore</a>
 117 </div>
 118 <div class="sub">
 119     <a title="Program Interface: PerlMagick" href="../www/perl-magick.html">PerlMagick</a>
 120 </div>
 121 <div class="sub">
 122     <a title="Program Interface: Magick++" href="../www/magick++.html">Magick++</a>
 123 </div>
 124 <div class="sep"></div>\r
 125 <div  class="menu">
 126    <a title="Install from Source" href="../www/install-source.html">Install from Source</a>
 127 </div>
 128 <div class="sub">
 129     <a title="Install from Source: Unix" href="../www/install-source.html#unix">Unix</a>
 130 </div>
 131 <div class="sub">
 132     <a title="Install from Source: Windows" href="../www/install-source.html#windows">Windows</a>
 133  </div>
 134 <div class="menu">
 135   <a title="Resources" href="../www/resources.html">Resources</a>
 136 </div>
 137 <div class="menu">
 138   <a title="Architecture" href="../www/architecture.html">Architecture</a>
 139 </div>
 140 <div class="menu">
 141   <a title="Download" href="../www/download.html">Download</a>
 142 </div>
 143 <div class="sep"></div>\r
 144 <div class="menu">
 145   <a title="Search" href="../www/search.html">Search</a>
 146 </div>
 147 <div class="sep"></div>\r
 148 <div class="menu">
 149   <a title="Site Map" href="../www/sitemap.html">Site Map</a>
 150 </div>
 151 <div  class="sub">
 152   <a title="Site Map: Links" href="../www/links.html">Links</a>
 153 </div>
 154 <div class="sep"></div>\r
 155 <div  class="menu">
 156   <a rel="follow" title="Sponsors" href="../www/sponsors.html">Sponsors:</a>
 157
 158 <a href="http://www.networkredux.com">
 159   <img src="../images/networkredux.png" alt="[sponsor]"
 160   style="margin-top: 4px; margin-left: 4px; border: 0px; float: left;" /></a>
 161 <div class="sponsbox">
 162 <div  class="sponsor">
 163   <a rel="follow" title="Sponsor: Web Hosting Break" href="http://www.webhostingbreak.com">Web Hosting Break</a><!-- 201109010090 ian@ian-m... -->
 164 </div>
 165 <div  class="sponsor">
 166   <a rel="follow" title="Sponsor: Druckerei" href="http://www.allesdruck.de">Druckerei</a><!-- 201303011500 r.leo -->
 167 </div>
 168 <div  class="sponsor">
 169   <a rel="follow" title="Sponsor: Website Hosting" href="http://www.hostreviewgeeks.com">Website Hosting</a><!-- 201109010090 alexanian media -->
 170 </div>
 171 <div  class="sponsor">
 172   <a rel="follow" title="Sponsor: Hotel München" href="http://www.messehotel-erb-muenchen.de">Hotel München</a><!-- 201111010450 cerb -->
 173 </div>
 174 <div  class="sponsor">
 175   <a rel="follow" title="Sponsor: Best Web Hosting" href="http://webhostinggeeks.com">Best Web Hosting</a><!-- 201110010720 -->
 176 </div>
 177 <div  class="sponsor">
 178   <a rel="follow" title="Sponsor: Flyer drucken" href="http://www.online-druck.biz">Flyer drucken</a><!-- 201109010900 Floeter-->
 179 </div>
 180 <div  class="sponsor">
 181   <a rel="follow" title="Sponsor: Web Hosting Reviews" href="http://www.webhostingmasters.com">Web Hosting Reviews</a><!-- 201107011500 affliatelabel -->
 182 </div>
 183 <div  class="sponsor">
 184   <a rel="follow" title="Sponsor: Druckerei" href="http://print24.com/de/">Druckerei</a><!-- 201110010720 -->
 185 </div>
 186 <div  class="sponsor">
 187   <a rel="follow" title="Sponsor: Web Hosting Ratings" href="http://webhostingrating.com">Web Hosting Ratings</a><!-- 201110010720 -->
 188 </div>
 189 <div  class="sponsor">
 190    <a rel="follow" title="Sponsor: alaTest.com" href="http://alatest.com">alaTest.com</a><!-- 20110801000300 -->
 191 </div>
 192 </div>
 193 </div>
 194 </div>\r
 195 \r
 196 <div class="eastbar">\r
 197 \r
 198 </div>\r
 199 \r
 200 <div class="main">\r
 201 \r
 202 \r
 203 <h1>PerlMagick API</h1>
 204 <p class="navigation-index">[<a href="#installation">Installation</a> &bull; <a href="#overview">Overview</a> &bull; <a href="#example">Example Script</a> &bull; <a href="#read">Read or Write an Image</a> &bull; <a href="#manipulate">Manipulate an Image</a> &bull; <a href="#set-attribute">Set an Image Attribute</a> &bull; <a href="#get-attribute">Get an Image Attribute</a> &bull; <a href="#compare">Compare an Image to its Reconstruction</a> &bull; <a href="#montage">Create an Image Montage</a> &bull; <a href="#blobs">Working with Blobs</a> &bull; <a href="#direct-access">Direct-access to Image Pixels</a> &bull; <a href="#miscellaneous">Miscellaneous Methods</a> &bull; <a href="#exceptions">Handling Exceptions</a>&bull; <a href="#constants">Constant</a> ]</p>
 205
 206 <div class="doc-section">
 207 <a id="introduction"></a>
 208 <p><a href="../www/download.html">PerlMagick</a> is an objected-oriented <a href="http://www.perl.com/perl/">Perl</a> interface to ImageMagick. Use the module to read, manipulate, or write an image or image sequence from within a Perl script. This makes it very suitable for Web CGI scripts. You must have ImageMagick 6.5.5 or above and Perl version 5.005_02 or greater installed on your system for PerlMagick to build properly.</p>
 209
 210 <p>There are a number of useful scripts available to show you the value of PerlMagick. You can do Web based image manipulation and conversion with <a href="http://www.imagemagick.org/download/perl">MagickStudio</a>, or use <a href="https://www.imagemagick.org/subversion/ImageMagick/trunk/PerlMagick/demo/">L-systems</a> to create images of plants using mathematical constructs, and finally navigate through collections of thumbnail images and select the image to view with the <a href="http://webmagick.sourceforge.net/">WebMagick Image Navigator</a>.</p>
 211
 212 <p>You can try PerlMagick from your Web browser at the <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">ImageMagick Studio</a>. Or, you can see <a href="../www/examples.html">examples</a> of select PerlMagick functions.</p>
 213 </div>
 214
 215 <h2><a id="installation"></a>Installation</h2>
 216 <div class="doc-section">
 217
 218 <p><b>UNIX</b></p>
 219
 220 <p>The following instructions for Unix apply only to the unbundled PerlMagick as obtained from CPAN. PerlMagick is included as a subdirectory (PerlMagick) of the ImageMagick source distribution, and may be configured and built using the instructions provided in the ImageMagick distribution's README.txt file. It is usually most convenient to install PerlMagick as part of the ImageMagick distribution.</p>
 221
 222 <p>ImageMagick must already be installed on your system. Next, get
 223 the <a href="../www/download.html">PerlMagick</a> distribution corresponding to the installed ImageMagick distribution
 224 (e.g., PerlMagick 6.69 for
 225 ImageMagick 6.6.9) and unpack it as shown below:</p>
 226
 227 <p class='crt'><span class="crtprompt"> $magick&gt; </span><span class='crtin'>tar xvfz PerlMagick-6.69.tar.gz</span><span class='crtout'></span><span class="crtprompt"> $magick&gt; </span><span class='crtin'>cd PerlMagick</span></p>
 228 <p>Next, edit <kbd>Makefile.PL</kbd> and change LIBS and INC to include the appropriate path information to the required <kbd>MagickCore</kbd> library. You may need paths to JPEG, PNG, TIFF, etc.  delegates if they were included with your installed version of ImageMagick. Build and install it like this:</p>
 229
 230 <p class='crt'><span class="crtprompt"> $magick&gt; </span><span class='crtin'>perl Makefile.PL</span><span class='crtout'></span><span class="crtprompt"> $magick&gt; </span><span class='crtin'>make</span><span class='crtout'></span><span class="crtprompt"> $magick&gt; </span><span class='crtin'>make install</span></p>
 231 <p>For Unix, you typically need to be <kbd>root</kbd> to install the software. There are ways around this. Consult the Perl manual pages for more information.</p>
 232
 233 <p><b>Windows XP / Windows 2000</b></p>
 234
 235 <p>ImageMagick must already be installed on your system. Also, the ImageMagick source distribution for <a href="../www/download.html">Windows 2000</a> is required. You must also have the <kbd>nmake</kbd> from the Visual C++ or J++ development environment. Copy <kbd>\bin\IMagick.dll</kbd> and <kbd>\bin\X11.dll</kbd> to a directory in your dynamic load path such as <kbd>c:\perl\site\5.00502</kbd>.</p>
 236
 237 <p>Next, type</p>
 238
 239 <p class='crt'><span class="crtprompt"> $magick&gt; </span><span class='crtin'>cd PerlMagick</span><span class='crtout'></span><span class="crtprompt"> $magick&gt; </span><span class='crtin'>perl Makefile.nt</span><span class='crtout'></span><span class="crtprompt"> $magick&gt; </span><span class='crtin'>nmake</span><span class='crtout'></span><span class="crtprompt"> $magick&gt; </span><span class='crtin'>nmake install</span></p>
 240 <p>See the <a href="http://www.dylanbeattie.net/magick/">PerlMagick Windows HowTo</a> page for further installation instructions.</p>
 241
 242 <p><b>Running the Regression Tests</b></p>
 243
 244 <p>To verify a correct installation, type</p>
 245
 246 <p class='crt'><span class="crtprompt"> $magick&gt; </span><span class='crtin'>make test</span></p>
 247 <p>Use <kbd>nmake test</kbd> under Windows. There are a few demonstration scripts available to exercise many of the functions PerlMagick can perform. Type</p>
 248
 249 <p class='crt'><span class="crtprompt"> $magick&gt; </span><span class='crtin'>cd demo</span><span class='crtout'></span><span class="crtprompt"> $magick&gt; </span><span class='crtin'>make</span></p>
 250 <p>You are now ready to utilize the PerlMagick methods from within your Perl scripts.</p>
 251
 252 </div>
 253
 254 <h2><a id="overview"></a>Overview</h2>
 255 <div class="doc-section">
 256
 257 <p>Any script that wants to use PerlMagick methods must first define the methods within its namespace and instantiate an image object. Do this with:</p>
 258
 259 <pre class="code">
 260   use Image::Magick;
 261
 262   $image=Image::Magick-&gt;new;
 263 </pre>
 264
 265 <p>The new() method takes the same parameters as <a href="#set-attribute">SetAttribute</a> . For example,</p>
 266
 267 <pre class="code">
 268   $image=Image::Magick-&gt;new(size=&gt;'384x256');
 269 </pre>
 270
 271 <p>Next you will want to read an image or image sequence, manipulate it, and then display or write it. The input and output methods for PerlMagick are defined in <a href="#read">Read or Write an Image</a>. See <a href="#set-attribute">Set an Image Attribute</a> for methods that affect the way an image is read or written. Refer to <a href="#manipulate">Manipulate an Image</a> for a list of methods to transform an image. <a href="#get-attribute">Get an Image Attribute</a> describes how to retrieve an attribute for an image. Refer to <a href="#montage">Create an Image Montage</a> for details about tiling your images as thumbnails on a background. Finally, some methods do not neatly fit into any of the categories just mentioned. Review <a href="#misc">Miscellaneous Methods</a> for a list of these methods.</p>
 272
 273 <p>Once you are finished with a PerlMagick object you should consider destroying it. Each image in an image sequence is stored in virtual memory. This can potentially add up to mebibytes of memory. Upon destroying a PerlMagick object, the memory is returned for use by other Perl methods. The recommended way to destroy an object is with <kbd>undef</kbd>:</p>
 274
 275 <pre class="code">
 276   undef $image;
 277 </pre>
 278
 279 <p>To delete all the images but retain the <kbd>Image::Magick</kbd> object use</p>
 280
 281 <pre class="code">
 282   @$image = ();
 283 </pre>
 284
 285 <p>and finally, to delete a single image from a multi-image sequence, use</p>
 286
 287 <pre class="code">
 288   undef $image-&gt;[$x];
 289 </pre>
 290
 291 <p>The next section illustrates how to use various PerlMagick methods to manipulate an image sequence.</p>
 292
 293 <p>Some of the PerlMagick methods require external programs such as <a href="http://www.cs.wisc.edu/~ghost/">Ghostscript</a>. This may require an explicit path in your PATH environment variable to work properly. For example (in Unix),</p>
 294
 295 <p class='crt'><span class="crtprompt"> $magick&gt; </span><span class='crtin'>$ENV{PATH}='/../bin:/usr/bin:/usr/local/bin';</span></p>
 296 <div style="margin: auto;">
 297 <h2><a id="example"></a>Example Script</h2>
 298 </div>
 299
 300 <p>Here is an example script to get you started:</p>
 301
 302 <pre class="code">
 303   #!/usr/local/bin/perl
 304   use Image::Magick;<br />
 305   my($image, $x);<br />
 306   $image = Image::Magick-&gt;new;
 307   $x = $image-&gt;Read('girl.png', 'logo.png', 'rose.png');
 308   warn "$x" if "$x";<br />
 309   $x = $image-&gt;Crop(geometry=&gt;'100x100+100+100');
 310   warn "$x" if "$x";<br />
 311   $x = $image-&gt;Write('x.png');
 312   warn "$x" if "$x";
 313 </pre>
 314
 315 <p>The script reads three images, crops them, and writes a single image as a GIF animation sequence. In many cases you may want to access individual images of a sequence. The next example illustrates how this done:</p>
 316
 317 <pre class="code">
 318   #!/usr/local/bin/perl
 319   use Image::Magick;<br />
 320   my($image, $p, $q);<br />
 321   $image = new Image::Magick;
 322   $image-&gt;Read('x1.png');
 323   $image-&gt;Read('j*.jpg');
 324   $image-&gt;Read('k.miff[1, 5, 3]');
 325   $image-&gt;Contrast();
 326   for ($x = 0; $image-&gt;[$x]; $x++)
 327   {
 328     $image-&gt;[$x]-&gt;Frame('100x200') if $image-&gt;[$x]-&gt;Get('magick') eq 'GIF';
 329     undef $image-&gt;[$x] if $image-&gt;[$x]-&gt;Get('columns') &lt; 100;
 330   }
 331   $p = $image-&gt;[1];
 332   $p-&gt;Draw(stroke=&gt;'red', primitive=&gt;'rectangle', points=&gt;20,20 100,100');
 333   $q = $p-&gt;Montage();
 334   undef $image;
 335   $q-&gt;Write('x.miff');
 336 </pre>
 337
 338 <p>Suppose you want to start out with a 100 by 100 pixel white canvas with a red pixel in the center. Try</p>
 339
 340 <pre class="code">
 341   $image = Image::Magick-&gt;new;
 342   $image-&gt;Set(size=&gt;'100x100');
 343   $image-&gt;ReadImage('canvas:white');
 344   $image-&gt;Set('pixel[49,49]'=&gt;'red');
 345 </pre>
 346
 347 <p>Here we reduce the intensity of the red component at (1,1) by half:</p>
 348
 349 <pre class="code">
 350   @pixels = $image-&gt;GetPixel(x=&gt;1,y=&gt;1);
 351   $pixels[0]*=0.5;
 352   $image-&gt;SetPixel(x=&gt;1,y=&gt;1,color=&gt;\@pixels);
 353 </pre>
 354
 355 <p>Or suppose you want to convert your color image to grayscale:</p>
 356
 357 <pre class="code">
 358   $image-&gt;Quantize(colorspace=&gt;'gray');
 359 </pre>
 360
 361 <p>Let's annotate an image with a Taipai TrueType font:</p>
 362
 363 <pre class="code">
 364   $text = 'Works like magick!';
 365   $image-&gt;Annotate(font=&gt;'kai.ttf', pointsize=&gt;40, fill=&gt;'green', text=&gt;$text);
 366 </pre>
 367
 368 <p>Perhaps you want to extract all the pixel intensities from an image and write them to STDOUT:</p>
 369
 370 <pre class="code">
 371   @pixels = $image-&gt;GetPixels(map=&gt;'I', height=&gt;$height, width=&gt;$width, normalize=&gt;true);
 372   binmode STDOUT;
 373   print pack('B*',join('',@pixels));
 374 </pre>
 375
 376 <p>Other clever things you can do with a PerlMagick objects include</p>
 377
 378 <pre  class="code">
 379   $i = $#$p"+1";   # return the number of images associated with object p
 380   push(@$q, @$p);  # push the images from object p onto object q
 381   @$p = ();        # delete the images but not the object p
 382   $p-&gt;Convolve([1, 2, 1, 2, 4, 2, 1, 2, 1]);   # 3x3 Gaussian kernel
 383 </pre>
 384
 385 <div style="margin: auto;">
 386   <h2><a id="read"></a>Read or Write an Image</h2>
 387 </div>
 388
 389 <p>Use the methods listed below to either read, write, or display an image or image sequence:</p>
 390
 391 <table class="doc">
 392 <caption>Read or Write Methods</caption>
 393 <colgroup>
 394   <col width="20%"></col>
 395   <col width="20%"></col>
 396   <col width="20%"></col>
 397   <col width="40%"></col>
 398 </colgroup>
 399 <tbody>
 400
 401   <tr>
 402     <th>Method</th>
 403     <th>Parameters</th>
 404     <th>Return Value</th>
 405     <th>Description</th>
 406   </tr>
 407
 408   <tr>
 409     <td valign="top">Read</td>
 410     <td valign="top">one or more filenames</td>
 411     <td valign="top">the number of images read</td>
 412     <td valign="top">read an image or image sequence</td>
 413   </tr>
 414
 415   <tr>
 416     <td valign="top">Write</td>
 417     <td valign="top">filename</td>
 418     <td valign="top">the number of images written</td>
 419     <td valign="top">write an image or image sequence</td>
 420   </tr>
 421
 422   <tr>
 423     <td valign="top">Display</td>
 424     <td valign="top">server name</td>
 425     <td valign="top">the number of images displayed</td>
 426     <td valign="top">display the image or image sequence to an X server</td>
 427   </tr>
 428
 429   <tr>
 430     <td valign="top">Animate</td>
 431     <td valign="top">server name</td>
 432     <td valign="top">the number of images animated</td>
 433     <td valign="top">animate image sequence to an X server</td>
 434   </tr>
 435 </tbody>
 436 </table>
 437
 438 <p>For convenience, methods Write(), Display(), and Animate() can take any parameter that <a href="#set-attribute">SetAttribute</a> knows about. For example,</p>
 439
 440 <pre class="code">
 441   $image-&gt;Write(filename=&gt;'image.png', compression=&gt;'None');
 442 </pre>
 443
 444 <p>Use <kbd>-</kbd> as the filename to method Read() to read from standard in or to method Write() to write to standard out:</p>
 445
 446 <pre class="code">
 447   binmode STDOUT;
 448   $image-&gt;Write('png:-');
 449 </pre>
 450
 451 <p>To read an image in the GIF format from a PERL filehandle, use:</p>
 452
 453 <pre class="code">
 454   $image = Image::Magick-&gt;new;
 455   open(IMAGE, 'image.gif');
 456   $image-&gt;Read(file=&gt;\*IMAGE);
 457   close(IMAGE);
 458 </pre>
 459
 460 <p>To write an image in the PNG format to a PERL filehandle, use:</p>
 461
 462 <pre class="code">
 463   $filename = "image.png";
 464   open(IMAGE, ">$filename");
 465   $image-&gt;Write(file=&gt;\*IMAGE, filename=&gt;$filename);
 466   close(IMAGE);
 467 </pre>
 468
 469 <p>Note, reading from or writing to a Perl filehandle may fail under Windows due to different versions of the C-runtime libraries between ImageMagick and the ActiveState Perl distributions or if one of the DLL's is linked with the /MT option.  See <a href="http://msdn.microsoft.com/en-us/library/ms235460.aspx">Potential Errors Passing CRT Objects Across DLL Boundaries</a> for an explanation.</p>
 470
 471 <p>If <kbd>%0Nd, %0No, or %0Nx</kbd> appears in the filename, it is interpreted as a printf format specification and the specification is replaced with the specified decimal, octal, or hexadecimal encoding of the scene number. For example,</p>
 472
 473 <pre class="text">
 474   image%03d.miff
 475 </pre>
 476
 477 <p>converts files image000.miff, image001.miff, etc.</p>
 478
 479 <p>You can optionally add <i>Image</i> to any method name. For example, ReadImage() is an alias for method Read().</p>
 480
 481 </div>
 482
 483 <h2><a id="manipulate"></a>Manipulate an Image</h2>
 484 <div class="doc-section">
 485
 486 <p>Once you create an image with, for example, method ReadImage() you may want to operate on it. Below is a list of all the image manipulations methods available to you with PerlMagick.  There are <a href="../www/examples.html">examples</a> of select PerlMagick methods. Here is an example call to an image manipulation method:</p>
 487
 488 <pre class="code">
 489   $image-&gt;Crop(geometry=&gt;'100x100+10+20');
 490   $image-&gt;[$x]-&gt;Frame("100x200");
 491 </pre>
 492
 493 <p>And here is a list of other image manipulation methods you can call:</p>
 494
 495 <table class="doc">
 496 <caption>Image Manipulation Methods</caption>
 497 <tbody>
 498   <tr>
 499     <th>Method</th>
 500     <th style="width: 40%">Parameters</th>
 501     <th style="width: 40%">Description</th>
 502   </tr>
 503
 504   <tr>
 505     <td valign="top">AdaptiveBlur</td>
 506     <td valign="top">geometry=&gt;<i>geometry</i>, radius=&gt;<i>double</i>, sigma=&gt;<i>double</i>, channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
 507     <td valign="top">adaptively blur the image with a Gaussian operator of the given radius and standard deviation (sigma).  Decrease the effect near edges.</td>
 508   </tr>
 509
 510   <tr>
 511     <td valign="top">AdaptiveResize</td>
 512     <td valign="top">geometry=&gt;<i>geometry</i>, width=&gt;<i>integer</i>, height=&gt;<i>integer</i>, filter=&gt;{Point, Box, Triangle, Hermite, Hanning, Hamming, Blackman, Gaussian, Quadratic, Cubic, Catrom, Mitchell, Lanczos, Bessel, Sinc}, support=&gt;<i>double</i>, blur=&gt;<i>double</i></td>
 513     <td valign="top">adaptively resize image using data dependant triangulation. Specify <kbd>blur</kbd> &gt; 1 for blurry or &lt; 1 for sharp</td>
 514   </tr>
 515
 516   <tr>
 517     <td valign="top">AdaptiveSharpen</td>
 518     <td valign="top">geometry=&gt;<i>geometry</i>, radius=&gt;<i>double</i>, sigma=&gt;<i>double</i>, channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
 519     <td valign="top">adaptively sharpen the image with a Gaussian operator of the given radius and standard deviation (sigma).  Increase the effect near edges.</td>
 520   </tr>
 521
 522   <tr>
 523     <td valign="top">AdaptiveThreshold</td>
 524     <td valign="top">geometry=&gt;<i>geometry</i>, width=&gt;<i>integer</i>, height=&gt;<i>integer</i>, offset=&gt;<i>integer</i></td>
 525     <td valign="top">local adaptive thresholding.</td>
 526   </tr>
 527
 528   <tr>
 529     <td valign="top">AddNoise</td>
 530     <td valign="top">noise=&gt;{Uniform, Gaussian, Multiplicative, Impulse, Laplacian, Poisson}, channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
 531     <td valign="top">add noise to an image</td>
 532   </tr>
 533
 534   <tr>
 535     <td valign="top">AffineTransform</td>
 536     <td valign="top">affine=&gt;<i>array of float values</i>, translate=&gt;<i>float, float</i>, scale=&gt; <i>float, float</i>, rotate=&gt;<i>float</i>, skewX=&gt;<i>float</i>, skewY=&gt;<i>float</i>, interpolate={Average, Bicubic, Bilinear, Filter, Integer, Mesh, NearestNeighbor}, background=&gt;<i><a href="../www/color.html">color name</a></i></td>
 537     <td valign="top">affine transform image</td>
 538   </tr>
 539
 540   <tr>
 541     <td valign="top">Affinity</td>
 542     <td valign="top">image=&gt;<i>image-handle</i>, method=&gt;{None, FloydSteinberg, Riemersma}</td>
 543     <td valign="top">choose a particular set of colors from this image</td>
 544   </tr>
 545
 546   <tr>
 547     <td valign="top">Annotate</td>
 548     <td valign="top">text=&gt;<i>string</i>, font=&gt;<i>string</i>, family=&gt;<i>string</i>, style=&gt;{Normal, Italic, Oblique, Any}, stretch=&gt;{Normal, UltraCondensed, ExtraCondensed, Condensed, SemiCondensed, SemiExpanded, Expanded, ExtraExpanded, UltraExpanded}, weight=&gt;<i>integer</i>, pointsize=&gt;<i>integer</i>, density=&gt;<i>geometry</i>, stroke=&gt;<i><a href="../www/color.html">color name</a></i>, strokewidth=&gt;<i>integer</i>, fill=&gt;<i><a href="../www/color.html">color name</a></i>, undercolor=&gt;<i><a href="../www/color.html">color name</a></i>, kerning=&gt;<i>float</i>, geometry=&gt;<i>geometry</i>, gravity=&gt;{NorthWest, North, NorthEast, West, Center, East, SouthWest, South, SouthEast}, antialias=&gt;{true, false}, x=&gt;<i>integer</i>, y=&gt;<i>integer</i>, affine=&gt;<i>array of float values</i>, translate=&gt;<i>float, float</i>, scale=&gt;<i>float, float</i>, rotate=&gt;<i>float</i>. skewX=&gt;<i>float</i>, skewY=&gt; <i>float</i>, align=&gt;{Left, Center, Right}, encoding=&gt;{UTF-8}, interline-spacing=&gt;<i>double</i>, interword-spacing=&gt;<i>double</i>, direction=&gt;{right-to-left, left-to-right}</td>
 549     <td valign="top">annotate an image with text. See <a href="#misc">QueryFontMetrics</a> to get font metrics without rendering any text.</td>
 550   </tr>
 551
 552   <tr>
 553     <td valign="top">AutoGamma</td>
 554     <td valign="top">channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
 555     <td valign="top">automagically adjust gamma level of image</td>
 556   </tr>
 557
 558   <tr>
 559     <td valign="top">AutoLevel</td>
 560     <td valign="top">channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
 561     <td valign="top">automagically adjust color levels of image</td>
 562   </tr>
 563
 564   <tr>
 565     <td valign="top">AutoOrient</td>
 566     <td valign="top"><br /></td>
 567     <td valign="top">automagically orient the image</td>
 568   </tr>
 569
 570   <tr>
 571     <td valign="top">BlackThreshold</td>
 572     <td valign="top">threshold=&gt;<i>string</i>, , channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
 573     <td valign="top">force all pixels below the threshold intensity into black</td>
 574   </tr>
 575
 576   <tr>
 577     <td valign="top">BlueShift</td>
 578     <td valign="top">factor=&gt;<i>double</i>,</td>
 579     <td valign="top">simulate a scene at nighttime in the moonlight.  Start with a factor of 1.5.</td>
 580   </tr>
 581
 582   <tr>
 583     <td valign="top">Blur</td>
 584     <td valign="top">geometry=&gt;<i>geometry</i>, radius=&gt;<i>double</i>, sigma=&gt;<i>double</i>, channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
 585     <td valign="top">reduce image noise and reduce detail levels with a Gaussian operator of the given radius and standard deviation (sigma).</td>
 586   </tr>
 587
 588   <tr>
 589     <td valign="top">Border</td>
 590     <td valign="top">geometry=&gt;<i>geometry</i>, width=&gt;<i>integer</i>, height=&gt;<i>integer</i>, bordercolor=&gt;<i><a href="../www/color.html">color name</a></i>,  compose=&gt;{Undefined, Add, Atop, Blend, Bumpmap, Clear, ColorBurn, ColorDodge, Colorize, CopyBlack, CopyBlue, CopyCMYK, Cyan, CopyGreen, Copy, CopyMagenta, CopyOpacity, CopyRed, RGB, CopyYellow, Darken, Dst, Difference, Displace, Dissolve, DstAtop, DstIn, DstOut, DstOver, Dst, Exclusion, HardLight, Hue, In, Lighten, Luminize, Minus, Modulate, Multiply, None, Out, Overlay, Over, Plus, ReplaceCompositeOp, Saturate, Screen, SoftLight, Src, SrcAtop, SrcIn, SrcOut, SrcOver, Src, Subtract, Threshold, Xor },</td>
 591     <td valign="top">surround the image with a border of color</td>
 592   </tr>
 593
 594   <tr>
 595     <td valign="top">Charcoal</td>
 596     <td valign="top">geometry=&gt;<i>geometry</i>, radius=&gt;<i>double</i>, sigma=&gt;<i>double</i></td>
 597     <td valign="top">simulate a charcoal drawing</td>
 598   </tr>
 599
 600   <tr>
 601     <td valign="top">Chop</td>
 602     <td valign="top">geometry=&gt;<i>geometry</i>, width=&gt;<i>integer</i>, height=&gt;<i>integer</i>, x=&gt;<i>integer</i>, y=&gt;<i>integer</i></td>
 603     <td valign="top">chop an image</td>
 604   </tr>
 605
 606   <tr>
 607     <td valign="top">Clamp</td>
 608     <td valign="top"><br /></td>
 609     <td valign="top">restrict color values from 0 to the quantum depth.</td>
 610   </tr>
 611
 612   <tr>
 613     <td valign="top">Clip</td>
 614     <td valign="top">id=&gt;<i>name</i>, inside=&gt;<i>{true, false}</i>,</td>
 615     <td valign="top">apply along a named path from the 8BIM profile.</td>
 616   </tr>
 617
 618   <tr>
 619     <td valign="top">ClipMask</td>
 620     <td valign="top">mask=&gt;<i>image-handle</i></td>
 621     <td valign="top">clip image as defined by the image mask</td>
 622   </tr>
 623
 624   <tr>
 625     <td valign="top">Clut</td>
 626     <td valign="top">image=&gt;<i>image-handle</i>,  channel=&gt;{Red, RGB, CMYK, Cyan, Green, Magenta, Blue, Yellow, Opacity, Black, or All}</td>
 627     <td valign="top">apply a color lookup table to an image sequence</td>
 628   </tr>
 629
 630   <tr>
 631     <td valign="top">Coalesce</td>
 632     <td valign="top"><br /></td>
 633     <td valign="top">merge a sequence of images</td>
 634   </tr>
 635
 636   <tr>
 637     <td valign="top">Color</td>
 638     <td valign="top">color=&gt;<i><a href="../www/color.html">color name</a></i></td>
 639     <td valign="top">set the entire image to this color.</td>
 640   </tr>
 641
 642   <tr>
 643     <td valign="top">ColorDecisionList</td>
 644     <td valign="top">filename=&gt;<i>string</i>,</td>
 645     <td valign="top">color correct with a color decision list.</td>
 646   </tr>
 647
 648   <tr>
 649     <td valign="top">Colorize</td>
 650     <td valign="top">fill=&gt;<i><a href="../www/color.html">color name</a></i>, opacity=&gt;<i>string</i></td>
 651     <td valign="top">colorize the image with the fill color</td>
 652   </tr>
 653
 654   <tr>
 655     <td valign="top">ColorMatrix</td>
 656     <td valign="top">matrix=&gt;<i>array of float values</i></td>
 657     <td valign="top">apply color correction to the image.  Although you can use variable sized matrices, typically you use a 5 x 5 for an RGBA image and a 6x6 for CMYKA.  A 6x6 matrix is required for offsets (populate the last column with normalized values).</td>
 658   </tr>
 659
 660   <tr>
 661     <td valign="top">Comment</td>
 662     <td valign="top">string</td>
 663     <td valign="top">add a comment to your image</td>
 664   </tr>
 665
 666   <tr>
 667     <td valign="top">CompareLayers</td>
 668     <td valign="top">method=&gt;{any, clear, overlay}</td>
 669     <td valign="top">compares each image with the next in a sequence and returns the minimum bounding region of any pixel differences it discovers.  Images do not have to be the same size, though it is best that all the images are coalesced (images are all the same size, on a flattened canvas, so as to represent exactly how a specific frame should look).</td>
 670   </tr>
 671
 672   <tr>
 673     <td valign="top">Composite</td>
 674     <td valign="top">image=&gt;<i>image-handle</i>, compose=&gt;{Undefined, Add, Atop, Blend, Bumpmap, Clear, ColorBurn, ColorDodge, Colorize, CopyBlack, CopyBlue, CopyCMYK, Cyan, CopyGreen, Copy, CopyMagenta, CopyOpacity, CopyRed, RGB, CopyYellow, Darken, Dst, Difference, Displace, Dissolve, DstAtop, DstIn, DstOut, DstOver, Dst, Exclusion, HardLight, Hue, In, Lighten, Luminize, Minus, Modulate, Multiply, None, Out, Overlay, Over, Plus, ReplaceCompositeOp, Saturate, Screen, SoftLight, Src, SrcAtop, SrcIn, SrcOut, SrcOver, Src, Subtract, Threshold, Xor }, mask=&gt;<i>image-handle</i>, geometry=&gt;<i>geometry</i>, x=&gt;<i>integer</i>, y=&gt;<i>integer</i>, gravity=&gt;{NorthWest, North, NorthEast, West, Center, East, SouthWest, South, SouthEast}, opacity=&gt;<i>integer</i>, tile=&gt;{True, False}, rotate=&gt;<i>double</i>, color=&gt;<i><a href="../www/color.html">color name</a></i>, blend=&gt;<i>geometry</i>, interpolate=&gt;{undefined, average, bicubic, bilinear, filter, integer, mesh, nearest-neighbor, spline}</td>
 675     <td valign="top">composite one image onto another.  Use the rotate parameter in concert with the tile parameter.</td>
 676   </tr>
 677
 678   <tr>
 679     <td valign="top">Contrast</td>
 680     <td valign="top">sharpen=&gt;{True, False}</td>
 681     <td valign="top">enhance or reduce the image contrast</td>
 682   </tr>
 683
 684   <tr>
 685     <td valign="top">ContrastStretch</td>
 686     <td valign="top">levels=&gt;<i>string</i>, 'black-point'=&gt;<i>double</i>, 'white-point'=&gt;<i>double</i>, channel=&gt;{Red, RGB, CMYK, Cyan, Green, Magenta, Blue, Yellow, Opacity, Black, or All}</td>
 687     <td valign="top">improve the contrast in an image by `stretching' the range of intensity values</td>
 688   </tr>
 689
 690   <tr>
 691     <td valign="top">Convolve</td>
 692     <td valign="top">coefficients=&gt;<i>array of float values</i>, channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}, bias=&gt;<i>double</i></td>
 693     <td valign="top">apply a convolution kernel to the image. Given a kernel <i>order</i> , you would supply <i>order*order</i> float values (e.g. 3x3 implies 9 values).</td>
 694   </tr>
 695
 696   <tr>
 697     <td valign="top">Crop</td>
 698     <td valign="top">geometry=&gt;<i>geometry</i>, width=&gt;<i>integer</i>, height=&gt;<i>integer</i>, x=&gt;<i>integer</i>, y=&gt;<i>integer</i>, fuzz=&gt;<i>double</i>, gravity=&gt;{NorthWest, North, NorthEast, West, Center, East, SouthWest, South, SouthEast}</td>
 699     <td valign="top">crop an image</td>
 700   </tr>
 701
 702   <tr>
 703     <td valign="top">CycleColormap</td>
 704     <td valign="top">amount=&gt;<i>integer</i></td>
 705     <td valign="top">displace image colormap by amount</td>
 706   </tr>
 707
 708   <tr>
 709     <td valign="top">Decipher</td>
 710     <td valign="top">passphrase=&gt;<i>string</i></td>
 711     <td valign="top">convert cipher pixels to plain pixels</td>
 712   </tr>
 713
 714   <tr>
 715     <td valign="top">Deconstruct</td>
 716     <td valign="top"><br /></td>
 717     <td valign="top">break down an image sequence into constituent parts</td>
 718   </tr>
 719
 720   <tr>
 721     <td valign="top">Deskew</td>
 722     <td valign="top">geometry=&gt;<i>string</i>,threshold=&gt;<i>double</i></td>
 723     <td valign="top">straighten the image</td>
 724   </tr>
 725
 726   <tr>
 727     <td valign="top">Despeckle</td>
 728     <td valign="top">&nbsp;</td>
 729     <td valign="top">reduce the speckles within an image</td>
 730   </tr>
 731
 732   <tr>
 733     <td valign="top">Difference</td>
 734     <td valign="top">image=&gt;<i>image-handle</i></td>
 735     <td valign="top">compute the difference metrics between two images </td>
 736   </tr>
 737
 738   <tr>
 739     <td valign="top">Distort</td>
 740     <td valign="top">points=&gt;<i>array of float values</i>, method=&gt;{Affine, AffineProjection, Bilinear, Perspective, Resize, ScaleRotateTranslate}, virtual-pixel=&gt;{Background Black Constant Dither Edge Gray Mirror Random Tile Transparent White}, best-fit=&gt;{True, False}</td>
 741     <td valign="top">distort image</td>
 742   </tr>
 743
 744   <tr>
 745     <td valign="top">Draw</td>
 746     <td valign="top">primitive=&gt;{point, line, rectangle, arc, ellipse, circle, path, polyline, polygon, bezier, color, matte, text, @<i>filename</i>}, points=&gt;<i>string</i> , method=&gt;<i>{Point, Replace, Floodfill, FillToBorder, Reset}</i>, stroke=&gt;<i><a href="../www/color.html">color name</a></i>, fill=&gt;<i><a href="../www/color.html">color name</a></i>, font=&gt;<i>string</i>, pointsize=&gt;<i>integer</i>, strokewidth=&gt;<i>float</i>, antialias=&gt;{true, false}, bordercolor=&gt;<i><a href="../www/color.html">color name</a></i>, x=&gt;<i>float</i>, y=&gt;<i>float</i>, dash-offset=&gt;<i>float</i>, dash-pattern=&gt;<i>array of float values</i>, affine=&gt;<i>array of float values</i>, translate=&gt;<i>float, float</i>, scale=&gt;<i>float, float</i>, rotate=&gt;<i>float</i>,  skewX=&gt;<i>float</i>, skewY=&gt;<i>float</i>, interpolate=&gt;{undefined, average, bicubic, bilinear, mesh, nearest-neighbor, spline}, kerning=&gt;<i>float</i>, text=&gt;<i>string</i>, vector-graphics=&gt;<i>string</i>, interline-spacing=&gt;<i>double</i>, interword-spacing=&gt;<i>double</i>, direction=&gt;{right-to-left, left-to-right}</td>
 747     <td valign="top">annotate an image with one or more graphic primitives.</td>
 748   </tr>
 749
 750   <tr>
 751     <td valign="top">Encipher</td>
 752     <td valign="top">passphrase=&gt;<i>string</i></td>
 753     <td valign="top">convert plain pixels to cipher pixels</td>
 754   </tr>
 755
 756   <tr>
 757     <td valign="top">Edge</td>
 758     <td valign="top">radius=&gt;<i>double</i></td>
 759     <td valign="top">enhance edges within the image with a convolution filter of the given radius.</td>
 760   </tr>
 761
 762   <tr>
 763     <td valign="top">Emboss</td>
 764     <td valign="top">geometry=&gt;<i>geometry</i>, radius=&gt;<i>double</i>, sigma=&gt;<i>double</i></td>
 765     <td valign="top">emboss the image with a convolution filter of the given radius and standard deviation (sigma).</td>
 766   </tr>
 767
 768   <tr>
 769     <td valign="top">Enhance</td>
 770     <td valign="top"><br /></td>
 771     <td valign="top">apply a digital filter to enhance a noisy image</td>
 772   </tr>
 773
 774   <tr>
 775     <td valign="top">Equalize</td>
 776     <td valign="top">channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}<br /></td>
 777     <td valign="top">perform histogram equalization to the image</td>
 778   </tr>
 779
 780   <tr>
 781     <td valign="top">Extent</td>
 782     <td valign="top">geometry=&gt;<i>geometry</i>, width=&gt;<i>integer</i>, height=&gt;<i>integer</i>, x=&gt;<i>integer</i>, y=&gt;<i>integer</i>, fuzz=&gt;<i>double</i>, background=&gt;<i><a href="../www/color.html">color name</a></i>, gravity=&gt;{NorthWest, North, NorthEast, West, Center, East, SouthWest, South, SouthEast}</td>
 783     <td valign="top">set the image size</td>
 784   </tr>
 785
 786   <tr>
 787     <td valign="top">Evaluate</td>
 788     <td valign="top">value=&gt;<i>double</i>, operator=&gt;<i>{Add, And, Divide, LeftShift, Max, Min, Multiply, Or, Rightshift, Subtract, Xor}</i>, channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow} </td>
 789     <td valign="top">apply an arithmetic, relational, or logical expression to the image</td>
 790   </tr>
 791
 792   <tr>
 793     <td valign="top">Filter</td>
 794     <td valign="top">kernel=&gt;<i>string</i>, channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}, bias=&gt;<i>double</i></td>
 795     <td valign="top">apply a convolution kernel to the image.</td>
 796   </tr>
 797
 798   <tr>
 799     <td valign="top">Flip</td>
 800     <td valign="top"><br /></td>
 801     <td valign="top">reflect the image scanlines in the vertical direction</td>
 802   </tr>
 803
 804   <tr>
 805     <td valign="top">Flop</td>
 806     <td valign="top"><br /></td>
 807     <td valign="top">reflect the image scanlines in the horizontal direction</td>
 808   </tr>
 809
 810   <tr>
 811     <td valign="top">FloodfillPaint</td>
 812     <td valign="top">geometry=&gt;<i>geometry</i>, channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}, x=&gt;<i>integer</i>, y=&gt;<i>integer</i> , fill=&gt;<i><a href="../www/color.html">color name</a></i>, bordercolor=&gt;<i><a href="../www/color.html">color name</a></i>, fuzz=&gt;<i>double</i>, invert=&gt;{True, False}</td>
 813     <td valign="top">changes the color value of any pixel that matches the color of the target pixel and is a neighbor. If you specify a border color, the color value is changed for any neighbor pixel that is not that color.</td>
 814   </tr>
 815
 816   <tr>
 817     <td valign="top">ForwardFourierTransform</td>
 818     <td valign="top">magnitude=&gt;{True, False}</td>
 819     <td valign="top">implements the forward discrete Fourier transform (DFT)</td>
 820   </tr>
 821
 822   <tr>
 823     <td valign="top">Frame</td>
 824     <td valign="top">geometry=&gt;<i>geometry</i>, width=&gt;<i>integer</i>, height=&gt;<i>integer</i>, inner=&gt;<i>integer</i>, outer=&gt;<i>integer</i>, fill=&gt;<i><a href="../www/color.html">color name</a></i>,  compose=&gt;{Undefined, Add, Atop, Blend, Bumpmap, Clear, ColorBurn, ColorDodge, Colorize, CopyBlack, CopyBlue, CopyCMYK, Cyan, CopyGreen, Copy, CopyMagenta, CopyOpacity, CopyRed, RGB, CopyYellow, Darken, Dst, Difference, Displace, Dissolve, DstAtop, DstIn, DstOut, DstOver, Dst, Exclusion, HardLight, Hue, In, Lighten, Luminize, Minus, Modulate, Multiply, None, Out, Overlay, Over, Plus, ReplaceCompositeOp, Saturate, Screen, SoftLight, Src, SrcAtop, SrcIn, SrcOut, SrcOver, Src, Subtract, Threshold, Xor },</td>
 825     <td valign="top">surround the image with an ornamental border</td>
 826   </tr>
 827
 828   <tr>
 829     <td valign="top">Function</td>
 830     <td valign="top">parameters=&gt;<i>array of float values</i>, function=&gt;{Sin}, virtual-pixel=&gt;{Background Black Constant Dither Edge Gray Mirror Random Tile Transparent White}</td>
 831     <td valign="top">apply a function to the image</td>
 832   </tr>
 833
 834   <tr>
 835     <td valign="top">Gamma</td>
 836     <td valign="top">gamma=&gt;<i>string</i>, channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
 837     <td valign="top">gamma correct the image</td>
 838   </tr>
 839
 840   <tr>
 841     <td valign="top">GaussianBlur</td>
 842     <td valign="top">geometry=&gt;<i>geometry</i>, radius=&gt;<i>double</i>, sigma=&gt;<i>double</i>, channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
 843     <td valign="top">reduce image noise and reduce detail levels with a Gaussian operator of the given radius and standard deviation (sigma).</td>
 844   </tr>
 845
 846   <tr>
 847     <td valign="top">GetPixel</td>
 848     <td valign="top">geometry=&gt;<i>geometry</i>, channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}, normalize=&gt;{true, false}, x=&gt;<i>integer</i>, y=&gt;<i>integer</i></td>
 849     <td valign="top">get a single pixel. By default normalized pixel values are returned.</td>
 850   </tr>
 851
 852   <tr>
 853     <td valign="top">GetPixels</td>
 854     <td valign="top">geometry=&gt;<i>geometry</i>, width=&gt;<i>integer</i>, height=&gt;<i>integer</i>, x=&gt;<i>integer</i>, y=&gt;<i>integer</i>, map=&gt;<i>string</i>, normalize=&gt;{true, false}</td>
 855     <td valign="top">get image pixels as defined by the map (e.g. "RGB", "RGBA", etc.).  By default non-normalized pixel values are returned.</td>
 856   </tr>
 857
 858   <tr>
 859     <td valign="top">HaldClut</td>
 860     <td valign="top">image=&gt;<i>image-handle</i>,  channel=&gt;{Red, RGB, CMYK, Cyan, Green, Magenta, Blue, Yellow, Opacity, Black, or All}</td>
 861     <td valign="top">apply a Hald color lookup table to an image sequence</td>
 862   </tr>
 863
 864   <tr>
 865     <td valign="top">Identify</td>
 866     <td valign="top">file=&gt;<i>file</i>, features=&gt;<i>distance</i>, unique=&gt;{True, False}</td>
 867     <td valign="top">identify the attributes of an image</td>
 868   </tr>
 869
 870   <tr>
 871     <td valign="top">Implode</td>
 872     <td valign="top">amount=&gt;<i>double</i>, interpolate=&gt;{undefined, average, bicubic, bilinear, mesh, nearest-neighbor, spline}</td>
 873     <td valign="top">implode image pixels about the center</td>
 874   </tr>
 875
 876   <tr>
 877     <td valign="top">InverseDiscreteFourierTransform</td>
 878     <td valign="top">magnitude=&gt;{True, False}</td>
 879     <td valign="top">implements the inverse discrete Fourier transform (DFT)</td>
 880   </tr>
 881
 882   <tr>
 883     <td valign="top">Label</td>
 884     <td valign="top">string</td>
 885     <td valign="top">assign a label to an image</td>
 886   </tr>
 887
 888   <tr>
 889     <td valign="top">Layers</td>
 890     <td valign="top">method=&gt;{coalesce, compare-any, compare-clear, compare-over, composite, dispose, flatten, merge, mosaic, optimize, optimize-image, optimize-plus, optimize-trans, remove-dups, remove-zero},  compose=&gt;{Undefined, Add, Atop, Blend, Bumpmap, Clear, ColorBurn, ColorDodge, Colorize, CopyBlack, CopyBlue, CopyCMYK, Cyan, CopyGreen, Copy, CopyMagenta, CopyOpacity, CopyRed, RGB, CopyYellow, Darken, Dst, Difference, Displace, Dissolve, DstAtop, DstIn, DstOut, DstOver, Dst, Exclusion, HardLight, Hue, In, Lighten, LinearLight, Luminize, Minus, Modulate, Multiply, None, Out, Overlay, Over, Plus, ReplaceCompositeOp, Saturate, Screen, SoftLight, Src, SrcAtop, SrcIn, SrcOut, SrcOver, Src, Subtract, Threshold, Xor }, dither=&gt;{true, false}</td>
 891     <td valign="top">compare each image the GIF disposed forms of the previous image in the sequence.  From this, attempt to select the smallest cropped image to replace each frame, while preserving the results of the animation.</td>
 892   </tr>
 893
 894   <tr>
 895     <td valign="top">Level</td>
 896     <td valign="top">levels=&gt;<i>string</i>, 'black-point'=&gt;<i>double</i>, 'gamma'=&gt;<i>double</i>, 'white-point'=&gt;<i>double</i>, channel=&gt;{Red, RGB, CMYK, Cyan, Green, Magenta, Blue, Yellow, Opacity, Black, or All}</td>
 897     <td valign="top">adjust the level of image contrast</td>
 898   </tr>
 899
 900   <tr>
 901     <td valign="top">LevelColors</td>
 902     <td valign="top">invert=&gt;&gt;{True, False}, 'black-point'=&gt;<i>string</i>,  'white-point'=&gt;<i>string</i>, channel=&gt;{Red, RGB, CMYK, Cyan, Green, Magenta, Blue, Yellow, Opacity, Black, or All}</td>
 903     <td valign="top">level image with the given colors</td>
 904   </tr>
 905
 906   <tr>
 907     <td valign="top">LinearStretch</td>
 908     <td valign="top">levels=&gt;<i>string</i>, 'black-point'=&gt;<i>double</i>, 'white-point'=&gt;<i>double</i></td>
 909     <td valign="top">linear with saturation stretch</td>
 910   </tr>
 911
 912   <tr>
 913     <td valign="top">LiquidResize</td>
 914     <td valign="top">geometry=&gt;<i>geometry</i>, width=&gt;<i>integer</i>, height=&gt;<i>integer</i>, delta-x=&gt;<i>double</i>, rigidity=&gt;<i>double</i></td>
 915     <td valign="top">rescale image with seam-carving.</td>
 916   </tr>
 917
 918   <tr>
 919     <td valign="top">Magnify</td>
 920     <td valign="top"><br /></td>
 921     <td valign="top">double the size of an image</td>
 922   </tr>
 923
 924   <tr>
 925     <td valign="top">Mask</td>
 926     <td valign="top">mask=&gt;<i>image-handle</i></td>
 927     <td valign="top">composite image pixels as defined by the mask</td>
 928   </tr>
 929
 930   <tr>
 931     <td valign="top">MatteFloodfill</td>
 932     <td valign="top">geometry=&gt;<i>geometry</i>, x=&gt;<i>integer</i>, y=&gt;<i>integer</i> , matte=&gt;<i>integer</i>, bordercolor=&gt;<i><a href="../www/color.html">color name</a></i>, fuzz=&gt;<i>double</i>, invert=&gt;{True, False}</td>
 933     <td valign="top">changes the matte value of any pixel that matches the color of the target pixel and is a neighbor. If you specify a border color, the matte value is changed for any neighbor pixel that is not that color.</td>
 934   </tr>
 935
 936   <tr>
 937     <td valign="top">MedianFilter</td>
 938     <td valign="top">geometry=&gt;<i>geometry</i>, width=&gt;<i>integer</i>, height=&gt;<i>integer</i>, channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
 939     <td valign="top">replace each pixel with the median intensity pixel of a neighborhood.</td>
 940   </tr>
 941
 942   <tr>
 943     <td valign="top">Minify</td>
 944     <td valign="top"><br /></td>
 945     <td valign="top">half the size of an image</td>
 946   </tr>
 947
 948   <tr>
 949     <td valign="top">Mode</td>
 950     <td valign="top">geometry=&gt;<i>geometry</i>, width=&gt;<i>integer</i>, height=&gt;<i>integer</i>, channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
 951     <td valign="top">make each pixel the <em>predominate color</em> of the neighborhood.</td>
 952   </tr>
 953
 954   <tr>
 955     <td valign="top">Modulate</td>
 956     <td valign="top">brightness=&gt;<i>double</i>, saturation=&gt;<i>double</i>, hue=&gt;<i>double</i>, lightness=&gt;<i>double</i>, whiteness=&gt;<i>double</i>, blackness=&gt;<i>double</i> </td>
 957     <td valign="top">vary the brightness, saturation, and hue of an image by the specified percentage</td>
 958   </tr>
 959
 960   <tr>
 961     <td valign="top">Morphology</td>
 962     <td valign="top">kernel=&gt;<i>string</i>, channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}, iterations=&gt;<i>integer</i></td>
 963     <td valign="top">apply a morphology method to the image.</td>
 964   </tr>
 965
 966   <tr>
 967     <td valign="top">MotionBlur</td>
 968     <td valign="top">geometry=&gt;<i>geometry</i>, radius=&gt;<i>double</i>, sigma=&gt;<i>double</i>, angle=&gt;<i>double</i>, channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
 969     <td valign="top">reduce image noise and reduce detail levels with a Gaussian operator of the given radius and standard deviation (sigma) at the given angle to simulate the effect of motion</td>
 970   </tr>
 971
 972   <tr>
 973     <td valign="top">Negate</td>
 974     <td valign="top">gray=&gt;{True, False}, channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
 975     <td valign="top">replace each pixel with its complementary color (white becomes black, yellow becomes blue, etc.)</td>
 976   </tr>
 977
 978   <tr>
 979     <td valign="top">Normalize</td>
 980     <td valign="top">channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}<br /></td>
 981     <td valign="top">transform image to span the full range of color values</td>
 982   </tr>
 983
 984   <tr>
 985     <td valign="top">OilPaint</td>
 986     <td valign="top">radius=&gt;<i>integer</i></td>
 987     <td valign="top">simulate an oil painting</td>
 988   </tr>
 989
 990   <tr>
 991     <td valign="top">Opaque</td>
 992     <td valign="top">color=&gt;<i><a href="../www/color.html">color name</a></i>,
 993 fill=&gt;<i><a href="../www/color.html">color name</a></i>, channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}, invert=&gt;{True, False}</td>
 994     <td valign="top">change this color to the fill color within the image</td>
 995   </tr>
 996
 997   <tr>
 998     <td valign="top">OrderedDither</td>
 999     <td valign="top">threshold=&gt;{threshold, checks, o2x2, o3x3, o4x4, o8x8, h4x4a, h6x6a, h8x8a, h4x4o, h6x6o, h8x8o, h16x16o, hlines6x4}, channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
1000     <td valign="top">order dither image</td>
1001   </tr>
1002
1003   <tr>
1004     <td valign="top">Polaroid</td>
1005     <td valign="top">caption=&gt;<i>string</i>, angle=&gt;<i>double</i>, pointsize=&gt;<i>double</i>, font=&gt;<i>string</i>, stroke=&gt; <i><a href="../www/color.html">color name</a></i>, strokewidth=&gt;<i>integer</i>, fill=&gt;<i><a href="../www/color.html">color name</a></i>, gravity=&gt;{NorthWest, North, NorthEast, West, Center, East, SouthWest, South, SouthEast},  background=&gt;<i><a href="../www/color.html">color name</a></i></td>
1006     <td valign="top">simulate a Polaroid picture.</td>
1007   </tr>
1008
1009   <tr>
1010     <td valign="top">Posterize</td>
1011     <td valign="top">levels=&gt;<i>integer</i>, dither=&gt;{True, False}</td>
1012     <td valign="top">reduce the image to a limited number of color level</td>
1013   </tr>
1014
1015   <tr>
1016     <td valign="top">Profile</td>
1017     <td valign="top">name=&gt;<i>string</i>, profile=&gt;<i>blob</i>, rendering-intent=&gt;{Undefined, Saturation, Perceptual, Absolute, Relative}, black-point-compensation=&gt;{True, False}</td>
1018     <td valign="top">add or remove ICC or IPTC image profile; name is formal name (e.g. ICC or filename; set profile to <kbd>''</kbd> to remove profile</td>
1019   </tr>
1020
1021   <tr>
1022     <td valign="top">Quantize</td>
1023     <td valign="top">colors=&gt;<i>integer</i>, colorspace=&gt;{RGB, Gray, Transparent, OHTA, XYZ, YCbCr, YIQ, YPbPr, YUV, CMYK, sRGB, HSL, HSB}, treedepth=&gt; <i>integer</i>, dither=&gt;{True, False}, dither-method=&gt;{Riemersma, Floyd-Steinberg}, measure_error=&gt;{True, False}, global_colormap=&gt;{True, False}, transparent-color=&gt;<i>color</i></td>
1024     <td valign="top">preferred number of colors in the image</td>
1025   </tr>
1026
1027   <tr>
1028     <td valign="top">RadialBlur</td>
1029     <td valign="top">angle=&gt;<i>double</i></td>
1030     <td valign="top">radial blur the image.</td>
1031   </tr>
1032
1033   <tr>
1034     <td valign="top">Raise</td>
1035     <td valign="top">geometry=&gt;<i>geometry</i>, width=&gt;<i>integer</i>, height=&gt;<i>integer</i>, x=&gt;<i>integer</i>, y=&gt;<i>integer</i>, raise=&gt;{True, False}</td>
1036     <td valign="top">lighten or darken image edges to create a 3-D effect</td>
1037   </tr>
1038
1039   <tr>
1040     <td valign="top">ReduceNoise</td>
1041     <td valign="top">geometry=&gt;<i>geometry</i>, width=&gt;<i>integer</i>, height=&gt;<i>integer</i>, channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
1042     <td valign="top">reduce noise in the image with a noise peak elimination filter</td>
1043   </tr>
1044
1045   <tr>
1046     <td valign="top">Remap</td>
1047     <td valign="top">image=&gt;<i>image-handle</i>,  dither=&gt;{true, false}, dither-method=&gt;{Riemersma, Floyd-Steinberg}</td>
1048     <td valign="top">replace the colors of an image with the closest color from a reference image.</td>
1049   </tr>
1050
1051   <tr>
1052     <td valign="top">Resample</td>
1053     <td valign="top">density=&gt;<i>geometry</i>, x=&gt;<i>double</i>, y=&gt;<i>double</i>, filter=&gt;{Point, Box, Triangle, Hermite, Hanning, Hamming, Blackman, Gaussian, Quadratic, Cubic, Catrom, Mitchell, Lanczos, Bessel, Sinc}, support=&gt;<i>double</i></td>
1054     <td valign="top">resample image to desired resolution. Specify <kbd>blur</kbd> &gt; 1 for blurry or &lt; 1 for sharp</td>
1055   </tr>
1056
1057   <tr>
1058     <td valign="top">Resize</td>
1059     <td valign="top">geometry=&gt;<i>geometry</i>, width=&gt;<i>integer</i>, height=&gt;<i>integer</i>, filter=&gt;{Point, Box, Triangle, Hermite, Hanning, Hamming, Blackman, Gaussian, Quadratic, Cubic, Catrom, Mitchell, Lanczos, Bessel, Sinc}, support=&gt;<i>double</i>, blur=&gt;<i>double</i></td>
1060     <td valign="top">scale image to desired size. Specify <kbd>blur</kbd> &gt; 1 for blurry or &lt; 1 for sharp</td>
1061   </tr>
1062
1063   <tr>
1064     <td valign="top">Roll</td>
1065     <td valign="top">geometry=&gt;<i>geometry</i>, x=&gt;<i>integer</i>, y=&gt;<i>integer</i></td>
1066     <td valign="top">roll an image vertically or horizontally</td>
1067   </tr>
1068
1069   <tr>
1070     <td valign="top">Rotate</td>
1071     <td valign="top">degrees=&gt;<i>double</i>, background=&gt;<i><a href="../www/color.html">color name</a></i></td>
1072     <td valign="top">rotate an image</td>
1073   </tr>
1074
1075   <tr>
1076     <td valign="top">Sample</td>
1077     <td valign="top">geometry=&gt;<i>geometry</i>, width=&gt;<i>integer</i>, height=&gt;<i>integer</i></td>
1078     <td valign="top">scale image with pixel sampling.</td>
1079   </tr>
1080
1081   <tr>
1082     <td valign="top">Scale</td>
1083     <td valign="top">geometry=&gt;<i>geometry</i>, width=&gt;<i>integer</i>, height=&gt;<i>integer</i></td>
1084     <td valign="top">scale image to desired size</td>
1085   </tr>
1086
1087   <tr>
1088     <td valign="top">Segment</td>
1089     <td valign="top">colorspace=&gt;{RGB, Gray, Transparent, OHTA, XYZ, YCbCr, YCC, YIQ, YPbPr, YUV, CMYK}, verbose={True, False}, cluster-threshold=&gt;<i>double</i>, smoothing-threshold=<i>double</i></td>
1090     <td valign="top">segment an image by analyzing the histograms of the color components and identifying units that are homogeneous</td>
1091   </tr>
1092
1093   <tr>
1094     <td valign="top">SelectiveBlur</td>
1095     <td valign="top">geometry=&gt;<i>geometry</i>, radius=&gt;<i>double</i>, sigma=&gt;<i>double</i>, threshold=&gt;<i>double</i>, channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
1096     <td valign="top">selectively blur pixels within a contrast threshold.</td>
1097   </tr>
1098   <tr>
1099     <td valign="top">Separate</td>
1100     <td valign="top">channel=&gt;{Red, RGB, CMYK, Cyan, Green, Magenta, Blue, Yellow, Opacity, Black, or All}</td>
1101     <td valign="top">separate a channel from the image into a grayscale image</td>
1102   </tr>
1103
1104   <tr>
1105     <td valign="top">Shade</td>
1106     <td valign="top">geometry=&gt;<i>geometry</i>, azimuth=&gt;<i>double</i>, elevation=&gt;<i>double</i>, gray=&gt;{true, false}</td>
1107     <td valign="top">shade the image using a distant light source</td>
1108   </tr>
1109
1110   <tr>
1111     <td valign="top">SetPixel</td>
1112     <td valign="top">geometry=&gt;<i>geometry</i>, channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}, color=&gt;<i>array of float values</i>, x=&gt;<i>integer</i>, y=&gt;<i>integer</i>, color=&gt;<i>array of float values</i></td>
1113     <td valign="top">set a single pixel.  By default normalized pixel values are expected.</td>
1114   </tr>
1115
1116   <tr>
1117     <td valign="top">Shadow</td>
1118     <td valign="top">geometry=&gt;<i>geometry</i>, opacity=&gt;<i>double</i>, sigma=&gt;<i>double</i>, x=&gt;<i>integer</i>, y=&gt;<i>integer</i></td>
1119     <td valign="top">simulate an image shadow</td>
1120   </tr>
1121
1122   <tr>
1123     <td valign="top">Sharpen</td>
1124     <td valign="top">geometry=&gt;<i>geometry</i>, radius=&gt;<i>double</i>, sigma=&gt;<i>double</i>, channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
1125     <td valign="top">sharpen the image with a Gaussian operator of the given radius and standard deviation (sigma).</td>
1126   </tr>
1127
1128   <tr>
1129     <td valign="top">Shave</td>
1130     <td valign="top">geometry=&gt;<i>geometry</i>, width=&gt;<i>integer</i>, height=&gt;<i>integer</i></td>
1131     <td valign="top">shave pixels from the image edges</td>
1132   </tr>
1133
1134   <tr>
1135     <td valign="top">Shear</td>
1136     <td valign="top">geometry=&gt;<i>geometry</i>, x=&gt;<i>double</i>, y=&gt;<i>double</i> fill=&gt;<i><a href="../www/color.html">color name</a></i></td>
1137     <td valign="top">shear the image along the X or Y axis by a positive or negative shear angle</td>
1138   </tr>
1139
1140   <tr>
1141     <td valign="top">SigmoidalContrast</td>
1142     <td valign="top">geometry=&gt;<i>string</i>, 'contrast'=&gt;<i>double</i>, 'mid-point'=&gt;<i>double</i> channel=&gt;{Red, RGB, CMYK, Cyan, Green, Magenta, Blue, Yellow, Opacity, Black, or All}, sharpen=&gt;{True, False}</td>
1143     <td valign="top">sigmoidal non-lineraity contrast control.  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). To decrease contrast, set sharpen to False.</td>
1144   </tr>
1145
1146   <tr>
1147     <td valign="top">Signature</td>
1148     <td valign="top"><br /></td>
1149     <td valign="top">generate an SHA-256 message digest for the image pixel stream</td>
1150   </tr>
1151
1152   <tr>
1153     <td valign="top">Sketch</td>
1154     <td valign="top">geometry=&gt;<i>geometry</i>, radius=&gt;<i>double</i>, sigma=&gt;<i>double</i>, angle=&gt;<i>double</i></td>
1155     <td valign="top">sketch the image with a Gaussian operator of the given radius and standard deviation (sigma) at the given angle</td>
1156   </tr>
1157
1158   <tr>
1159     <td valign="top">Solarize</td>
1160     <td valign="top">geometry=&gt;<i>string</i>,threshold=&gt;<i>double</i></td>
1161     <td valign="top">negate all pixels above the threshold level</td>
1162   </tr>
1163
1164   <tr>
1165     <td valign="top">SparseColor</td>
1166     <td valign="top">points=&gt;<i>array of float values</i>, method=&gt;{Barycentric, Bilinear, Shepards, Voronoi}, virtual-pixel=&gt;{Background Black Constant Dither Edge Gray Mirror Random Tile Transparent White}</td>
1167     <td valign="top">interpolate the image colors around the supplied points</td>
1168   </tr>
1169
1170   <tr>
1171     <td valign="top">Splice</td>
1172     <td valign="top">geometry=&gt;<i>geometry</i>, width=&gt;<i>integer</i>, height=&gt;<i>integer</i>, x=&gt;<i>integer</i>, y=&gt;<i>integer</i>, fuzz=&gt;<i>double</i>, background=&gt;<i><a href="../www/color.html">color name</a></i>, gravity=&gt;{NorthWest, North, NorthEast, West, Center, East, SouthWest, South, SouthEast}</td>
1173     <td valign="top">splice an image</td>
1174   </tr>
1175
1176   <tr>
1177     <td valign="top">Spread</td>
1178     <td valign="top">radius=&gt;<i>double</i></td>
1179     <td valign="top">displace image pixels by a random amount</td>
1180   </tr>
1181
1182   <tr>
1183     <td valign="top">Statistic</td>
1184     <td valign="top">geometry=&gt;<i>geometry</i>, width=&gt;<i>integer</i>, height=&gt;<i>integer</i>, channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}, type=&gt;{Median, Mode, Mean, Maximum, Minimum, ReduceNoise}</td>
1185     <td valign="top">replace each pixel with corresponding statistic from the neighborhood.</td>
1186   </tr>
1187   <tr>
1188     <td valign="top">Stegano</td>
1189     <td valign="top">image=&gt;<i>image-handle</i>, offset=&gt;<i>integer</i></td>
1190     <td valign="top">hide a digital watermark within the image</td>
1191   </tr>
1192
1193   <tr>
1194     <td valign="top">Stereo</td>
1195     <td valign="top">image=&gt;<i>image-handle</i>, x=&gt;<i>integer</i>, y=&gt;<i>integer</i></td>
1196     <td valign="top">composites two images and produces a single image that is the composite of a left and right image of a stereo pair</td>
1197   </tr>
1198
1199   <tr>
1200     <td valign="top">Strip</td>
1201     <td valign="top"><br /></td>
1202     <td valign="top">strip an image of all profiles and comments.</td>
1203   </tr>
1204
1205   <tr>
1206     <td valign="top">Swirl</td>
1207     <td valign="top">degrees=&gt;<i>double</i>, interpolate=&gt;{undefined, average, bicubic, bilinear, mesh, nearest-neighbor, spline}</td>
1208     <td valign="top">swirl image pixels about the center</td>
1209   </tr>
1210
1211   <tr>
1212     <td valign="top">Texture</td>
1213     <td valign="top">texture=&gt;<i>image-handle</i></td>
1214     <td valign="top">name of texture to tile onto the image background</td>
1215   </tr>
1216
1217   <tr>
1218     <td valign="top">Thumbnail</td>
1219     <td valign="top">geometry=&gt;<i>geometry</i>, width=&gt;<i>integer</i>, height=&gt;<i>integer</i></td>
1220     <td valign="top">changes the size of an image to the given dimensions and removes any associated profiles.</td>
1221   </tr>
1222
1223   <tr>
1224     <td valign="top">Threshold</td>
1225     <td valign="top">threshold=&gt;<i>string</i>, channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
1226     <td valign="top">threshold the image</td>
1227   </tr>
1228
1229   <tr>
1230     <td valign="top">Tint</td>
1231     <td valign="top">fill=&gt;<i><a href="../www/color.html">color name</a></i>, opacity=&gt;<i>string</i></td>
1232     <td valign="top">tint the image with the fill color.</td>
1233   </tr>
1234
1235   <tr>
1236     <td valign="top">Transparent</td>
1237     <td valign="top">color=&gt;<i><a href="../www/color.html">color name</a></i>, invert=&gt;{True, False}</td>
1238     <td valign="top">make this color transparent within the image</td>
1239   </tr>
1240
1241   <tr>
1242     <td valign="top">Transpose</td>
1243     <td valign="top"><br /></td>
1244     <td valign="top">flip image in the vertical direction and rotate 90 degrees</td>
1245   </tr>
1246
1247   <tr>
1248     <td valign="top">Transverse</td>
1249     <td valign="top"><br /></td>
1250     <td valign="top">flop image in the horizontal direction and rotate 270 degrees</td>
1251   </tr>
1252
1253   <tr>
1254     <td valign="top">Trim</td>
1255     <td valign="top"><br /></td>
1256     <td valign="top">remove edges that are the background color from the image</td>
1257   </tr>
1258
1259   <tr>
1260     <td valign="top">UnsharpMask</td>
1261     <td valign="top">geometry=&gt;<i>geometry</i>, radius=&gt;<i>double</i>, sigma=&gt;<i>double</i>, amount=&gt;<i>double</i>, threshold=&gt;<i>double</i></td>
1262     <td valign="top">sharpen the image with the unsharp mask algorithm.</td>
1263   </tr>
1264
1265   <tr>
1266     <td valign="top">Vignette</td>
1267     <td valign="top">geometry=&gt;<i>geometry</i>, radius=&gt;<i>double</i>, sigma=&gt;<i>double</i>, x=&gt;<i>integer</i>, y=&gt;<i>integer</i>, background=&gt;<i><a href="../www/color.html">color name</a></i></td>
1268     <td valign="top">offset the edges of the image in vignette style</td>
1269   </tr>
1270
1271   <tr>
1272     <td valign="top">Wave</td>
1273     <td valign="top">geometry=&gt;<i>geometry</i>, amplitude=&gt;<i>double</i>, wavelength=&gt;<i>double</i>, interpolate=&gt;{undefined, average, bicubic, bilinear, mesh, nearest-neighbor, spline}</td>
1274     <td valign="top">alter an image along a sine wave</td>
1275   </tr>
1276
1277   <tr>
1278     <td valign="top">WhiteThreshold</td>
1279     <td valign="top">threshold=&gt;<i>string</i>, , channel=&gt;{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
1280     <td valign="top">force all pixels above the threshold intensity into white</td>
1281   </tr>
1282 </tbody>
1283 </table>
1284
1285 <p>Note, that the <kbd>geometry</kbd> parameter is a short cut for the <kbd>width</kbd> and <kbd>height</kbd> parameters (e.g.  <kbd>geometry=&gt;'106x80'</kbd> is equivalent to <kbd>width=&gt;106, height=&gt;80</kbd> ).</p>
1286
1287 <p>You can specify <kbd>@filename</kbd> in both Annotate() and Draw(). This reads the text or graphic primitive instructions from a file on disk. For example,</p>
1288
1289 <pre class="code">
1290    $image-&gt;Draw(fill=&gt;'red', primitive=&gt;'rectangle',
1291      points=&gt;'20,20 100,100  40,40 200,200  60,60 300,300');
1292 </pre>
1293
1294 <p>Is equivalent to</p>
1295
1296 <pre class="code">
1297    $image-&gt;Draw(fill=&gt;'red', primitive=&gt;'@draw.txt');
1298 </pre>
1299
1300 <p>Where <kbd>draw.txt</kbd> is a file on disk that contains this:</p>
1301
1302 <pre class="text">
1303   rectangle 20, 20 100, 100
1304   rectangle 40, 40 200, 200
1305   rectangle 60, 60 300, 300
1306 </pre>
1307
1308 <p>The <i>text</i> parameter for methods, Annotate(), Comment(), Draw(), and Label() can include the image filename, type, width, height, or other image attribute by embedding these special format characters:</p>
1309
1310 <pre class="text">
1311    %b   file size
1312    %c   comment
1313    %d   directory
1314    %e   filename extension
1315    %f   filename
1316    %g   page geometry
1317    %h   height
1318    %i   input filename
1319    %k   number of unique colors
1320    %l   label
1321    %m   magick
1322    %n   number of scenes
1323    %o   output filename
1324    %p   page number
1325    %q   quantum depth
1326    %r   image class and colorspace
1327    %s   scene number
1328    %t   top of filename
1329    %u   unique temporary filename
1330    %w   width
1331    %x   x resolution
1332    %y   y resolution
1333    %z   image depth
1334    %C   image compression type
1335    %D   image dispose method
1336    %H   page height
1337    %Q   image compression quality
1338    %T   image delay
1339    %W   page width
1340    %X   page x offset
1341    %Y   page y offset
1342    %@   bounding box
1343    %#   signature
1344    %%   a percent sign
1345    \n   newline
1346    \r   carriage return
1347 </pre>
1348
1349 <p>For example,</p>
1350
1351 <pre class="code">
1352   text=&gt;"%m:%f %wx%h"
1353 </pre>
1354
1355 <p>produces an annotation of <b>MIFF:bird.miff 512x480</b> for an image titled <b>bird.miff</b> and whose width is 512 and height is 480.</p>
1356
1357 <p>You can optionally add <i>Image</i> to any method name. For example, TrimImage() is an alias for method Trim().</p>
1358
1359 <p>Most of the attributes listed above have an analog in <a href="../www/convert.html">convert</a>. See the documentation for a more detailed description of these attributes.</p>
1360
1361 </div>
1362
1363 <h2><a id="set-attribute"></a>Set an Image Attribute</h2>
1364 <div class="doc-section">
1365
1366 <p>Use method Set() to set an image attribute. For example,</p>
1367
1368 <pre class="code">
1369   $image-&gt;Set(dither=&gt;'True');
1370   $image-&gt;[$x]-&gt;Set(delay=&gt;3);
1371 </pre>
1372
1373 <p>Where this example uses 'True' and this document says '{True, False}',
1374 you can use the case-insensitive strings 'True' and 'False', or you
1375 can use the integers 1 and 0.</p>
1376
1377 <p>When you call Get() on a Boolean attribute, Image::Magick returns 1 or 0, not a string.</p>
1378
1379 <p>And here is a list of all the image attributes you can set:</p>
1380
1381 <table class="doc">
1382   <caption>Image Attributes</caption>
1383   <tbody>
1384   <tr>
1385     <th>Attribute</th>
1386     <th style="width: 40%">Values</th>
1387     <th style="width: 40%">Description</th>
1388   </tr>
1389
1390   <tr>
1391     <td valign="top">adjoin</td>
1392     <td valign="top">{True, False}</td>
1393     <td valign="top">join images into a single multi-image file</td>
1394   </tr>
1395
1396   <tr>
1397     <td valign="top">alpha</td>
1398     <td valign="top">{On, Off, Opaque, Transparent, Copy, Extract, Set}</td>
1399     <td valign="top">control of and special operations involving the alpha/matte channel</td>
1400   </tr>
1401
1402   <tr>
1403     <td valign="top">antialias</td>
1404     <td valign="top">{True, False}</td>
1405     <td valign="top">remove pixel aliasing</td>
1406   </tr>
1407
1408   <tr>
1409     <td valign="top">area-limit</td>
1410     <td valign="top"><i>integer</i></td>
1411     <td valign="top">set pixel area resource limit.</td>
1412   </tr>
1413
1414   <tr>
1415     <td valign="top">attenuate</td>
1416     <td valign="top"><i>double</i></td>
1417     <td valign="top">lessen (or intensify) when adding noise to an image.</td>
1418   </tr>
1419
1420   <tr>
1421     <td valign="top">authenticate</td>
1422     <td valign="top"><i>string</i></td>
1423     <td valign="top">decrypt image with this password.</td>
1424   </tr>
1425
1426   <tr>
1427     <td valign="top">background</td>
1428     <td valign="top"><i><a href="../www/color.html">color name</a></i></td>
1429     <td valign="top">image background color</td>
1430   </tr>
1431
1432   <tr>
1433     <td valign="top">blue-primary</td>
1434     <td valign="top"><i>x-value</i>, <i>y-value</i></td>
1435     <td valign="top">chromaticity blue primary point (e.g. 0.15, 0.06)</td>
1436   </tr>
1437
1438   <tr>
1439     <td valign="top">bordercolor</td>
1440     <td valign="top"><i><a href="../www/color.html">color name</a></i></td>
1441     <td valign="top">set the image border color</td>
1442   </tr>
1443
1444   <tr>
1445     <td valign="top">clip-mask</td>
1446     <td valign="top"><i>image</i></td>
1447     <td valign="top">associate a clip mask with the image.</td>
1448   </tr>
1449
1450   <tr>
1451     <td valign="top">colormap[<i>i</i>]</td>
1452     <td valign="top"><i><a href="../www/color.html">color name</a></i></td>
1453     <td valign="top">color name (e.g. red) or hex value (e.g. #ccc) at position
1454 <i>i</i></td>
1455   </tr>
1456
1457   <tr>
1458     <td valign="top">comment</td>
1459     <td valign="top"><i>string</i></td>
1460     <td valign="top">set the image comment</td>
1461   </tr>
1462
1463   <tr>
1464     <td valign="top">compression</td>
1465     <td valign="top">{None, BZip, Fax, Group4, JPEG, JPEG2000, LosslessJPEG, LZW, RLE, Zip}</td>
1466     <td valign="top">type of image compression</td>
1467   </tr>
1468
1469   <tr>
1470     <td valign="top">debug</td>
1471     <td valign="top">{All, Annotate, Blob, Cache, Coder, Configure, Deprecate, Draw, Exception, Locale, None, Resource, Transform, X11}</td>
1472     <td valign="top">display copious debugging information</td>
1473   </tr>
1474
1475   <tr>
1476     <td valign="top">delay</td>
1477     <td valign="top"><i>integer</i></td>
1478     <td valign="top">this many 1/100ths of a second must expire before displaying the next image in a sequence</td>
1479   </tr>
1480
1481   <tr>
1482     <td valign="top">density</td>
1483     <td valign="top"><i>geometry</i></td>
1484     <td valign="top">vertical and horizontal resolution in pixels of the image</td>
1485   </tr>
1486
1487   <tr>
1488     <td valign="top">depth</td>
1489     <td valign="top"><i>integer</i></td>
1490     <td valign="top">image depth</td>
1491   </tr>
1492
1493   <tr>
1494     <td valign="top">direction</td>
1495     <td valign="top"><i>{Undefined, right-to-left, left-to-right</i></td>
1496     <td valign="top">render text right-to-left or left-to-right</td>
1497   </tr>
1498
1499   <tr>
1500     <td valign="top">disk-limit</td>
1501     <td valign="top"><i>integer</i></td>
1502     <td valign="top">set disk resource limit</td>
1503   </tr>
1504
1505   <tr>
1506     <td valign="top">dispose</td>
1507     <td valign="top"><i>{Undefined, None, Background, Previous}</i></td>
1508     <td valign="top">layer disposal method</td>
1509   </tr>
1510
1511   <tr>
1512     <td valign="top">dither</td>
1513     <td valign="top">{True, False}</td>
1514     <td valign="top">apply error diffusion to the image</td>
1515   </tr>
1516
1517   <tr>
1518     <td valign="top">display</td>
1519     <td valign="top"><i>string</i></td>
1520     <td valign="top">specifies the X server to contact</td>
1521   </tr>
1522
1523   <tr>
1524     <td valign="top">extract</td>
1525     <td valign="top"><i>geometry</i></td>
1526     <td valign="top">extract area from image</td>
1527   </tr>
1528
1529   <tr>
1530     <td valign="top">file</td>
1531     <td valign="top"><i>filehandle</i></td>
1532     <td valign="top">set the image filehandle</td>
1533   </tr>
1534
1535   <tr>
1536     <td valign="top">filename</td>
1537     <td valign="top"><i>string</i></td>
1538     <td valign="top">set the image filename</td>
1539   </tr>
1540
1541   <tr>
1542     <td valign="top">fill</td>
1543     <td valign="top"><i>color</i></td>
1544     <td valign="top">The fill color paints any areas inside the outline of drawn shape.</td>
1545   </tr>
1546
1547   <tr>
1548     <td valign="top">font</td>
1549     <td valign="top"><i>string</i></td>
1550     <td valign="top">use this font when annotating the image with text</td>
1551   </tr>
1552
1553   <tr>
1554     <td valign="top">fuzz</td>
1555     <td valign="top"><i>integer</i></td>
1556     <td valign="top">colors within this distance are considered equal</td>
1557   </tr>
1558
1559   <tr>
1560     <td valign="top">gamma</td>
1561     <td valign="top"><i>double</i></td>
1562     <td valign="top">gamma level of the image</td>
1563   </tr>
1564
1565   <tr>
1566     <td valign="top">Gravity</td>
1567     <td valign="top">{Forget, NorthWest, North, NorthEast, West, Center, East, SouthWest, South, SouthEast}</td>
1568     <td valign="top">type of image gravity</td>
1569   </tr>
1570
1571   <tr>
1572     <td valign="top">green-primary</td>
1573     <td valign="top"><i>x-value</i>, <i>y-value</i></td>
1574     <td valign="top">chromaticity green primary point (e.g. 0.3, 0.6)</td>
1575   </tr>
1576
1577   <tr>
1578     <td valign="top">index[<i>x</i>, <i>y</i>]</td>
1579     <td valign="top"><i>string</i></td>
1580     <td valign="top">colormap index at position (<i>x</i>, <i>y</i>)</td>
1581   </tr>
1582
1583   <tr>
1584     <td valign="top">interlace</td>
1585     <td valign="top">{None, Line, Plane, Partition, JPEG, GIF, PNG}</td>
1586     <td valign="top">the type of interlacing scheme</td>
1587   </tr>
1588
1589   <tr>
1590     <td valign="top">iterations</td>
1591     <td valign="top"><i>integer</i></td>
1592     <td valign="top">add Netscape loop extension to your GIF animation</td>
1593   </tr>
1594
1595   <tr>
1596     <td valign="top">label</td>
1597     <td valign="top"><i>string</i></td>
1598     <td valign="top">set the image label</td>
1599   </tr>
1600
1601   <tr>
1602     <td valign="top">loop</td>
1603     <td valign="top"><i>integer</i></td>
1604     <td valign="top">add Netscape loop extension to your GIF animation</td>
1605   </tr>
1606
1607   <tr>
1608     <td valign="top">magick</td>
1609     <td valign="top"><i>string</i></td>
1610     <td valign="top">set the image format</td>
1611   </tr>
1612
1613   <tr>
1614     <td valign="top">map-limit</td>
1615     <td valign="top"><i>integer</i></td>
1616     <td valign="top">set map resource limit</td>
1617   </tr>
1618
1619   <tr>
1620     <td valign="top">mask</td>
1621     <td valign="top"><i>image</i></td>
1622     <td valign="top">associate a mask with the image.</td>
1623   </tr>
1624
1625   <tr>
1626     <td valign="top">matte</td>
1627     <td valign="top">{True, False}</td>
1628     <td valign="top">enable the image matte channel</td>
1629   </tr>
1630
1631   <tr>
1632     <td valign="top">mattecolor</td>
1633     <td valign="top"><i><a href="../www/color.html">color name</a></i></td>
1634     <td valign="top">set the image matte color</td>
1635   </tr>
1636
1637   <tr>
1638     <td valign="top">memory-limit</td>
1639     <td valign="top"><i>integer</i></td>
1640     <td valign="top">set memory resource limit</td>
1641   </tr>
1642
1643   <tr>
1644     <td valign="top">monochrome</td>
1645     <td valign="top">{True, False}</td>
1646     <td valign="top">transform the image to black and white</td>
1647   </tr>
1648
1649   <tr>
1650     <td valign="top">option</td>
1651     <td valign="top"><i>string</i></td>
1652     <td valign="top">associate an option with an image format (e.g.  option=&gt;'ps:imagemask'</td>
1653   </tr>
1654
1655   <tr>
1656     <td valign="top">orientation</td>
1657     <td valign="top">{top-left, top-right, bottom-right, bottom-left, left-top, right-top, right-bottom, left-bottom}</td>
1658     <td valign="top">image orientation</td>
1659   </tr>
1660
1661   <tr>
1662     <td valign="top">page</td>
1663     <td valign="top">{ Letter, Tabloid, Ledger, Legal, Statement, Executive, A3, A4, A5, B4, B5, Folio, Quarto, 10x14} or <i>geometry</i></td>
1664     <td valign="top">preferred size and location of an image canvas</td>
1665   </tr>
1666
1667   <tr>
1668     <td valign="top">pixel[<i>x</i>, <i>y</i>]</td>
1669     <td valign="top"><i>string</i></td>
1670     <td valign="top">hex value (e.g. #ccc) at position (<i>x</i>, <i>y</i>)</td>
1671   </tr>
1672
1673   <tr>
1674     <td valign="top">pointsize</td>
1675     <td valign="top"><i>integer</i></td>
1676     <td valign="top">pointsize of the Postscript or TrueType font</td>
1677   </tr>
1678
1679   <tr>
1680     <td valign="top">quality</td>
1681     <td valign="top"><i>integer</i></td>
1682     <td valign="top">JPEG/MIFF/PNG compression level</td>
1683   </tr>
1684
1685   <tr>
1686     <td valign="top">red-primary</td>
1687     <td valign="top"><i>x-value</i>, <i>y-value</i></td>
1688     <td valign="top">chromaticity red primary point (e.g. 0.64, 0.33)</td>
1689   </tr>
1690
1691   <tr>
1692     <td valign="top">sampling-factor</td>
1693     <td valign="top"><i>geometry</i></td>
1694     <td valign="top">horizontal and vertical sampling factor</td>
1695   </tr>
1696
1697   <tr>
1698     <td valign="top">scene</td>
1699     <td valign="top"><i>integer</i></td>
1700     <td valign="top">image scene number</td>
1701   </tr>
1702
1703   <tr>
1704     <td valign="top">server</td>
1705     <td valign="top"><i>string</i></td>
1706     <td valign="top">specifies the X server to contact</td>
1707   </tr>
1708
1709   <tr>
1710     <td valign="top">size</td>
1711     <td valign="top"><i>string</i></td>
1712     <td valign="top">width and height of a raw image</td>
1713   </tr>
1714
1715   <tr>
1716     <td valign="top">stroke</td>
1717     <td valign="top"><i>color</i></td>
1718     <td valign="top">The stroke color paints along the outline of a shape.</td>
1719   </tr>
1720
1721   <tr>
1722     <td valign="top">texture</td>
1723     <td valign="top"><i>string</i></td>
1724     <td valign="top">name of texture to tile onto the image background</td>
1725   </tr>
1726
1727   <tr>
1728     <td valign="top">tile-offset</td>
1729     <td valign="top"><i>geometry</i></td>
1730     <td valign="top">image tile offset</td>
1731   </tr>
1732
1733   <tr>
1734     <td valign="top">time-limit</td>
1735     <td valign="top"><i>integer</i></td>
1736     <td valign="top">set time resource limit in seconds</td>
1737   </tr>
1738
1739   <tr>
1740     <td valign="top">type</td>
1741     <td valign="top">{Bilevel, Grayscale, GrayscaleMatte, Palette, PaletteMatte, TrueColor, TrueColorMatte, ColorSeparation, ColorSeparationMatte}</td>
1742     <td valign="top">image type</td>
1743   </tr>
1744
1745   <tr>
1746     <td valign="top">units</td>
1747     <td valign="top">{ Undefined, PixelsPerInch, PixelsPerCentimeter}</td>
1748     <td valign="top">units of image resolution</td>
1749   </tr>
1750
1751   <tr>
1752     <td valign="top">verbose</td>
1753     <td valign="top">{True, False}</td>
1754     <td valign="top">print detailed information about the image</td>
1755   </tr>
1756
1757   <tr>
1758     <td valign="top">virtual-pixel</td>
1759     <td valign="top">{Background Black Constant Dither Edge Gray Mirror Random Tile Transparent White}</td>
1760     <td valign="top">the virtual pixel method</td>
1761   </tr>
1762
1763   <tr>
1764     <td valign="top">white-point</td>
1765     <td valign="top"><i>x-value</i>, <i>y-value</i></td>
1766     <td valign="top">chromaticity white point (e.g. 0.3127, 0.329)</td>
1767   </tr>
1768   </tbody>
1769 </table>
1770
1771 <p>Note, that the <kbd>geometry</kbd> parameter is a short cut for the <kbd>width</kbd> and <kbd>height</kbd> parameters (e.g.  <kbd>geometry=&gt;'106x80'</kbd> is equivalent to <kbd>width=&gt;106, height=&gt;80</kbd>).</p>
1772
1773 <p>SetAttribute() is an alias for method Set().</p>
1774
1775 <p>Most of the attributes listed above have an analog in
1776 <a href="../www/convert.html">convert</a>. See the documentation for a more detailed description of these attributes.</p>
1777
1778 </div>
1779
1780 <h2><a id="get-attribute"></a>Get an Image Attribute</h2>
1781 <div class="doc-section">
1782
1783 <p>Use method Get() to get an image attribute. For example,</p>
1784
1785 <pre class="code">
1786   ($a, $b, $c) = $image-&gt;Get('colorspace', 'magick', 'adjoin');
1787   $width = $image-&gt;[3]-&gt;Get('columns');
1788 </pre>
1789
1790 <p>In addition to all the attributes listed in <a href="#set-attribute">Set an Image Attribute</a> , you can get these additional attributes:</p>
1791
1792 <table class="doc">
1793   <caption>Image Attributes</caption>
1794   <tbody>
1795   <tr>
1796     <th>Attribute</th>
1797     <th>Values</th>
1798     <th style="width: 60%">Description</th>
1799   </tr>
1800
1801   <tr>
1802     <td valign="top">area</td>
1803     <td valign="top"><i>integer</i></td>
1804     <td valign="top">current area resource consumed</td>
1805   </tr>
1806
1807   <tr>
1808     <td valign="top">base-columns</td>
1809     <td valign="top"><i>integer</i></td>
1810     <td valign="top">base image width (before transformations)</td>
1811   </tr>
1812
1813   <tr>
1814     <td valign="top">base-filename</td>
1815     <td valign="top"><i>string</i></td>
1816     <td valign="top">base image filename (before transformations)</td>
1817   </tr>
1818
1819   <tr>
1820     <td valign="top">base-rows</td>
1821     <td valign="top"><i>integer</i></td>
1822     <td valign="top">base image height (before transformations)</td>
1823   </tr>
1824
1825   <tr>
1826     <td valign="top">class</td>
1827     <td valign="top">{Direct, Pseudo}</td>
1828     <td valign="top">image class</td>
1829   </tr>
1830
1831   <tr>
1832     <td valign="top">colors</td>
1833     <td valign="top"><i>integer</i></td>
1834     <td valign="top">number of unique colors in the image</td>
1835   </tr>
1836
1837   <tr>
1838     <td valign="top">columns</td>
1839     <td valign="top"><i>integer</i></td>
1840     <td valign="top">image width</td>
1841   </tr>
1842
1843   <tr>
1844     <td valign="top">copyright</td>
1845     <td valign="top"><i>string</i></td>
1846     <td valign="top">get PerlMagick's copyright</td>
1847   </tr>
1848
1849   <tr>
1850     <td valign="top">directory</td>
1851     <td valign="top"><i>string</i></td>
1852     <td valign="top">tile names from within an image montage</td>
1853   </tr>
1854
1855   <tr>
1856     <td valign="top">elapsed-time</td>
1857     <td valign="top"><i>double</i></td>
1858     <td valign="top">elapsed time in seconds since the image was created</td>
1859   </tr>
1860
1861   <tr>
1862     <td valign="top">error</td>
1863     <td valign="top"><i>double</i></td>
1864     <td valign="top">the mean error per pixel computed with methods Compare() or Quantize()</td>
1865   </tr>
1866
1867   <tr>
1868     <td valign="top">bounding-box</td>
1869     <td valign="top"><i>string</i></td>
1870     <td valign="top">image bounding box</td>
1871   </tr>
1872
1873   <tr>
1874     <td valign="top">disk</td>
1875     <td valign="top"><i>integer</i></td>
1876     <td valign="top">current disk resource consumed</td>
1877   </tr>
1878
1879   <tr>
1880     <td valign="top">filesize</td>
1881     <td valign="top"><i>integer</i></td>
1882     <td valign="top">number of bytes of the image on disk</td>
1883   </tr>
1884
1885   <tr>
1886     <td valign="top">format</td>
1887     <td valign="top"><i>string</i></td>
1888     <td valign="top">get the descriptive image format</td>
1889   </tr>
1890
1891   <tr>
1892     <td valign="top">geometry</td>
1893     <td valign="top"><i>string</i></td>
1894     <td valign="top">image geometry</td>
1895   </tr>
1896
1897   <tr>
1898     <td valign="top">height</td>
1899     <td valign="top"><i>integer</i></td>
1900     <td valign="top">the number of rows or height of an image</td>
1901   </tr>
1902
1903   <tr>
1904     <td valign="top">id</td>
1905     <td valign="top"><i>integer</i></td>
1906     <td valign="top">ImageMagick registry id</td>
1907   </tr>
1908
1909   <tr>
1910     <td valign="top">mean-error</td>
1911     <td valign="top"><i>double</i></td>
1912     <td valign="top">the normalized mean error per pixel computed with methods Compare() or Quantize()</td>
1913   </tr>
1914
1915   <tr>
1916     <td valign="top">map</td>
1917     <td valign="top"><i>integer</i></td>
1918     <td valign="top">current memory-mapped resource consumed</td>
1919   </tr>
1920
1921   <tr>
1922     <td valign="top">matte</td>
1923     <td valign="top">{True, False}</td>
1924     <td valign="top">whether or not the image has a matte channel</td>
1925   </tr>
1926
1927   <tr>
1928     <td valign="top">maximum-error</td>
1929     <td valign="top"><i>double</i></td>
1930     <td valign="top">the normalized max error per pixel computed with methods Compare() or Quantize()</td>
1931   </tr>
1932
1933   <tr>
1934     <td valign="top">memory</td>
1935     <td valign="top"><i>integer</i></td>
1936     <td valign="top">current memory resource consumed</td>
1937   </tr>
1938
1939   <tr>
1940     <td valign="top">mime</td>
1941     <td valign="top"><i>string</i></td>
1942     <td valign="top">MIME of the image format</td>
1943   </tr>
1944
1945   <tr>
1946     <td valign="top">montage</td>
1947     <td valign="top"><i>geometry</i></td>
1948     <td valign="top">tile size and offset within an image montage</td>
1949   </tr>
1950
1951   <tr>
1952     <td valign="top">page.x</td>
1953     <td valign="top"><i>integer</i></td>
1954     <td valign="top">x offset of image virtual canvas</td>
1955   </tr>
1956
1957   <tr>
1958     <td valign="top">page.y</td>
1959     <td valign="top"><i>integer</i></td>
1960     <td valign="top">y offset of image virtual canvas</td>
1961   </tr>
1962
1963   <tr>
1964     <td valign="top">rows</td>
1965     <td valign="top"><i>integer</i></td>
1966     <td valign="top">the number of rows or height of an image</td>
1967   </tr>
1968
1969   <tr>
1970     <td valign="top">signature</td>
1971     <td valign="top"><i>string</i></td>
1972     <td valign="top">SHA-256 message digest associated with the image pixel stream</td>
1973   </tr>
1974
1975   <tr>
1976     <td valign="top">taint</td>
1977     <td valign="top">{True, False}</td>
1978     <td valign="top">True if the image has been modified</td>
1979   </tr>
1980
1981   <tr>
1982     <td valign="top">total-ink-density</td>
1983     <td valign="top"><i>double</i></td>
1984     <td valign="top">returns the total ink density for a CMYK image</td>
1985   </tr>
1986
1987   <tr>
1988     <td valign="top">transparent-color</td>
1989     <td valign="top"><i><a href="../www/color.html">color name</a></i></td>
1990     <td valign="top">set the image transparent color</td>
1991   </tr>
1992
1993   <tr>
1994     <td valign="top">user-time</td>
1995     <td valign="top"><i>double</i></td>
1996     <td valign="top">user time in seconds since the image was created</td>
1997   </tr>
1998
1999   <tr>
2000     <td valign="top">version</td>
2001     <td valign="top"><i>string</i></td>
2002     <td valign="top">get PerlMagick's version</td>
2003   </tr>
2004
2005   <tr>
2006     <td valign="top">width</td>
2007     <td valign="top"><i>integer</i></td>
2008     <td valign="top">the number of columns or width of an image</td>
2009   </tr>
2010
2011   <tr>
2012     <td valign="top">x-resolution</td>
2013     <td valign="top"><i>integer</i></td>
2014     <td valign="top">x resolution of the image</td>
2015   </tr>
2016
2017   <tr>
2018     <td valign="top">y-resolution</td>
2019     <td valign="top"><i>integer</i></td>
2020     <td valign="top">y resolution of the image</td>
2021   </tr>
2022   </tbody>
2023 </table>
2024
2025 <p>GetAttribute() is an alias for method Get().</p>
2026
2027 <p>Most of the attributes listed above have an analog in
2028 <a href="../www/convert.html">convert</a>. See the documentation for a more detailed description of these attributes.</p>
2029
2030 </div>
2031
2032 <h2><a id="compare"></a>Compare an Image to its Reconstruction</h2>
2033 <div class="doc-section">
2034 </div>
2035
2036 <p>Mathematically and visually annotate the difference between an image and its reconstruction with the Compare() method.  The method supports these parameters:</p>
2037
2038 <table class="doc">
2039   <caption>Compare Parameters</caption>
2040   <tbody>
2041   <tr>
2042     <th>Parameter</th>
2043     <th style="width: 40%">Values</th>
2044     <th style="width: 40%">Description</th>
2045   </tr>
2046
2047   <tr>
2048     <td valign="top">channel</td>
2049     <td valign="top"><i>double</i></td>
2050     <td valign="top">select image channels, the default is all channels except alpha.</td>
2051   </tr>
2052
2053   <tr>
2054     <td valign="top">fuzz</td>
2055     <td valign="top"><i>double</i></td>
2056     <td valign="top">colors within this distance are considered equal</td>
2057   </tr>
2058
2059   <tr>
2060     <td valign="top">image</td>
2061     <td valign="top"><i>image-reference</i></td>
2062     <td valign="top">the image reconstruction</td>
2063   </tr>
2064
2065   <tr>
2066     <td valign="top">metric</td>
2067     <td valign="top">AE, MAE, MEPP, MSE, PAE, PSNR, RMSE</td>
2068     <td valign="top">measure differences between images with this metric</td>
2069   </tr>
2070   </tbody>
2071 </table>
2072
2073 <p>In this example, we compare the ImageMagick logo to a sharpened reconstruction:</p>
2074
2075 <pre class="code">
2076   use Image::Magick;
2077
2078   $logo=Image::Magick->New();
2079   $logo->Read('logo:');
2080   $sharp=Image::Magick->New();
2081   $sharp->Read('logo:');
2082   $sharp->Sharpen('0x1');
2083   $difference=$logo->Compare(image=>$sharp, metric=>'rmse');
2084   print $difference->Get('error'), "\n";
2085   $difference->Display();
2086 </pre>
2087
2088 <p>In addition to the reported root mean squared error of around 0.024, a difference image is displayed so you can visually identify the difference between the images.</p>
2089
2090 <h2><a id="montage"></a>Create an Image Montage</h2>
2091 <div class="doc-section">
2092
2093 <p>Use method Montage() to create a composite image by combining several separate images. The images are tiled on the composite image with the name of the image optionally appearing just below the individual tile. For example,</p>
2094
2095 <pre class="code">
2096   $image-&gt;Montage(geometry=&gt;'160x160', tile=&gt;'2x2', texture=&gt;'granite:');
2097 </pre>
2098
2099 <p>And here is a list of Montage() parameters you can set:</p>
2100
2101 <table class="doc">
2102   <caption>Montage Parameters</caption>
2103   <tbody>
2104   <tr>
2105     <th>Parameter</th>
2106     <th style="width: 40%">Values</th>
2107     <th style="width: 40%">Description</th>
2108   </tr>
2109
2110   <tr>
2111     <td valign="top">background</td>
2112     <td valign="top"><i><a href="../www/color.html">color name</a></i></td>
2113     <td valign="top">background color name</td>
2114   </tr>
2115
2116   <tr>
2117     <td valign="top">border</td>
2118     <td valign="top"><i>integer</i></td>
2119     <td valign="top">image border width</td>
2120   </tr>
2121
2122   <tr>
2123     <td valign="top">filename</td>
2124     <td valign="top"><i>string</i></td>
2125     <td valign="top">name of montage image</td>
2126   </tr>
2127
2128   <tr>
2129     <td valign="top">fill</td>
2130     <td valign="top"><a href="../www/color.html">color name</a></td>
2131     <td valign="top">fill color for annotations</td>
2132   </tr>
2133
2134   <tr>
2135     <td valign="top">font</td>
2136     <td valign="top"><i>string</i></td>
2137     <td valign="top">X11 font name</td>
2138   </tr>
2139
2140   <tr>
2141     <td valign="top">frame</td>
2142     <td valign="top"><i>geometry</i></td>
2143     <td valign="top">surround the image with an ornamental border</td>
2144   </tr>
2145
2146   <tr>
2147     <td valign="top">geometry</td>
2148     <td valign="top"><i>geometry</i></td>
2149     <td valign="top">preferred tile and border size of each tile of the composite
2150 image (e.g. 120x120+4+3>)</td>
2151   </tr>
2152
2153   <tr>
2154     <td valign="top">gravity</td>
2155     <td valign="top">NorthWest, North, NorthEast, West, Center, East, SouthWest,
2156 South, SouthEast</td>
2157     <td valign="top">direction image gravitates to within a tile</td>
2158   </tr>
2159
2160   <tr>
2161     <td valign="top">label</td>
2162     <td valign="top"><i>string</i></td>
2163     <td valign="top">assign a label to an image</td>
2164   </tr>
2165
2166   <tr>
2167     <td valign="top">mode</td>
2168     <td valign="top">Frame, Unframe, Concatenate</td>
2169     <td valign="top">thumbnail framing options</td>
2170   </tr>
2171
2172   <tr>
2173     <td valign="top">pointsize</td>
2174     <td valign="top"><i>integer</i></td>
2175     <td valign="top">pointsize of the Postscript or TrueType font</td>
2176   </tr>
2177
2178   <tr>
2179     <td valign="top">shadow</td>
2180     <td valign="top">{True, False}</td>
2181     <td valign="top">add a shadow beneath a tile to simulate depth</td>
2182   </tr>
2183
2184   <tr>
2185     <td valign="top">stroke</td>
2186     <td valign="top"><a href="../www/color.html">color name</a></td>
2187     <td valign="top">stroke color for annotations</td>
2188   </tr>
2189
2190   <tr>
2191     <td valign="top">texture</td>
2192     <td valign="top"><i>string</i></td>
2193     <td valign="top">name of texture to tile onto the image background</td>
2194   </tr>
2195
2196   <tr>
2197     <td valign="top">tile</td>
2198     <td valign="top"><i>geometry</i></td>
2199     <td valign="top">the number of tiles per row and page (e.g. 6x4)</td>
2200   </tr>
2201
2202   <tr>
2203     <td valign="top">title</td>
2204     <td valign="top">string</td>
2205     <td valign="top">assign a title to the image montage</td>
2206   </tr>
2207
2208   <tr>
2209     <td valign="top">transparent</td>
2210     <td valign="top"><i>string</i></td>
2211     <td valign="top">make this color transparent within the image</td>
2212   </tr>
2213   </tbody>
2214 </table>
2215
2216 <p>Note, that the <kbd>geometry</kbd> parameter is a short cut for the <kbd>width</kbd> and <kbd>height</kbd> parameters (e.g.  <kbd>geometry=&gt;'106x80'</kbd> is equivalent to <kbd>width=&gt;106, height=&gt;80</kbd>).</p>
2217
2218 <p>MontageImage() is an alias for method Montage().</p>
2219
2220 <p>Most of the attributes listed above have an analog in <a href="../www/montage.html">montage</a>. See the documentation for a more detailed description of these attributes.</p>
2221
2222 </div>
2223
2224 <h2><a id="blobs"></a>Working with Blobs</h2>
2225 <div class="doc-section">
2226
2227 <p>A blob contains data that directly represent a particular image
2228 format in memory instead of on disk. PerlMagick supports
2229 blobs in any of these image <a href="../www/formats.html">formats</a> and provides methods to convert a blob to or from a particular image format.</p>
2230
2231 <table class="doc">
2232   <caption>Blob Methods</caption>
2233   <tbody>
2234   <tr>
2235     <th>Method</th>
2236     <th>Parameters</th>
2237     <th>Return Value</th>
2238     <th>Description</th>
2239   </tr>
2240
2241   <tr>
2242     <td valign="top">ImageToBlob</td>
2243     <td valign="top">any image <a href="#set-attribute">attribute</a></td>
2244     <td valign="top">an array of image data in the respective image format</td>
2245     <td valign="top">convert an image or image sequence to an array of blobs</td>
2246   </tr>
2247
2248   <tr>
2249     <td valign="top">BlobToImage</td>
2250     <td valign="top">one or more blobs</td>
2251     <td valign="top">the number of blobs converted to an image</td>
2252     <td valign="top">convert one or more blobs to an image</td>
2253   </tr>
2254   </tbody>
2255 </table>
2256
2257 <p>ImageToBlob() returns the image data in their respective formats. You can then print it, save it to an ODBC database, write it to a file, or pipe it to a display program:</p>
2258
2259 <pre class="code">
2260   @blobs = $image-&gt;ImageToBlob();
2261   open(DISPLAY,"| display -") || die;
2262   binmode DISPLAY;
2263   print DISPLAY $blobs[0];
2264   close DISPLAY;
2265 </pre>
2266
2267 <p>Method BlobToImage() returns an image or image sequence converted from the supplied blob:</p>
2268
2269 <pre class="code">
2270   @blob=$db-&gt;GetImage();
2271   $image=Image::Magick-&gt;new(magick=&gt;'jpg');
2272   $image-&gt;BlobToImage(@blob);
2273 </pre>
2274
2275 </div>
2276
2277 <h2><a id="direct-access"></a>Direct-access to Image Pixels</h2>
2278 <div class="doc-section">
2279
2280 <p>Use these methods to obtain direct access to the image pixels:</p>
2281
2282 <table class="doc">
2283 <caption>Direct-access to Image Pixels</caption>
2284 <tbody>
2285   <tr>
2286     <th>Method</th>
2287     <th>Parameters</th>
2288     <th style="width: 50%">Description</th>
2289   </tr>
2290
2291   <tr>
2292     <td valign="top">GetAuthenticPixels</td>
2293     <td valign="top">geometry=&gt;<i>geometry</i>, width=&gt;<i>integer</i>, height=&gt;<i>integer</i>, x=&gt;<i>integer</i>, y=&gt;<i>integer</i></td>
2294     <td valign="top">return image pixels as a C pointer</td>
2295   </tr>
2296
2297   <tr>
2298     <td valign="top">GetVirtualPixels</td>
2299     <td valign="top">geometry=&gt;<i>geometry</i>, width=&gt;<i>integer</i>, height=&gt;<i>integer</i>, x=&gt;<i>integer</i>, y=&gt;<i>integer</i></td>
2300     <td valign="top">return image pixels as a const C pointer</td>
2301   </tr>
2302
2303   <tr>
2304     <td valign="top">GetAuthenticIndexQueue</td>
2305     <td valign="top"></td>
2306     <td valign="top">return image indexes as a C pointer</td>
2307   </tr>
2308
2309   <tr>
2310     <td valign="top">GetVirtualIndexQueue</td>
2311     <td valign="top"></td>
2312     <td valign="top">return image indexes as a const C pointer</td>
2313   </tr>
2314
2315   <tr>
2316     <td valign="top">SyncAuthenticPixels</td>
2317     <td valign="top"></td>
2318     <td valign="top">sync image pixels to pixel cache</td>
2319   </tr>
2320
2321 </tbody>
2322 </table>
2323
2324 </div>
2325
2326 <h2><a id="miscellaneous"></a>Miscellaneous Methods</h2>
2327 <div class="doc-section">
2328
2329 <p>The Append() method append a set of images. For example,</p>
2330
2331 <pre class="code">
2332   $p = $image-&gt;Append(stack=&gt;{true,false});
2333 </pre>
2334
2335 <p>appends all the images associated with object <kbd>$image</kbd>. By default, images are stacked left-to-right. Set <kbd>stack</kbd> to True to stack them top-to-bottom.</p>
2336
2337 <p>The Clone() method copies a set of images. For example,</p>
2338
2339 <pre class="code">
2340   $q = $p-&gt;Clone();
2341 </pre>
2342
2343 <p>copies all the images from object <kbd>$p</kbd> to <kbd>$q</kbd>. You can use this method for single or multi-image sequences.</p>
2344
2345 <p>The EvaluateImages() method applies an arithemtic, logical or relational expression to a set of images. For example,</p>
2346
2347 <pre class="code">
2348   $p = $image-&gt;EvaluateImages('mean');
2349 </pre>
2350
2351 <p>averages all the images associated with object <kbd>$image</kbd>.</p>
2352
2353 <p>The Features() method returns features for each channel in the image in each of four directions (horizontal, vertical, left and right diagonals) for the specified distance.  The features include the angular second momentum, contrast, correlation, sum of squares: variance, inverse difference moment, sum average, sum varience, sum entropy, entropy, difference variance, difference entropy, information measures of correlation 1, information measures of correlation 2, and maximum correlation coefficient.  Values in RGB, CMYK, RGBA, or CMYKA order (depending on the image type).</p>
2354
2355 <pre class="code">
2356   @features = $image-&gt;Features(1);
2357 </pre>
2358
2359 <p>Finally, the Transform() method accepts a fully-qualified geometry specification for cropping or resizing one or more images.  For example,</p>
2360
2361 <p>The Flatten() method flattens a set of images and returns it. For example,</p>
2362
2363 <pre class="code">
2364   $p = $images-&gt;Flatten(background=&gt;'none');
2365   $p-&gt;Write('flatten.png');
2366 </pre>
2367
2368 <p>The sequence of images is replaced by a single image created by composing each image after the first over the first image.</p>
2369
2370 <p>The Fx() method applies a mathematical expression to a set of images and returns the results. For example,</p>
2371
2372 <pre class="code">
2373   $p = $image-&gt;Fx(expression=&gt;'(g+b)/2.0',channel=&gt;'red');
2374   $p-&gt;Write('fx.miff');
2375 </pre>
2376
2377 <p>replaces the red channel with the average of the green and blue channels.</p>
2378
2379 <p>See <a href="../www/fx.html">FX, The Special Effects Image Operator</a> for a detailed discussion of this method.</p>
2380
2381 <p>Histogram() returns the unique colors in the image and a count for each one. The returned values are an array of red, green, blue, opacity, and count values.</p>
2382
2383 <p>The Morph() method morphs a set of images. Both the image pixels and size are linearly interpolated to give the appearance of a meta-morphosis from one image to the next:</p>
2384
2385 <pre class="code">
2386   $p = $image-&gt;Morph(frames=&gt;<i>integer</i>);
2387 </pre>
2388
2389 <p>where <i>frames</i> is the number of in-between images to generate.  The default is 1.</p>
2390
2391 <p>Mosaic() creates an mosaic from an image sequence.</p>
2392
2393 <p>Method Mogrify() is a single entry point for the image manipulation methods (<a href="#manipulate">Manipulate an Image</a>). The parameters are the name of a method followed by any parameters the method may require. For example, these calls are equivalent:</p>
2394
2395 <pre class="code">
2396   $image-&gt;Crop('340x256+0+0');
2397   $image-&gt;Mogrify('crop', '340x256+0+0');
2398 </pre>
2399
2400 <p>Method MogrifyRegion() applies a transform to a region of the image. It is similar to Mogrify() but begins with the region geometry. For example, suppose you want to brighten a 100x100 region of your image at location (40, 50):</p>
2401
2402 <pre class="code">
2403   $image-&gt;MogrifyRegion('100x100+40+50', 'modulate', brightness=&gt;50);
2404 </pre>
2405
2406 <p>Ping() is a convenience method that returns information about an image without having to read the image into memory. It returns the width, height, file size in bytes, and the file format of the image. You can specify more than one filename but only one filehandle:</p>
2407
2408 <pre class="code">
2409   ($width, $height, $size, $format) = $image-&gt;Ping('logo.png');
2410   ($width, $height, $size, $format) = $image-&gt;Ping(file=&gt;\*IMAGE);
2411   ($width, $height, $size, $format) = $image-&gt;Ping(blob=&gt;$blob);
2412 </pre>
2413
2414 <p>This a more efficient and less memory intensive way to query if an image exists and what its characteristics are.  <kbd>PreviewImage()</kbd> tiles 9 thumbnails of the specified image with an image processing operation applied at varying strengths. This may be helpful pin-pointing an appropriate parameter for a particular image processing operation. Choose from these operations: <kbd>Rotate, Shear, Roll, Hue, Saturation, Brightness, Gamma, Spiff, Dull, Grayscale, Quantize, Despeckle, ReduceNoise, AddNoise, Sharpen, Blur, Threshold, EdgeDetect, Spread, Solarize, Shade, Raise, Segment, Swirl, Implode, Wave, OilPaint, CharcoalDrawing, JPEG</kbd>. Here is an example:</p>
2415
2416 <pre class="code">
2417   $preview = $image-&gt;Preview('Gamma');
2418   $preview-&gt;Display();
2419 </pre>
2420
2421 <p>To have full control over text positioning you need font metric information. Use</p>
2422
2423 <pre class="code">
2424   ($x_ppem, $y_ppem, $ascender, $descender, $width, $height, $max_advance)
2425          = $image-&gt;QueryFontMetrics(<i>parameters</i>);
2426 </pre>
2427
2428 <p>Where <i>parameters</i> is any parameter of the <a href="#manipulate">Annotate</a> method. The return values are:</p>
2429
2430 <ul>
2431   <li>character width</li>
2432   <li>character height</li>
2433   <li>ascender</li>
2434   <li>descender</li>
2435   <li>text width</li>
2436   <li>text height</li>
2437   <li>maximum horizontal advance</li>
2438   <li>bounds: x1</li>
2439   <li>bounds: y1</li>
2440   <li>bounds: x2</li>
2441   <li>bounds: y2</li>
2442   <li>origin: x</li>
2443   <li>origin: y</li>
2444 </ul>
2445
2446 <p>Use QueryMultilineFontMetrics() to get the maximum text width and height for multiple lines of text.</p>
2447
2448 <p>Call QueryColor() with no parameters to return a list of known colors names or specify one or more color names to get these attributes: red, green, blue, and opacity value.</p>
2449
2450 <pre class="code">
2451   @colors = $image-&gt;QueryColor();
2452   ($red, $green, $blue, $opacity) = $image-&gt;QueryColor('cyan');
2453   ($red, $green, $blue, $opacity) = $image-&gt;QueryColor('#716bae');
2454 </pre>
2455
2456 <p>QueryColorname() accepts a color value and returns its respective name or hex value;</p>
2457
2458 <pre class="code">
2459     $name = $image-&gt;QueryColorname('rgba(80,60,0,0)');
2460 </pre>
2461
2462 <p>Call QueryFont() with no parameters to return a list of known fonts or specify one or more font names to get these attributes: font name, description, family, style, stretch, weight, encoding, foundry, format, metrics, and glyphs values.</p>
2463
2464 <pre class="code">
2465   @fonts = $image-&gt;QueryFont();
2466   $weight = ($image-&gt;QueryFont('Helvetica'))[5];
2467 </pre>
2468
2469 <p>Call QueryFormat() with no parameters to return a list of known image formats or specify one or more format names to get these attributes: adjoin, blob support, raw, decoder, encoder, description, and module.</p>
2470
2471 <pre class="code">
2472   @formats = $image-&gt;QueryFormat();
2473   ($adjoin, $blob_support, $raw, $decoder, $encoder, $description, $module)
2474             = $image-&gt;QueryFormat('gif');
2475 </pre>
2476
2477 <p>Call MagickToMime() with the image format name to get its MIME type such as <kbd>images/tiff</kbd> from <kbd>tif</kbd>.</p>
2478
2479 <pre class="code">
2480   $mime = $image-&gt;MagickToMime('tif');
2481 </pre>
2482
2483 <p>Use RemoteCommand() to send a command to an already running <a href="../www/display.html">display</a> or <a href="../www/animate.html">animate</a> application. The only parameter is the name of the image file to display or animate.</p>
2484
2485 <pre class="code">
2486   $image-&gt;RemoteCommand('image.jpg');
2487 </pre>
2488
2489 <p>The Smush() method smushes a set of images together. For example,</p>
2490
2491 <pre class="code">
2492   $p = $image-&gt;Smush(stack=&gt;{true,false},offset=&gt;<em>integer</em>);
2493 </pre>
2494
2495 <p>smushes together all the images associated with object <kbd>$image</kbd>. By default, images are smushed left-to-right. Set <kbd>stack</kbd> to True to smushed them top-to-bottom.</p>
2496
2497 <p>Statistics() returns the image statistics for each channel in the image. The returned values are an array of depth, minima, maxima, mean, standard deviation, kurtosis, and skewness values in RGB, CMYK, RGBA, or CMYKA order (depending on the image type).</p>
2498
2499 <pre class="code">
2500   @statistics = $image-&gt;Statistics();
2501 </pre>
2502
2503 <p>Finally, the Transform() method accepts a fully-qualified geometry specification for cropping or resizing one or more images.  For example,</p>
2504
2505 <pre class="code">
2506   $p = $image-&gt;Transform(crop=&gt;'100x100+0+0', gravity=&gt;'Center');
2507 </pre>
2508
2509 <p>You can optionally add <i>Image</i> to any method name above. For example, PingImage() is an alias for method Ping().</p>
2510
2511 </div>
2512
2513 <h2><a id="exceptions"></a>Handling Exceptions</h2>
2514 <div class="doc-section">
2515
2516 <p>All PerlMagick methods return an undefined string context upon success. If any problems occur, the error is returned as a string with an embedded numeric status code. A status code less than 400 is a warning. This means that the operation did not complete but was recoverable to some degree. A numeric code greater or equal to 400 is an error and indicates the operation failed completely. Here is how exceptions are returned for the different methods:</p>
2517
2518 <p>Methods which return a number (e.g. Read(), Write()):</p>
2519
2520 <pre class="code">
2521   $x = $image-&gt;Read(...);
2522   warn "$x" if "$x";      # print the error message
2523   $x =~ /(\d+)/;
2524   print $1;               # print the error number
2525   print 0+$x;             # print the number of images read
2526 </pre>
2527
2528 <p>Methods which operate on an image (e.g. Resize(), Crop()):</p>
2529
2530 <pre class="code">
2531   $x = $image-&gt;Crop(...);
2532   warn "$x" if "$x";      # print the error message
2533   $x =~ /(\d+)/;
2534   print $1;               # print the error number
2535 </pre>
2536
2537 <p>Methods which return images (EvaluateSequence(), Montage(), Clone()) should be checked for errors this way:</p>
2538
2539 <pre class="code">
2540   $x = $image-&gt;Montage(...);
2541   warn "$x" if !ref($x);  # print the error message
2542   $x =~ /(\d+)/;
2543   print $1;               # print the error number
2544 </pre>
2545
2546 <p>Here is an example error message:</p>
2547
2548 <pre class="code">
2549   Error 400: Memory allocation failed
2550 </pre>
2551
2552 <p>Review the complete list of <a href="../www/exception.html">error and warning codes</a>.</p>
2553
2554 <p>The following illustrates how you can use a numeric status code:</p>
2555
2556 <pre class="code">
2557   $x = $image-&gt;Read('rose.png');
2558   $x =~ /(\d+)/;
2559   die "unable to continue" if ($1 == ResourceLimitError);
2560 </pre>
2561
2562 </div>
2563
2564 <h2><a id="constants"></a>Constants</h2>
2565 <div class="doc-section">
2566
2567 <p>PerlMagick includes these constants:</p>
2568
2569 <pre class="text">
2570   BlobError
2571   BlobWarning
2572   CacheError
2573   CacheWarning
2574   CoderError
2575   CoderWarning
2576   ConfigureError
2577   ConfigureWarning
2578   CorruptImageError
2579   CorruptImageWarning
2580   DelegateError
2581   DelegateWarning
2582   DrawError
2583   DrawWarning
2584   ErrorException
2585   FatalErrorException
2586   FileOpenError
2587   FileOpenWarning
2588   ImageError
2589   ImageWarning
2590   MissingDelegateError
2591   MissingDelegateWarning
2592   ModuleError
2593   ModuleWarning
2594   Opaque
2595   OptionError
2596   OptionWarning
2597   QuantumDepth
2598   QuantumRange
2599   RegistryError
2600   RegistryWarning
2601   ResourceLimitError
2602   ResourceLimitWarning
2603   StreamError
2604   StreamWarning
2605   Success
2606   Transparent
2607   TypeError
2608   TypeWarning
2609   WarningException
2610   XServerError
2611   XServerWarning
2612 </pre>
2613
2614 <p>You can access them like this:</p>
2615
2616 <pre class="code">
2617   Image::Magick-&gt;QuantumDepth
2618 </pre>
2619
2620 </div>
2621 \r
2622 </div>\r
2623 \r
2624 <div id="linkbar">\r
2625     <span id="linkbar-west">&nbsp;</span>\r
2626     <span id="linkbar-center">\r
2627       <a href="http://www.imagemagick.org/discourse-server/">Discourse Server</a> &bull;\r
2628       <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Studio</a>\r
2629     </span>\r
2630     <span id="linkbar-east">&nbsp;</span>\r
2631   </div>\r
2632   <div class="footer">\r
2633     <span id="footer-west">&copy; 1999-2011 ImageMagick Studio LLC</span>\r
2634     <span id="footer-east"> <a href="http://www.imagemagick.org/script/contact.php">Contact the Wizards</a></span>\r
2635   </div>\r
2636   <div style="clear: both; margin: 0; width: 100%; "></div>\r
2637   <script type="text/javascript">\r
2638     var _gaq = _gaq || [];\r
2639     _gaq.push(['_setAccount', 'UA-17690367-1']);\r
2640     _gaq.push(['_trackPageview']);\r
2641 \r
2642     (function() {\r
2643       var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;\r
2644       ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';\r
2645       var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);\r
2646     })();\r
2647   </script>\r
2648 </body>\r
2649 </html>\r