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">\r
   5 <head>\r
   6   <meta http-equiv="Content-Type" value="application/xhtml+xml" />\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="screen,projection"><!--\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 href="../index.html">About ImageMagick</a>
  50 </div>
  51 <div class="sep"></div>\r
  52 <div class="menu">
  53   <a href="../www/command-line-tools.html">Command-line Tools</a>
  54 </div>
  55 <div class="sub">
  56     <a href="../www/command-line-processing.html">Processing</a>
  57 </div>
  58 <div class="sub">
  59     <a href="../www/command-line-options.html">Options</a>
  60 </div>
  61 <div class="sub">
  62     <a href="http://www.imagemagick.org/Usage/">Usage</a>
  63 </div>
  64 <div class="menu">
  65   <a href="../www/api.html">Program Interfaces</a>
  66 </div>
  67 <div class="sub">
  68     <a href="../www/magick-wand.html">MagickWand</a>
  69 </div>
  70 <div class="sub">
  71     <a href="../www/magick-core.html">MagickCore</a>
  72 </div>
  73 <div class="sub">
  74     <a href="../www/perl-magick.html">PerlMagick</a>
  75 </div>
  76 <div class="sub">
  77     <a href="../Magick++/">Magick++</a>
  78 </div>
  79 <div class="menu">
  80   <a href="../www/architecture.html">Architecture</a>
  81 </div>
  82 <div class="sep"></div>\r
  83 <div  class="menu">
  84    <a href="../www/install-source.html">Install from Source</a>
  85 </div>
  86 <div class="sub">
  87     <a href="../www/install-source.html#unix">Unix</a>
  88 </div>
  89 <div class="sub">
  90     <a href="../www/install-source.html#windows">Windows</a>
  91  </div>
  92 <div class="menu">
  93   <a href="../www/binary-releases.html">Binary Releases</a>
  94 </div>
  95 <div class="sub">
  96     <a href="../www/binary-releases.html#unix">Unix</a>
  97 </div>
  98 <div class="sub">
  99     <a href="../www/binary-releases.html#macosx">Mac OS X</a>
 100 </div>
 101 <div class="sub">
 102     <a href="../www/binary-releases.html#windows">Windows</a>
 103 </div>
 104 <div class="menu">
 105   <a href="../www/resources.html">Resources</a>
 106 </div>
 107 <div class="sep"></div>\r
 108 <div class="menu">
 109   <a href="../www/download.html">Download</a>
 110 </div>
 111 <div class="sep"></div>\r
 112 <div class="menu">
 113   <a href="http://www.imagemagick.org/script/search.php">Search</a>
 114 </div>
 115 <div class="sep"></div>\r
 116 <div class="menu">
 117   <a href="../www/sitemap.html">Site Map</a>
 118 </div>
 119 <div  class="sub">
 120     <a href="../www/links.html">Links</a>
 121 </div>
 122 <div class="sep"></div>\r
 123 <div  class="menu">
 124   <a href="../www/sponsors.html">Sponsors:</a>
 125
 126 <div class="sponsbox">
 127 <div  class="sponsor">
 128    <a href="http://www.hygi.de">Reinigungsmittel</a><!-- 201002000400+ -->
 129 </div>
 130 <div  class="sponsor">
 131   <a href="http://www.tomsgutscheine.de">Tom's Gutscheine</a><!-- 201005010360 invendio.de-->
 132 </div>
 133 <div  class="sponsor">
 134   <a href="http://www.online-kredit-index.de">Kredit</a><!-- 201006010120 Buchhorn -->
 135 </div>
 136 <div  class="sponsor">
 137   <a href="http://www.blumenversender.com">Blumenversand</a><!-- 201005010120 -->
 138 </div>
 139 <div  class="sponsor">
 140   <a href="http://www.print24.de/">Druckerei</a><!-- 201009010720 -->
 141 </div>
 142 <div  class="sponsor">
 143    <a href="http://www.goyax.de">Börse</a><!-- 201004010240 Gewiese digital-finance.de -->
 144 </div>
 145 <div  class="sponsor">
 146    <a href="http://www.allesdruck.de">Druckerei Online</a><!-- 201012011200 allesdruck.de-->
 147 </div>
 148 <div  class="sponsor">
 149   <a href="http://www.who-sells-it.com/">Free Catalogs</a><!-- 201002010000 -->
 150 </div>
 151 </div>
 152 </div>
 153 \r
 154 \r
 155 </div>\r
 156 \r
 157 <div class="main">\r
 158 \r
 159 <p class="navigation-index"></p>
 160
 161 <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>
 162
 163 <ul>
 164   <li><a href="../www/api/magick-wand.html">Magick Wand Methods</a></li>
 165   <li><a href="../www/api/magick-property.html">Set or Get Magick Wand Properties</a></li>
 166   <li><a href="../www/api/magick-image.html">Magick Wand Image Methods</a></li>
 167   <li><a href="../www/api/pixel-iterator.html">Pixel Iterator Methods</a></li>
 168   <li><a href="../www/api/pixel-view.html">Pixel View Methods</a></li>
 169   <li><a href="../www/api/pixel-wand.html">Pixel Wand Methods</a></li>
 170   <li><a href="../www/api/drawing-wand.html">Image Vector Drawing</a></li>
 171   <li><a href="../www/api/magick-deprecate.html">Deprecated Methods</a></li>
 172   <li><a href="../www/exception.html">Error and Warning Codes</a></li>
 173 </li>
 174 </ul>
 175
 176 <p>After you write your MagickWand program, compile it like this:</p>
 177
 178 <p class='crt'><span class="crtprompt"> $magick&gt; </span><span class='crtin'>cc `MagickWand-config --cflags --cppflags` -o wand wand.c `MagickWand-config --ldflags --libs`</span></p>
 179 <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>
 180
 181 <div class="viewport">
 182 <pre class="code">
 183 #include &lt;stdio.h>
 184 #include &lt;stdlib.h>
 185 #include &lt;wand/MagickWand.h>
 186
 187 int main(int argc,char **argv)
 188 {
 189 #define ThrowWandException(wand) \
 190 { \
 191   char \
 192     *description; \
 193  \
 194   ExceptionType \
 195     severity; \
 196  \
 197   description=MagickGetException(wand,&amp;severity); \
 198   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
 199   description=(char *) MagickRelinquishMemory(description); \
 200   exit(-1); \
 201 }
 202
 203   MagickBooleanType
 204     status;
 205
 206   MagickWand
 207     *magick_wand;
 208
 209   if (argc != 3)
 210     {
 211       (void) fprintf(stdout,"Usage: %s image thumbnail\n",argv[0]);
 212       exit(0);
 213     }
 214   /*
 215     Read an image.
 216   */
 217   MagickWandGenesis();
 218   magick_wand=NewMagickWand();
 219   status=MagickReadImage(magick_wand,argv[1]);
 220   if (status == MagickFalse)
 221     ThrowWandException(magick_wand);
 222   /*
 223     Turn the images into a thumbnail sequence.
 224   */
 225   MagickResetIterator(magick_wand);
 226   while (MagickNextImage(magick_wand) != MagickFalse)
 227     MagickResizeImage(magick_wand,106,80,LanczosFilter,1.0);
 228   /*
 229     Write the image then destroy it.
 230   */
 231   status=MagickWriteImages(magick_wand,argv[2],MagickTrue);
 232   if (status == MagickFalse)
 233     ThrowWandException(magick_wand);
 234   magick_wand=DestroyMagickWand(magick_wand);
 235   MagickWandTerminus();
 236   return(0);
 237 }
 238 </pre>
 239 </div>
 240
 241 <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>
 242
 243 <div class="viewport">
 244 <pre class="code">
 245 #include &lt;stdio.h>
 246 #include &lt;stdlib.h>
 247 #include &lt;math.h>
 248 #include &lt;wand/MagickWand.h>
 249
 250 int main(int argc,char **argv)
 251 {
 252 #define QuantumScale  ((MagickRealType) 1.0/(MagickRealType) QuantumRange)
 253 #define SigmoidalContrast(x) \
 254   (QuantumRange*(1.0/(1+exp(10.0*(0.5-QuantumScale*x)))-0.0066928509)*1.0092503)
 255 #define ThrowWandException(wand) \
 256 { \
 257   char \
 258     *description; \
 259  \
 260   ExceptionType \
 261     severity; \
 262  \
 263   description=MagickGetException(wand,&amp;severity); \
 264   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
 265   description=(char *) MagickRelinquishMemory(description); \
 266   exit(-1); \
 267 }
 268
 269   long
 270     y;
 271
 272   MagickBooleanType
 273     status;
 274
 275   MagickPixelPacket
 276     pixel;
 277
 278   MagickWand
 279     *contrast_wand,
 280     *image_wand;
 281
 282   PixelIterator
 283     *contrast_iterator,
 284     *iterator;
 285
 286   PixelWand
 287     **contrast_pixels,
 288     **pixels;
 289
 290   register long
 291     x;
 292
 293   unsigned long
 294     width;
 295
 296   if (argc != 3)
 297     {
 298       (void) fprintf(stdout,"Usage: %s image sigmoidal-image\n",argv[0]);
 299       exit(0);
 300     }
 301   /*
 302     Read an image.
 303   */
 304   MagickWandGenesis();
 305   image_wand=NewMagickWand();
 306   status=MagickReadImage(image_wand,argv[1]);
 307   if (status == MagickFalse)
 308     ThrowWandException(image_wand);
 309   contrast_wand=CloneMagickWand(image_wand);
 310   /*
 311     Sigmoidal non-linearity contrast control.
 312   */
 313   iterator=NewPixelIterator(image_wand);
 314   contrast_iterator=NewPixelIterator(contrast_wand);
 315   if ((iterator == (PixelIterator *) NULL) ||
 316       (contrast_iterator == (PixelIterator *) NULL))
 317     ThrowWandException(image_wand);
 318   for (y=0; y &lt; (long) MagickGetImageHeight(image_wand); y++)
 319   {
 320     pixels=PixelGetNextIteratorRow(iterator,&amp;width);
 321     contrast_pixels=PixelGetNextIteratorRow(contrast_iterator,&amp;width);
 322     if ((pixels == (PixelWand **) NULL) ||
 323         (contrast_pixels == (PixelWand **) NULL))
 324       break;
 325     for (x=0; x &lt; (long) width; x++)
 326     {
 327       PixelGetMagickColor(pixels[x],&amp;pixel);
 328       pixel.red=SigmoidalContrast(pixel.red);
 329       pixel.green=SigmoidalContrast(pixel.green);
 330       pixel.blue=SigmoidalContrast(pixel.blue);
 331       pixel.index=SigmoidalContrast(pixel.index);
 332       PixelSetMagickColor(contrast_pixels[x],&amp;pixel);
 333     }
 334     (void) PixelSyncIterator(contrast_iterator);
 335   }
 336   if (y &lt; (long) MagickGetImageHeight(image_wand))
 337     ThrowWandException(image_wand);
 338   contrast_iterator=DestroyPixelIterator(contrast_iterator);
 339   iterator=DestroyPixelIterator(iterator);
 340   image_wand=DestroyMagickWand(image_wand);
 341   /*
 342     Write the image then destroy it.
 343   */
 344   status=MagickWriteImages(contrast_wand,argv[2],MagickTrue);
 345   if (status == MagickFalse)
 346     ThrowWandException(image_wand);
 347   contrast_wand=DestroyMagickWand(contrast_wand);
 348   MagickWandTerminus();
 349   return(0);
 350 }
 351 </pre>
 352 </div>
 353 <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 pixel views.  The <a href="../www/source/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>
 354
 355 <div class="viewport">
 356 <pre class="code">
 357 #include &lt;stdio.h>
 358 #include &lt;stdlib.h>
 359 #include &lt;math.h>
 360 #include &lt;wand/MagickWand.h>
 361
 362 static MagickBooleanType SigmoidalContrast(PixelView *pixel_view,
 363   void *context)
 364 {
 365 #define QuantumScale  ((MagickRealType) 1.0/(MagickRealType) QuantumRange)
 366 #define SigmoidalContrast(x) \
 367   (QuantumRange*(1.0/(1+exp(10.0*(0.5-QuantumScale*x)))-0.0066928509)*1.0092503)
 368
 369   MagickPixelPacket
 370     pixel;
 371
 372   PixelWand
 373     **pixels;
 374
 375   register long
 376     x;
 377
 378   pixels=GetPixelViewPixels(contrast_view);
 379   for (x=0; x &lt; (long) GetPixelViewWidth(contrast_view); x++)
 380   {
 381     PixelGetMagickColor(pixels[x],&amp;pixel);
 382     pixel.red=SigmoidalContrast(pixel.red);
 383     pixel.green=SigmoidalContrast(pixel.green);
 384     pixel.blue=SigmoidalContrast(pixel.blue);
 385     pixel.index=SigmoidalContrast(pixel.index);
 386     PixelSetMagickColor(contrast_pixels[x],&amp;pixel);
 387   }
 388   return(MagickTrue);
 389 }
 390
 391 int main(int argc,char **argv)
 392 {
 393 #define ThrowWandException(wand) \
 394 { \
 395   char \
 396     *description; \
 397  \
 398   ExceptionType \
 399     severity; \
 400  \
 401   description=MagickGetException(wand,&amp;severity); \
 402   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
 403   description=(char *) MagickRelinquishMemory(description); \
 404   exit(-1); \
 405 }
 406
 407   MagickBooleanType
 408     status;
 409
 410   MagickPixelPacket
 411     pixel;
 412
 413   MagickWand
 414     *contrast_wand;
 415
 416   PixelView
 417     *contrast_view;
 418
 419   if (argc != 3)
 420     {
 421       (void) fprintf(stdout,"Usage: %s image sigmoidal-image\n",argv[0]);
 422       exit(0);
 423     }
 424   /*
 425     Read an image.
 426   */
 427   MagickWandGenesis();
 428   contrast_wand=NewMagickWand();
 429   status=MagickReadImage(contrast_wand,argv[1]);
 430   if (status == MagickFalse)
 431     ThrowWandException(contrast_wand);
 432   /*
 433     Sigmoidal non-linearity contrast control.
 434   */
 435   contrast_view=NewPixelView(contrast_wand);
 436   if (contrast_view == (PixelView *) NULL)
 437     ThrowWandException(contrast_wand);
 438   status=UpdatePixelViewIterator(contrast_view,SigmoidalContrast,(void *) NULL);
 439   if (status == MagickFalse)
 440     ThrowWandException(contrast_wand);
 441   contrast_view=DestroyPixelView(contrast_view);
 442   /*
 443     Write the image then destroy it.
 444   */
 445   status=MagickWriteImages(contrast_wand,argv[2],MagickTrue);
 446   if (status == MagickFalse)
 447     ThrowWandException(contrast_wand);
 448   contrast_wand=DestroyMagickWand(contrast_wand);
 449   MagickWandTerminus();
 450   return(0);
 451 }
 452 </pre>
 453 </div>
 454 \r
 455 </div>\r
 456 \r
 457 <div id="linkbar">\r
 458  <!--    <span id="linkbar-west">&nbsp;</span>  -->\r
 459     <span id="linkbar-center">\r
 460       <a href="http://www.imagemagick.org/discourse-server/">Discourse Server</a> &bull;\r
 461     <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Studio</a>\r
 462     </span>\r
 463     <span id="linkbar-east">&nbsp;</span>\r
 464   </div>\r
 465   <div class="footer">\r
 466     <span id="footer-west">&copy; 1999-2010 ImageMagick Studio LLC</span>\r
 467     <span id="footer-east"> <a href="http://www.imagemagick.org/script/contact.php">Contact the Wizards</a></span>\r
 468   </div>\r
 469   <div style="clear: both; margin: 0; width: 100%; "></div>\r
 470 </body>\r
 471 </html>\r