github.com/kaydxh/golang@v0.0.131/pkg/gocv/cgo/third_path/graphics-magick/share/doc/GraphicsMagick/www/perl.html (about) 1 <?xml version="1.0" encoding="utf-8" ?> 2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> 6 <meta name="generator" content="Docutils 0.15.2: http://docutils.sourceforge.net/" /> 7 <title>GraphicsMagick Perl API -- PerlMagick</title> 8 <link rel="stylesheet" href="docutils-articles.css" type="text/css" /> 9 </head> 10 <body> 11 12 <div class="banner"> 13 <img src="images/gm-107x76.png" alt="GraphicMagick logo" width="107" height="76" /> 14 <span class="title">GraphicsMagick</span> 15 <form action="http://www.google.com/search"> 16 <input type="hidden" name="domains" value="www.graphicsmagick.org" /> 17 <input type="hidden" name="sitesearch" value="www.graphicsmagick.org" /> 18 <span class="nowrap"><input type="text" name="q" size="25" maxlength="255" /> <input type="submit" name="sa" value="Search" /></span> 19 </form> 20 </div> 21 22 <div class="navmenu"> 23 <ul> 24 <li><a href="index.html">Home</a></li> 25 <li><a href="project.html">Project</a></li> 26 <li><a href="download.html">Download</a></li> 27 <li><a href="README.html">Install</a></li> 28 <li><a href="Hg.html">Source</a></li> 29 <li><a href="NEWS.html">News</a> </li> 30 <li><a href="utilities.html">Utilities</a></li> 31 <li><a href="programming.html">Programming</a></li> 32 <li><a href="reference.html">Reference</a></li> 33 </ul> 34 </div> 35 <div class="document" id="graphicsmagick-perl-api-perlmagick"> 36 <h1 class="title">GraphicsMagick Perl API -- PerlMagick</h1> 37 38 <!-- -*- mode: rst -*- --> 39 <!-- This text is in reStucturedText format, so it may look a bit odd. --> 40 <!-- See http://docutils.sourceforge.net/rst.html for details. --> 41 <div class="contents local topic" id="contents"> 42 <ul class="simple"> 43 <li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li> 44 <li><a class="reference internal" href="#installation" id="id2">Installation</a><ul> 45 <li><a class="reference internal" href="#unix" id="id3">UNIX</a></li> 46 <li><a class="reference internal" href="#windows-xp-windows-8" id="id4">Windows XP - Windows 8</a></li> 47 <li><a class="reference internal" href="#running-the-regression-tests" id="id5">Running the Regression Tests</a></li> 48 </ul> 49 </li> 50 <li><a class="reference internal" href="#overview" id="id6">Overview</a></li> 51 <li><a class="reference internal" href="#example-script" id="id7">Example Script</a></li> 52 <li><a class="reference internal" href="#read-or-write-an-image" id="id8">Read or Write an Image</a></li> 53 <li><a class="reference internal" href="#manipulate-an-image" id="id9">Manipulate an Image</a></li> 54 <li><a class="reference internal" href="#set-an-image-attribute" id="id10">Set an Image Attribute</a></li> 55 <li><a class="reference internal" href="#get-an-image-attribute" id="id11">Get an Image Attribute</a></li> 56 <li><a class="reference internal" href="#create-an-image-montage" id="id12">Create an Image Montage</a></li> 57 <li><a class="reference internal" href="#working-with-blobs" id="id13">Working with Blobs</a></li> 58 <li><a class="reference internal" href="#miscellaneous-methods" id="id14">Miscellaneous Methods</a></li> 59 <li><a class="reference internal" href="#handling-errors" id="id15">Handling Errors</a></li> 60 </ul> 61 </div> 62 <div class="section" id="introduction"> 63 <h1><a class="toc-backref" href="#id1">Introduction</a></h1> 64 <p>PerlMagick is an objected-oriented Perl interface to GraphicsMagick. Use 65 the module to read, manipulate, or write an image or image sequence from 66 within a Perl script. This makes it very suitable for Web CGI scripts. 67 You must have GraphicsMagick 1.0.0 or above and Perl version 5.005_02 or 68 greater installed on your system for either of these utilities to work. 69 There are a number of useful scripts available to show you the value of 70 PerlMagick. The PerlMagick demo directory provides a number of sample 71 demos.</p> 72 </div> 73 <div class="section" id="installation"> 74 <h1><a class="toc-backref" href="#id2">Installation</a></h1> 75 <div class="section" id="unix"> 76 <h2><a class="toc-backref" href="#id3">UNIX</a></h2> 77 <p>PerlMagick is installed by default by installing GraphicsMagick. 78 Installing PerlMagick as a subordinate package of GraphicsMagick is the 79 best way to avoid problems.</p> 80 <p>For Unix, you typically need to be root to install the software. There 81 are ways around this. Consult the Perl manual pages for more information.</p> 82 </div> 83 <div class="section" id="windows-xp-windows-8"> 84 <h2><a class="toc-backref" href="#id4">Windows XP - Windows 8</a></h2> 85 <p>Please note that a nice GUI installer is available for GraphicsMagick. 86 PerlMagick is included in this installer. If you are using the installer, 87 then there is no need to compile PerlMagick.</p> 88 <p>After GraphicsMagick has been compiled from the GraphicsMagick Windows 89 source distribution using Microsoft Visual C++, PerlMagick may be 90 manually built and installed by opening a CLI window and performing the 91 following steps:</p> 92 <pre class="literal-block"> 93 cd PerlMagick 94 copy Makefile.nt Makefile.PL 95 perl Makefile.PL 96 nmake 97 nmake install 98 </pre> 99 <p>See the PerlMagick Windows HowTo page for further installation 100 instructions.</p> 101 </div> 102 <div class="section" id="running-the-regression-tests"> 103 <h2><a class="toc-backref" href="#id5">Running the Regression Tests</a></h2> 104 <p>To verify a correct installation, type:</p> 105 <pre class="literal-block"> 106 make test 107 </pre> 108 <p>Use nmake test under Windows. There are a few demonstration scripts 109 available to exercise many of the functions PerlMagick can perform. Type</p> 110 <pre class="literal-block"> 111 cd demo 112 make 113 </pre> 114 <p>You are now ready to utilize the PerlMagick methods from within your Perl 115 scripts.</p> 116 </div> 117 </div> 118 <div class="section" id="overview"> 119 <h1><a class="toc-backref" href="#id6">Overview</a></h1> 120 <p>Any script that wants to use PerlMagick methods must first define the 121 methods within its namespace and instantiate an image object. Do this 122 with</p> 123 <pre class="literal-block"> 124 use Graphics::Magick; 125 $image=Graphics::Magick->new; 126 </pre> 127 <p>Note that this differs from the ImageMagick version of PerlMagick which 128 uses the namespace Image::Magick. Any PerlMagick code written for the 129 ImageMagick version of PerlMagick requires a global substition of 130 Image::Magick to Graphics::Magick in order to work with the 131 GraphicsMagick version.</p> 132 <p>The new() method takes the same parameters as SetAttribute . For example:</p> 133 <pre class="literal-block"> 134 $image=Graphics::Magick->new(size=>'384x256'); 135 </pre> 136 <p>Next you will want to read an image or image sequence, manipulate it, and 137 then display or write it. The input and output methods for PerlMagick are 138 defined in Read or Write an Image. See Set an Image Attribute for methods 139 that affect the way an image is read or written. Refer to Manipulate an 140 Image for a list of methods to transform an image. Get an Image Attribute 141 describes how to retrieve an attribute for an image. Refer to Create an 142 Image Montage for details about tiling your images as thumbnails on a 143 background. Finally, some methods do not neatly fit into any of the 144 categories just mentioned. Review Miscellaneous Methods for a list of 145 these methods.</p> 146 <p>Once you are finished with a PerlMagick object you should consider 147 destroying it. Each image in an image sequence is stored in either 148 virtual memory or as a file in the system's temporary file directory. 149 This can potentially add up to megabytes of memory or disk. Upon 150 destroying a PerlMagick object, the memory is returned for use by other 151 Perl methods. The recommended way to destroy an object is with undef</p> 152 <pre class="literal-block"> 153 undef $image; 154 </pre> 155 <p>To delete all the images but retain the Graphics::Magick object use</p> 156 <pre class="literal-block"> 157 @$image = (); 158 </pre> 159 <p>and finally, to delete a single image from a multi-image sequence, use</p> 160 <pre class="literal-block"> 161 undef $image->[x]; 162 </pre> 163 <p>The next section illustrates how to use various PerlMagick methods to 164 manipulate an image sequence.</p> 165 <p>Some of the PerlMagick methods require external programs such as 166 Ghostscript. This may require an explicit path in your PATH environment 167 variable to work properly. For example,</p> 168 <pre class="literal-block"> 169 $ENV{PATH}='/bin:/usr/bin:/usr/local/bin'; 170 </pre> 171 </div> 172 <div class="section" id="example-script"> 173 <h1><a class="toc-backref" href="#id7">Example Script</a></h1> 174 <p>Here is an example script to get you started:</p> 175 <pre class="literal-block"> 176 #!/usr/local/bin/perl 177 use Graphics::Magick; 178 my($image, $status); 179 $image = Graphics::Magick->new; 180 $status = $image->Read('girl.png', 'logo.png', 'rose.png'); 181 warn "$status" if "$status"; 182 $status = $image->Crop(geometry=>'100x100+100+100'); 183 warn "$status" if "$status"; 184 $status = $image->Write('x.gif'); 185 warn "$status" if "$status"; 186 </pre> 187 <p>The script reads three images, crops them, and writes a single image as a 188 GIF animation sequence. In many cases you may want to access individual 189 images of a sequence. The next example illustrates how this is done:</p> 190 <pre class="literal-block"> 191 #!/usr/local/bin/perl 192 use Graphics::Magick; 193 my($image, $p, $q); 194 $image = new Graphics::Magick; 195 $image->Read('x1.png'); 196 $image->Read('j*.jpg'); 197 $image->Read('k.miff[1, 5, 3]'); 198 $image->Contrast(); 199 for ($x = 0; $image->[x]; $x++) 200 { 201 $image->[x]->Frame('100x200') if $image->[x]->Get('magick') eq 'GIF'; 202 undef $image->[x] if $image->[x]->Get('columns') < 100; 203 } 204 $p = $image->[1]; 205 $p->Draw(stroke=>'red', primitive=>'rectangle', points=>'20,20 100,100'); 206 $q = $p->Montage(); 207 undef $image; 208 $q->Write('x.miff'); 209 </pre> 210 <p>Suppose you want to start out with a 100 by 100 pixel white canvas with a 211 red pixel in the center. Try</p> 212 <pre class="literal-block"> 213 $image = Graphics::Magick->new; 214 $image->Set(size=>'100x100'); 215 $image->ReadImage('xc:white'); 216 $image->Set('pixel[49,49]'=>'red'); 217 </pre> 218 <p>Or suppose you want to convert your color image to grayscale:</p> 219 <pre class="literal-block"> 220 $image->Quantize(colorspace=>'gray'); 221 </pre> 222 <p>Here we annotate an image with a Taipai TrueType font:</p> 223 <pre class="literal-block"> 224 $text = 'Works like magick!'; 225 $image->Annotate(font=>'kai.ttf', pointsize=>40, fill=>'green', text=>$text); 226 </pre> 227 <p>Other clever things you can do with a PerlMagick objects include</p> 228 <pre class="literal-block"> 229 $i = $#$p"+1"; # return the number of images associated with object p 230 push(@$q, @$p); # push the images from object p onto object q 231 @$p = (); # delete the images but not the object p 232 $p->Convolve([1, 2, 1, 2, 4, 2, 1, 2, 1]); # 3x3 Gaussian kernel 233 </pre> 234 </div> 235 <div class="section" id="read-or-write-an-image"> 236 <h1><a class="toc-backref" href="#id8">Read or Write an Image</a></h1> 237 <p>Use the methods listed below to either read, write, or display an image 238 or image sequence.</p> 239 <table border="1" class="docutils"> 240 <caption>Read or Write Methods</caption> 241 <colgroup> 242 <col width="10%" /> 243 <col width="19%" /> 244 <col width="27%" /> 245 <col width="44%" /> 246 </colgroup> 247 <tbody valign="top"> 248 <tr><td>Method</td> 249 <td>Parameters</td> 250 <td>Return Value</td> 251 <td>Description</td> 252 </tr> 253 <tr><td>Read</td> 254 <td>one or more 255 filenames</td> 256 <td>the number of 257 images read</td> 258 <td>read an image or image sequence</td> 259 </tr> 260 <tr><td>Write</td> 261 <td>filename</td> 262 <td>the number of 263 images written</td> 264 <td>write an image or image 265 sequence</td> 266 </tr> 267 <tr><td>Display</td> 268 <td>server name</td> 269 <td>the number of 270 images displayed</td> 271 <td>display the image or image 272 sequence to an X server</td> 273 </tr> 274 <tr><td>Animate</td> 275 <td>server name</td> 276 <td>the number of 277 images animated</td> 278 <td>animate image sequence to an X 279 server</td> 280 </tr> 281 </tbody> 282 </table> 283 <p>For convenience, methods Write(), Display(), and Animate() can take any 284 parameter that SetAttribute knows about. For example,</p> 285 <pre class="literal-block"> 286 $image->Write(filename=>'image.png', compression=>'None'); 287 </pre> 288 <p>Use - as the filename to method Read() to read from standard in or to 289 method Write() to write to standard out:</p> 290 <pre class="literal-block"> 291 binmode STDOUT; 292 $image->Write('png:-'); 293 </pre> 294 <dl class="docutils"> 295 <dt>To read an image from a disk file, use::</dt> 296 <dd>$image = Graphics::Magick->new; 297 $filename = 'test.gif'; 298 $status = $image->Read ($filename);</dd> 299 </dl> 300 <p>and to write the image back to the disk file, use:</p> 301 <pre class="literal-block"> 302 $status = $image->Write($filename); 303 </pre> 304 <p>To read an image in the GIF format from a PERL filehandle, use:</p> 305 <pre class="literal-block"> 306 $image = Graphics::Magick->new; 307 open(IMAGE, 'image.gif'); 308 $status = $image->Read(file=>\*IMAGE); 309 close(IMAGE); 310 </pre> 311 <p>To write an image in the PNG format to a PERL filehandle, use:</p> 312 <pre class="literal-block"> 313 $filename = "image.png"; 314 open(IMAGE, ">$filename"); 315 $status = $image->Write(file=>\*IMAGE, filename=>$filename); 316 close(IMAGE); 317 </pre> 318 <p>If %0Nd appears in the filename, it is interpreted as a printf format 319 specification and the specification is replaced with the specified 320 decimal encoding of the scene number. For example,</p> 321 <pre class="literal-block"> 322 image%03d.miff 323 </pre> 324 <p>converts files image000.miff, image001.miff, etc.</p> 325 <p>You can optionally add Image to any method name. For example, ReadImage() 326 is an alias for method Read().</p> 327 </div> 328 <div class="section" id="manipulate-an-image"> 329 <h1><a class="toc-backref" href="#id9">Manipulate an Image</a></h1> 330 <p>Once you create an image with, for example, method ReadImage() you may want 331 to operate on it. Below is a list of all the image manipulations methods 332 available to you with PerlMagick. There are examples of select PerlMagick 333 methods. Here is an example call to an image manipulation method:</p> 334 <pre class="literal-block"> 335 $image->Crop(geometry=>'100x100"+1"0+20'); 336 $image->[x]->Frame("100x200"); 337 </pre> 338 <p>Image method parameters are often redundant. For example, a 'geometry' 339 string parameter (e.g. 800x600+10+20) is equivalent to the explicit use of 340 width, height, x, and y, parameters.</p> 341 <p>The following image manipulation methods are available:</p> 342 <table border="1" class="docutils"> 343 <caption>Image Manipulation Methods</caption> 344 <colgroup> 345 <col width="24%" /> 346 <col width="46%" /> 347 <col width="30%" /> 348 </colgroup> 349 <tbody valign="top"> 350 <tr><td>Method</td> 351 <td>Parameters</td> 352 <td>Description</td> 353 </tr> 354 <tr><td>AdaptiveThreshold</td> 355 <td>geometry=>geometry, width=> 356 integer, height=> integer, offset 357 =>integer</td> 358 <td>Local adaptive 359 thresholding. Width 360 and height specify 361 the size of the local 362 region while offset 363 specifies the amount 364 to subtract from the 365 average of the 366 region.</td> 367 </tr> 368 <tr><td>AddNoise</td> 369 <td>noise=>{Uniform, Gaussian, 370 Multiplicative, Impulse, 371 Laplacian, Poisson, Random}</td> 372 <td>Add noise to an image 373 across the red, 374 green, and blue, 375 channels. Set the 376 image colorspace to 377 GRAY to obtain 378 intensity noise.</td> 379 </tr> 380 <tr><td>AffineTransform</td> 381 <td>affine=>array of float values, 382 translate=>float, float, scale=> 383 float, float, rotate=>float, 384 skewX=>float, skewY=>float</td> 385 <td>Affine transform 386 image</td> 387 </tr> 388 <tr><td>Annotate</td> 389 <td>text=>string, font=>string, 390 family=>string, style=>{Normal, 391 Italic, Oblique, Any}, stretch=> 392 {Normal, UltraCondensed, 393 ExtraCondensed, Condensed, 394 SemiCondensed, SemiExpanded, 395 Expanded, ExtraExpanded, 396 UltraExpanded}, weight=>integer, 397 pointsize=>integer, density=> 398 geometry, stroke=> color name, 399 strokewidth=>integer, fill=>color 400 name, undercolor=>color name, 401 geometry=>geometry, gravity=> 402 {NorthWest, North, NorthEast, 403 West, Center, East, SouthWest, 404 South, SouthEast}, antialias=> 405 {true, false}, x=>integer, y=> 406 integer, affine=>array of float 407 values, translate=>float, float, 408 scale=>float, float, rotate=> 409 float. skewX=>float, skewY=> 410 float, align=>{Left, Center, 411 Right}, encoding=>{UTF-8}</td> 412 <td>annotate an image 413 with text. See 414 QueryFontMetrics to 415 get font metrics 416 without rendering any 417 text.</td> 418 </tr> 419 <tr><td>Blur</td> 420 <td>geometry=>geometry, radius=> 421 double, sigma=> double</td> 422 <td>blur the image with a 423 Gaussian operator of 424 the given radius and 425 standard deviation 426 (sigma).</td> 427 </tr> 428 <tr><td>Border</td> 429 <td>geometry=>geometry, width=> 430 integer, height=> integer, fill=> 431 color name</td> 432 <td>surround the image 433 with a border of 434 color</td> 435 </tr> 436 <tr><td>Channel</td> 437 <td>channel=>{Red, Cyan, Green, 438 Magenta, Blue, Yellow, Opacity, 439 Black, Matte, All, Gray}</td> 440 <td>extract a channel 441 from the image</td> 442 </tr> 443 <tr><td>Charcoal</td> 444 <td>order=>integer</td> 445 <td>simulate a charcoal 446 drawing</td> 447 </tr> 448 <tr><td>Chop</td> 449 <td>geometry=>geometry, width=> 450 integer, height=> integer, x=> 451 integer, y=>integer</td> 452 <td>chop an image</td> 453 </tr> 454 <tr><td>Coalesce</td> 455 <td> </td> 456 <td>merge a sequence of 457 images</td> 458 </tr> 459 <tr><td>Clip</td> 460 <td> </td> 461 <td>apply any clipping 462 path information as 463 an image clip mask.</td> 464 </tr> 465 <tr><td>ColorFloodfill</td> 466 <td>geometry=>geometry, x=>integer, y 467 =>integer , fill=>color name, 468 bordercolor=> color name</td> 469 <td>changes the color 470 value of any pixel 471 that matches the 472 color of the target 473 pixel and is a 474 neighbor. If you 475 specify a border 476 color, the color 477 value is changed for 478 any neighbor pixel 479 that is not that 480 color.</td> 481 </tr> 482 <tr><td>Colorize</td> 483 <td>fill=>color name, opacity=>string</td> 484 <td>colorize the image 485 with the fill color</td> 486 </tr> 487 <tr><td>Comment</td> 488 <td>string</td> 489 <td>add a comment to your 490 image</td> 491 </tr> 492 <tr><td>Compare</td> 493 <td>image=>image-handle</td> 494 <td>compare image to a 495 reference image</td> 496 </tr> 497 <tr><td>Composite</td> 498 <td>image=>image-handle, compose=>{ 499 Over, In, Out, Atop, Xor, Plus, 500 Minus, Add, Subtract, 501 Difference, Multiply, Bumpmap, 502 Copy, CopyRed, CopyGreen, 503 CopyBlue, CopyOpacity, 504 Clear, Dissolve, Displace, 505 Modulate, Threshold, No, Darken, 506 Lighten, Hue, Saturate, 507 Colorize, Luminize, Screen, 508 Overlay, CopyCyan, CopyMagenta, 509 CopyYellow, CopyBlack, Divide, 510 HardLight}, 511 mask=> 512 image-handle, geometry=>geometry, 513 x=>integer, y=>integer, gravity=> 514 {NorthWest, North, NorthEast, 515 West, Center, East, SouthWest, 516 South, SouthEast}, opacity=> 517 integer, tile=>{True, False}, 518 rotate=>double, color=>color name</td> 519 <td>composite one image 520 onto another</td> 521 </tr> 522 <tr><td>Contrast</td> 523 <td>sharpen=>{True, False}</td> 524 <td>enhance or reduce the 525 image contrast</td> 526 </tr> 527 <tr><td>Convolve</td> 528 <td>coefficients=>array of float 529 values</td> 530 <td>apply a convolution 531 kernel to the image. 532 Given a kernel order 533 , you would supply 534 order*order float 535 values (e.g. 3x3 536 implies 9 values).</td> 537 </tr> 538 <tr><td>Crop</td> 539 <td>geometry=>geometry, width=> 540 integer, height=> integer, x=> 541 integer, y=>integer</td> 542 <td>crop an image</td> 543 </tr> 544 <tr><td>CycleColormap</td> 545 <td>amount=>integer</td> 546 <td>displace image 547 colormap by amount</td> 548 </tr> 549 <tr><td>Deconstruct</td> 550 <td> </td> 551 <td>break down an image 552 sequence into 553 constituent parts</td> 554 </tr> 555 <tr><td>Despeckle</td> 556 <td> </td> 557 <td>reduce the speckles 558 within an image</td> 559 </tr> 560 <tr><td>Draw</td> 561 <td>primitive=>{point, line, 562 rectangle, roundRectangle, arc, 563 ellipse, circle, polyline, 564 polygon, ,bezier, path, color, 565 matte, text, image, @filename}, 566 points=>string , method=>{Point, 567 Replace, Floodfill, FillToBorder, 568 Reset}, stroke=> color name, fill 569 =>color name, tile=>image-handle, 570 strokewidth=>float, antialias=> 571 {true, false}, bordercolor=>color 572 name, x=> float, y=>float, affine 573 =>array of float values, 574 translate=>float, float, scale=> 575 float, float, rotate=>float. 576 skewX=>float, skewY=> float</td> 577 <td>annotate an image 578 with one or more 579 graphic primitives</td> 580 </tr> 581 <tr><td>Edge</td> 582 <td>radius=>double</td> 583 <td>enhance edges within 584 the image with a 585 convolution filter of 586 the given radius.</td> 587 </tr> 588 <tr><td>Emboss</td> 589 <td>geometry=>geometry, radius=> 590 double, sigma=> double</td> 591 <td>emboss the image with 592 a convolution filter 593 of the given radius 594 and standard 595 deviation (sigma).</td> 596 </tr> 597 <tr><td>Enhance</td> 598 <td> </td> 599 <td>apply a digital 600 filter to enhance a 601 noisy image</td> 602 </tr> 603 <tr><td>Equalize</td> 604 <td> </td> 605 <td>perform histogram 606 equalization to the 607 image</td> 608 </tr> 609 <tr><td>Flatten</td> 610 <td> </td> 611 <td>flatten a sequence of 612 images</td> 613 </tr> 614 <tr><td>Flip</td> 615 <td> </td> 616 <td>create a mirror image 617 by reflecting the 618 image scanlines in 619 the vertical 620 direction</td> 621 </tr> 622 <tr><td>Flop</td> 623 <td> </td> 624 <td>create a mirror image 625 by reflecting the 626 image scanlines in 627 the horizontal 628 direction</td> 629 </tr> 630 <tr><td>Frame</td> 631 <td>geometry=>geometry, width=> 632 integer, height=> integer, inner 633 =>integer, outer=>integer, fill=> 634 color name</td> 635 <td>surround the image 636 with an ornamental 637 border</td> 638 </tr> 639 <tr><td>Gamma</td> 640 <td>gamma=>string, red=>double, green 641 =>double , blue=>double</td> 642 <td>gamma correct the 643 image</td> 644 </tr> 645 <tr><td>Implode</td> 646 <td>amount=>double</td> 647 <td>implode image pixels 648 about the center</td> 649 </tr> 650 <tr><td>Label</td> 651 <td>string</td> 652 <td>assign a label to an 653 image</td> 654 </tr> 655 <tr><td>Level</td> 656 <td>level=>string, 'black-point'=> 657 double, 'mid-point'=>double, 658 'white-point'=>double</td> 659 <td>adjust the level of 660 image contrast</td> 661 </tr> 662 <tr><td>Magnify</td> 663 <td> </td> 664 <td>double the size of an 665 image</td> 666 </tr> 667 <tr><td>Map</td> 668 <td>image=>image-handle, dither=> 669 {True, False}</td> 670 <td>choose a particular 671 set of colors from 672 this image</td> 673 </tr> 674 <tr><td>MatteFloodfill</td> 675 <td>geometry=>geometry, x=>integer, y 676 =>integer , matte=>integer, 677 bordercolor=>color name</td> 678 <td>changes the matte 679 value of any pixel 680 that matches the 681 color of the target 682 pixel and is a 683 neighbor. If you 684 specify a border 685 color, the matte 686 value is changed for 687 any neighbor pixel 688 that is not that 689 color.</td> 690 </tr> 691 <tr><td>MedianFilter</td> 692 <td>radius=>double</td> 693 <td>replace each pixel 694 with the median 695 intensity pixel of a 696 neighborhood.</td> 697 </tr> 698 <tr><td>Minify</td> 699 <td> </td> 700 <td>half the size of an 701 image</td> 702 </tr> 703 <tr><td>Modulate</td> 704 <td>brightness=>double, saturation=> 705 double, hue=> double</td> 706 <td>vary the brightness, 707 saturation, and hue 708 of an image by the 709 specified percentage</td> 710 </tr> 711 <tr><td>MotionBlur</td> 712 <td>geometry=>geometry, radius=> 713 double, sigma=> double, angle=> 714 double</td> 715 <td>blur the image with a 716 Gaussian operator of 717 the given radius and 718 standard deviation 719 (sigma) at the given 720 angle to simulate the 721 effect of motion</td> 722 </tr> 723 <tr><td>Negate</td> 724 <td>gray=>{True, False}</td> 725 <td>replace every pixel 726 with its 727 complementary color 728 (white becomes black, 729 yellow becomes blue, 730 etc.)</td> 731 </tr> 732 <tr><td>Normalize</td> 733 <td> </td> 734 <td>transform image to 735 span the full range 736 of color values</td> 737 </tr> 738 <tr><td>OilPaint</td> 739 <td>radius=>integer</td> 740 <td>simulate an oil 741 painting</td> 742 </tr> 743 <tr><td>Opaque</td> 744 <td>color=>color name, fill=> color 745 name</td> 746 <td>change this color to 747 the fill color within 748 the image</td> 749 </tr> 750 <tr><td>Quantize</td> 751 <td>colors=>integer, colorspace=> 752 {RGB, Gray, Transparent, OHTA, 753 XYZ, YCbCr, YIQ, YPbPr, YUV, 754 CMYK}, treedepth=> integer, 755 dither=>{True, False}, 756 measure_error=>{True, False}, 757 global_colormap=>{True, False}</td> 758 <td>preferred number of 759 colors in the image</td> 760 </tr> 761 <tr><td>Profile</td> 762 <td>name=>{ICM, IPTC}, profile=>blob</td> 763 <td>add or remove ICC or 764 IPTC image profile</td> 765 </tr> 766 <tr><td>Raise</td> 767 <td>geometry=>geometry, width=> 768 integer, height=> integer, x=> 769 integer, y=>integer, raise=> 770 {True, False}</td> 771 <td>lighten or darken 772 image edges to create 773 a 3-D effect</td> 774 </tr> 775 <tr><td>ReduceNoise</td> 776 <td>radius=>double</td> 777 <td>reduce noise in the 778 image with a noise 779 peak elimination 780 filter</td> 781 </tr> 782 <tr><td>Resize</td> 783 <td>geometry=>geometry, width=> 784 integer, height=> integer, filter 785 =>{Point, Box, Triangle, Hermite, 786 Hanning, Hamming, Blackman, 787 Gaussian, Quadratic, Cubic, 788 Catrom, Mitchell, Lanczos, 789 Bessel, Sinc}, blur=>double</td> 790 <td>scale image to 791 desired size. Specify 792 blur > 1 for blurry 793 or < 1 for sharp</td> 794 </tr> 795 <tr><td>Roll</td> 796 <td>geometry=>geometry, x=>integer, y 797 =>integer</td> 798 <td>roll an image 799 vertically or 800 horizontally</td> 801 </tr> 802 <tr><td>Rotate</td> 803 <td>degrees=>double, color=>color 804 name</td> 805 <td>rotate an image</td> 806 </tr> 807 <tr><td>Sample</td> 808 <td>geometry=>geometry, width=> 809 integer, height=> integer</td> 810 <td>scale image with 811 pixel sampling</td> 812 </tr> 813 <tr><td>Scale</td> 814 <td>geometry=>geometry, width=> 815 integer, height=> integer</td> 816 <td>scale image to 817 desired size</td> 818 </tr> 819 <tr><td>Segment</td> 820 <td>colorspace=>{RGB, Gray, 821 Transparent, OHTA, XYZ, YCbCr, 822 YCC, YIQ, YPbPr, YUV, CMYK}, 823 verbose={True, False}, cluster=> 824 double, smooth= double</td> 825 <td>segment an image by 826 analyzing the 827 histograms of the 828 color components and 829 identifying units 830 that are homogeneous</td> 831 </tr> 832 <tr><td>Shade</td> 833 <td>geometry=>geometry, azimuth=> 834 double, elevation=> double, gray 835 =>{true, false}</td> 836 <td>shade the image using 837 a distant light 838 source</td> 839 </tr> 840 <tr><td>Sharpen</td> 841 <td>geometry=>geometry, radius=> 842 double, sigma=> double</td> 843 <td>sharpen the image 844 with a Gaussian 845 operator of the given 846 radius and standard 847 deviation (sigma).</td> 848 </tr> 849 <tr><td>Shave</td> 850 <td>geometry=>geometry, width=> 851 integer, height=> integer</td> 852 <td>shave pixels from the 853 image edges</td> 854 </tr> 855 <tr><td>Shear</td> 856 <td>geometry=>geometry, x=>double, y 857 =>double color=>color name</td> 858 <td>shear the image along 859 the X or Y axis by a 860 positive or negative 861 shear angle</td> 862 </tr> 863 <tr><td>Signature</td> 864 <td> </td> 865 <td>generate an SHA-256 866 message digest for 867 the image pixel 868 stream</td> 869 </tr> 870 <tr><td>Solarize</td> 871 <td>threshold=>integer</td> 872 <td>negate all pixels 873 above the threshold 874 level</td> 875 </tr> 876 <tr><td>Spread</td> 877 <td>amount=>integer</td> 878 <td>displace image pixels 879 by a random amount</td> 880 </tr> 881 <tr><td>Stereo</td> 882 <td>image=>image-handle</td> 883 <td>composites two images 884 and produces a single 885 image that is the 886 composite of a left 887 and right image of a 888 stereo pair</td> 889 </tr> 890 <tr><td>Stegano</td> 891 <td>image=>image-handle, offset=> 892 integer</td> 893 <td>hide a digital 894 watermark within the 895 image</td> 896 </tr> 897 <tr><td>Swirl</td> 898 <td>degrees=>double</td> 899 <td>swirl image pixels 900 about the center</td> 901 </tr> 902 <tr><td>Texture</td> 903 <td>texture=>image-handle</td> 904 <td>name of texture to 905 tile onto the image 906 background</td> 907 </tr> 908 <tr><td>Threshold</td> 909 <td>threshold=>string</td> 910 <td>threshold the image</td> 911 </tr> 912 <tr><td>Transparent</td> 913 <td>color=>color name</td> 914 <td>make this color 915 transparent within 916 the image</td> 917 </tr> 918 <tr><td>Trim</td> 919 <td> </td> 920 <td>remove edges that are 921 the background color 922 from the image</td> 923 </tr> 924 <tr><td>UnsharpMask</td> 925 <td>geometry=>geometry, radius=> 926 double, sigma=> double, amount=> 927 double, threshold=>double</td> 928 <td>sharpen the image 929 with the unsharp mask 930 algorithm.</td> 931 </tr> 932 <tr><td>Wave</td> 933 <td>geometry=>geometry, amplitude=> 934 double, wavelength=> double</td> 935 <td>alter an image along 936 a sine wave</td> 937 </tr> 938 </tbody> 939 </table> 940 <p>Note, that the geometry parameter is a short cut for the width and height 941 parameters (e.g. geometry=>'106x80' is equivalent to width=>106, 942 height=>80).</p> 943 <p>You can specify @filename in both Annotate() and Draw(). This reads the 944 text or graphic primitive instructions from a file on disk. For example,</p> 945 <pre class="literal-block"> 946 $image->Draw(fill=>'red', primitive=>'rectangle', 947 points=>'20,20 100,100 40,40 200,200 60,60 300,300'); 948 </pre> 949 <p>Is equivalent to</p> 950 <pre class="literal-block"> 951 $image->Draw(fill=>'red', primitive=>'@draw.txt'); 952 </pre> 953 <p>Where draw.txt is a file on disk that contains this:</p> 954 <pre class="literal-block"> 955 rectangle 20, 20 100, 100 956 rectangle 40, 40 200, 200 957 rectangle 60, 60 300, 300 958 </pre> 959 <p>The text parameter for methods, Annotate(), Comment(), Draw(), and 960 Label() can include the image filename, type, width, height, or other 961 image attribute by embedding these special format characters:</p> 962 <pre class="literal-block"> 963 %b file size 964 %d comment 965 %d directory 966 %e filename extension 967 %f filename 968 %h height 969 %m magick 970 %p page number 971 %s scene number 972 %t top of filename 973 %w width 974 %x x resolution 975 %y y resolution 976 \n newline 977 \r carriage return 978 </pre> 979 <p>For example,</p> 980 <pre class="literal-block"> 981 text=>"%m:%f %wx%h" 982 </pre> 983 <p>produces an annotation of MIFF:bird.miff 512x480 for an image titled 984 bird.miff and whose width is 512 and height is 480.</p> 985 <p>You can optionally add Image to any method name. For example, TrimImage() 986 is an alias for method Trim().</p> 987 <p>Most of the attributes listed above have an analog in convert. See the 988 documentation for a more detailed description of these attributes.</p> 989 </div> 990 <div class="section" id="set-an-image-attribute"> 991 <h1><a class="toc-backref" href="#id10">Set an Image Attribute</a></h1> 992 <p>Use method Set() to set an image attribute. For example,</p> 993 <pre class="literal-block"> 994 $image->Set(dither=>'True'); 995 $image->[$x]->Set(delay=>3); 996 </pre> 997 <p>And here is a list of all the image attributes you can set:</p> 998 <table border="1" class="docutils"> 999 <caption>Image Attributes</caption> 1000 <colgroup> 1001 <col width="23%" /> 1002 <col width="51%" /> 1003 <col width="27%" /> 1004 </colgroup> 1005 <tbody valign="top"> 1006 <tr><td>Attribute</td> 1007 <td>Values</td> 1008 <td>Description</td> 1009 </tr> 1010 <tr><td>adjoin</td> 1011 <td>{True, False}</td> 1012 <td>join images into a 1013 single multi-image 1014 file</td> 1015 </tr> 1016 <tr><td>antialias</td> 1017 <td>{True, False}</td> 1018 <td>remove pixel 1019 aliasing</td> 1020 </tr> 1021 <tr><td>authenticate</td> 1022 <td>string</td> 1023 <td>decrypt image with 1024 this password.</td> 1025 </tr> 1026 <tr><td>background</td> 1027 <td>color name</td> 1028 <td>image background 1029 color</td> 1030 </tr> 1031 <tr><td>blue-primary</td> 1032 <td>x-value, y-value</td> 1033 <td>chromaticity blue 1034 primary point (e.g. 1035 0.15, 0.06)</td> 1036 </tr> 1037 <tr><td>bordercolor</td> 1038 <td>color name</td> 1039 <td>set the image 1040 border color</td> 1041 </tr> 1042 <tr><td>clip-mask</td> 1043 <td>image</td> 1044 <td>Associate a clip 1045 mask with the 1046 image.</td> 1047 </tr> 1048 <tr><td>colormap[i]</td> 1049 <td>color name</td> 1050 <td>color name (e.g. 1051 red) or hex value 1052 (e.g. #ccc) at 1053 position i</td> 1054 </tr> 1055 <tr><td>colorspace</td> 1056 <td>{RGB, CMYK}</td> 1057 <td>type of colorspace</td> 1058 </tr> 1059 <tr><td>comment</td> 1060 <td>string</td> 1061 <td>Append to the image 1062 comment.</td> 1063 </tr> 1064 <tr><td>compression</td> 1065 <td>{None, BZip, Fax, Group4, JPEG, 1066 LosslessJPEG, LZW, RLE, Zip, LZMA 1067 JPEG2000, JBIG1, JBIG2}</td> 1068 <td>type of image 1069 compression</td> 1070 </tr> 1071 <tr><td>debug</td> 1072 <td>{No, Configure, Annotate, Render, 1073 Transform, Locale, Coder, X11, 1074 Cache, Blob, Deprecate, User, 1075 Resource, TemporaryFile, 1076 Exception,All}</td> 1077 <td>log copious 1078 debugging 1079 information for 1080 one or more event 1081 types</td> 1082 </tr> 1083 <tr><td>delay</td> 1084 <td>integer</td> 1085 <td>this many 1/100ths 1086 of a second must 1087 expire before 1088 displaying the next 1089 image in a sequence</td> 1090 </tr> 1091 <tr><td>density</td> 1092 <td>geometry</td> 1093 <td>vertical and 1094 horizontal 1095 resolution in 1096 pixels of the image</td> 1097 </tr> 1098 <tr><td>disk-limit</td> 1099 <td>integer</td> 1100 <td>set disk resource 1101 limit in megabytes</td> 1102 </tr> 1103 <tr><td>dispose</td> 1104 <td>{Undefined, None, Background, 1105 Previous}</td> 1106 <td>GIF disposal method</td> 1107 </tr> 1108 <tr><td>dither</td> 1109 <td>{True, False}</td> 1110 <td>apply error 1111 diffusion to the 1112 image</td> 1113 </tr> 1114 <tr><td>display</td> 1115 <td>string</td> 1116 <td>specifies the X 1117 server to contact</td> 1118 </tr> 1119 <tr><td>endian</td> 1120 <td>{Undefined, LSB, MSB, Native}</td> 1121 <td>specifies the 1122 ordering of bytes 1123 in a multi-byte 1124 word. MSB is 1125 big-endian, LSB is 1126 little-endian, and 1127 Native is whatever 1128 the current host 1129 uses by default.</td> 1130 </tr> 1131 <tr><td>file</td> 1132 <td>filehandle</td> 1133 <td>set the image 1134 filehandle</td> 1135 </tr> 1136 <tr><td>filename</td> 1137 <td>string</td> 1138 <td>set the image 1139 filename</td> 1140 </tr> 1141 <tr><td>fill</td> 1142 <td>color</td> 1143 <td>The fill color 1144 paints any areas 1145 inside the outline 1146 of drawn shape.</td> 1147 </tr> 1148 <tr><td>font</td> 1149 <td>string</td> 1150 <td>use this font when 1151 annotating the 1152 image with text</td> 1153 </tr> 1154 <tr><td>fuzz</td> 1155 <td>integer</td> 1156 <td>colors within this 1157 distance are 1158 considered equal</td> 1159 </tr> 1160 <tr><td>gamma</td> 1161 <td>double</td> 1162 <td>gamma level of the 1163 image</td> 1164 </tr> 1165 <tr><td>Gravity</td> 1166 <td>{Forget, NorthWest, North, 1167 NorthEast, West, Center, East, 1168 SouthWest, South, SouthEast}</td> 1169 <td>type of image 1170 gravity</td> 1171 </tr> 1172 <tr><td>green-primary</td> 1173 <td>x-value, y-value</td> 1174 <td>chromaticity green 1175 primary point (e.g. 1176 0.3, 0.6)</td> 1177 </tr> 1178 <tr><td>index[x, y]</td> 1179 <td>string</td> 1180 <td>colormap index at 1181 position (x, y)</td> 1182 </tr> 1183 <tr><td>interlace</td> 1184 <td>{None, Line, Plane, Partition}</td> 1185 <td>the type of 1186 interlacing scheme</td> 1187 </tr> 1188 <tr><td>iterations</td> 1189 <td>integer</td> 1190 <td>add Netscape loop 1191 extension to your 1192 GIF animation</td> 1193 </tr> 1194 <tr><td>label</td> 1195 <td>string</td> 1196 <td>Append to the image 1197 label.</td> 1198 </tr> 1199 <tr><td>loop</td> 1200 <td>integer</td> 1201 <td>add Netscape loop 1202 extension to your 1203 GIF animation</td> 1204 </tr> 1205 <tr><td>magick</td> 1206 <td>string</td> 1207 <td>set the image 1208 format</td> 1209 </tr> 1210 <tr><td>matte</td> 1211 <td>{True, False}</td> 1212 <td>True if the image 1213 has transparency</td> 1214 </tr> 1215 <tr><td>mattecolor</td> 1216 <td>color name</td> 1217 <td>set the image matte 1218 color</td> 1219 </tr> 1220 <tr><td>map-limit</td> 1221 <td>integer</td> 1222 <td>set map resource 1223 limit in megabytes</td> 1224 </tr> 1225 <tr><td>memory-limit</td> 1226 <td>integer</td> 1227 <td>set memory resource 1228 limit in megabytes</td> 1229 </tr> 1230 <tr><td>monochrome</td> 1231 <td>{True, False}</td> 1232 <td>transform the image 1233 to black and white</td> 1234 </tr> 1235 <tr><td>page</td> 1236 <td>{ Letter, Tabloid, Ledger, Legal, 1237 Statement, Executive, A3, A4, A5, 1238 B4, B5, Folio, Quarto, 10x14} or 1239 geometry</td> 1240 <td>preferred size and 1241 location of an 1242 image canvas</td> 1243 </tr> 1244 <tr><td>pixel[x, y]</td> 1245 <td>string</td> 1246 <td>hex value (e.g. # 1247 ccc) at position (x 1248 , y)</td> 1249 </tr> 1250 <tr><td>pointsize</td> 1251 <td>integer</td> 1252 <td>pointsize of the 1253 Postscript or 1254 TrueType font</td> 1255 </tr> 1256 <tr><td>preview</td> 1257 <td>{ Rotate, Shear, Roll, Hue, 1258 Saturation, Brightness, Gamma, 1259 Spiff, Dull, Grayscale, Quantize, 1260 Despeckle, ReduceNoise, AddNoise, 1261 Sharpen, Blur, Threshold, 1262 EdgeDetect, Spread, Solarize, Shade, 1263 Raise, Segment, Swirl, Implode, 1264 Wave, OilPaint, Charcoal, 1265 JPEG}</td> 1266 <td>type of preview for 1267 the Preview image 1268 format</td> 1269 </tr> 1270 <tr><td>quality</td> 1271 <td>integer</td> 1272 <td>JPEG/MIFF/PNG 1273 compression level</td> 1274 </tr> 1275 <tr><td>red-primary</td> 1276 <td>x-value, y-value</td> 1277 <td>chromaticity red 1278 primary point (e.g. 1279 0.64, 0.33)</td> 1280 </tr> 1281 <tr><td>rendering-intent</td> 1282 <td>{Undefined, Saturation, Perceptual, 1283 Absolute, Relative}</td> 1284 <td>the type of 1285 rendering intent</td> 1286 </tr> 1287 <tr><td>sampling-factor</td> 1288 <td>geometry</td> 1289 <td>horizontal and 1290 vertical sampling 1291 factor</td> 1292 </tr> 1293 <tr><td>scene</td> 1294 <td>integer</td> 1295 <td>image scene number</td> 1296 </tr> 1297 <tr><td>subimage</td> 1298 <td>integer</td> 1299 <td>subimage of an 1300 image sequence</td> 1301 </tr> 1302 <tr><td>subrange</td> 1303 <td>integer</td> 1304 <td>number of images 1305 relative to the 1306 base image</td> 1307 </tr> 1308 <tr><td>server</td> 1309 <td>string</td> 1310 <td>specifies the X 1311 server to contact</td> 1312 </tr> 1313 <tr><td>size</td> 1314 <td>string</td> 1315 <td>width and height of 1316 a raw image</td> 1317 </tr> 1318 <tr><td>stroke</td> 1319 <td>color</td> 1320 <td>The stroke color 1321 paints along the 1322 outline of a shape.</td> 1323 </tr> 1324 <tr><td>tile</td> 1325 <td>string</td> 1326 <td>tile name</td> 1327 </tr> 1328 <tr><td>texture</td> 1329 <td>string</td> 1330 <td>name of texture to 1331 tile onto the image 1332 background</td> 1333 </tr> 1334 <tr><td>type</td> 1335 <td>{Bilevel, Grayscale, GrayscaleMatte, 1336 Palette, PaletteMatte, TrueColor, 1337 TrueColorMatte, ColorSeparation, 1338 ColorSeparationMatte, Optimize }</td> 1339 <td>image type</td> 1340 </tr> 1341 <tr><td>units</td> 1342 <td>{ Undefined, PixelsPerInch, 1343 PixelsPerCentimeters}</td> 1344 <td>units of image 1345 resolution</td> 1346 </tr> 1347 <tr><td>verbose</td> 1348 <td>{True, False}</td> 1349 <td>print detailed 1350 information about 1351 the image</td> 1352 </tr> 1353 <tr><td>virtual-pixel</td> 1354 <td>{Constant, Edge, Mirror, Tile}</td> 1355 <td>the virtual pixel 1356 method</td> 1357 </tr> 1358 <tr><td>white-point</td> 1359 <td>x-value, y-value</td> 1360 <td>chromaticity white 1361 point (e.g. 0.3127, 1362 0.329)</td> 1363 </tr> 1364 </tbody> 1365 </table> 1366 <p>Note, that the geometry parameter is a short cut for the width and height 1367 parameters (e.g. geometry=>'106x80' is equivalent to width=>106, height=> 1368 80).</p> 1369 <p>SetAttribute() is an alias for method Set().</p> 1370 <p>Most of the attributes listed above have an analog in gm convert. See the 1371 gm documentation for a more detailed description of these attributes.</p> 1372 </div> 1373 <div class="section" id="get-an-image-attribute"> 1374 <h1><a class="toc-backref" href="#id11">Get an Image Attribute</a></h1> 1375 <p>Use method Get() to get an image attribute. For example,</p> 1376 <pre class="literal-block"> 1377 ($a, $b, $c) = $image->Get('colorspace', 'magick', 'adjoin'); 1378 $width = $image->[3]->Get('columns'); 1379 </pre> 1380 <p>In addition to all the attributes listed in Set an Image Attribute , you 1381 can get these additional attributes:</p> 1382 <table border="1" class="docutils"> 1383 <caption>Image Attributes</caption> 1384 <colgroup> 1385 <col width="18%" /> 1386 <col width="14%" /> 1387 <col width="68%" /> 1388 </colgroup> 1389 <tbody valign="top"> 1390 <tr><td>Attribute</td> 1391 <td>Values</td> 1392 <td>Description</td> 1393 </tr> 1394 <tr><td>base-columns</td> 1395 <td>integer</td> 1396 <td>base image width (before transformations)</td> 1397 </tr> 1398 <tr><td>base-filename</td> 1399 <td>string</td> 1400 <td>base image filename (before transformations)</td> 1401 </tr> 1402 <tr><td>base-rows</td> 1403 <td>integer</td> 1404 <td>base image height (before transformations)</td> 1405 </tr> 1406 <tr><td>class</td> 1407 <td>{Direct, 1408 Pseudo}</td> 1409 <td>image class</td> 1410 </tr> 1411 <tr><td>colors</td> 1412 <td>integer</td> 1413 <td>number of unique colors in the image</td> 1414 </tr> 1415 <tr><td>comment</td> 1416 <td>string</td> 1417 <td>image comment</td> 1418 </tr> 1419 <tr><td>columns</td> 1420 <td>integer</td> 1421 <td>image width</td> 1422 </tr> 1423 <tr><td>depth</td> 1424 <td>integer</td> 1425 <td>image depth</td> 1426 </tr> 1427 <tr><td>directory</td> 1428 <td>string</td> 1429 <td>tile names from within an image montage</td> 1430 </tr> 1431 <tr><td>error</td> 1432 <td>double</td> 1433 <td>the mean error per pixel computed with methods 1434 Compare() or Quantize()</td> 1435 </tr> 1436 <tr><td>filesize</td> 1437 <td>integer</td> 1438 <td>number of bytes of the image on disk</td> 1439 </tr> 1440 <tr><td>format</td> 1441 <td>string</td> 1442 <td>get the descriptive image format</td> 1443 </tr> 1444 <tr><td>geometry</td> 1445 <td>string</td> 1446 <td>image geometry</td> 1447 </tr> 1448 <tr><td>height</td> 1449 <td>integer</td> 1450 <td>the number of rows or height of an image</td> 1451 </tr> 1452 <tr><td>id</td> 1453 <td>integer</td> 1454 <td>GraphicsMagick registry id</td> 1455 </tr> 1456 <tr><td>label</td> 1457 <td>string</td> 1458 <td>image label</td> 1459 </tr> 1460 <tr><td>maximum-error</td> 1461 <td>double</td> 1462 <td>the normalized max error per pixel computed with 1463 methods Compare() or Quantize()</td> 1464 </tr> 1465 <tr><td>mean-error</td> 1466 <td>double</td> 1467 <td>the normalized mean error per pixel computed 1468 with methods Compare() or Quantize()</td> 1469 </tr> 1470 <tr><td>montage</td> 1471 <td>geometry</td> 1472 <td>tile size and offset within an image montage</td> 1473 </tr> 1474 <tr><td>rows</td> 1475 <td>integer</td> 1476 <td>the number of rows or height of an image</td> 1477 </tr> 1478 <tr><td>signature</td> 1479 <td>string</td> 1480 <td>SHA-256 message digest associated with the image 1481 pixel stream</td> 1482 </tr> 1483 <tr><td>taint</td> 1484 <td>{True, 1485 False}</td> 1486 <td>True if the image has been modified</td> 1487 </tr> 1488 <tr><td>width</td> 1489 <td>integer</td> 1490 <td>the number of columns or width of an image</td> 1491 </tr> 1492 <tr><td>x-resolution</td> 1493 <td>integer</td> 1494 <td>x resolution of the image</td> 1495 </tr> 1496 <tr><td>y-resolution</td> 1497 <td>integer</td> 1498 <td>y resolution of the image</td> 1499 </tr> 1500 </tbody> 1501 </table> 1502 <p>GetAttribute() is an alias for method Get().</p> 1503 <p>Most of the attributes listed above have an analog in convert. See the 1504 documentation for a more detailed description of these attributes.</p> 1505 </div> 1506 <div class="section" id="create-an-image-montage"> 1507 <h1><a class="toc-backref" href="#id12">Create an Image Montage</a></h1> 1508 <p>Use method Montage() to create a composite image by combining several 1509 separate images. The images are tiled on the composite image with the 1510 name of the image optionally appearing just below the individual tile. 1511 For example,</p> 1512 <pre class="literal-block"> 1513 $image->Montage(geometry=>'160x160', tile=>'2x2', texture=>'granite:'); 1514 </pre> 1515 <p>And here is a list of Montage() parameters you can set:</p> 1516 <table border="1" class="docutils"> 1517 <caption>Montage Parameters</caption> 1518 <colgroup> 1519 <col width="15%" /> 1520 <col width="52%" /> 1521 <col width="32%" /> 1522 </colgroup> 1523 <tbody valign="top"> 1524 <tr><td>Parameter</td> 1525 <td>Values</td> 1526 <td>Description</td> 1527 </tr> 1528 <tr><td>background</td> 1529 <td>color name</td> 1530 <td>background color name</td> 1531 </tr> 1532 <tr><td>borderwidth</td> 1533 <td>integer</td> 1534 <td>image border width</td> 1535 </tr> 1536 <tr><td>compose</td> 1537 <td>{Over, In, Out, Atop, Xor, Plus, 1538 Minus, Add, Subtract, Difference, 1539 Bumpmap, Copy, Mask, Dissolve, Clear, 1540 Displace}</td> 1541 <td>composite operator</td> 1542 </tr> 1543 <tr><td>filename</td> 1544 <td>string</td> 1545 <td>name of montage image</td> 1546 </tr> 1547 <tr><td>fill</td> 1548 <td>color name</td> 1549 <td>fill color for 1550 annotations</td> 1551 </tr> 1552 <tr><td>font</td> 1553 <td>string</td> 1554 <td>X11 font name</td> 1555 </tr> 1556 <tr><td>frame</td> 1557 <td>geometry</td> 1558 <td>surround the image with 1559 an ornamental border</td> 1560 </tr> 1561 <tr><td>geometry</td> 1562 <td>geometry</td> 1563 <td>preferred tile and 1564 border size of each 1565 tile of the composite 1566 image</td> 1567 </tr> 1568 <tr><td>gravity</td> 1569 <td>{NorthWest, North, NorthEast, West, 1570 Center, East, SouthWest, South, 1571 SouthEast}</td> 1572 <td>direction image 1573 gravitates to within a 1574 tile</td> 1575 </tr> 1576 <tr><td>ICM</td> 1577 <td>blob</td> 1578 <td>color information 1579 profile</td> 1580 </tr> 1581 <tr><td>IPTC</td> 1582 <td>blob</td> 1583 <td>newswire information 1584 profile</td> 1585 </tr> 1586 <tr><td>label</td> 1587 <td>string</td> 1588 <td>assign a label to an 1589 image</td> 1590 </tr> 1591 <tr><td>mode</td> 1592 <td>{Frame, Unframe, Concatenate}</td> 1593 <td>thumbnail framing 1594 options</td> 1595 </tr> 1596 <tr><td>pointsize</td> 1597 <td>integer</td> 1598 <td>pointsize of the 1599 Postscript or TrueType 1600 font</td> 1601 </tr> 1602 <tr><td>shadow</td> 1603 <td>{True, False}</td> 1604 <td>add a shadow beneath a 1605 tile to simulate depth</td> 1606 </tr> 1607 <tr><td>stroke</td> 1608 <td>color name</td> 1609 <td>stroke color for 1610 annotations</td> 1611 </tr> 1612 <tr><td>texture</td> 1613 <td>string</td> 1614 <td>name of texture to tile 1615 onto the image 1616 background</td> 1617 </tr> 1618 <tr><td>tile</td> 1619 <td>geometry</td> 1620 <td>number of tiles per row 1621 and column</td> 1622 </tr> 1623 <tr><td>title</td> 1624 <td>string</td> 1625 <td>assign a title to the 1626 image montage</td> 1627 </tr> 1628 <tr><td>transparent</td> 1629 <td>string</td> 1630 <td>make this color 1631 transparent within the 1632 image</td> 1633 </tr> 1634 </tbody> 1635 </table> 1636 <p>Note, that the geometry parameter is a short cut for the width and height 1637 parameters (e.g. geometry=>'106x80' is equivalent to width=>106, height=> 1638 80).</p> 1639 <p>MontageImage() is an alias for method Montage().</p> 1640 <p>Most of the attributes listed above have an analog in montage. See the 1641 documentation for a more detailed description of these attributes.</p> 1642 </div> 1643 <div class="section" id="working-with-blobs"> 1644 <h1><a class="toc-backref" href="#id13">Working with Blobs</a></h1> 1645 <p>A blob contains data that directly represent a particular image format in 1646 memory instead of on disk. PerlMagick supports blobs in any of these 1647 image formats and provides methods to convert a blob to or from a 1648 particular image format.</p> 1649 <table border="1" class="docutils"> 1650 <caption>Blob Methods</caption> 1651 <colgroup> 1652 <col width="16%" /> 1653 <col width="14%" /> 1654 <col width="34%" /> 1655 <col width="36%" /> 1656 </colgroup> 1657 <tbody valign="top"> 1658 <tr><td>Method</td> 1659 <td>Parameters</td> 1660 <td>Return Value</td> 1661 <td>Description</td> 1662 </tr> 1663 <tr><td>ImageToBlob</td> 1664 <td>any image 1665 attribute</td> 1666 <td>an array of image data 1667 in the respective image 1668 format</td> 1669 <td>convert an image or image 1670 sequence to an array of 1671 blobs</td> 1672 </tr> 1673 <tr><td>BlobToImage</td> 1674 <td>one or 1675 more blobs</td> 1676 <td>the number of blobs 1677 converted to an image</td> 1678 <td>convert one or more blobs 1679 to an image</td> 1680 </tr> 1681 </tbody> 1682 </table> 1683 <p>ImageToBlob() returns the image data in their respective formats. You can 1684 then print it, save it to an ODBC database, write it to a file, or pipe 1685 it to a display program:</p> 1686 <pre class="literal-block"> 1687 @blobs = $image->ImageToBlob(); 1688 open(DISPLAY,"| display -") || die; 1689 binmode DISPLAY; 1690 print DISPLAY $blobs[0]; 1691 close DISPLAY; 1692 </pre> 1693 <p>Method BlobToImage() returns an image or image sequence converted from 1694 the supplied blob:</p> 1695 <pre class="literal-block"> 1696 @blob=$db->GetImage(); 1697 $image=Graphics::Magick->new(magick=>'jpg'); 1698 $image->BlobToImage(@blob); 1699 </pre> 1700 </div> 1701 <div class="section" id="miscellaneous-methods"> 1702 <h1><a class="toc-backref" href="#id14">Miscellaneous Methods</a></h1> 1703 <p>The Append() method append a set of images. For example,</p> 1704 <pre class="literal-block"> 1705 $p = $image->Append(stack=>{true,false}); 1706 </pre> 1707 <p>appends all the images associated with object $image. By default, images 1708 are stacked left-to-right. Set stack to True to stack them top-to-bottom.</p> 1709 <p>The Average() method averages a set of images. For example,</p> 1710 <pre class="literal-block"> 1711 $p = $image->Average(); 1712 </pre> 1713 <p>averages all the images associated with object $image.</p> 1714 <p>The Clone() method copies a set of images. For example,</p> 1715 <pre class="literal-block"> 1716 $p = $image->Clone(); 1717 </pre> 1718 <p>copies all the images from object $q to $p. You can use this method for 1719 single or multi-image sequences.</p> 1720 <p>The Morph() method morphs a set of images. Both the image pixels and size 1721 are linearly interpolated to give the appearance of a meta-morphosis from 1722 one image to the next:</p> 1723 <pre class="literal-block"> 1724 $p = $image->Morph(frames=>integer); 1725 </pre> 1726 <p>where frames is the number of in-between images to generate. The default 1727 is 1.</p> 1728 <p>Mosaic() creates an mosaic from an image sequence.</p> 1729 <p>Method Mogrify() is a single entry point for the image manipulation 1730 methods (Manipulate an Image). The parameters are the name of a method 1731 followed by any parameters the method may require. For example, these 1732 calls are equivalent:</p> 1733 <pre class="literal-block"> 1734 $image->Crop('340x256+0+0'); 1735 $image->Mogrify('crop', '340x256+0+0'); 1736 </pre> 1737 <p>Method MogrifyRegion() applies a transform to a region of the image. It 1738 is similar to Mogrify() but begins with the region geometry. For example, 1739 suppose you want to brighten a 100x100 region of your image at location 1740 (40, 50):</p> 1741 <pre class="literal-block"> 1742 $image->MogrifyRegion('100x100+40+50', 'modulate', brightness=>50); 1743 </pre> 1744 <p>Ping() is a convenience method that returns information about an image 1745 without having to read the image into memory. It returns the width, 1746 height, file size in bytes, and the file format of the image. You can 1747 specify more than one filename but only one filehandle:</p> 1748 <pre class="literal-block"> 1749 ($width, $height, $size, $format) = $image->Ping('logo.png'); 1750 ($width, $height, $size, $format) = $image->Ping(file=>\*IMAGE); 1751 ($width, $height, $size, $format) = $image->Ping(blob=>@blob); 1752 </pre> 1753 <p>This is a more efficient and less memory intensive way to query if an 1754 image exists and what its characteristics are.</p> 1755 <p>To have full control over text positioning you need font metric 1756 information. Use</p> 1757 <pre class="literal-block"> 1758 ($x_ppem, $y_ppem, $ascender, $descender, $width, $height, $max_advance) = 1759 $image->QueryFontMetrics(parameters); 1760 1761 Where parameters is any parameter of the Annotate method. The 1762 'text' parameter must be specified since there can be no default for 1763 the text to render. The return values are 1764 1765 * character width 1766 * character height 1767 * ascender 1768 * descender 1769 * text width 1770 * text height 1771 * maximum horizontal advance 1772 </pre> 1773 <p>Call QueryColor() with no parameters to return a list of known colors 1774 names or specify one or more color names to get these attributes: red, 1775 green, blue, and opacity value.</p> 1776 <pre class="literal-block"> 1777 @colors = $image->QueryColor(); 1778 ($red, $green, $blue, $opacity) = $image->QueryColor('cyan'); 1779 ($red, $green, $blue, $opacity) = $image->QueryColor('#716bae'); 1780 </pre> 1781 <p>QueryColorname() accepts a color value and returns its respective name or 1782 hex value;</p> 1783 <pre class="literal-block"> 1784 $name = $image->QueryColorname('rgba(80,60,0,0)'); 1785 </pre> 1786 <p>Call QueryFont() with no parameters to return a list of known fonts or 1787 specify one or more font names to get these attributes: font name, 1788 description, family, style, stretch, weight, encoding, foundry, format, 1789 metrics, and glyphs values.</p> 1790 <pre class="literal-block"> 1791 @fonts = $image->QueryFont(); 1792 $weight = ($image->QueryFont('Helvetica'))[5]; 1793 </pre> 1794 <p>Call QueryFormat() with no parameters to return a list of known image 1795 formats or specify one or more format names to get these attributes: 1796 adjoin, blob support, raw, decoder, encoder, description, and module.</p> 1797 <pre class="literal-block"> 1798 @formats = $image->QueryFormat(); 1799 ($adjoin, $blob_support, $raw, $decoder, $encoder, $description, $module) = $image->QueryFormat('gif'); 1800 </pre> 1801 <p>Use RemoteCommand() to send a command to an already running display or 1802 animate application. The only parameter is the name of the image file to 1803 display or animate.</p> 1804 <p>Finally, the Transform() method accepts a fully-qualified geometry 1805 specification for cropping or resizing one or more images. For example,</p> 1806 <pre class="literal-block"> 1807 $p = $image->Transform(crop=>'100x100'); 1808 </pre> 1809 <p>You can optionally add Image to any method name above. For example, 1810 PingImage() is an alias for method Ping().</p> 1811 </div> 1812 <div class="section" id="handling-errors"> 1813 <h1><a class="toc-backref" href="#id15">Handling Errors</a></h1> 1814 <p>All PerlMagick methods return an undefined string context upon success. If 1815 any problems occur, the error is returned as a string with an embedded 1816 numeric status code. A status code less than 400 is a warning. This means 1817 that the operation did not complete but was recoverable to some degree. A 1818 numeric code greater or equal to 400 is an error and indicates the 1819 operation failed completely. Here is how errors are returned for the 1820 different methods:</p> 1821 <blockquote> 1822 <ul> 1823 <li><p class="first">Methods which return a number (e.g. Read(), Write()):</p> 1824 <pre class="literal-block"> 1825 $status = $image->Read(...); 1826 warn "$status" if "$status"; # print the error message 1827 $status =~ /(\d+)/; 1828 print $1; # print the error number 1829 print 0+$status; # print the number of images read 1830 </pre> 1831 </li> 1832 <li><p class="first">Methods which operate on an image (e.g. Resize(), Crop()):</p> 1833 <pre class="literal-block"> 1834 $status = $image->Crop(...); 1835 warn "$status" if "$status"; # print the error message 1836 $status =~ /(\d+)/; 1837 print $1; # print the error number 1838 </pre> 1839 </li> 1840 <li><p class="first">Methods which return images (Average(), Montage(), Clone()) should be 1841 checked for errors this way:</p> 1842 <pre class="literal-block"> 1843 $status = $image->Montage(...); 1844 warn "$status" if !ref($status); # print the error message 1845 $status =~ /(\d+)/; 1846 print $1; # print the error number 1847 </pre> 1848 </li> 1849 </ul> 1850 </blockquote> 1851 <p>Here is an example error message:</p> 1852 <pre class="literal-block"> 1853 Error 400: Memory allocation failed 1854 </pre> 1855 <p>Below is a list of error and warning codes:</p> 1856 <table border="1" class="docutils"> 1857 <caption>Error and Warning Codes</caption> 1858 <colgroup> 1859 <col width="6%" /> 1860 <col width="31%" /> 1861 <col width="63%" /> 1862 </colgroup> 1863 <tbody valign="top"> 1864 <tr><td>Code</td> 1865 <td>Mnemonic</td> 1866 <td>Description</td> 1867 </tr> 1868 <tr><td>0</td> 1869 <td>Success</td> 1870 <td>method completed without an error or warning</td> 1871 </tr> 1872 <tr><td>300</td> 1873 <td>ResourceLimitWarning</td> 1874 <td>a program resource is exhausted (e.g. not 1875 enough memory)</td> 1876 </tr> 1877 <tr><td>305</td> 1878 <td>TypeWarning</td> 1879 <td>A font is unavailable; a substitution may 1880 have occurred</td> 1881 </tr> 1882 <tr><td>310</td> 1883 <td>OptionWarning</td> 1884 <td>a command-line option was malformed</td> 1885 </tr> 1886 <tr><td>315</td> 1887 <td>DelegateWarning</td> 1888 <td>an GraphicsMagick delegate returned a warning</td> 1889 </tr> 1890 <tr><td>320</td> 1891 <td>MissingDelegateWarning</td> 1892 <td>the image type can not be read or written 1893 because the appropriate Delegate is missing</td> 1894 </tr> 1895 <tr><td>325</td> 1896 <td>CorruptImageWarning</td> 1897 <td>the image file may be corrupt</td> 1898 </tr> 1899 <tr><td>330</td> 1900 <td>FileOpenWarning</td> 1901 <td>the image file could not be opened</td> 1902 </tr> 1903 <tr><td>335</td> 1904 <td>BlobWarning</td> 1905 <td>a binary large object could not be allocated</td> 1906 </tr> 1907 <tr><td>340</td> 1908 <td>StreamWarning</td> 1909 <td>there was a problem reading or writing from a 1910 stream</td> 1911 </tr> 1912 <tr><td>345</td> 1913 <td>CacheWarning</td> 1914 <td>pixels could not be saved to the pixel cache</td> 1915 </tr> 1916 <tr><td>350</td> 1917 <td>CoderWarning</td> 1918 <td>there was a problem with an image coder</td> 1919 </tr> 1920 <tr><td>355</td> 1921 <td>ModuleWarning</td> 1922 <td>there was a problem with an image module</td> 1923 </tr> 1924 <tr><td>360</td> 1925 <td>DrawWarning</td> 1926 <td>a drawing operation failed</td> 1927 </tr> 1928 <tr><td>365</td> 1929 <td>ImageWarning</td> 1930 <td>the operation could not complete due to an 1931 incompatible image</td> 1932 </tr> 1933 <tr><td>380</td> 1934 <td>XServerWarning</td> 1935 <td>an X resource is unavailable</td> 1936 </tr> 1937 <tr><td>385</td> 1938 <td>MonitorWarning</td> 1939 <td>there was a problem with prgress monitor</td> 1940 </tr> 1941 <tr><td>390</td> 1942 <td>RegistryWarning</td> 1943 <td>there was a problem getting or setting the 1944 registry</td> 1945 </tr> 1946 <tr><td>395</td> 1947 <td>ConfigureWarning</td> 1948 <td>there was a problem getting a configuration 1949 file</td> 1950 </tr> 1951 <tr><td>400</td> 1952 <td>ResourceLimitError</td> 1953 <td>a program resource is exhausted (e.g. not 1954 enough memory)</td> 1955 </tr> 1956 <tr><td>405</td> 1957 <td>TypeError</td> 1958 <td>A font is unavailable; a substitution may 1959 have occurred</td> 1960 </tr> 1961 <tr><td>410</td> 1962 <td>OptionError</td> 1963 <td>a command-line option was malformed</td> 1964 </tr> 1965 <tr><td>415</td> 1966 <td>DelegateError</td> 1967 <td>an GraphicsMagick delegate returned a warning</td> 1968 </tr> 1969 <tr><td>420</td> 1970 <td>MissingDelegateError</td> 1971 <td>the image type can not be read or written 1972 because the appropriate Delegate is missing</td> 1973 </tr> 1974 <tr><td>425</td> 1975 <td>CorruptImageError</td> 1976 <td>the image file may be corrupt</td> 1977 </tr> 1978 <tr><td>430</td> 1979 <td>FileOpenError</td> 1980 <td>the image file could not be opened</td> 1981 </tr> 1982 <tr><td>435</td> 1983 <td>BlobError</td> 1984 <td>a binary large object could not be allocated</td> 1985 </tr> 1986 <tr><td>440</td> 1987 <td>StreamError</td> 1988 <td>there was a problem reading or writing from a 1989 stream</td> 1990 </tr> 1991 <tr><td>445</td> 1992 <td>CacheError</td> 1993 <td>pixels could not be saved to the pixel cache</td> 1994 </tr> 1995 <tr><td>450</td> 1996 <td>CoderError</td> 1997 <td>there was a problem with an image coder</td> 1998 </tr> 1999 <tr><td>455</td> 2000 <td>ModuleError</td> 2001 <td>there was a problem with an image module</td> 2002 </tr> 2003 <tr><td>460</td> 2004 <td>DrawError</td> 2005 <td>a drawing operation failed</td> 2006 </tr> 2007 <tr><td>465</td> 2008 <td>ImageError</td> 2009 <td>the operation could not complete due to an 2010 incompatible image</td> 2011 </tr> 2012 <tr><td>480</td> 2013 <td>XServerError</td> 2014 <td>an X resource is unavailable</td> 2015 </tr> 2016 <tr><td>480</td> 2017 <td>MonitorError</td> 2018 <td>there was a progress monitor error</td> 2019 </tr> 2020 <tr><td>490</td> 2021 <td>RegistryError</td> 2022 <td>there was a problem getting or setting the 2023 registry</td> 2024 </tr> 2025 <tr><td>495</td> 2026 <td>ConfigureError</td> 2027 <td>there was a problem getting a configuration 2028 file</td> 2029 </tr> 2030 </tbody> 2031 </table> 2032 <p>The following illustrates how you can use a numeric status code:</p> 2033 <pre class="literal-block"> 2034 $status = $image->Read('rose.png'); 2035 $status =~ /(\d+)/; 2036 die "unable to continue" if ($1 == ResourceLimitError); 2037 </pre> 2038 <hr class="docutils" /> 2039 <p>Copyright © GraphicsMagick Group 2002 - 2020</p> 2040 </div> 2041 </div> 2042 </body> 2043 </html>