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

   1
   2
   3
   4
   5 <!DOCTYPE html>
   6 <html lang="en">
   7 <head>
   8   <meta charset="utf-8"  />
   9   <meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1,shrink-to-fit=no"  />
  10   <title>ImageMagick - MagickWand, C API</title>
  11   <meta name="application-name" content="ImageMagick" />
  12   <meta name="description" content="ImageMagick® creates, edits, composes, and converts bitmap images. Resize an image, crop it, change its shades and colors, add captions, and more." />
  13   <meta name="application-url" content="https://imagemagick.org" />
  14   <meta name="generator" content="PHP" />
  15   <meta name="keywords" content="magickwc, api, ImageMagick, PerlMagick, image processing, image, photo, software, Magick++, OpenMP, convert" />
  16   <meta name="rating" content="GENERAL" />
  17   <meta name="robots" content="INDEX, FOLLOW" />
  18   <meta name="generator" content="ImageMagick Studio LLC" />
  19   <meta name="author" content="ImageMagick Studio LLC" />
  20   <meta name="revisit-after" content="2 DAYS" />
  21   <meta name="resource-type" content="document" />
  22   <meta name="copyright" content="Copyright (c) 1999-2019 ImageMagick Studio LLC" />
  23   <meta name="distribution" content="Global" />
  24   <meta name="magick-serial" content="P131-S030410-R485315270133-P82224-A6668-G1245-1" />
  25   <meta property='og:url' content='../' />
  26   <meta property='og:title' content='ImageMagick' />
  27   <meta property='og:image' content='../images/logo.png' />
  28   <meta property='og:type' content='website' />
  29   <meta property='og:site_name' content='ImageMagick' />
  30   <meta property='og:description' content="Convert, Edit, or Compose Bitmap Images" />
  31   <meta name="google-site-verification" content="_bMOCDpkx9ZAzBwb2kF3PRHbfUUdFj2uO8Jd1AXArz4" />
  32   <link href="magick-wand.html" rel="canonical" />
  33   <link href="../images/wand.png" rel="icon" />
  34   <link href="../images/wand.ico" rel="shortcut icon" />
  35   <link href="assets/magick.css" rel="stylesheet" />
  36 </head>
  37 <body>
  38   <header>
  39   <nav class="navbar navbar-expand-md navbar-dark fixed-top bg-dark">
  40     <a class="navbar-brand" href="../index.html"><img class="d-block" id="icon" alt="ImageMagick" width="32" height="32" src="../images/wand.ico"/></a>
  41     <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarsMagick" aria-controls="navbarsMagick" aria-expanded="false" aria-label="Toggle navigation">
  42       <span class="navbar-toggler-icon"></span>
  43     </button>
  44
  45     <div class="navbar-collapse collapse" id="navbarsMagick" style="">
  46     <ul class="navbar-nav mr-auto">
  47       <li class="nav-item ">
  48         <a class="nav-link" href="../index.html">Home <span class="sr-only">(current)</span></a>
  49       </li>
  50       <li class="nav-item ">
  51         <a class="nav-link" href="download.html">Download</a>
  52       </li>
  53       <li class="nav-item ">
  54         <a class="nav-link" href="command-line-tools.html">Tools</a>
  55       </li>
  56       <li class="nav-item ">
  57         <a class="nav-link" href="command-line-processing.html">Command-line</a>
  58       </li>
  59       <li class="nav-item ">
  60         <a class="nav-link" href="resources.html">Resources</a>
  61       </li>
  62       <li class="nav-item ">
  63         <a class="nav-link" href="develop.html">Develop</a>
  64       </li>
  65       <li class="nav-item">
  66         <a class="nav-link" target="_blank" href="https://imagemagick.org/discourse-server/">Community</a>
  67       </li>
  68     </ul>
  69     <form class="form-inline my-2 my-lg-0" action="https://imagemagick.org/script/search.php">
  70       <input class="form-control mr-sm-2" type="text" name="q" placeholder="Search" aria-label="Search">
  71       <button class="btn btn-outline-success my-2 my-sm-0" type="submit" name="sa">Search</button>
  72     </form>
  73     </div>
  74   </nav>
  75   <div class="container">
  76    <script async="async" src="https://localhost/pagead/js/adsbygoogle.js"></script>    <ins class="adsbygoogle"
  77          style="display:block"
  78          data-ad-client="ca-pub-3129977114552745"
  79          data-ad-slot="6345125851"
  80          data-full-width-responsive="true"
  81          data-ad-format="horizontal"></ins>
  82     <script>
  83       (adsbygoogle = window.adsbygoogle || []).push({});
  84     </script>
  85
  86   </div>
  87   </header>
  88   <main class="container">
  89     <div class="magick-template">
  90 <div class="magick-header">
  91
  92 <p class="lead magick-description">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>
  93
  94 <ul>
  95   <li><a href="api/magick-wand.html">Magick Wand Methods</a></li>
  96   <li><a href="api/magick-property.html">Set or Get Magick Wand Properties</a></li>
  97   <li><a href="api/magick-image.html">Magick Wand Image Methods</a></li>
  98   <li><a href="api/pixel-iterator.html">Pixel Iterator Methods</a></li>
  99   <li><a href="api/pixel-wand.html">Pixel Wand Methods</a></li>
 100   <li><a href="api/drawing-wand.html">Image Vector Drawing</a></li>
 101   <li><a href="api/mogrify.html">Command-line Interface</a></li>
 102   <li><a href="api/wand-view.html">Wand View Methods</a></li>
 103   <li><a href="api/magick-deprecate.html">Deprecated Methods</a></li>
 104   <li><a href="exception.html">Error and Warning Codes</a></li>
 105 </ul>
 106
 107 <p>After you write your MagickWand program, compile it like this:</p>
 108
 109 <pre class="highlight"><code>cc -o wand wand.c `pkg-config --cflags --libs MagickWand`
 110 </code></pre>
 111
 112 <p>Set the <code>PKG_CONFIG_PATH</code> environment variable if ImageMagick is not in your default system path:</p>
 113
 114 <pre class="highlight"><code>export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
 115 </code></pre>
 116
 117 <p>Here is a example program that utilizes the MagickWand API to get you started, <a href="https://imagemagick.org/source/wand.c">wand.c</a>. It reads an image, creates a thumbnail, and writes the result to disk.</p>
 118
 119 <pre class="pre-scrollable"><code>#include &lt;stdio.h>
 120 #include &lt;stdlib.h>
 121 #include &lt;wand/MagickWand.h>
 122
 123 int main(int argc,char **argv)
 124 {
 125 #define ThrowWandException(wand) \
 126 { \
 127   char \
 128     *description; \
 129  \
 130   ExceptionType \
 131     severity; \
 132  \
 133   description=MagickGetException(wand,&amp;severity); \
 134   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
 135   description=(char *) MagickRelinquishMemory(description); \
 136   exit(-1); \
 137 }
 138
 139   MagickBooleanType
 140     status;
 141
 142   MagickWand
 143     *magick_wand;
 144
 145   if (argc != 3)
 146     {
 147       (void) fprintf(stdout,"Usage: %s image thumbnail\n",argv[0]);
 148       exit(0);
 149     }
 150   /*
 151     Read an image.
 152   */
 153   MagickWandGenesis();
 154   magick_wand=NewMagickWand();
 155   status=MagickReadImage(magick_wand,argv[1]);
 156   if (status == MagickFalse)
 157     ThrowWandException(magick_wand);
 158   /*
 159     Turn the images into a thumbnail sequence.
 160   */
 161   MagickResetIterator(magick_wand);
 162   while (MagickNextImage(magick_wand) != MagickFalse)
 163     MagickResizeImage(magick_wand,106,80,LanczosFilter,1.0);
 164   /*
 165     Write the image then destroy it.
 166   */
 167   status=MagickWriteImages(magick_wand,argv[2],MagickTrue);
 168   if (status == MagickFalse)
 169     ThrowWandException(magick_wand);
 170   magick_wand=DestroyMagickWand(magick_wand);
 171   MagickWandTerminus();
 172   return(0);
 173 }
 174 </code></pre>
 175
 176 <p>Here is another program that shows one way to get and set image pixels with the MagickWand API, <a href="https://imagemagick.org/source/contrast.c">contrast.c</a>. It reads an image, applies sigmoidal non-linearity contrast control, and writes the result to disk.</p>
 177
 178 <pre class="pre-scrollable"><code>#include &lt;stdio.h>
 179 #include &lt;stdlib.h>
 180 #include &lt;math.h>
 181 #include &lt;wand/MagickWand.h>
 182
 183 int main(int argc,char **argv)
 184 {
 185 #define QuantumScale  ((MagickRealType) 1.0/(MagickRealType) QuantumRange)
 186 #define SigmoidalContrast(x) \
 187   (QuantumRange*(1.0/(1+exp(10.0*(0.5-QuantumScale*x)))-0.0066928509)*1.0092503)
 188 #define ThrowWandException(wand) \
 189 { \
 190   char \
 191     *description; \
 192  \
 193   ExceptionType \
 194     severity; \
 195  \
 196   description=MagickGetException(wand,&amp;severity); \
 197   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
 198   description=(char *) MagickRelinquishMemory(description); \
 199   exit(-1); \
 200 }
 201
 202   long
 203     y;
 204
 205   MagickBooleanType
 206     status;
 207
 208   MagickPixelPacket
 209     pixel;
 210
 211   MagickWand
 212     *contrast_wand,
 213     *image_wand;
 214
 215   PixelIterator
 216     *contrast_iterator,
 217     *iterator;
 218
 219   PixelWand
 220     **contrast_pixels,
 221     **pixels;
 222
 223   register long
 224     x;
 225
 226   unsigned long
 227     width;
 228
 229   if (argc != 3)
 230     {
 231       (void) fprintf(stdout,"Usage: %s image sigmoidal-image\n",argv[0]);
 232       exit(0);
 233     }
 234   /*
 235     Read an image.
 236   */
 237   MagickWandGenesis();
 238   image_wand=NewMagickWand();
 239   status=MagickReadImage(image_wand,argv[1]);
 240   if (status == MagickFalse)
 241     ThrowWandException(image_wand);
 242   contrast_wand=CloneMagickWand(image_wand);
 243   /*
 244     Sigmoidal non-linearity contrast control.
 245   */
 246   iterator=NewPixelIterator(image_wand);
 247   contrast_iterator=NewPixelIterator(contrast_wand);
 248   if ((iterator == (PixelIterator *) NULL) ||
 249       (contrast_iterator == (PixelIterator *) NULL))
 250     ThrowWandException(image_wand);
 251   for (y=0; y &lt; (long) MagickGetImageHeight(image_wand); y++)
 252   {
 253     pixels=PixelGetNextIteratorRow(iterator,&amp;width);
 254     contrast_pixels=PixelGetNextIteratorRow(contrast_iterator,&amp;width);
 255     if ((pixels == (PixelWand **) NULL) ||
 256         (contrast_pixels == (PixelWand **) NULL))
 257       break;
 258     for (x=0; x &lt; (long) width; x++)
 259     {
 260       PixelGetMagickColor(pixels[x],&amp;pixel);
 261       pixel.red=SigmoidalContrast(pixel.red);
 262       pixel.green=SigmoidalContrast(pixel.green);
 263       pixel.blue=SigmoidalContrast(pixel.blue);
 264       pixel.index=SigmoidalContrast(pixel.index);
 265       PixelSetMagickColor(contrast_pixels[x],&amp;pixel);
 266     }
 267     (void) PixelSyncIterator(contrast_iterator);
 268   }
 269   if (y &lt; (long) MagickGetImageHeight(image_wand))
 270     ThrowWandException(image_wand);
 271   contrast_iterator=DestroyPixelIterator(contrast_iterator);
 272   iterator=DestroyPixelIterator(iterator);
 273   image_wand=DestroyMagickWand(image_wand);
 274   /*
 275     Write the image then destroy it.
 276   */
 277   status=MagickWriteImages(contrast_wand,argv[2],MagickTrue);
 278   if (status == MagickFalse)
 279     ThrowWandException(image_wand);
 280   contrast_wand=DestroyMagickWand(contrast_wand);
 281   MagickWandTerminus();
 282   return(0);
 283 }
 284 </code></pre>
 285 <p><a class="anchor" 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="https://imagemagick.org/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>
 286
 287 <pre class="pre-scrollable"><code>#include &lt;stdio.h>
 288 #include &lt;stdlib.h>
 289 #include &lt;math.h>
 290 #include &lt;wand/MagickWand.h>
 291
 292 static MagickBooleanType SigmoidalContrast(WandView *pixel_view,
 293   const ssize_t y,const int id,void *context)
 294 {
 295 #define QuantumScale  ((MagickRealType) 1.0/(MagickRealType) QuantumRange)
 296 #define SigmoidalContrast(x) \
 297   (QuantumRange*(1.0/(1+exp(10.0*(0.5-QuantumScale*x)))-0.0066928509)*1.0092503)
 298
 299   RectangleInfo
 300     extent;
 301
 302   MagickPixelPacket
 303     pixel;
 304
 305   PixelWand
 306     **pixels;
 307
 308   register long
 309     x;
 310
 311   extent=GetWandViewExtent(contrast_view);
 312   pixels=GetWandViewPixels(contrast_view);
 313   for (x=0; x &lt; (long) (extent.width-extent.height); x++)
 314   {
 315     PixelGetMagickColor(pixels[x],&amp;pixel);
 316     pixel.red=SigmoidalContrast(pixel.red);
 317     pixel.green=SigmoidalContrast(pixel.green);
 318     pixel.blue=SigmoidalContrast(pixel.blue);
 319     pixel.index=SigmoidalContrast(pixel.index);
 320     PixelSetMagickColor(contrast_pixels[x],&amp;pixel);
 321   }
 322   return(MagickTrue);
 323 }
 324
 325 int main(int argc,char **argv)
 326 {
 327 #define ThrowViewException(view) \
 328 { \
 329   description=GetWandViewException(view,&amp;severity); \
 330   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
 331   description=(char *) MagickRelinquishMemory(description); \
 332   exit(-1); \
 333 }
 334 #define ThrowWandException(wand) \
 335 { \
 336   description=MagickGetException(wand,&amp;severity); \
 337   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
 338   description=(char *) MagickRelinquishMemory(description); \
 339   exit(-1); \
 340 }
 341
 342   char
 343     *description;
 344
 345   ExceptionType
 346     severity;
 347
 348   MagickBooleanType
 349     status;
 350
 351   MagickPixelPacket
 352     pixel;
 353
 354   MagickWand
 355     *contrast_wand;
 356
 357   WandView
 358     *contrast_view;
 359
 360   if (argc != 3)
 361     {
 362       (void) fprintf(stdout,"Usage: %s image sigmoidal-image\n",argv[0]);
 363       exit(0);
 364     }
 365   /*
 366     Read an image.
 367   */
 368   MagickWandGenesis();
 369   contrast_wand=NewMagickWand();
 370   status=MagickReadImage(contrast_wand,argv[1]);
 371   if (status == MagickFalse)
 372     ThrowWandException(contrast_wand);
 373   /*
 374     Sigmoidal non-linearity contrast control.
 375   */
 376   contrast_view=NewWandView(contrast_wand);
 377   if (contrast_view == (WandView *) NULL)
 378     ThrowWandException(contrast_wand);
 379   status=UpdateWandViewIterator(contrast_view,SigmoidalContrast,(void *) NULL);
 380   if (status == MagickFalse)
 381     ThrowWandException(contrast_wand);
 382   contrast_view=DestroyWandView(contrast_view);
 383   /*
 384     Write the image then destroy it.
 385   */
 386   status=MagickWriteImages(contrast_wand,argv[2],MagickTrue);
 387   if (status == MagickFalse)
 388     ThrowWandException(contrast_wand);
 389   contrast_wand=DestroyMagickWand(contrast_wand);
 390   MagickWandTerminus();
 391   return(0);
 392 }
 393 </code></pre>
 394 <p><a href="../MagickWand/index.html">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>
 395 </div>
 396     </div>
 397   </main><!-- /.container -->
 398   <footer class="magick-footer">
 399     <p><a href="security-policy.html">Security</a> •
 400     <a href="architecture.html">Architecture</a>
 401
 402     <a href="magick-wand.html#"><img class="d-inline" id="wand" alt="And Now a Touch of Magick" width="16" height="16" src="../images/wand.ico"/></a>
 403
 404     <a href="links.html">Related</a> •
 405      <a href="sitemap.html">Sitemap</a>
 406     <br/>
 407     <a href="support.html">Donate</a> •
 408     <a href="http://pgp.mit.edu/pks/lookup?op=get&amp;search=0x89AB63D48277377A">Public Key</a> •
 409     <a href="https://imagemagick.org/script/contact.php">Contact Us</a>
 410     <br/>
 411     <small>© 1999-2019 ImageMagick Studio LLC</small></p>
 412   </footer>
 413
 414   <!-- Javascript assets -->
 415   <script src="assets/magick.js" crossorigin="anonymous"></script>
 416   <script>window.jQuery || document.write('<script src="https://localhost/ajax/libs/jquery/3.3.1/jquery.min.js"><\/script>')</script>
 417 </body>
 418 </html>