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

   1 \r
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"\r
   3     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">\r
   4 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" dir="ltr">\r
   5 <head>\r
   6   <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>\r
   7   <meta name="verify-v1" content="g222frIIxcQTrvDR3NBRUSKP3AnMNoqxOkIniCEkV7U="/>\r
   8   <title>ImageMagick: MagickWand, C API for ImageMagick</title/>
   9   <meta http-equiv="Content-Language" content="en-US"/>
  10   <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
  11   <meta http-equiv="Reply-to" content="magick-users@imagemagick.org"/>
  12   <meta name="Application-name" content="ImageMagick"/>
  13   <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."/>
  14   <meta name="Application-url" content="http://www.imagemagick.org"/>
  15   <meta name="Generator" content="PHP"/>
  16   <meta name="Keywords" content="magickwc, api, for, imagemagick, ImageMagick, ImageMagic, MagickCore, MagickWand, PerlMagick, Magick++, RMagick, PythonMagick, JMagick, TclMagick, Image, Magick, Magic, Wand, ImageMagickObject, Swiss, Army, Knife, Image, Processing"/>
  17   <meta name="Rating" content="GENERAL"/>
  18   <meta name="Robots" content="INDEX, FOLLOW"/>
  19   <meta name="Generator" content="ImageMagick Studio LLC"/>
  20   <meta name="Author" content="ImageMagick Studio LLC"/>
  21   <meta name="Revisit-after" content="2 DAYS"/>
  22   <meta name="Resource-type" content="document"/>
  23   <meta name="Copyright" content="Copyright (c) 1999-2010 ImageMagick Studio LLC"/>
  24   <meta name="Distribution" content="Global"/>
  25   <link rel="icon" href="../images/wand.png"  sizes="32x32"/>
  26   <link rel="shortcut icon" href="../images/wand.ico"  type="images/x-icon"/>
  27   <link rel="meta" type="application/rdf+xml" title="ICI" href="http://imagemagick.org/ici.rdf"/>\r
  28   <style type="text/css" media="all">\r
  29     @import url("../www/magick.css");\r
  30   </style>\r
  31 </head>\r
  32 \r
  33 <body id="www-imagemagick-org">\r
  34 <div class="titlebar">\r
  35 <a href="../index.html">\r
  36   <img src="../images/script.png" alt="[ImageMagick]"\r
  37   style="width: 350px; height: 60px; margin: 28px auto; float: left;" /></a>\r
  38 <a href="http://www.networkredux.com">\r
  39   <img src="../images/networkredux.png" alt="[sponsor]"\r
  40   style="margin: 45px auto; border: 0px; float: left;" /></a>\r
  41 <a href="http://www.imagemagick.org/discourse-server/">\r
  42   <img src="../images/logo.jpg" alt=""\r
  43   style="width: 114px; height: 118px; border: 0px; float: right;" /></a>\r
  44 <a href="../index.html">\r
  45   <img src="../images/sprite.jpg" alt=""\r
  46   style="width: 114px; height: 118px; border: 0px; float: right;" /></a>\r
  47 </div>\r
  48 \r
  49 <div class="westbar">\r
  50 \r
  51 <div class="menu">
  52   <a title="About ImageMagick" href="../index.html">About ImageMagick</a>
  53 </div>
  54 <div class="sep"></div>\r
  55 <div class="menu">
  56   <a title="Binary Releases" href="../www/binary-releases.html">Binary Releases</a>
  57 </div>
  58 <div class="sub">
  59     <a title="Binary Release: Unix" href="../www/binary-releases.html#unix">Unix</a>
  60 </div>
  61 <div class="sub">
  62     <a title="Binary Release: MacOS X" href="../www/binary-releases.html#macosx">Mac OS X</a>
  63 </div>
  64 <div class="sub">
  65     <a title="Binary Release: Windows" href="../www/binary-releases.html#windows">Windows</a>
  66 </div>
  67 <div class="sep"></div>\r
  68 <div class="menu">
  69   <a title="Command-line Tools" href="../www/command-line-tools.html">Command-line Tools</a>
  70 </div>
  71 <div class="sub">
  72     <a title="Command-line Tools: Processing" href="../www/command-line-processing.html">Processing</a>
  73 </div>
  74 <div class="sub">
  75     <a title="Command-line Tools: Options" href="../www/command-line-options.html">Options</a>
  76 </div>
  77 <div class="sub">
  78     <a title="Command-line Tools: Usage" href="http://www.imagemagick.org/Usage/">Usage</a>
  79 </div>
  80 <div class="menu">
  81   <a title="Program Interfaces" href="../www/api.html">Program Interfaces</a>
  82 </div>
  83 <div class="sub">
  84     <a title="Program Interface: MagickWand" href="../www/magick-wand.html">MagickWand</a>
  85 </div>
  86 <div class="sub">
  87     <a title="Program Interface: MagickCore" href="../www/magick-core.html">MagickCore</a>
  88 </div>
  89 <div class="sub">
  90     <a title="Program Interface: PerlMagick" href="../www/perl-magick.html">PerlMagick</a>
  91 </div>
  92 <div class="sub">
  93     <a title="Program Interface: Magick++" href="../Magick++/">Magick++</a>
  94 </div>
  95 <div class="sep"></div>\r
  96 <div  class="menu">
  97    <a title="Install from Source" href="../www/install-source.html">Install from Source</a>
  98 </div>
  99 <div class="sub">
 100     <a title="Install from Source: Unix" href="../www/install-source.html#unix">Unix</a>
 101 </div>
 102 <div class="sub">
 103     <a title="Install from Source: Windows" href="../www/install-source.html#windows">Windows</a>
 104  </div>
 105 <div class="menu">
 106   <a title="Resources" href="../www/resources.html">Resources</a>
 107 </div>
 108 <div class="menu">
 109   <a title="Architecture" href="../www/architecture.html">Architecture</a>
 110 </div>
 111 <div class="menu">
 112   <a title="Download" href="../www/download.html">Download</a>
 113 </div>
 114 <div class="sep"></div>\r
 115 <div class="menu">
 116   <a title="Search" href="http://www.imagemagick.org/script/search.php">Search</a>
 117 </div>
 118 <div class="sep"></div>\r
 119 <div class="menu">
 120   <a title="Site Map"href="../www/sitemap.html">Site Map</a>
 121 </div>
 122 <div  class="sub">
 123     <a title="Site Map: Links"href="../www/links.html">Links</a>
 124 </div>
 125 <div class="sep"></div>\r
 126 <div  class="menu">
 127   <a title="Sponsors" href="../www/sponsors.html">Sponsors:</a>
 128
 129 <div class="sponsbox">
 130 <div  class="sponsor">
 131    <a title="Sponsor: alaTest.com" href="http://alatest.com">alaTest.com</a><!-- 20110801000300 -->
 132 </div>
 133 <div  class="sponsor">
 134   <a title="Sponsor: Druckerei" href="http://print24.com/de/">Druckerei</a><!-- 201110010720 -->
 135 </div>
 136 <div  class="sponsor">
 137   <a title="Sponsor: Image Converter" href="http://www.batchphoto.com">Image Converter</a><!-- 201103010900 Bits Coffee-->
 138 </div>
 139 <div  class="sponsor">
 140   <a title="Sponsor: Flyer drucken" href="http://www.online-druck.biz">Flyer drucken</a><!-- 201109010900 Floeter-->
 141 </div>
 142 <div  class="sponsor">
 143   <a title="Sponsor: Webdesign Agentur" href="http://www.ventzke-partner.de">Webdesign Agentur</a><!-- 201101010480 invendio.de-->
 144 </div>
 145 <div  class="sponsor">
 146   <a title="Sponsor: LVM Versicherung" href="http://www.neu-reich.de">LVM Versicherung</a><!-- 201101010480 -->
 147 </div>
 148 <div  class="sponsor">
 149   <a title="Sponsor: Diamonds are a Girls Best Friend" href="http://www.schmuck.org">Diamonds are a Girls Best Friend</a><!-- 201101010600 Peterssen-->
 150 </div>
 151 <div  class="sponsor">
 152    <a title="Sponsor: Druckerei Online" href="http://www.allesdruck.de">Druckerei Online</a><!-- 201012011200 allesdruck.de-->
 153 </div>
 154 </div>
 155 </div>
 156 </div>\r
 157 \r
 158 <div class="eastbar">\r
 159   <script type="text/javascript">\r
 160   <!--\r
 161     google_ad_client = "pub-3129977114552745";\r
 162     google_ad_slot = "0574824969";\r
 163     google_ad_width = 160;\r
 164     google_ad_height = 600;\r
 165   //-->\r
 166   </script>\r
 167   <script type="text/javascript"\r
 168     src="http://pagead2.googlesyndication.com/pagead/show_ads.js">\r
 169   </script>\r
 170 </div>\r
 171 \r
 172 <div class="main">\r
 173 \r
 174 <p class="navigation-index"></p>
 175
 176 <p>The <a href="../www/api/MagickWand/index.html">MagickWand API</a> is the recommended interface between the C programming language and the ImageMagick image processing libraries.  Unlike the <a href="../www/magick-core.html">MagickCore</a> C API, MagickWand uses only a few opaque types.  Accessors are available to set or get important wand properties.  A description of the MagickWand public methods are found here:</p>
 177
 178 <ul>
 179   <li><a href="../www/api/magick-wand.html">Magick Wand Methods</a></li>
 180   <li><a href="../www/api/magick-property.html">Set or Get Magick Wand Properties</a></li>
 181   <li><a href="../www/api/magick-image.html">Magick Wand Image Methods</a></li>
 182   <li><a href="../www/api/pixel-iterator.html">Pixel Iterator Methods</a></li>
 183   <li><a href="../www/api/pixel-wand.html">Pixel Wand Methods</a></li>
 184   <li><a href="../www/api/drawing-wand.html">Image Vector Drawing</a></li>
 185   <li><a href="../www/api/mogrify.html">Command-line Interface</a></li>
 186   <li><a href="../www/api/wand-view.html">Wand View Methods</a></li>
 187   <li><a href="../www/api/magick-deprecate.html">Deprecated Methods</a></li>
 188   <li><a href="../www/exception.html">Error and Warning Codes</a></li>
 189 </li>
 190 </ul>
 191
 192 <p>After you write your MagickWand program, compile it like this:</p>
 193
 194 <p class='crt'><span class="crtprompt"> $magick&gt; </span><span class='crtin'>cc `MagickWand-config --cflags --cppflags` -O2 -o wand wand.c  \ <br/> `MagickWand-config --ldflags --libs`</span></p>
 195 <p>Here is a example program that utilizes the MagickWand API to get you started, <a href="../www/source/wand.c">wand.c</a>. It reads an image, creates a thumbnail, and writes the result to disk.</p>
 196
 197 <div class="viewport">
 198 <pre class="code">
 199 #include &lt;stdio.h>
 200 #include &lt;stdlib.h>
 201 #include &lt;wand/MagickWand.h>
 202
 203 int main(int argc,char **argv)
 204 {
 205 #define ThrowWandException(wand) \
 206 { \
 207   char \
 208     *description; \
 209  \
 210   ExceptionType \
 211     severity; \
 212  \
 213   description=MagickGetException(wand,&amp;severity); \
 214   (void) fprintf(stderr,"%s %s %u %s\n",GetMagickModule(),description); \
 215   description=(char *) MagickRelinquishMemory(description); \
 216   exit(-1); \
 217 }
 218
 219   MagickBooleanType
 220     status;
 221
 222   MagickWand
 223     *magick_wand;
 224
 225   if (argc != 3)
 226     {
 227       (void) fprintf(stdout,"Usage: %s image thumbnail\n",argv[0]);
 228       exit(0);
 229     }
 230   /*
 231     Read an image.
 232   */
 233   MagickWandGenesis();
 234   magick_wand=NewMagickWand();
 235   status=MagickReadImage(magick_wand,argv[1]);
 236   if (status == MagickFalse)
 237     ThrowWandException(magick_wand);
 238   /*
 239     Turn the images into a thumbnail sequence.
 240   */
 241   MagickResetIterator(magick_wand);
 242   while (MagickNextImage(magick_wand) != MagickFalse)
 243     MagickResizeImage(magick_wand,106,80,LanczosFilter,1.0);
 244   /*
 245     Write the image then destroy it.
 246   */
 247   status=MagickWriteImages(magick_wand,argv[2],MagickTrue);
 248   if (status == MagickFalse)
 249     ThrowWandException(magick_wand);
 250   magick_wand=DestroyMagickWand(magick_wand);
 251   MagickWandTerminus();
 252   return(0);
 253 }
 254 </pre>
 255 </div>
 256
 257 <p>Here is another program that shows one way to get and set image pixels with the MagickWand API, <a href="../www/source/contrast.c">contrast.c</a>. It reads an image, applies sigmoidal non-linearity contrast control, and writes the result to disk.</p>
 258
 259 <div class="viewport">
 260 <pre class="code">
 261 #include &lt;stdio.h>
 262 #include &lt;stdlib.h>
 263 #include &lt;math.h>
 264 #include &lt;wand/MagickWand.h>
 265
 266 int main(int argc,char **argv)
 267 {
 268 #define QuantumScale  ((MagickRealType) 1.0/(MagickRealType) QuantumRange)
 269 #define SigmoidalContrast(x) \
 270   (QuantumRange*(1.0/(1+exp(10.0*(0.5-QuantumScale*x)))-0.0066928509)*1.0092503)
 271 #define ThrowWandException(wand) \
 272 { \
 273   char \
 274     *description; \
 275  \
 276   ExceptionType \
 277     severity; \
 278  \
 279   description=MagickGetException(wand,&amp;severity); \
 280   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
 281   description=(char *) MagickRelinquishMemory(description); \
 282   exit(-1); \
 283 }
 284
 285   long
 286     y;
 287
 288   MagickBooleanType
 289     status;
 290
 291   MagickPixelPacket
 292     pixel;
 293
 294   MagickWand
 295     *contrast_wand,
 296     *image_wand;
 297
 298   PixelIterator
 299     *contrast_iterator,
 300     *iterator;
 301
 302   PixelWand
 303     **contrast_pixels,
 304     **pixels;
 305
 306   register long
 307     x;
 308
 309   unsigned long
 310     width;
 311
 312   if (argc != 3)
 313     {
 314       (void) fprintf(stdout,"Usage: %s image sigmoidal-image\n",argv[0]);
 315       exit(0);
 316     }
 317   /*
 318     Read an image.
 319   */
 320   MagickWandGenesis();
 321   image_wand=NewMagickWand();
 322   status=MagickReadImage(image_wand,argv[1]);
 323   if (status == MagickFalse)
 324     ThrowWandException(image_wand);
 325   contrast_wand=CloneMagickWand(image_wand);
 326   /*
 327     Sigmoidal non-linearity contrast control.
 328   */
 329   iterator=NewPixelIterator(image_wand);
 330   contrast_iterator=NewPixelIterator(contrast_wand);
 331   if ((iterator == (PixelIterator *) NULL) ||
 332       (contrast_iterator == (PixelIterator *) NULL))
 333     ThrowWandException(image_wand);
 334   for (y=0; y &lt; (long) MagickGetImageHeight(image_wand); y++)
 335   {
 336     pixels=PixelGetNextIteratorRow(iterator,&amp;width);
 337     contrast_pixels=PixelGetNextIteratorRow(contrast_iterator,&amp;width);
 338     if ((pixels == (PixelWand **) NULL) ||
 339         (contrast_pixels == (PixelWand **) NULL))
 340       break;
 341     for (x=0; x &lt; (long) width; x++)
 342     {
 343       PixelGetMagickColor(pixels[x],&amp;pixel);
 344       pixel.red=SigmoidalContrast(pixel.red);
 345       pixel.green=SigmoidalContrast(pixel.green);
 346       pixel.blue=SigmoidalContrast(pixel.blue);
 347       pixel.index=SigmoidalContrast(pixel.index);
 348       PixelSetMagickColor(contrast_pixels[x],&amp;pixel);
 349     }
 350     (void) PixelSyncIterator(contrast_iterator);
 351   }
 352   if (y &lt; (long) MagickGetImageHeight(image_wand))
 353     ThrowWandException(image_wand);
 354   contrast_iterator=DestroyPixelIterator(contrast_iterator);
 355   iterator=DestroyPixelIterator(iterator);
 356   image_wand=DestroyMagickWand(image_wand);
 357   /*
 358     Write the image then destroy it.
 359   */
 360   status=MagickWriteImages(contrast_wand,argv[2],MagickTrue);
 361   if (status == MagickFalse)
 362     ThrowWandException(image_wand);
 363   contrast_wand=DestroyMagickWand(contrast_wand);
 364   MagickWandTerminus();
 365   return(0);
 366 }
 367 </pre>
 368 </div>
 369 <p><a name="wand-view"></a>Now lets perform the same contrast enhancement while taking advantage of our dual or quad-core processing system by running the algorithm in parallel utilizing wand views.  The <a href="../www/source/wand/sigmoidal-contrast.c">sigmoidal-contrast.c</a> module reads an image, applies sigmoidal non-linearity contrast control, and writes the result to disk just like the previous contrast enhancement program, but now it does its work in parallel (assumes ImageMagick is built with OpenMP support).</p>
 370
 371 <div class="viewport">
 372 <pre class="code">
 373 #include &lt;stdio.h>
 374 #include &lt;stdlib.h>
 375 #include &lt;math.h>
 376 #include &lt;wand/MagickWand.h>
 377
 378 static MagickBooleanType SigmoidalContrast(WandView *pixel_view,
 379   const ssize_t y,const int id,void *context)
 380 {
 381 #define QuantumScale  ((MagickRealType) 1.0/(MagickRealType) QuantumRange)
 382 #define SigmoidalContrast(x) \
 383   (QuantumRange*(1.0/(1+exp(10.0*(0.5-QuantumScale*x)))-0.0066928509)*1.0092503)
 384
 385   RectangleInfo
 386     extent;
 387
 388   MagickPixelPacket
 389     pixel;
 390
 391   PixelWand
 392     **pixels;
 393
 394   register long
 395     x;
 396
 397   extent=GetWandViewExtent(contrast_view);
 398   pixels=GetWandViewPixels(contrast_view);
 399   for (x=0; x &lt; (long) (extent.width-extent.height); x++)
 400   {
 401     PixelGetMagickColor(pixels[x],&amp;pixel);
 402     pixel.red=SigmoidalContrast(pixel.red);
 403     pixel.green=SigmoidalContrast(pixel.green);
 404     pixel.blue=SigmoidalContrast(pixel.blue);
 405     pixel.index=SigmoidalContrast(pixel.index);
 406     PixelSetMagickColor(contrast_pixels[x],&amp;pixel);
 407   }
 408   return(MagickTrue);
 409 }
 410
 411 int main(int argc,char **argv)
 412 {
 413 #define ThrowViewException(view) \
 414 { \
 415   description=GetWandViewException(view,&severity); \
 416   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
 417   description=(char *) MagickRelinquishMemory(description); \
 418   exit(-1); \
 419 }
 420 #define ThrowWandException(wand) \
 421 { \
 422   description=MagickGetException(wand,&severity); \
 423   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
 424   description=(char *) MagickRelinquishMemory(description); \
 425   exit(-1); \
 426 }
 427
 428   char
 429     *description;
 430
 431   ExceptionType
 432     severity;
 433
 434   MagickBooleanType
 435     status;
 436
 437   MagickPixelPacket
 438     pixel;
 439
 440   MagickWand
 441     *contrast_wand;
 442
 443   WandView
 444     *contrast_view;
 445
 446   if (argc != 3)
 447     {
 448       (void) fprintf(stdout,"Usage: %s image sigmoidal-image\n",argv[0]);
 449       exit(0);
 450     }
 451   /*
 452     Read an image.
 453   */
 454   MagickWandGenesis();
 455   contrast_wand=NewMagickWand();
 456   status=MagickReadImage(contrast_wand,argv[1]);
 457   if (status == MagickFalse)
 458     ThrowWandException(contrast_wand);
 459   /*
 460     Sigmoidal non-linearity contrast control.
 461   */
 462   contrast_view=NewWandView(contrast_wand);
 463   if (contrast_view == (WandView *) NULL)
 464     ThrowWandException(contrast_wand);
 465   status=UpdateWandViewIterator(contrast_view,SigmoidalContrast,(void *) NULL);
 466   if (status == MagickFalse)
 467     ThrowWandException(contrast_wand);
 468   contrast_view=DestroyWandView(contrast_view);
 469   /*
 470     Write the image then destroy it.
 471   */
 472   status=MagickWriteImages(contrast_wand,argv[2],MagickTrue);
 473   if (status == MagickFalse)
 474     ThrowWandException(contrast_wand);
 475   contrast_wand=DestroyMagickWand(contrast_wand);
 476   MagickWandTerminus();
 477   return(0);
 478 }
 479 </pre>
 480 </div>
 481 \r
 482 </div>\r
 483 \r
 484 <div id="linkbar">\r
 485     <span id="linkbar-west">&nbsp;</span>\r
 486     <span id="linkbar-center">\r
 487       <a href="http://www.imagemagick.org/discourse-server/">Discourse Server</a> &bull;\r
 488       <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Studio</a>\r
 489     </span>\r
 490     <span id="linkbar-east">&nbsp;</span>\r
 491   </div>\r
 492   <div class="footer">\r
 493     <span id="footer-west">&copy; 1999-2010 ImageMagick Studio LLC</span>\r
 494     <span id="footer-east"> <a href="http://www.imagemagick.org/script/contact.php">Contact the Wizards</a></span>\r
 495   </div>\r
 496   <div style="clear: both; margin: 0; width: 100%; "></div>\r
 497   <script type="text/javascript">\r
 498     var _gaq = _gaq || [];\r
 499     _gaq.push(['_setAccount', 'UA-17690367-1']);\r
 500     _gaq.push(['_trackPageview']);\r
 501 \r
 502     (function() {\r
 503       var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;\r
 504       ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';\r
 505       var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);\r
 506     })();\r
 507   </script>\r
 508 </body>\r
 509 </html>\r