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