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.abi-stoff.de/abizeitung/" title="Abibuch">Abizeitung</a><!-- 20090501000200 -->
 128 </div>
 129 <div  class="sponsor">
 130   <a href="http://www.online-kredit-index.de">Kredit</a><!-- 201003010120 Buchhorn -->
 131 </div>
 132 <div  class="sponsor">
 133   <a href="http://www.print24.de/">Druckerei</a><!-- 201009010720 -->
 134 </div>
 135 <div  class="sponsor">
 136    <a href="http://www.goyax.de">Börse</a><!-- 201001000240 Gewiese digital-finance.de -->
 137 </div>
 138 <div  class="sponsor">
 139    <a href="http://www.allesdruck.de">Druckerei Online</a><!-- 201012001200 allesdruck.de-->
 140 </div>
 141 <div  class="sponsor">
 142   <a href="http://www.blumenversender.com">Blumenversand</a><!-- 200911010120 -->
 143 </div>
 144 <div  class="sponsor">
 145   <a href="http://www.who-sells-it.com/">Free Catalogs</a><!-- 201002010000 -->
 146 </div>
 147 </div>
 148 </div>
 149 \r
 150 \r
 151 </div>\r
 152 \r
 153 <div class="main">\r
 154 \r
 155 <p class="navigation-index"></p>
 156
 157 <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>
 158
 159 <ul>
 160   <li><a href="../www/api/magick-wand.html">Magick Wand Methods</a></li>
 161   <li><a href="../www/api/magick-property.html">Set or Get Magick Wand Properties</a></li>
 162   <li><a href="../www/api/magick-image.html">Magick Wand Image Methods</a></li>
 163   <li><a href="../www/api/pixel-iterator.html">Pixel Iterator Methods</a></li>
 164   <li><a href="../www/api/pixel-view.html">Pixel View 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/magick-deprecate.html">Deprecated Methods</a></li>
 168   <li><a href="../www/exception.html">Error and Warning Codes</a></li>
 169 </li>
 170 </ul>
 171
 172 <p>After you write your MagickWand program, compile it like this:</p>
 173
 174 <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>
 175 <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>
 176
 177 <div class="viewport">
 178 <pre class="code">
 179 #include &lt;stdio.h>
 180 #include &lt;stdlib.h>
 181 #include &lt;wand/MagickWand.h>
 182
 183 int main(int argc,char **argv)
 184 {
 185 #define ThrowWandException(wand) \
 186 { \
 187   char \
 188     *description; \
 189  \
 190   ExceptionType \
 191     severity; \
 192  \
 193   description=MagickGetException(wand,&amp;severity); \
 194   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
 195   description=(char *) MagickRelinquishMemory(description); \
 196   exit(-1); \
 197 }
 198
 199   MagickBooleanType
 200     status;
 201
 202   MagickWand
 203     *magick_wand;
 204
 205   if (argc != 3)
 206     {
 207       (void) fprintf(stdout,"Usage: %s image thumbnail\n",argv[0]);
 208       exit(0);
 209     }
 210   /*
 211     Read an image.
 212   */
 213   MagickWandGenesis();
 214   magick_wand=NewMagickWand();
 215   status=MagickReadImage(magick_wand,argv[1]);
 216   if (status == MagickFalse)
 217     ThrowWandException(magick_wand);
 218   /*
 219     Turn the images into a thumbnail sequence.
 220   */
 221   MagickResetIterator(magick_wand);
 222   while (MagickNextImage(magick_wand) != MagickFalse)
 223     MagickResizeImage(magick_wand,106,80,LanczosFilter,1.0);
 224   /*
 225     Write the image then destroy it.
 226   */
 227   status=MagickWriteImages(magick_wand,argv[2],MagickTrue);
 228   if (status == MagickFalse)
 229     ThrowWandException(magick_wand);
 230   magick_wand=DestroyMagickWand(magick_wand);
 231   MagickWandTerminus();
 232   return(0);
 233 }
 234 </pre>
 235 </div>
 236
 237 <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>
 238
 239 <div class="viewport">
 240 <pre class="code">
 241 #include &lt;stdio.h>
 242 #include &lt;stdlib.h>
 243 #include &lt;math.h>
 244 #include &lt;wand/MagickWand.h>
 245
 246 int main(int argc,char **argv)
 247 {
 248 #define QuantumScale  ((MagickRealType) 1.0/(MagickRealType) QuantumRange)
 249 #define SigmoidalContrast(x) \
 250   (QuantumRange*(1.0/(1+exp(10.0*(0.5-QuantumScale*x)))-0.0066928509)*1.0092503)
 251 #define ThrowWandException(wand) \
 252 { \
 253   char \
 254     *description; \
 255  \
 256   ExceptionType \
 257     severity; \
 258  \
 259   description=MagickGetException(wand,&amp;severity); \
 260   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
 261   description=(char *) MagickRelinquishMemory(description); \
 262   exit(-1); \
 263 }
 264
 265   long
 266     y;
 267
 268   MagickBooleanType
 269     status;
 270
 271   MagickPixelPacket
 272     pixel;
 273
 274   MagickWand
 275     *contrast_wand,
 276     *image_wand;
 277
 278   PixelIterator
 279     *contrast_iterator,
 280     *iterator;
 281
 282   PixelWand
 283     **contrast_pixels,
 284     **pixels;
 285
 286   register long
 287     x;
 288
 289   unsigned long
 290     width;
 291
 292   if (argc != 3)
 293     {
 294       (void) fprintf(stdout,"Usage: %s image sigmoidal-image\n",argv[0]);
 295       exit(0);
 296     }
 297   /*
 298     Read an image.
 299   */
 300   MagickWandGenesis();
 301   image_wand=NewMagickWand();
 302   status=MagickReadImage(image_wand,argv[1]);
 303   if (status == MagickFalse)
 304     ThrowWandException(image_wand);
 305   contrast_wand=CloneMagickWand(image_wand);
 306   /*
 307     Sigmoidal non-linearity contrast control.
 308   */
 309   iterator=NewPixelIterator(image_wand);
 310   contrast_iterator=NewPixelIterator(contrast_wand);
 311   if ((iterator == (PixelIterator *) NULL) ||
 312       (contrast_iterator == (PixelIterator *) NULL))
 313     ThrowWandException(image_wand);
 314   for (y=0; y &lt; (long) MagickGetImageHeight(image_wand); y++)
 315   {
 316     pixels=PixelGetNextIteratorRow(iterator,&amp;width);
 317     contrast_pixels=PixelGetNextIteratorRow(contrast_iterator,&amp;width);
 318     if ((pixels == (PixelWand **) NULL) ||
 319         (contrast_pixels == (PixelWand **) NULL))
 320       break;
 321     for (x=0; x &lt; (long) width; x++)
 322     {
 323       PixelGetMagickColor(pixels[x],&amp;pixel);
 324       pixel.red=SigmoidalContrast(pixel.red);
 325       pixel.green=SigmoidalContrast(pixel.green);
 326       pixel.blue=SigmoidalContrast(pixel.blue);
 327       pixel.index=SigmoidalContrast(pixel.index);
 328       PixelSetMagickColor(contrast_pixels[x],&amp;pixel);
 329     }
 330     (void) PixelSyncIterator(contrast_iterator);
 331   }
 332   if (y &lt; (long) MagickGetImageHeight(image_wand))
 333     ThrowWandException(image_wand);
 334   contrast_iterator=DestroyPixelIterator(contrast_iterator);
 335   iterator=DestroyPixelIterator(iterator);
 336   image_wand=DestroyMagickWand(image_wand);
 337   /*
 338     Write the image then destroy it.
 339   */
 340   status=MagickWriteImages(contrast_wand,argv[2],MagickTrue);
 341   if (status == MagickFalse)
 342     ThrowWandException(image_wand);
 343   contrast_wand=DestroyMagickWand(contrast_wand);
 344   MagickWandTerminus();
 345   return(0);
 346 }
 347 </pre>
 348 </div>
 349 <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>
 350
 351 <div class="viewport">
 352 <pre class="code">
 353 #include &lt;stdio.h>
 354 #include &lt;stdlib.h>
 355 #include &lt;math.h>
 356 #include &lt;wand/MagickWand.h>
 357
 358 static MagickBooleanType SigmoidalContrast(PixelView *pixel_view,
 359   void *context)
 360 {
 361 #define QuantumScale  ((MagickRealType) 1.0/(MagickRealType) QuantumRange)
 362 #define SigmoidalContrast(x) \
 363   (QuantumRange*(1.0/(1+exp(10.0*(0.5-QuantumScale*x)))-0.0066928509)*1.0092503)
 364
 365   MagickPixelPacket
 366     pixel;
 367
 368   PixelWand
 369     **pixels;
 370
 371   register long
 372     x;
 373
 374   pixels=GetPixelViewPixels(contrast_view);
 375   for (x=0; x &lt; (long) GetPixelViewWidth(contrast_view); x++)
 376   {
 377     PixelGetMagickColor(pixels[x],&amp;pixel);
 378     pixel.red=SigmoidalContrast(pixel.red);
 379     pixel.green=SigmoidalContrast(pixel.green);
 380     pixel.blue=SigmoidalContrast(pixel.blue);
 381     pixel.index=SigmoidalContrast(pixel.index);
 382     PixelSetMagickColor(contrast_pixels[x],&amp;pixel);
 383   }
 384   return(MagickTrue);
 385 }
 386
 387 int main(int argc,char **argv)
 388 {
 389 #define ThrowWandException(wand) \
 390 { \
 391   char \
 392     *description; \
 393  \
 394   ExceptionType \
 395     severity; \
 396  \
 397   description=MagickGetException(wand,&amp;severity); \
 398   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
 399   description=(char *) MagickRelinquishMemory(description); \
 400   exit(-1); \
 401 }
 402
 403   MagickBooleanType
 404     status;
 405
 406   MagickPixelPacket
 407     pixel;
 408
 409   MagickWand
 410     *contrast_wand;
 411
 412   PixelView
 413     *contrast_view;
 414
 415   if (argc != 3)
 416     {
 417       (void) fprintf(stdout,"Usage: %s image sigmoidal-image\n",argv[0]);
 418       exit(0);
 419     }
 420   /*
 421     Read an image.
 422   */
 423   MagickWandGenesis();
 424   contrast_wand=NewMagickWand();
 425   status=MagickReadImage(contrast_wand,argv[1]);
 426   if (status == MagickFalse)
 427     ThrowWandException(contrast_wand);
 428   /*
 429     Sigmoidal non-linearity contrast control.
 430   */
 431   contrast_view=NewPixelView(contrast_wand);
 432   if (contrast_view == (PixelView *) NULL)
 433     ThrowWandException(contrast_wand);
 434   status=UpdatePixelViewIterator(contrast_view,SigmoidalContrast,(void *) NULL);
 435   if (status == MagickFalse)
 436     ThrowWandException(contrast_wand);
 437   contrast_view=DestroyPixelView(contrast_view);
 438   /*
 439     Write the image then destroy it.
 440   */
 441   status=MagickWriteImages(contrast_wand,argv[2],MagickTrue);
 442   if (status == MagickFalse)
 443     ThrowWandException(contrast_wand);
 444   contrast_wand=DestroyMagickWand(contrast_wand);
 445   MagickWandTerminus();
 446   return(0);
 447 }
 448 </pre>
 449 </div>
 450 \r
 451 </div>\r
 452 \r
 453 <div id="linkbar">\r
 454  <!--    <span id="linkbar-west">&nbsp;</span>  -->\r
 455     <span id="linkbar-center">\r
 456       <a href="http://www.imagemagick.org/discourse-server/">Discourse Server</a> &bull;\r
 457       <a href="../www/mailing-list.html">Mailing Lists</a> &bull;\r
 458     <a href="http://studio.webbyland.com/ImageMagick/MagickStudio/scripts/MagickStudio.cgi">Studio</a>\r
 459     </span>\r
 460     <span id="linkbar-east">&nbsp;</span>\r
 461   </div>\r
 462   <div class="footer">\r
 463     <span id="footer-west">&copy; 1999-2009 ImageMagick Studio LLC</span>\r
 464     <span id="footer-east"> <a href="http://www.imagemagick.org/script/contact.php">Contact the Wizards</a></span>\r
 465   </div>\r
 466   <div style="clear: both; margin: 0; width: 100%; "></div>\r
 467 </body>\r
 468 </html>\r