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

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