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

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