]> 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 automagically."/>
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, Image, Processing, Automagically"/>
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: iOS" href="../www/binary-releases.html#iOS">iOS</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" href="http://www.micfo.com">Web Hosting</a><!-- 209901010090s golestan -->
165 </div>
166 <div  class="sponsor">
167   <a rel="follow" title="Sponsor: Search engine optimisation" href="http://www.seomoves.com.au">Search engine optimisation</a><!-- 201110010090s jen@seo lowprofilelinks -->
168 </div>
169 <div  class="sponsor">
170   <a rel="follow" title="Sponsor: Druckerei" href="http://print24.com/de/">Druckerei</a><!-- 201110010720 -->
171 </div>
172 <div  class="sponsor">
173   <a rel="follow" title="Sponsor: Web Hosting Deals" href="http://www.webhostingdeals.org">Web Hosting Deals</a><!-- 201111010270 chee.hoa darin -->
174 </div>
175 <div  class="sponsor">
176   <a rel="follow" title="Sponsor: Web Hosting Reviews" href="http://www.webhostingsecretrevealed.com">Web Hosting Secret Revealed</a><!-- 201204010540 iamchee jerry -->
177 </div>
178 <div  class="sponsor">
179   <a rel="follow" title="Sponsor: Web Hosting Break" href="http://www.webhostingbreak.com">Web Hosting Break</a><!-- 201109010090 ian@ian-m... -->
180 </div>
181 <div  class="sponsor">
182   <a rel="follow" title="Sponsor: Druckerei" href="http://www.allesdruck.de">Druckerei</a><!-- 201303011500 r.leo -->
183 </div>
184 <div  class="sponsor">
185   <a rel="follow" title="Sponsor: Website Hosting" href="http://www.hostreviewgeeks.com">Website Hosting</a><!-- 201110010090 alexanian media -->
186 </div>
187 <div  class="sponsor">
188   <a rel="follow" title="Sponsor: Hotel München" href="http://www.messehotel-erb-muenchen.de">Hotel München</a><!-- 201111010450 cerb -->
189 </div>
190 <div  class="sponsor">
191   <a rel="follow" title="Sponsor: Best Web Hosting" href="http://webhostinggeeks.com">Best Web Hosting</a><!-- 201110010720 -->
192 </div>
193 <div  class="sponsor">
194   <a rel="follow" title="Sponsor: Flyer drucken" href="http://www.online-druck.biz">Flyer drucken</a><!-- 201109010900 Floeter-->
195 </div>
196 <div  class="sponsor">
197   <a rel="follow" title="Sponsor: Web Hosting Reviews" href="http://www.webhostingmasters.com">Web Hosting Reviews</a><!-- 201107011500 affliatelabel -->
198 </div>
199 <div  class="sponsor">
200   <a rel="follow" title="Sponsor: Web Hosting Ratings" href="http://webhostingrating.com">Web Hosting Ratings</a><!-- 201110010720 -->
201 </div>
202 <div  class="sponsor">
203    <a rel="follow" title="Sponsor: alaTest.com" href="http://alatest.com">alaTest.com</a><!-- 20110801000300 -->
204 </div>
205 </div>
206 </div>
207 </div>\r
208 \r
209 <div class="eastbar">\r
210 \r
211 </div>\r
212 \r
213 <div class="main">\r
214 \r
215 <h1>MagickWand C API</h1>
216
217 <div class="doc-section">
218 <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>
219
220 <ul>
221   <li><a href="../www/api/magick-wand.html">Magick Wand Methods</a></li>
222   <li><a href="../www/api/magick-property.html">Set or Get Magick Wand Properties</a></li>
223   <li><a href="../www/api/magick-image.html">Magick Wand Image Methods</a></li>
224   <li><a href="../www/api/pixel-iterator.html">Pixel Iterator Methods</a></li>
225   <li><a href="../www/api/pixel-wand.html">Pixel Wand Methods</a></li>
226   <li><a href="../www/api/drawing-wand.html">Image Vector Drawing</a></li>
227   <li><a href="../www/api/mogrify.html">Command-line Interface</a></li>
228   <li><a href="../www/api/wand-view.html">Wand View Methods</a></li>
229   <li><a href="../www/api/magick-deprecate.html">Deprecated Methods</a></li>
230   <li><a href="../www/exception.html">Error and Warning Codes</a></li>
231 </ul>
232
233 <p>After you write your MagickWand program, compile it like this:</p>
234
235 <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>
236 <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>
237
238 <div class="viewport">
239 #include &lt;stdio.h>
240 #include &lt;stdlib.h>
241 #include &lt;wand/MagickWand.h>
242
243 int main(int argc,char **argv)
244 {
245 #define ThrowWandException(wand) \
246 { \
247   char \
248     *description; \
249  \
250   ExceptionType \
251     severity; \
252  \
253   description=MagickGetException(wand,&amp;severity); \
254   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
255   description=(char *) MagickRelinquishMemory(description); \
256   exit(-1); \
257 }
258
259   MagickBooleanType
260     status;
261
262   MagickWand
263     *magick_wand;
264
265   if (argc != 3)
266     {
267       (void) fprintf(stdout,"Usage: %s image thumbnail\n",argv[0]);
268       exit(0);
269     }
270   /*
271     Read an image.
272   */
273   MagickWandGenesis();
274   magick_wand=NewMagickWand();
275   status=MagickReadImage(magick_wand,argv[1]);
276   if (status == MagickFalse)
277     ThrowWandException(magick_wand);
278   /*
279     Turn the images into a thumbnail sequence.
280   */
281   MagickResetIterator(magick_wand);
282   while (MagickNextImage(magick_wand) != MagickFalse)
283     MagickResizeImage(magick_wand,106,80,LanczosFilter,1.0);
284   /*
285     Write the image then destroy it.
286   */
287   status=MagickWriteImages(magick_wand,argv[2],MagickTrue);
288   if (status == MagickFalse)
289     ThrowWandException(magick_wand);
290   magick_wand=DestroyMagickWand(magick_wand);
291   MagickWandTerminus();
292   return(0);
293 }
294 </div>
295
296 <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>
297
298 <div class="viewport">
299 #include &lt;stdio.h>
300 #include &lt;stdlib.h>
301 #include &lt;math.h>
302 #include &lt;wand/MagickWand.h>
303
304 int main(int argc,char **argv)
305 {
306 #define QuantumScale  ((MagickRealType) 1.0/(MagickRealType) QuantumRange)
307 #define SigmoidalContrast(x) \
308   (QuantumRange*(1.0/(1+exp(10.0*(0.5-QuantumScale*x)))-0.0066928509)*1.0092503)
309 #define ThrowWandException(wand) \
310 { \
311   char \
312     *description; \
313  \
314   ExceptionType \
315     severity; \
316  \
317   description=MagickGetException(wand,&amp;severity); \
318   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
319   description=(char *) MagickRelinquishMemory(description); \
320   exit(-1); \
321 }
322
323   long
324     y;
325
326   MagickBooleanType
327     status;
328
329   MagickPixelPacket
330     pixel;
331
332   MagickWand
333     *contrast_wand,
334     *image_wand;
335
336   PixelIterator
337     *contrast_iterator,
338     *iterator;
339
340   PixelWand
341     **contrast_pixels,
342     **pixels;
343
344   register long
345     x;
346
347   unsigned long
348     width;
349
350   if (argc != 3)
351     {
352       (void) fprintf(stdout,"Usage: %s image sigmoidal-image\n",argv[0]);
353       exit(0);
354     }
355   /*
356     Read an image.
357   */
358   MagickWandGenesis();
359   image_wand=NewMagickWand();
360   status=MagickReadImage(image_wand,argv[1]);
361   if (status == MagickFalse)
362     ThrowWandException(image_wand);
363   contrast_wand=CloneMagickWand(image_wand);
364   /*
365     Sigmoidal non-linearity contrast control.
366   */
367   iterator=NewPixelIterator(image_wand);
368   contrast_iterator=NewPixelIterator(contrast_wand);
369   if ((iterator == (PixelIterator *) NULL) ||
370       (contrast_iterator == (PixelIterator *) NULL))
371     ThrowWandException(image_wand);
372   for (y=0; y &lt; (long) MagickGetImageHeight(image_wand); y++)
373   {
374     pixels=PixelGetNextIteratorRow(iterator,&amp;width);
375     contrast_pixels=PixelGetNextIteratorRow(contrast_iterator,&amp;width);
376     if ((pixels == (PixelWand **) NULL) ||
377         (contrast_pixels == (PixelWand **) NULL))
378       break;
379     for (x=0; x &lt; (long) width; x++)
380     {
381       PixelGetMagickColor(pixels[x],&amp;pixel);
382       pixel.red=SigmoidalContrast(pixel.red);
383       pixel.green=SigmoidalContrast(pixel.green);
384       pixel.blue=SigmoidalContrast(pixel.blue);
385       pixel.index=SigmoidalContrast(pixel.index);
386       PixelSetMagickColor(contrast_pixels[x],&amp;pixel);
387     }
388     (void) PixelSyncIterator(contrast_iterator);
389   }
390   if (y &lt; (long) MagickGetImageHeight(image_wand))
391     ThrowWandException(image_wand);
392   contrast_iterator=DestroyPixelIterator(contrast_iterator);
393   iterator=DestroyPixelIterator(iterator);
394   image_wand=DestroyMagickWand(image_wand);
395   /*
396     Write the image then destroy it.
397   */
398   status=MagickWriteImages(contrast_wand,argv[2],MagickTrue);
399   if (status == MagickFalse)
400     ThrowWandException(image_wand);
401   contrast_wand=DestroyMagickWand(contrast_wand);
402   MagickWandTerminus();
403   return(0);
404 }
405 </div>
406 <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>
407
408 <div class="viewport">
409 #include &lt;stdio.h>
410 #include &lt;stdlib.h>
411 #include &lt;math.h>
412 #include &lt;wand/MagickWand.h>
413
414 static MagickBooleanType SigmoidalContrast(WandView *pixel_view,
415   const ssize_t y,const int id,void *context)
416 {
417 #define QuantumScale  ((MagickRealType) 1.0/(MagickRealType) QuantumRange)
418 #define SigmoidalContrast(x) \
419   (QuantumRange*(1.0/(1+exp(10.0*(0.5-QuantumScale*x)))-0.0066928509)*1.0092503)
420
421   RectangleInfo
422     extent;
423
424   MagickPixelPacket
425     pixel;
426
427   PixelWand
428     **pixels;
429
430   register long
431     x;
432
433   extent=GetWandViewExtent(contrast_view);
434   pixels=GetWandViewPixels(contrast_view);
435   for (x=0; x &lt; (long) (extent.width-extent.height); x++)
436   {
437     PixelGetMagickColor(pixels[x],&amp;pixel);
438     pixel.red=SigmoidalContrast(pixel.red);
439     pixel.green=SigmoidalContrast(pixel.green);
440     pixel.blue=SigmoidalContrast(pixel.blue);
441     pixel.index=SigmoidalContrast(pixel.index);
442     PixelSetMagickColor(contrast_pixels[x],&amp;pixel);
443   }
444   return(MagickTrue);
445 }
446
447 int main(int argc,char **argv)
448 {
449 #define ThrowViewException(view) \
450 { \
451   description=GetWandViewException(view,&amp;severity); \
452   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
453   description=(char *) MagickRelinquishMemory(description); \
454   exit(-1); \
455 }
456 #define ThrowWandException(wand) \
457 { \
458   description=MagickGetException(wand,&amp;severity); \
459   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
460   description=(char *) MagickRelinquishMemory(description); \
461   exit(-1); \
462 }
463
464   char
465     *description;
466
467   ExceptionType
468     severity;
469
470   MagickBooleanType
471     status;
472
473   MagickPixelPacket
474     pixel;
475
476   MagickWand
477     *contrast_wand;
478
479   WandView
480     *contrast_view;
481
482   if (argc != 3)
483     {
484       (void) fprintf(stdout,"Usage: %s image sigmoidal-image\n",argv[0]);
485       exit(0);
486     }
487   /*
488     Read an image.
489   */
490   MagickWandGenesis();
491   contrast_wand=NewMagickWand();
492   status=MagickReadImage(contrast_wand,argv[1]);
493   if (status == MagickFalse)
494     ThrowWandException(contrast_wand);
495   /*
496     Sigmoidal non-linearity contrast control.
497   */
498   contrast_view=NewWandView(contrast_wand);
499   if (contrast_view == (WandView *) NULL)
500     ThrowWandException(contrast_wand);
501   status=UpdateWandViewIterator(contrast_view,SigmoidalContrast,(void *) NULL);
502   if (status == MagickFalse)
503     ThrowWandException(contrast_wand);
504   contrast_view=DestroyWandView(contrast_view);
505   /*
506     Write the image then destroy it.
507   */
508   status=MagickWriteImages(contrast_wand,argv[2],MagickTrue);
509   if (status == MagickFalse)
510     ThrowWandException(contrast_wand);
511   contrast_wand=DestroyMagickWand(contrast_wand);
512   MagickWandTerminus();
513   return(0);
514 }
515 </div>
516 </div>
517 \r
518 </div>\r
519 \r
520 <div id="linkbar">\r
521     <span id="linkbar-west">&nbsp;</span>\r
522     <span id="linkbar-center">\r
523       <a href="http://www.imagemagick.org/discourse-server/">Discourse Server</a> &bull;\r
524       <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Studio</a>\r
525     </span>\r
526     <span id="linkbar-east">&nbsp;</span>\r
527   </div>\r
528   <div class="footer">\r
529     <span id="footer-west">&copy; 1999-2011 ImageMagick Studio LLC</span>\r
530     <span id="footer-east"> <a href="http://www.imagemagick.org/script/contact.php">Contact the Wizards</a></span>\r
531   </div>\r
532   <div style="clear: both; margin: 0; width: 100%; "></div>\r
533   <script type="text/javascript">\r
534     var _gaq = _gaq || [];\r
535     _gaq.push(['_setAccount', 'UA-17690367-1']);\r
536     _gaq.push(['_trackPageview']);\r
537 \r
538     (function() {\r
539       var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;\r
540       ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';\r
541       var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);\r
542     })();\r
543   </script>\r
544 </body>\r
545 </html>\r