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