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