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: Flyer drucken" href="http://www.online-druck.biz">Flyer drucken</a><!-- 201109010900 Floeter-->
 132 </div>
 133 <div  class="sponsor">
 134   <a title="Sponsor: Webdesign Agentur" href="http://www.ventzke-partner.de">Webdesign Agentur</a><!-- 201101010480 invendio.de-->
 135 </div>
 136 <div  class="sponsor">
 137   <a title="Sponsor: LVM Versicherung" href="http://www.neu-reich.de">LVM Versicherung</a><!-- 201101010480 -->
 138 </div>
 139 <div  class="sponsor">
 140   <a title="Sponsor: Deko.net" href="http://www.deko.net">Deko.net</a><!-- 201101010600 Peterssen-->
 141 </div>
 142 <div  class="sponsor">
 143   <a title="Sponsor: Druckerei" href="http://www.print24.de/">Druckerei</a><!-- 201009010720 -->
 144 </div>
 145 <div  class="sponsor">
 146    <a title="Sponsor: Druckerei Online" href="http://www.allesdruck.de">Druckerei Online</a><!-- 201012011200 allesdruck.de-->
 147 </div>
 148 <div  class="sponsor">
 149    <a title="Sponsor: Webdesign" href="http://www.renehornig.com/">Webdesign</a><!-- 20111001000240 -->
 150 </div>
 151 </div>
 152 </div>
 153 </div>\r
 154 \r
 155 <div class="eastbar">\r
 156   <script type="text/javascript">\r
 157   <!--\r
 158     google_ad_client = "pub-3129977114552745";\r
 159     google_ad_slot = "0574824969";\r
 160     google_ad_width = 160;\r
 161     google_ad_height = 600;\r
 162   //-->\r
 163   </script>\r
 164   <script type="text/javascript"\r
 165     src="http://pagead2.googlesyndication.com/pagead/show_ads.js">\r
 166   </script>\r
 167 </div>\r
 168 \r
 169 <div class="main">\r
 170 \r
 171 <p class="navigation-index"></p>
 172
 173 <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>
 174
 175 <ul>
 176   <li><a href="../www/api/magick-wand.html">Magick Wand Methods</a></li>
 177   <li><a href="../www/api/magick-property.html">Set or Get Magick Wand Properties</a></li>
 178   <li><a href="../www/api/magick-image.html">Magick Wand Image Methods</a></li>
 179   <li><a href="../www/api/pixel-iterator.html">Pixel Iterator Methods</a></li>
 180   <li><a href="../www/api/pixel-wand.html">Pixel Wand Methods</a></li>
 181   <li><a href="../www/api/drawing-wand.html">Image Vector Drawing</a></li>
 182   <li><a href="../www/api/wand-view.html">Wand View Methods</a></li>
 183   <li><a href="../www/api/magick-deprecate.html">Deprecated Methods</a></li>
 184   <li><a href="../www/exception.html">Error and Warning Codes</a></li>
 185 </li>
 186 </ul>
 187
 188 <p>After you write your MagickWand program, compile it like this:</p>
 189
 190 <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>
 191 <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>
 192
 193 <div class="viewport">
 194 <pre class="code">
 195 #include &lt;stdio.h>
 196 #include &lt;stdlib.h>
 197 #include &lt;wand/MagickWand.h>
 198
 199 int main(int argc,char **argv)
 200 {
 201 #define ThrowWandException(wand) \
 202 { \
 203   char \
 204     *description; \
 205  \
 206   ExceptionType \
 207     severity; \
 208  \
 209   description=MagickGetException(wand,&amp;severity); \
 210   (void) fprintf(stderr,"%s %s %u %s\n",GetMagickModule(),description); \
 211   description=(char *) MagickRelinquishMemory(description); \
 212   exit(-1); \
 213 }
 214
 215   MagickBooleanType
 216     status;
 217
 218   MagickWand
 219     *magick_wand;
 220
 221   if (argc != 3)
 222     {
 223       (void) fprintf(stdout,"Usage: %s image thumbnail\n",argv[0]);
 224       exit(0);
 225     }
 226   /*
 227     Read an image.
 228   */
 229   MagickWandGenesis();
 230   magick_wand=NewMagickWand();
 231   status=MagickReadImage(magick_wand,argv[1]);
 232   if (status == MagickFalse)
 233     ThrowWandException(magick_wand);
 234   /*
 235     Turn the images into a thumbnail sequence.
 236   */
 237   MagickResetIterator(magick_wand);
 238   while (MagickNextImage(magick_wand) != MagickFalse)
 239     MagickResizeImage(magick_wand,106,80,LanczosFilter,1.0);
 240   /*
 241     Write the image then destroy it.
 242   */
 243   status=MagickWriteImages(magick_wand,argv[2],MagickTrue);
 244   if (status == MagickFalse)
 245     ThrowWandException(magick_wand);
 246   magick_wand=DestroyMagickWand(magick_wand);
 247   MagickWandTerminus();
 248   return(0);
 249 }
 250 </pre>
 251 </div>
 252
 253 <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>
 254
 255 <div class="viewport">
 256 <pre class="code">
 257 #include &lt;stdio.h>
 258 #include &lt;stdlib.h>
 259 #include &lt;math.h>
 260 #include &lt;wand/MagickWand.h>
 261
 262 int main(int argc,char **argv)
 263 {
 264 #define QuantumScale  ((MagickRealType) 1.0/(MagickRealType) QuantumRange)
 265 #define SigmoidalContrast(x) \
 266   (QuantumRange*(1.0/(1+exp(10.0*(0.5-QuantumScale*x)))-0.0066928509)*1.0092503)
 267 #define ThrowWandException(wand) \
 268 { \
 269   char \
 270     *description; \
 271  \
 272   ExceptionType \
 273     severity; \
 274  \
 275   description=MagickGetException(wand,&amp;severity); \
 276   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
 277   description=(char *) MagickRelinquishMemory(description); \
 278   exit(-1); \
 279 }
 280
 281   long
 282     y;
 283
 284   MagickBooleanType
 285     status;
 286
 287   MagickPixelPacket
 288     pixel;
 289
 290   MagickWand
 291     *contrast_wand,
 292     *image_wand;
 293
 294   PixelIterator
 295     *contrast_iterator,
 296     *iterator;
 297
 298   PixelWand
 299     **contrast_pixels,
 300     **pixels;
 301
 302   register long
 303     x;
 304
 305   unsigned long
 306     width;
 307
 308   if (argc != 3)
 309     {
 310       (void) fprintf(stdout,"Usage: %s image sigmoidal-image\n",argv[0]);
 311       exit(0);
 312     }
 313   /*
 314     Read an image.
 315   */
 316   MagickWandGenesis();
 317   image_wand=NewMagickWand();
 318   status=MagickReadImage(image_wand,argv[1]);
 319   if (status == MagickFalse)
 320     ThrowWandException(image_wand);
 321   contrast_wand=CloneMagickWand(image_wand);
 322   /*
 323     Sigmoidal non-linearity contrast control.
 324   */
 325   iterator=NewPixelIterator(image_wand);
 326   contrast_iterator=NewPixelIterator(contrast_wand);
 327   if ((iterator == (PixelIterator *) NULL) ||
 328       (contrast_iterator == (PixelIterator *) NULL))
 329     ThrowWandException(image_wand);
 330   for (y=0; y &lt; (long) MagickGetImageHeight(image_wand); y++)
 331   {
 332     pixels=PixelGetNextIteratorRow(iterator,&amp;width);
 333     contrast_pixels=PixelGetNextIteratorRow(contrast_iterator,&amp;width);
 334     if ((pixels == (PixelWand **) NULL) ||
 335         (contrast_pixels == (PixelWand **) NULL))
 336       break;
 337     for (x=0; x &lt; (long) width; x++)
 338     {
 339       PixelGetMagickColor(pixels[x],&amp;pixel);
 340       pixel.red=SigmoidalContrast(pixel.red);
 341       pixel.green=SigmoidalContrast(pixel.green);
 342       pixel.blue=SigmoidalContrast(pixel.blue);
 343       pixel.index=SigmoidalContrast(pixel.index);
 344       PixelSetMagickColor(contrast_pixels[x],&amp;pixel);
 345     }
 346     (void) PixelSyncIterator(contrast_iterator);
 347   }
 348   if (y &lt; (long) MagickGetImageHeight(image_wand))
 349     ThrowWandException(image_wand);
 350   contrast_iterator=DestroyPixelIterator(contrast_iterator);
 351   iterator=DestroyPixelIterator(iterator);
 352   image_wand=DestroyMagickWand(image_wand);
 353   /*
 354     Write the image then destroy it.
 355   */
 356   status=MagickWriteImages(contrast_wand,argv[2],MagickTrue);
 357   if (status == MagickFalse)
 358     ThrowWandException(image_wand);
 359   contrast_wand=DestroyMagickWand(contrast_wand);
 360   MagickWandTerminus();
 361   return(0);
 362 }
 363 </pre>
 364 </div>
 365 <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>
 366
 367 <div class="viewport">
 368 <pre class="code">
 369 #include &lt;stdio.h>
 370 #include &lt;stdlib.h>
 371 #include &lt;math.h>
 372 #include &lt;wand/MagickWand.h>
 373
 374 static MagickBooleanType SigmoidalContrast(WandView *pixel_view,
 375   const ssize_t y,const int id,void *context)
 376 {
 377 #define QuantumScale  ((MagickRealType) 1.0/(MagickRealType) QuantumRange)
 378 #define SigmoidalContrast(x) \
 379   (QuantumRange*(1.0/(1+exp(10.0*(0.5-QuantumScale*x)))-0.0066928509)*1.0092503)
 380
 381   RectangleInfo
 382     extent;
 383
 384   MagickPixelPacket
 385     pixel;
 386
 387   PixelWand
 388     **pixels;
 389
 390   register long
 391     x;
 392
 393   extent=GetWandViewExtent(contrast_view);
 394   pixels=GetWandViewPixels(contrast_view);
 395   for (x=0; x &lt; (long) (extent.width-extent.height); x++)
 396   {
 397     PixelGetMagickColor(pixels[x],&amp;pixel);
 398     pixel.red=SigmoidalContrast(pixel.red);
 399     pixel.green=SigmoidalContrast(pixel.green);
 400     pixel.blue=SigmoidalContrast(pixel.blue);
 401     pixel.index=SigmoidalContrast(pixel.index);
 402     PixelSetMagickColor(contrast_pixels[x],&amp;pixel);
 403   }
 404   return(MagickTrue);
 405 }
 406
 407 int main(int argc,char **argv)
 408 {
 409 #define ThrowViewException(view) \
 410 { \
 411   description=GetWandViewException(view,&severity); \
 412   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
 413   description=(char *) MagickRelinquishMemory(description); \
 414   exit(-1); \
 415 }
 416 #define ThrowWandException(wand) \
 417 { \
 418   description=MagickGetException(wand,&severity); \
 419   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
 420   description=(char *) MagickRelinquishMemory(description); \
 421   exit(-1); \
 422 }
 423
 424   char
 425     *description;
 426
 427   ExceptionType
 428     severity;
 429
 430   MagickBooleanType
 431     status;
 432
 433   MagickPixelPacket
 434     pixel;
 435
 436   MagickWand
 437     *contrast_wand;
 438
 439   WandView
 440     *contrast_view;
 441
 442   if (argc != 3)
 443     {
 444       (void) fprintf(stdout,"Usage: %s image sigmoidal-image\n",argv[0]);
 445       exit(0);
 446     }
 447   /*
 448     Read an image.
 449   */
 450   MagickWandGenesis();
 451   contrast_wand=NewMagickWand();
 452   status=MagickReadImage(contrast_wand,argv[1]);
 453   if (status == MagickFalse)
 454     ThrowWandException(contrast_wand);
 455   /*
 456     Sigmoidal non-linearity contrast control.
 457   */
 458   contrast_view=NewWandView(contrast_wand);
 459   if (contrast_view == (WandView *) NULL)
 460     ThrowWandException(contrast_wand);
 461   status=UpdateWandViewIterator(contrast_view,SigmoidalContrast,(void *) NULL);
 462   if (status == MagickFalse)
 463     ThrowWandException(contrast_wand);
 464   contrast_view=DestroyWandView(contrast_view);
 465   /*
 466     Write the image then destroy it.
 467   */
 468   status=MagickWriteImages(contrast_wand,argv[2],MagickTrue);
 469   if (status == MagickFalse)
 470     ThrowWandException(contrast_wand);
 471   contrast_wand=DestroyMagickWand(contrast_wand);
 472   MagickWandTerminus();
 473   return(0);
 474 }
 475 </pre>
 476 </div>
 477 \r
 478 </div>\r
 479 \r
 480 <div id="linkbar">\r
 481     <span id="linkbar-west">&nbsp;</span>\r
 482     <span id="linkbar-center">\r
 483       <a href="http://www.imagemagick.org/discourse-server/">Discourse Server</a> &bull;\r
 484       <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Studio</a>\r
 485     </span>\r
 486     <span id="linkbar-east">&nbsp;</span>\r
 487   </div>\r
 488   <div class="footer">\r
 489     <span id="footer-west">&copy; 1999-2010 ImageMagick Studio LLC</span>\r
 490     <span id="footer-east"> <a href="http://www.imagemagick.org/script/contact.php">Contact the Wizards</a></span>\r
 491   </div>\r
 492   <div style="clear: both; margin: 0; width: 100%; "></div>\r
 493   <script type="text/javascript">\r
 494     var _gaq = _gaq || [];\r
 495     _gaq.push(['_setAccount', 'UA-17690367-1']);\r
 496     _gaq.push(['_trackPageview']);\r
 497 \r
 498     (function() {\r
 499       var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;\r
 500       ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';\r
 501       var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);\r
 502     })();\r
 503   </script>\r
 504 </body>\r
 505 </html>\r