granicus.if.org Git - imagemagick/blob - www/magick-wand.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="-//W3C//DTD XHTML 1.1//EN" xml:lang="en" xsi:schemaLocation="http://www.w3.org/1999/xhtml                           http://www.w3.org/MarkUp/SCHEMA/xhtml11.xsd">
   3 <head>
   4   <meta http-equiv="content-type" content="text/html; charset=UTF-8"></meta>
   5   <meta name="google-site-verification" content="_bMOCDpkx9ZAzBwb2kF3PRHbfUUdFj2uO8Jd1AXArz4"></meta>
   6   <title>ImageMagick: MagickWand, C API for ImageMagick</title>
   7   <meta http-equiv="content-language" content="en-US"></meta>
   8   <meta http-equiv="content-type" content="text/html; charset=utf-8"></meta>
   9   <meta http-equiv="reply-to" content="magick-users@imagemagick.org"></meta>
  10   <meta name="application-name" content="ImageMagick"></meta>
  11   <meta name="description" content="Use ImageMagick to convert, edit, or compose bitmap images in a variety of formats.  In addition, resize, rotate, shear, distort or transform images automagically."></meta>
  12   <meta name="application-url" content="http://www.imagemagick.org"></meta>
  13   <meta name="generator" content="PHP"></meta>
  14   <meta name="keywords" content="magickwc, api, for, imagemagick, ImageMagick, PerlMagick, image processing, OpenMP, software development library, image, photo, software, Magick++, MagickWand"></meta>
  15   <meta name="rating" content="GENERAL"></meta>
  16   <meta name="robots" content="INDEX, FOLLOW"></meta>
  17   <meta name="generator" content="ImageMagick Studio LLC"></meta>
  18   <meta name="author" content="ImageMagick Studio LLC"></meta>
  19   <meta name="revisit-after" content="2 DAYS"></meta>
  20   <meta name="resource-type" content="document"></meta>
  21   <meta name="copyright" content="Copyright (c) 1999-2012 ImageMagick Studio LLC"></meta>
  22   <meta name="distribution" content="Global"></meta>
  23   <link rel="icon" href="../images/wand.png"></link>
  24   <link rel="shortcut icon" href="../images/wand.ico" type="images/x-icon"></link>
  25   <link rel="canonical" href="http://www.imagemagick.org"></link>
  26   <link rel="meta" type="application/rdf+xml" title="ICI" href="http://imagemagick.org/ici.rdf"></link>
  27
  28   <!-- Add jQuery library -->
  29   <script type="text/javascript" src="http://localhost/ajax/libs/jquery/1.7/jquery.min.js"></script>
  30
  31   <!-- Add mousewheel plugin (this is optional) -->
  32   <script type="text/javascript" src="http://www.imagemagick.org/fancybox/lib/jquery.mousewheel-3.0.6.pack.js"></script>
  33
  34   <!-- Add fancyBox -->
  35   <link rel="stylesheet" href="http://www.imagemagick.org/fancybox/source/jquery.fancybox.css?v=2.0.6" type="text/css" media="screen"></link>
  36   <script type="text/javascript" src="http://www.imagemagick.org/fancybox/source/jquery.fancybox.pack.js?v=2.0.6"></script>
  37
  38   <!-- Optionally add helpers - button, thumbnail and/or media -->
  39   <link rel="stylesheet" href="http://www.imagemagick.org/fancybox/source/helpers/jquery.fancybox-buttons.css?v=1.0.2" type="text/css" media="screen"></link>
  40   <script type="text/javascript" src="http://www.imagemagick.org/fancybox/source/helpers/jquery.fancybox-buttons.js?v=1.0.2"></script>
  41   <script type="text/javascript" src="http://www.imagemagick.org/fancybox/source/helpers/jquery.fancybox-media.js?v=1.0.0"></script>
  42
  43   <link rel="stylesheet" href="http://www.imagemagick.org/fancybox/source/helpers/jquery.fancybox-thumbs.css?v=2.0.6" type="text/css" media="screen"></link>
  44   <script type="text/javascript" src="http://www.imagemagick.org/fancybox/source/helpers/jquery.fancybox-thumbs.js?v=2.0.6"></script>
  45
  46   <script type="text/javascript">
  47         $(document).ready(function() {
  48                 $(".fancybox").fancybox();
  49         });
  50   </script>
  51
  52   <!-- ImageMagick style -->
  53   <style type="text/css" media="all">
  54     @import url("../www/magick.css");
  55   </style>
  56 </head>
  57
  58 <body id="www-imagemagick-org">
  59
  60
  61
  62 <div class="titlebar">
  63 <div style="margin: 17px auto; float: left;">
  64   <script type="text/javascript">
  65   <!--
  66     google_ad_client = "pub-3129977114552745";
  67     google_ad_slot = "5439289906";
  68     google_ad_width = 728;
  69     google_ad_height = 90;
  70   //-->
  71   </script>
  72
  73 </div>
  74 <a href="http://www.imagemagick.org/discourse-server/">
  75   <img src="../images/logo.jpg" alt="ImageMagick Logo" style="width: 123px; height: 118px; border: 0px; float: right;"></img></a>
  76 <a href="../index.html">
  77   <img src="../images/sprite.jpg" alt="ImageMagick Sprite" style="width: 114px; height: 118px; border: 0px; float: right;"></img></a>
  78 </div>
  79
  80 <div class="westbar">
  81
  82 <div class="menu">
  83   <a title="About ImageMagick" href="../index.html">About ImageMagick</a>
  84 </div>
  85 <div class="menu">
  86   <a title="Binary Releases" href="binary-releases.html">Binary Releases</a>
  87 </div>
  88 <div class="sub">
  89     <a title="Binary Release: Unix" href="binary-releases.html#unix">Unix</a>
  90 </div>
  91 <div class="sub">
  92     <a title="Binary Release: MacOS X" href="binary-releases.html#macosx">Mac OS X</a>
  93 </div>
  94 <div class="sub">
  95     <a title="Binary Release: iOS" href="binary-releases.html#iOS">iOS</a>
  96 </div>
  97 <div class="sub">
  98     <a title="Binary Release: Windows" href="binary-releases.html#windows">Windows</a>
  99 </div>
 100 <div class="sep"></div>
 101 <div class="menu">
 102   <a title="Command-line Tools" href="command-line-tools.html">Command-line Tools</a>
 103 </div>
 104 <div class="sub">
 105     <a title="Command-line Tools: Processing" href="command-line-processing.html">Processing</a>
 106 </div>
 107 <div class="sub">
 108     <a title="Command-line Tools: Options" href="command-line-options.html">Options</a>
 109 </div>
 110 <div class="sub">
 111     <a title="Command-line Tools: Usage" href="http://www.imagemagick.org/Usage/">Usage</a>
 112 </div>
 113 <div class="menu">
 114   <a title="Program Interfaces" href="api.html">Program Interfaces</a>
 115 </div>
 116 <div class="sub">
 117     <a title="Program Interface: MagickWand" href="magick-wand.html">MagickWand</a>
 118 </div>
 119 <div class="sub">
 120     <a title="Program Interface: MagickCore" href="magick-core.html">MagickCore</a>
 121 </div>
 122 <div class="sub">
 123     <a title="Program Interface: PerlMagick" href="perl-magick.html">PerlMagick</a>
 124 </div>
 125 <div class="sub">
 126     <a title="Program Interface: Magick++" href="magick++.html">Magick++</a>
 127 </div>
 128 <div class="sep"></div>
 129 <div class="menu">
 130    <a title="Install from Source" href="install-source.html">Install from Source</a>
 131 </div>
 132 <div class="sub">
 133     <a title="Install from Source: Unix" href="install-source.html#unix">Unix</a>
 134 </div>
 135 <div class="sub">
 136     <a title="Install from Source: Windows" href="install-source.html#windows">Windows</a>
 137  </div>
 138 <div class="menu">
 139   <a title="Resources" href="resources.html">Resources</a>
 140 </div>
 141 <div class="menu">
 142   <a title="Architecture" href="architecture.html">Architecture</a>
 143 </div>
 144 <div class="menu">
 145   <a title="Download" href="download.html">Download</a>
 146 </div>
 147 <div class="sep"></div>
 148 <div class="menu">
 149   <a title="Search" href="search.html">Search</a>
 150 </div>
 151 <div class="sep"></div>
 152 <div class="menu">
 153   <a title="Site Map" href="sitemap.html">Site Map</a>
 154 </div>
 155 <div class="sub">
 156   <a title="Site Map: Links" href="links.html">Links</a>
 157 </div>
 158 <div class="sep"></div>
 159 <div class="menu">
 160   <a title="Support ImageMagick Development" href="support.html">Support ImageMagick Development</a>
 161 </div>
 162 </div>
 163
 164 <div class="eastbar">
 165
 166   <div> <a class="FlattrButton" style="display:none;" rev="flattr;button:compact;" href="http://www.imagemagick.org/"></a></div>
 167   <noscript>
 168     <a href="http://flattr.com/thing/947300/Convert-Edit-And-Compose-Images" target="_blank">
 169     <img src="http://api.flattr.com/button/flattr-badge-large.png" alt="Flattr this" title="Flattr this" width="93" height="20" border="0"></img></a>
 170   </noscript>
 171
 172
 173 </div>
 174
 175 <div class="main">
 176
 177 <h1>MagickWand C API</h1>
 178
 179 <div class="doc-section">
 180 <p>The <a href="http://magick.imagemagick.org/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="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>
 181
 182 <ul>
 183   <li><a href="../api/magick-wand.html">Magick Wand Methods</a></li>
 184   <li><a href="../api/magick-property.html">Set or Get Magick Wand Properties</a></li>
 185   <li><a href="../api/magick-image.html">Magick Wand Image Methods</a></li>
 186   <li><a href="../api/pixel-iterator.html">Pixel Iterator Methods</a></li>
 187   <li><a href="../api/pixel-wand.html">Pixel Wand Methods</a></li>
 188   <li><a href="../api/drawing-wand.html">Image Vector Drawing</a></li>
 189   <li><a href="../api/mogrify.html">Command-line Interface</a></li>
 190   <li><a href="../api/wand-view.html">Wand View Methods</a></li>
 191   <li><a href="../api/magick-deprecate.html">Deprecated Methods</a></li>
 192   <li><a href="exception.html">Error and Warning Codes</a></li>
 193 </ul>
 194
 195 <p>After you write your MagickWand program, compile it like this:</p>
 196
 197 <p class="crt"><span class="crtprompt"> $ </span><span class="crtin">cc -o wand `pkg-config --cflags --libs MagickWand` wand.c</span></p>
 198 <p>Set the <code>PKG_CONFIG_PATH</code> environment variable if ImageMagick is not in your default system path:</p>
 199 <p class="crt"><span class="crtprompt"> $ </span><span class="crtin">export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig</span></p>
 200 <p>Here is a example program that utilizes the MagickWand API to get you started, <a href="../source/wand.c">wand.c</a>. It reads an image, creates a thumbnail, and writes the result to disk.</p>
 201
 202 <div class="viewport">
 203 #include &lt;stdio.h&gt;
 204 #include &lt;stdlib.h&gt;
 205 #include &lt;wand/MagickWand.h&gt;
 206
 207 int main(int argc,char **argv)
 208 {
 209 #define ThrowWandException(wand) \
 210 { \
 211   char \
 212     *description; \
 213  \
 214   ExceptionType \
 215     severity; \
 216  \
 217   description=MagickGetException(wand,&amp;severity); \
 218   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
 219   description=(char *) MagickRelinquishMemory(description); \
 220   exit(-1); \
 221 }
 222
 223   MagickBooleanType
 224     status;
 225
 226   MagickWand
 227     *magick_wand;
 228
 229   if (argc != 3)
 230     {
 231       (void) fprintf(stdout,"Usage: %s image thumbnail\n",argv[0]);
 232       exit(0);
 233     }
 234   /*
 235     Read an image.
 236   */
 237   MagickWandGenesis();
 238   magick_wand=NewMagickWand();
 239   status=MagickReadImage(magick_wand,argv[1]);
 240   if (status == MagickFalse)
 241     ThrowWandException(magick_wand);
 242   /*
 243     Turn the images into a thumbnail sequence.
 244   */
 245   MagickResetIterator(magick_wand);
 246   while (MagickNextImage(magick_wand) != MagickFalse)
 247     MagickResizeImage(magick_wand,106,80,LanczosFilter,1.0);
 248   /*
 249     Write the image then destroy it.
 250   */
 251   status=MagickWriteImages(magick_wand,argv[2],MagickTrue);
 252   if (status == MagickFalse)
 253     ThrowWandException(magick_wand);
 254   magick_wand=DestroyMagickWand(magick_wand);
 255   MagickWandTerminus();
 256   return(0);
 257 }
 258 </div>
 259
 260 <p>Here is another program that shows one way to get and set image pixels with the MagickWand API, <a href="../source/contrast.c">contrast.c</a>. It reads an image, applies sigmoidal non-linearity contrast control, and writes the result to disk.</p>
 261
 262 <div class="viewport">
 263 #include &lt;stdio.h&gt;
 264 #include &lt;stdlib.h&gt;
 265 #include &lt;math.h&gt;
 266 #include &lt;wand/MagickWand.h&gt;
 267
 268 int main(int argc,char **argv)
 269 {
 270 #define QuantumScale  ((MagickRealType) 1.0/(MagickRealType) QuantumRange)
 271 #define SigmoidalContrast(x) \
 272   (QuantumRange*(1.0/(1+exp(10.0*(0.5-QuantumScale*x)))-0.0066928509)*1.0092503)
 273 #define ThrowWandException(wand) \
 274 { \
 275   char \
 276     *description; \
 277  \
 278   ExceptionType \
 279     severity; \
 280  \
 281   description=MagickGetException(wand,&amp;severity); \
 282   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
 283   description=(char *) MagickRelinquishMemory(description); \
 284   exit(-1); \
 285 }
 286
 287   long
 288     y;
 289
 290   MagickBooleanType
 291     status;
 292
 293   MagickPixelPacket
 294     pixel;
 295
 296   MagickWand
 297     *contrast_wand,
 298     *image_wand;
 299
 300   PixelIterator
 301     *contrast_iterator,
 302     *iterator;
 303
 304   PixelWand
 305     **contrast_pixels,
 306     **pixels;
 307
 308   register long
 309     x;
 310
 311   unsigned long
 312     width;
 313
 314   if (argc != 3)
 315     {
 316       (void) fprintf(stdout,"Usage: %s image sigmoidal-image\n",argv[0]);
 317       exit(0);
 318     }
 319   /*
 320     Read an image.
 321   */
 322   MagickWandGenesis();
 323   image_wand=NewMagickWand();
 324   status=MagickReadImage(image_wand,argv[1]);
 325   if (status == MagickFalse)
 326     ThrowWandException(image_wand);
 327   contrast_wand=CloneMagickWand(image_wand);
 328   /*
 329     Sigmoidal non-linearity contrast control.
 330   */
 331   iterator=NewPixelIterator(image_wand);
 332   contrast_iterator=NewPixelIterator(contrast_wand);
 333   if ((iterator == (PixelIterator *) NULL) ||
 334       (contrast_iterator == (PixelIterator *) NULL))
 335     ThrowWandException(image_wand);
 336   for (y=0; y &lt; (long) MagickGetImageHeight(image_wand); y++)
 337   {
 338     pixels=PixelGetNextIteratorRow(iterator,&amp;width);
 339     contrast_pixels=PixelGetNextIteratorRow(contrast_iterator,&amp;width);
 340     if ((pixels == (PixelWand **) NULL) ||
 341         (contrast_pixels == (PixelWand **) NULL))
 342       break;
 343     for (x=0; x &lt; (long) width; x++)
 344     {
 345       PixelGetMagickColor(pixels[x],&amp;pixel);
 346       pixel.red=SigmoidalContrast(pixel.red);
 347       pixel.green=SigmoidalContrast(pixel.green);
 348       pixel.blue=SigmoidalContrast(pixel.blue);
 349       pixel.index=SigmoidalContrast(pixel.index);
 350       PixelSetMagickColor(contrast_pixels[x],&amp;pixel);
 351     }
 352     (void) PixelSyncIterator(contrast_iterator);
 353   }
 354   if (y &lt; (long) MagickGetImageHeight(image_wand))
 355     ThrowWandException(image_wand);
 356   contrast_iterator=DestroyPixelIterator(contrast_iterator);
 357   iterator=DestroyPixelIterator(iterator);
 358   image_wand=DestroyMagickWand(image_wand);
 359   /*
 360     Write the image then destroy it.
 361   */
 362   status=MagickWriteImages(contrast_wand,argv[2],MagickTrue);
 363   if (status == MagickFalse)
 364     ThrowWandException(image_wand);
 365   contrast_wand=DestroyMagickWand(contrast_wand);
 366   MagickWandTerminus();
 367   return(0);
 368 }
 369 </div>
 370 <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="../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>
 371
 372 <div class="viewport">
 373 #include &lt;stdio.h&gt;
 374 #include &lt;stdlib.h&gt;
 375 #include &lt;math.h&gt;
 376 #include &lt;wand/MagickWand.h&gt;
 377
 378 static MagickBooleanType SigmoidalContrast(WandView *pixel_view,
 379   const ssize_t y,const int id,void *context)
 380 {
 381 #define QuantumScale  ((MagickRealType) 1.0/(MagickRealType) QuantumRange)
 382 #define SigmoidalContrast(x) \
 383   (QuantumRange*(1.0/(1+exp(10.0*(0.5-QuantumScale*x)))-0.0066928509)*1.0092503)
 384
 385   RectangleInfo
 386     extent;
 387
 388   MagickPixelPacket
 389     pixel;
 390
 391   PixelWand
 392     **pixels;
 393
 394   register long
 395     x;
 396
 397   extent=GetWandViewExtent(contrast_view);
 398   pixels=GetWandViewPixels(contrast_view);
 399   for (x=0; x &lt; (long) (extent.width-extent.height); x++)
 400   {
 401     PixelGetMagickColor(pixels[x],&amp;pixel);
 402     pixel.red=SigmoidalContrast(pixel.red);
 403     pixel.green=SigmoidalContrast(pixel.green);
 404     pixel.blue=SigmoidalContrast(pixel.blue);
 405     pixel.index=SigmoidalContrast(pixel.index);
 406     PixelSetMagickColor(contrast_pixels[x],&amp;pixel);
 407   }
 408   return(MagickTrue);
 409 }
 410
 411 int main(int argc,char **argv)
 412 {
 413 #define ThrowViewException(view) \
 414 { \
 415   description=GetWandViewException(view,&amp;severity); \
 416   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
 417   description=(char *) MagickRelinquishMemory(description); \
 418   exit(-1); \
 419 }
 420 #define ThrowWandException(wand) \
 421 { \
 422   description=MagickGetException(wand,&amp;severity); \
 423   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
 424   description=(char *) MagickRelinquishMemory(description); \
 425   exit(-1); \
 426 }
 427
 428   char
 429     *description;
 430
 431   ExceptionType
 432     severity;
 433
 434   MagickBooleanType
 435     status;
 436
 437   MagickPixelPacket
 438     pixel;
 439
 440   MagickWand
 441     *contrast_wand;
 442
 443   WandView
 444     *contrast_view;
 445
 446   if (argc != 3)
 447     {
 448       (void) fprintf(stdout,"Usage: %s image sigmoidal-image\n",argv[0]);
 449       exit(0);
 450     }
 451   /*
 452     Read an image.
 453   */
 454   MagickWandGenesis();
 455   contrast_wand=NewMagickWand();
 456   status=MagickReadImage(contrast_wand,argv[1]);
 457   if (status == MagickFalse)
 458     ThrowWandException(contrast_wand);
 459   /*
 460     Sigmoidal non-linearity contrast control.
 461   */
 462   contrast_view=NewWandView(contrast_wand);
 463   if (contrast_view == (WandView *) NULL)
 464     ThrowWandException(contrast_wand);
 465   status=UpdateWandViewIterator(contrast_view,SigmoidalContrast,(void *) NULL);
 466   if (status == MagickFalse)
 467     ThrowWandException(contrast_wand);
 468   contrast_view=DestroyWandView(contrast_view);
 469   /*
 470     Write the image then destroy it.
 471   */
 472   status=MagickWriteImages(contrast_wand,argv[2],MagickTrue);
 473   if (status == MagickFalse)
 474     ThrowWandException(contrast_wand);
 475   contrast_wand=DestroyMagickWand(contrast_wand);
 476   MagickWandTerminus();
 477   return(0);
 478 }
 479 </div>
 480 <p><a href="http://members.shaw.ca/el.supremo/MagickWand/">MagickWand Examples in C</a> illustrates how to use the ImageMagick MagickWand API. Each example is presented as a C function, complete with headers, so that it can be copied to a file and then included in your own C project.</p>
 481 </div>
 482
 483 </div>
 484
 485 <div id="linkbar">
 486     <span id="linkbar-west"> </span>
 487
 488     <span id="linkbar-center">
 489       <a href="http://www.imagemagick.org/discourse-server/">Discourse Server</a> •
 490       <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Studio</a> •
 491       <a href="http://jqmagick.imagemagick.org/">JqMagick</a>
 492     </span>
 493     <span id="linkbar-east"> </span>
 494   </div>
 495   <div class="footer">
 496     <span id="footer-west">©  1999-2013 ImageMagick Studio LLC</span>
 497     <span id="footer-east"> <a href="contact.html">Contact the Wizards</a></span>
 498   </div>
 499   <div style="clear: both; margin: 0; width: 100%; "></div>
 500 </body>
 501 </html>