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="../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="http://www.imagemagick.org/ImageMagick-7.0.0/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="http://www.imagemagick.org/ImageMagick-7.0.0/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>
 160
 161 <div class="eastbar">
 162
 163   <div> <a class="FlattrButton" style="display:none;" rev="flattr;button:compact;" href="http://www.imagemagick.org/"></a></div>
 164   <noscript>
 165     <a href="http://flattr.com/thing/947300/Convert-Edit-And-Compose-Images" target="_blank">
 166     <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>
 167   </noscript>
 168
 169
 170 </div>
 171
 172 <div class="main">
 173
 174 <h1>MagickWand C API</h1>
 175
 176 <div class="doc-section">
 177 <p>The <a href="../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>
 178
 179 <ul>
 180   <li><a href="../api/magick-wand.html">Magick Wand Methods</a></li>
 181   <li><a href="../api/magick-property.html">Set or Get Magick Wand Properties</a></li>
 182   <li><a href="../api/magick-image.html">Magick Wand Image Methods</a></li>
 183   <li><a href="../api/pixel-iterator.html">Pixel Iterator Methods</a></li>
 184   <li><a href="../api/pixel-wand.html">Pixel Wand Methods</a></li>
 185   <li><a href="../api/drawing-wand.html">Image Vector Drawing</a></li>
 186   <li><a href="../api/mogrify.html">Command-line Interface</a></li>
 187   <li><a href="../api/wand-view.html">Wand View Methods</a></li>
 188   <li><a href="../api/magick-deprecate.html">Deprecated Methods</a></li>
 189   <li><a href="exception.html">Error and Warning Codes</a></li>
 190 </ul>
 191
 192 <p>After you write your MagickWand program, compile it like this:</p>
 193
 194 <p class="crt"><span class="crtprompt"> $magick&gt; </span><span class="crtin">cc -o wand `pkg-config --cflags --libs MagickWand` wand.c</span></p>
 195 <p>Set the <code>PKG_CONFIG_PATH</code> environment variable if ImageMagick is not in your default system path:</p>
 196 <p class="crt"><span class="crtprompt"> $magick&gt; </span><span class="crtin">export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig</span></p>
 197 <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>
 198
 199 <div class="viewport">
 200 #include &lt;stdio.h&gt;
 201 #include &lt;stdlib.h&gt;
 202 #include &lt;wand/MagickWand.h&gt;
 203
 204 int main(int argc,char **argv)
 205 {
 206 #define ThrowWandException(wand) \
 207 { \
 208   char \
 209     *description; \
 210  \
 211   ExceptionType \
 212     severity; \
 213  \
 214   description=MagickGetException(wand,&amp;severity); \
 215   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
 216   description=(char *) MagickRelinquishMemory(description); \
 217   exit(-1); \
 218 }
 219
 220   MagickBooleanType
 221     status;
 222
 223   MagickWand
 224     *magick_wand;
 225
 226   if (argc != 3)
 227     {
 228       (void) fprintf(stdout,"Usage: %s image thumbnail\n",argv[0]);
 229       exit(0);
 230     }
 231   /*
 232     Read an image.
 233   */
 234   MagickWandGenesis();
 235   magick_wand=NewMagickWand();
 236   status=MagickReadImage(magick_wand,argv[1]);
 237   if (status == MagickFalse)
 238     ThrowWandException(magick_wand);
 239   /*
 240     Turn the images into a thumbnail sequence.
 241   */
 242   MagickResetIterator(magick_wand);
 243   while (MagickNextImage(magick_wand) != MagickFalse)
 244     MagickResizeImage(magick_wand,106,80,LanczosFilter,1.0);
 245   /*
 246     Write the image then destroy it.
 247   */
 248   status=MagickWriteImages(magick_wand,argv[2],MagickTrue);
 249   if (status == MagickFalse)
 250     ThrowWandException(magick_wand);
 251   magick_wand=DestroyMagickWand(magick_wand);
 252   MagickWandTerminus();
 253   return(0);
 254 }
 255 </div>
 256
 257 <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>
 258
 259 <div class="viewport">
 260 #include &lt;stdio.h&gt;
 261 #include &lt;stdlib.h&gt;
 262 #include &lt;math.h&gt;
 263 #include &lt;wand/MagickWand.h&gt;
 264
 265 int main(int argc,char **argv)
 266 {
 267 #define QuantumScale  ((MagickRealType) 1.0/(MagickRealType) QuantumRange)
 268 #define SigmoidalContrast(x) \
 269   (QuantumRange*(1.0/(1+exp(10.0*(0.5-QuantumScale*x)))-0.0066928509)*1.0092503)
 270 #define ThrowWandException(wand) \
 271 { \
 272   char \
 273     *description; \
 274  \
 275   ExceptionType \
 276     severity; \
 277  \
 278   description=MagickGetException(wand,&amp;severity); \
 279   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
 280   description=(char *) MagickRelinquishMemory(description); \
 281   exit(-1); \
 282 }
 283
 284   long
 285     y;
 286
 287   MagickBooleanType
 288     status;
 289
 290   MagickPixelPacket
 291     pixel;
 292
 293   MagickWand
 294     *contrast_wand,
 295     *image_wand;
 296
 297   PixelIterator
 298     *contrast_iterator,
 299     *iterator;
 300
 301   PixelWand
 302     **contrast_pixels,
 303     **pixels;
 304
 305   register long
 306     x;
 307
 308   unsigned long
 309     width;
 310
 311   if (argc != 3)
 312     {
 313       (void) fprintf(stdout,"Usage: %s image sigmoidal-image\n",argv[0]);
 314       exit(0);
 315     }
 316   /*
 317     Read an image.
 318   */
 319   MagickWandGenesis();
 320   image_wand=NewMagickWand();
 321   status=MagickReadImage(image_wand,argv[1]);
 322   if (status == MagickFalse)
 323     ThrowWandException(image_wand);
 324   contrast_wand=CloneMagickWand(image_wand);
 325   /*
 326     Sigmoidal non-linearity contrast control.
 327   */
 328   iterator=NewPixelIterator(image_wand);
 329   contrast_iterator=NewPixelIterator(contrast_wand);
 330   if ((iterator == (PixelIterator *) NULL) ||
 331       (contrast_iterator == (PixelIterator *) NULL))
 332     ThrowWandException(image_wand);
 333   for (y=0; y &lt; (long) MagickGetImageHeight(image_wand); y++)
 334   {
 335     pixels=PixelGetNextIteratorRow(iterator,&amp;width);
 336     contrast_pixels=PixelGetNextIteratorRow(contrast_iterator,&amp;width);
 337     if ((pixels == (PixelWand **) NULL) ||
 338         (contrast_pixels == (PixelWand **) NULL))
 339       break;
 340     for (x=0; x &lt; (long) width; x++)
 341     {
 342       PixelGetMagickColor(pixels[x],&amp;pixel);
 343       pixel.red=SigmoidalContrast(pixel.red);
 344       pixel.green=SigmoidalContrast(pixel.green);
 345       pixel.blue=SigmoidalContrast(pixel.blue);
 346       pixel.index=SigmoidalContrast(pixel.index);
 347       PixelSetMagickColor(contrast_pixels[x],&amp;pixel);
 348     }
 349     (void) PixelSyncIterator(contrast_iterator);
 350   }
 351   if (y &lt; (long) MagickGetImageHeight(image_wand))
 352     ThrowWandException(image_wand);
 353   contrast_iterator=DestroyPixelIterator(contrast_iterator);
 354   iterator=DestroyPixelIterator(iterator);
 355   image_wand=DestroyMagickWand(image_wand);
 356   /*
 357     Write the image then destroy it.
 358   */
 359   status=MagickWriteImages(contrast_wand,argv[2],MagickTrue);
 360   if (status == MagickFalse)
 361     ThrowWandException(image_wand);
 362   contrast_wand=DestroyMagickWand(contrast_wand);
 363   MagickWandTerminus();
 364   return(0);
 365 }
 366 </div>
 367 <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>
 368
 369 <div class="viewport">
 370 #include &lt;stdio.h&gt;
 371 #include &lt;stdlib.h&gt;
 372 #include &lt;math.h&gt;
 373 #include &lt;wand/MagickWand.h&gt;
 374
 375 static MagickBooleanType SigmoidalContrast(WandView *pixel_view,
 376   const ssize_t y,const int id,void *context)
 377 {
 378 #define QuantumScale  ((MagickRealType) 1.0/(MagickRealType) QuantumRange)
 379 #define SigmoidalContrast(x) \
 380   (QuantumRange*(1.0/(1+exp(10.0*(0.5-QuantumScale*x)))-0.0066928509)*1.0092503)
 381
 382   RectangleInfo
 383     extent;
 384
 385   MagickPixelPacket
 386     pixel;
 387
 388   PixelWand
 389     **pixels;
 390
 391   register long
 392     x;
 393
 394   extent=GetWandViewExtent(contrast_view);
 395   pixels=GetWandViewPixels(contrast_view);
 396   for (x=0; x &lt; (long) (extent.width-extent.height); x++)
 397   {
 398     PixelGetMagickColor(pixels[x],&amp;pixel);
 399     pixel.red=SigmoidalContrast(pixel.red);
 400     pixel.green=SigmoidalContrast(pixel.green);
 401     pixel.blue=SigmoidalContrast(pixel.blue);
 402     pixel.index=SigmoidalContrast(pixel.index);
 403     PixelSetMagickColor(contrast_pixels[x],&amp;pixel);
 404   }
 405   return(MagickTrue);
 406 }
 407
 408 int main(int argc,char **argv)
 409 {
 410 #define ThrowViewException(view) \
 411 { \
 412   description=GetWandViewException(view,&amp;severity); \
 413   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
 414   description=(char *) MagickRelinquishMemory(description); \
 415   exit(-1); \
 416 }
 417 #define ThrowWandException(wand) \
 418 { \
 419   description=MagickGetException(wand,&amp;severity); \
 420   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
 421   description=(char *) MagickRelinquishMemory(description); \
 422   exit(-1); \
 423 }
 424
 425   char
 426     *description;
 427
 428   ExceptionType
 429     severity;
 430
 431   MagickBooleanType
 432     status;
 433
 434   MagickPixelPacket
 435     pixel;
 436
 437   MagickWand
 438     *contrast_wand;
 439
 440   WandView
 441     *contrast_view;
 442
 443   if (argc != 3)
 444     {
 445       (void) fprintf(stdout,"Usage: %s image sigmoidal-image\n",argv[0]);
 446       exit(0);
 447     }
 448   /*
 449     Read an image.
 450   */
 451   MagickWandGenesis();
 452   contrast_wand=NewMagickWand();
 453   status=MagickReadImage(contrast_wand,argv[1]);
 454   if (status == MagickFalse)
 455     ThrowWandException(contrast_wand);
 456   /*
 457     Sigmoidal non-linearity contrast control.
 458   */
 459   contrast_view=NewWandView(contrast_wand);
 460   if (contrast_view == (WandView *) NULL)
 461     ThrowWandException(contrast_wand);
 462   status=UpdateWandViewIterator(contrast_view,SigmoidalContrast,(void *) NULL);
 463   if (status == MagickFalse)
 464     ThrowWandException(contrast_wand);
 465   contrast_view=DestroyWandView(contrast_view);
 466   /*
 467     Write the image then destroy it.
 468   */
 469   status=MagickWriteImages(contrast_wand,argv[2],MagickTrue);
 470   if (status == MagickFalse)
 471     ThrowWandException(contrast_wand);
 472   contrast_wand=DestroyMagickWand(contrast_wand);
 473   MagickWandTerminus();
 474   return(0);
 475 }
 476 </div>
 477 <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>
 478 </div>
 479
 480 </div>
 481
 482 <div id="linkbar">
 483     <span id="linkbar-west"> </span>
 484
 485     <span id="linkbar-center">
 486       <a href="http://pgp.mit.edu:11371/pks/lookup?op=get&amp;search=0x89AB63D48277377A">Public Key</a> •
 487       <a href="../discourse-server">Discourse Server</a> •
 488       <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Studio</a> •
 489       <a href="http://jqmagick.imagemagick.org/">JqMagick</a>
 490     </span>
 491     <span id="linkbar-east"> </span>
 492 </div>
 493 <div class="footer">
 494   <span id="footer-west">©  1999-2013 ImageMagick Studio LLC</span>
 495   <span id="footer-east"> <a href="contact.html">Contact the Wizards</a></span>
 496 </div>
 497 <div style="clear: both; margin: 0; width: 100%; "></div>
 498 </body>
 499 </html>