]> granicus.if.org Git - imagemagick/blob - www/magick-wand.html
(no commit message)
[imagemagick] / www / magick-wand.html
1 \r
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" \r
3   "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">\r
4 <html version="-//W3C//DTD XHTML 1.1//EN"\r
5       xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"\r
6       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"\r
7       xsi:schemaLocation="http://www.w3.org/1999/xhtml\r
8                           http://www.w3.org/MarkUp/SCHEMA/xhtml11.xsd">\r
9 <head>\r
10   <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>\r
11   <meta name="verify-v1" content="g222frIIxcQTrvDR3NBRUSKP3AnMNoqxOkIniCEkV7U="/>\r
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="Application-name" content="ImageMagick"/>
17   <meta name="Description" content="Use ImageMagick to convert, edit, or compose bitmap images in a variety of formats.  In addition resize, rotate, shear, distort and transform images."/>
18   <meta name="Application-url" content="http://www.imagemagick.org"/>
19   <meta name="Generator" content="PHP"/>
20   <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"/>
21   <meta name="Rating" content="GENERAL"/>
22   <meta name="Robots" content="INDEX, FOLLOW"/>
23   <meta name="Generator" content="ImageMagick Studio LLC"/>
24   <meta name="Author" content="ImageMagick Studio LLC"/>
25   <meta name="Revisit-after" content="2 DAYS"/>
26   <meta name="Resource-type" content="document"/>
27   <meta name="Copyright" content="Copyright (c) 1999-2011 ImageMagick Studio LLC"/>
28   <meta name="Distribution" content="Global"/>
29   <link rel="icon" href="../images/wand.png"/>
30   <link rel="shortcut icon" href="../images/wand.ico"  type="images/x-icon"/>
31   <link rel="meta" type="application/rdf+xml" title="ICI" href="http://imagemagick.org/ici.rdf"/>\r
32   <link rel="stylesheet" href="http://www.google.com/cse/style/look/default.css" type="text/css" />\r
33   <style type="text/css" media="all">\r
34     @import url("../www/magick.css");\r
35   </style>\r
36   <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js"></script>\r
37   <script type="text/javascript" src="../fancybox/jquery.fancybox-1.3.4.pack.js"></script>\r
38   <link rel="stylesheet" type="text/css" href="../fancybox/jquery.fancybox-1.3.4.css" media="screen" />\r
39   <script type="text/javascript">\r
40     $(document).ready(function() {\r
41       $("a[href$=.jpg],a[href$=.png],a[href$=.gif]").fancybox({\r
42         'transitionIn'  : 'elastic',\r
43         'transitionOut' : 'elastic',\r
44         'overlayShow'   : false,\r
45         'opacity'       : true\r
46       });\r
47     });\r
48   </script>\r
49 </head>\r
50 \r
51 <body id="www-imagemagick-org">\r
52 <div class="titlebar">\r
53 <div style="margin: 17px auto; float: left;">\r
54   <script type="text/javascript">\r
55   <!--\r
56     google_ad_client = "pub-3129977114552745";\r
57     google_ad_slot = "5439289906";\r
58     google_ad_width = 728;\r
59     google_ad_height = 90;\r
60   //-->\r
61   </script>\r
62   <script type="text/javascript"\r
63     src="http://pagead2.googlesyndication.com/pagead/show_ads.js">\r
64   </script>\r
65 </div>\r
66 <a href="http://www.imagemagick.org/discourse-server/">\r
67   <img src="../images/logo.jpg"\r
68   alt="ImageMagick Logo"\r
69   style="width: 123px; height: 118px; border: 0px; float: right;" /></a>\r
70 <a href="../index.html">\r
71   <img src="../images/sprite.jpg"\r
72   alt="ImageMagick Sprite"\r
73   style="width: 114px; height: 118px; border: 0px; float: right;" /></a>\r
74 </div>\r
75 \r
76 <div class="westbar">\r
77 \r
78 <div class="menu">
79   <a title="About ImageMagick" href="../index.html">About ImageMagick</a>
80 </div>
81 <div class="sep"></div>\r
82 <div class="menu">
83   <a title="Binary Releases" href="../www/binary-releases.html">Binary Releases</a>
84 </div>
85 <div class="sub">
86     <a title="Binary Release: Unix" href="../www/binary-releases.html#unix">Unix</a>
87 </div>
88 <div class="sub">
89     <a title="Binary Release: MacOS X" href="../www/binary-releases.html#macosx">Mac OS X</a>
90 </div>
91 <div class="sub">
92     <a title="Binary Release: iPhone" href="../www/binary-releases.html#iPhone">iPhone</a>
93 </div>
94 <div class="sub">
95     <a title="Binary Release: Windows" href="../www/binary-releases.html#windows">Windows</a>
96 </div>
97 <div class="sep"></div>\r
98 <div class="menu">
99   <a title="Command-line Tools" href="../www/command-line-tools.html">Command-line Tools</a>
100 </div>
101 <div class="sub">
102     <a title="Command-line Tools: Processing" href="../www/command-line-processing.html">Processing</a>
103 </div>
104 <div class="sub">
105     <a title="Command-line Tools: Options" href="../www/command-line-options.html">Options</a>
106 </div>
107 <div class="sub">
108     <a title="Command-line Tools: Usage" href="http://www.imagemagick.org/Usage/">Usage</a>
109 </div>
110 <div class="menu">
111   <a title="Program Interfaces" href="../www/api.html">Program Interfaces</a>
112 </div>
113 <div class="sub">
114     <a title="Program Interface: MagickWand" href="../www/magick-wand.html">MagickWand</a>
115 </div>
116 <div class="sub">
117     <a title="Program Interface: MagickCore" href="../www/magick-core.html">MagickCore</a>
118 </div>
119 <div class="sub">
120     <a title="Program Interface: PerlMagick" href="../www/perl-magick.html">PerlMagick</a>
121 </div>
122 <div class="sub">
123     <a title="Program Interface: Magick++" href="../www/magick++.html">Magick++</a>
124 </div>
125 <div class="sep"></div>\r
126 <div  class="menu">
127    <a title="Install from Source" href="../www/install-source.html">Install from Source</a>
128 </div>
129 <div class="sub">
130     <a title="Install from Source: Unix" href="../www/install-source.html#unix">Unix</a>
131 </div>
132 <div class="sub">
133     <a title="Install from Source: Windows" href="../www/install-source.html#windows">Windows</a>
134  </div>
135 <div class="menu">
136   <a title="Resources" href="../www/resources.html">Resources</a>
137 </div>
138 <div class="menu">
139   <a title="Architecture" href="../www/architecture.html">Architecture</a>
140 </div>
141 <div class="menu">
142   <a title="Download" href="../www/download.html">Download</a>
143 </div>
144 <div class="sep"></div>\r
145 <div class="menu">
146   <a title="Search" href="../www/search.html">Search</a>
147 </div>
148 <div class="sep"></div>\r
149 <div class="menu">
150   <a title="Site Map" href="../www/sitemap.html">Site Map</a>
151 </div>
152 <div  class="sub">
153   <a title="Site Map: Links" href="../www/links.html">Links</a>
154 </div>
155 <div class="sep"></div>\r
156 <div  class="menu">
157   <a rel="follow" title="Sponsors" href="../www/sponsors.html">Sponsors:</a>
158
159 <a href="http://www.networkredux.com">
160   <img src="../images/networkredux.png" alt="[sponsor]"
161   style="margin-top: 4px; margin-left: 4px; border: 0px; float: left;" /></a>
162 <div class="sponsbox">
163 <div  class="sponsor">
164   <a rel="follow" title="Sponsor: Web Hosting Break" href="http://www.webhostingbreak.com">Web Hosting Break</a><!-- 201109010090 ian@ian-m... -->
165 </div>
166 <div  class="sponsor">
167   <a rel="follow" title="Sponsor: Druckerei" href="http://www.allesdruck.de">Druckerei</a><!-- 201303011500 r.leo -->
168 </div>
169 <div  class="sponsor">
170   <a rel="follow" title="Sponsor: Website Hosting" href="http://www.hostreviewgeeks.com">Website Hosting</a><!-- 201110010090 alexanian media -->
171 </div>
172 <div  class="sponsor">
173   <a rel="follow" title="Sponsor: Hotel München" href="http://www.messehotel-erb-muenchen.de">Hotel München</a><!-- 201111010450 cerb -->
174 </div>
175 <div  class="sponsor">
176   <a rel="follow" title="Sponsor: Best Web Hosting" href="http://webhostinggeeks.com">Best Web Hosting</a><!-- 201110010720 -->
177 </div>
178 <div  class="sponsor">
179   <a rel="follow" title="Sponsor: Flyer drucken" href="http://www.online-druck.biz">Flyer drucken</a><!-- 201109010900 Floeter-->
180 </div>
181 <div  class="sponsor">
182   <a rel="follow" title="Sponsor: Web Hosting Reviews" href="http://www.webhostingmasters.com">Web Hosting Reviews</a><!-- 201107011500 affliatelabel -->
183 </div>
184 <div  class="sponsor">
185   <a rel="follow" title="Sponsor: Druckerei" href="http://print24.com/de/">Druckerei</a><!-- 201110010720 -->
186 </div>
187 <div  class="sponsor">
188   <a rel="follow" title="Sponsor: Web Hosting Ratings" href="http://webhostingrating.com">Web Hosting Ratings</a><!-- 201110010720 -->
189 </div>
190 <div  class="sponsor">
191    <a rel="follow" title="Sponsor: Fernsehdienst Berlin" href="http://www.atlas-multimedia.de">Fernsehdienst Berlin</a><!-- 2011080100025 atlas.multimedia-->
192 </div>
193 </div>
194 </div>
195 </div>\r
196 \r
197 <div class="eastbar">\r
198 \r
199 </div>\r
200 \r
201 <div class="main">\r
202 \r
203 <h1>MagickWand C API</h1>
204
205 <div class="doc-section">
206 <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>
207
208 <ul>
209   <li><a href="../www/api/magick-wand.html">Magick Wand Methods</a></li>
210   <li><a href="../www/api/magick-property.html">Set or Get Magick Wand Properties</a></li>
211   <li><a href="../www/api/magick-image.html">Magick Wand Image Methods</a></li>
212   <li><a href="../www/api/pixel-iterator.html">Pixel Iterator Methods</a></li>
213   <li><a href="../www/api/pixel-wand.html">Pixel Wand Methods</a></li>
214   <li><a href="../www/api/drawing-wand.html">Image Vector Drawing</a></li>
215   <li><a href="../www/api/mogrify.html">Command-line Interface</a></li>
216   <li><a href="../www/api/wand-view.html">Wand View Methods</a></li>
217   <li><a href="../www/api/magick-deprecate.html">Deprecated Methods</a></li>
218   <li><a href="../www/exception.html">Error and Warning Codes</a></li>
219 </ul>
220
221 <p>After you write your MagickWand program, compile it like this:</p>
222
223 <p class='crt'><span class="crtprompt"> $magick&gt; </span><span class='crtin'>cc `MagickWand-config --cflags --cppflags` -O2 -o wand wand.c  \ <br/> `MagickWand-config --ldflags --libs`</span></p>
224 <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>
225
226 <div class="viewport">
227 #include &lt;stdio.h>
228 #include &lt;stdlib.h>
229 #include &lt;wand/MagickWand.h>
230
231 int main(int argc,char **argv)
232 {
233 #define ThrowWandException(wand) \
234 { \
235   char \
236     *description; \
237  \
238   ExceptionType \
239     severity; \
240  \
241   description=MagickGetException(wand,&amp;severity); \
242   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
243   description=(char *) MagickRelinquishMemory(description); \
244   exit(-1); \
245 }
246
247   MagickBooleanType
248     status;
249
250   MagickWand
251     *magick_wand;
252
253   if (argc != 3)
254     {
255       (void) fprintf(stdout,"Usage: %s image thumbnail\n",argv[0]);
256       exit(0);
257     }
258   /*
259     Read an image.
260   */
261   MagickWandGenesis();
262   magick_wand=NewMagickWand();
263   status=MagickReadImage(magick_wand,argv[1]);
264   if (status == MagickFalse)
265     ThrowWandException(magick_wand);
266   /*
267     Turn the images into a thumbnail sequence.
268   */
269   MagickResetIterator(magick_wand);
270   while (MagickNextImage(magick_wand) != MagickFalse)
271     MagickResizeImage(magick_wand,106,80,LanczosFilter,1.0);
272   /*
273     Write the image then destroy it.
274   */
275   status=MagickWriteImages(magick_wand,argv[2],MagickTrue);
276   if (status == MagickFalse)
277     ThrowWandException(magick_wand);
278   magick_wand=DestroyMagickWand(magick_wand);
279   MagickWandTerminus();
280   return(0);
281 }
282 </div>
283
284 <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>
285
286 <div class="viewport">
287 #include &lt;stdio.h>
288 #include &lt;stdlib.h>
289 #include &lt;math.h>
290 #include &lt;wand/MagickWand.h>
291
292 int main(int argc,char **argv)
293 {
294 #define QuantumScale  ((MagickRealType) 1.0/(MagickRealType) QuantumRange)
295 #define SigmoidalContrast(x) \
296   (QuantumRange*(1.0/(1+exp(10.0*(0.5-QuantumScale*x)))-0.0066928509)*1.0092503)
297 #define ThrowWandException(wand) \
298 { \
299   char \
300     *description; \
301  \
302   ExceptionType \
303     severity; \
304  \
305   description=MagickGetException(wand,&amp;severity); \
306   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
307   description=(char *) MagickRelinquishMemory(description); \
308   exit(-1); \
309 }
310
311   long
312     y;
313
314   MagickBooleanType
315     status;
316
317   MagickPixelPacket
318     pixel;
319
320   MagickWand
321     *contrast_wand,
322     *image_wand;
323
324   PixelIterator
325     *contrast_iterator,
326     *iterator;
327
328   PixelWand
329     **contrast_pixels,
330     **pixels;
331
332   register long
333     x;
334
335   unsigned long
336     width;
337
338   if (argc != 3)
339     {
340       (void) fprintf(stdout,"Usage: %s image sigmoidal-image\n",argv[0]);
341       exit(0);
342     }
343   /*
344     Read an image.
345   */
346   MagickWandGenesis();
347   image_wand=NewMagickWand();
348   status=MagickReadImage(image_wand,argv[1]);
349   if (status == MagickFalse)
350     ThrowWandException(image_wand);
351   contrast_wand=CloneMagickWand(image_wand);
352   /*
353     Sigmoidal non-linearity contrast control.
354   */
355   iterator=NewPixelIterator(image_wand);
356   contrast_iterator=NewPixelIterator(contrast_wand);
357   if ((iterator == (PixelIterator *) NULL) ||
358       (contrast_iterator == (PixelIterator *) NULL))
359     ThrowWandException(image_wand);
360   for (y=0; y &lt; (long) MagickGetImageHeight(image_wand); y++)
361   {
362     pixels=PixelGetNextIteratorRow(iterator,&amp;width);
363     contrast_pixels=PixelGetNextIteratorRow(contrast_iterator,&amp;width);
364     if ((pixels == (PixelWand **) NULL) ||
365         (contrast_pixels == (PixelWand **) NULL))
366       break;
367     for (x=0; x &lt; (long) width; x++)
368     {
369       PixelGetMagickColor(pixels[x],&amp;pixel);
370       pixel.red=SigmoidalContrast(pixel.red);
371       pixel.green=SigmoidalContrast(pixel.green);
372       pixel.blue=SigmoidalContrast(pixel.blue);
373       pixel.index=SigmoidalContrast(pixel.index);
374       PixelSetMagickColor(contrast_pixels[x],&amp;pixel);
375     }
376     (void) PixelSyncIterator(contrast_iterator);
377   }
378   if (y &lt; (long) MagickGetImageHeight(image_wand))
379     ThrowWandException(image_wand);
380   contrast_iterator=DestroyPixelIterator(contrast_iterator);
381   iterator=DestroyPixelIterator(iterator);
382   image_wand=DestroyMagickWand(image_wand);
383   /*
384     Write the image then destroy it.
385   */
386   status=MagickWriteImages(contrast_wand,argv[2],MagickTrue);
387   if (status == MagickFalse)
388     ThrowWandException(image_wand);
389   contrast_wand=DestroyMagickWand(contrast_wand);
390   MagickWandTerminus();
391   return(0);
392 }
393 </div>
394 <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="../www/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>
395
396 <div class="viewport">
397 #include &lt;stdio.h>
398 #include &lt;stdlib.h>
399 #include &lt;math.h>
400 #include &lt;wand/MagickWand.h>
401
402 static MagickBooleanType SigmoidalContrast(WandView *pixel_view,
403   const ssize_t y,const int id,void *context)
404 {
405 #define QuantumScale  ((MagickRealType) 1.0/(MagickRealType) QuantumRange)
406 #define SigmoidalContrast(x) \
407   (QuantumRange*(1.0/(1+exp(10.0*(0.5-QuantumScale*x)))-0.0066928509)*1.0092503)
408
409   RectangleInfo
410     extent;
411
412   MagickPixelPacket
413     pixel;
414
415   PixelWand
416     **pixels;
417
418   register long
419     x;
420
421   extent=GetWandViewExtent(contrast_view);
422   pixels=GetWandViewPixels(contrast_view);
423   for (x=0; x &lt; (long) (extent.width-extent.height); x++)
424   {
425     PixelGetMagickColor(pixels[x],&amp;pixel);
426     pixel.red=SigmoidalContrast(pixel.red);
427     pixel.green=SigmoidalContrast(pixel.green);
428     pixel.blue=SigmoidalContrast(pixel.blue);
429     pixel.index=SigmoidalContrast(pixel.index);
430     PixelSetMagickColor(contrast_pixels[x],&amp;pixel);
431   }
432   return(MagickTrue);
433 }
434
435 int main(int argc,char **argv)
436 {
437 #define ThrowViewException(view) \
438 { \
439   description=GetWandViewException(view,&amp;severity); \
440   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
441   description=(char *) MagickRelinquishMemory(description); \
442   exit(-1); \
443 }
444 #define ThrowWandException(wand) \
445 { \
446   description=MagickGetException(wand,&amp;severity); \
447   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
448   description=(char *) MagickRelinquishMemory(description); \
449   exit(-1); \
450 }
451
452   char
453     *description;
454
455   ExceptionType
456     severity;
457
458   MagickBooleanType
459     status;
460
461   MagickPixelPacket
462     pixel;
463
464   MagickWand
465     *contrast_wand;
466
467   WandView
468     *contrast_view;
469
470   if (argc != 3)
471     {
472       (void) fprintf(stdout,"Usage: %s image sigmoidal-image\n",argv[0]);
473       exit(0);
474     }
475   /*
476     Read an image.
477   */
478   MagickWandGenesis();
479   contrast_wand=NewMagickWand();
480   status=MagickReadImage(contrast_wand,argv[1]);
481   if (status == MagickFalse)
482     ThrowWandException(contrast_wand);
483   /*
484     Sigmoidal non-linearity contrast control.
485   */
486   contrast_view=NewWandView(contrast_wand);
487   if (contrast_view == (WandView *) NULL)
488     ThrowWandException(contrast_wand);
489   status=UpdateWandViewIterator(contrast_view,SigmoidalContrast,(void *) NULL);
490   if (status == MagickFalse)
491     ThrowWandException(contrast_wand);
492   contrast_view=DestroyWandView(contrast_view);
493   /*
494     Write the image then destroy it.
495   */
496   status=MagickWriteImages(contrast_wand,argv[2],MagickTrue);
497   if (status == MagickFalse)
498     ThrowWandException(contrast_wand);
499   contrast_wand=DestroyMagickWand(contrast_wand);
500   MagickWandTerminus();
501   return(0);
502 }
503 </div>
504 </div>
505 \r
506 </div>\r
507 \r
508 <div id="linkbar">\r
509     <span id="linkbar-west">&nbsp;</span>\r
510     <span id="linkbar-center">\r
511       <a href="http://www.imagemagick.org/discourse-server/">Discourse Server</a> &bull;\r
512       <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Studio</a>\r
513     </span>\r
514     <span id="linkbar-east">&nbsp;</span>\r
515   </div>\r
516   <div class="footer">\r
517     <span id="footer-west">&copy; 1999-2011 ImageMagick Studio LLC</span>\r
518     <span id="footer-east"> <a href="http://www.imagemagick.org/script/contact.php">Contact the Wizards</a></span>\r
519   </div>\r
520   <div style="clear: both; margin: 0; width: 100%; "></div>\r
521   <script type="text/javascript">\r
522     var _gaq = _gaq || [];\r
523     _gaq.push(['_setAccount', 'UA-17690367-1']);\r
524     _gaq.push(['_trackPageview']);\r
525 \r
526     (function() {\r
527       var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;\r
528       ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';\r
529       var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);\r
530     })();\r
531   </script>\r
532 </body>\r
533 </html>\r