]> granicus.if.org Git - imagemagick/blob - www/magick-core.html
(no commit message)
[imagemagick] / www / magick-core.html
1
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" 
3   "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
4 <html version="-//W3C//DTD XHTML 1.1//EN"
5       xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
6       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
7       xsi:schemaLocation="http://www.w3.org/1999/xhtml
8                           http://www.w3.org/MarkUp/SCHEMA/xhtml11.xsd">
9 <head>
10   <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
11   <meta name="google-site-verification" content="_bMOCDpkx9ZAzBwb2kF3PRHbfUUdFj2uO8Jd1AXArz4"/>
12   <title>ImageMagick: MagickCore, Low-level 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 or transform images automagically."/>
18   <meta name="application-url" content="http://www.imagemagick.org"/>
19   <meta name="generator" content="PHP"/>
20   <meta name="keywords" content="magickcore, low-level, c, api, for, imagemagick, ImageMagick, PerlMagick, image processing, OpenMP, software development library, image, photo, software, Magick++, MagickWand"/>
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-2012 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="canonical" href="http://www.imagemagick.org" />
32   <link rel="meta" type="application/rdf+xml" title="ICI" href="http://imagemagick.org/ici.rdf"/>
33
34   <!-- Add jQuery library -->
35   <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.7/jquery.min.js"></script>
36   
37   <!-- Add mousewheel plugin (this is optional) -->
38   <script type="text/javascript" src="http://www.imagemagick.org/fancybox/lib/jquery.mousewheel-3.0.6.pack.js"></script>
39   
40   <!-- Add fancyBox -->
41   <link rel="stylesheet" href="http://www.imagemagick.org/fancybox/source/jquery.fancybox.css?v=2.0.6" type="text/css" media="screen" />
42   <script type="text/javascript" src="http://www.imagemagick.org/fancybox/source/jquery.fancybox.pack.js?v=2.0.6"></script>
43   
44   <!-- Optionally add helpers - button, thumbnail and/or media -->
45   <link rel="stylesheet" href="http://www.imagemagick.org/fancybox/source/helpers/jquery.fancybox-buttons.css?v=1.0.2" type="text/css" media="screen" />
46   <script type="text/javascript" src="http://www.imagemagick.org/fancybox/source/helpers/jquery.fancybox-buttons.js?v=1.0.2"></script>
47   <script type="text/javascript" src="http://www.imagemagick.org/fancybox/source/helpers/jquery.fancybox-media.js?v=1.0.0"></script>
48   
49   <link rel="stylesheet" href="http://www.imagemagick.org/fancybox/source/helpers/jquery.fancybox-thumbs.css?v=2.0.6" type="text/css" media="screen" />
50   <script type="text/javascript" src="http://www.imagemagick.org/fancybox/source/helpers/jquery.fancybox-thumbs.js?v=2.0.6"></script>
51   
52   <script type="text/javascript">
53         $(document).ready(function() {
54                 $(".fancybox").fancybox();
55         });
56   </script>
57
58   <!-- ImageMagick style -->
59   <style type="text/css" media="all">
60     @import url("../www/magick.css");
61   </style>
62 </head>
63
64 <body id="www-imagemagick-org">
65
66 <script>
67   (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
68   (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
69   m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
70   })(window,document,'offline-script','//127.0.0.1/analytics.js','ga');
71
72   ga('create', 'UA-40133312-1', 'imagemagick.org');
73   ga('send', 'pageview');
74 </script>
75
76 <div class="titlebar">
77 <div style="margin: 17px auto; float: left;">
78   <script type="text/javascript">
79   <!--
80     google_ad_client = "pub-3129977114552745";
81     google_ad_slot = "5439289906";
82     google_ad_width = 728;
83     google_ad_height = 90;
84   //-->
85   </script>
86   <script type="text/javascript"
87     src="http://127.0.0.1/pagead/show_ads.js">
88   </script>
89 </div>
90 <a href="http://www.imagemagick.org/discourse-server/">
91   <img src="../images/logo.jpg"
92   alt="ImageMagick Logo"
93   style="width: 123px; height: 118px; border: 0px; float: right;" /></a>
94 <a href="../index.html">
95   <img src="../images/sprite.jpg"
96   alt="ImageMagick Sprite"
97   style="width: 114px; height: 118px; border: 0px; float: right;" /></a>
98 </div>
99
100 <div class="westbar">
101
102 <div class="menu">
103   <a title="About ImageMagick" href="../index.html">About ImageMagick</a>
104 </div>
105 <div class="menu">
106   <a title="Binary Releases" href="binary-releases.html">Binary Releases</a>
107 </div>
108 <div class="sub">
109     <a title="Binary Release: Unix" href="binary-releases.html#unix">Unix</a>
110 </div>
111 <div class="sub">
112     <a title="Binary Release: MacOS X" href="binary-releases.html#macosx">Mac OS X</a>
113 </div>
114 <div class="sub">
115     <a title="Binary Release: iOS" href="binary-releases.html#iOS">iOS</a>
116 </div>
117 <div class="sub">
118     <a title="Binary Release: Windows" href="binary-releases.html#windows">Windows</a>
119 </div>
120 <div class="sep"></div>
121 <div class="menu">
122   <a title="Command-line Tools" href="command-line-tools.html">Command-line Tools</a>
123 </div>
124 <div class="sub">
125     <a title="Command-line Tools: Processing" href="command-line-processing.html">Processing</a>
126 </div>
127 <div class="sub">
128     <a title="Command-line Tools: Options" href="command-line-options.html">Options</a>
129 </div>
130 <div class="sub">
131     <a title="Command-line Tools: Usage" href="http://www.imagemagick.org/Usage/">Usage</a>
132 </div>
133 <div class="menu">
134   <a title="Program Interfaces" href="api.html">Program Interfaces</a>
135 </div>
136 <div class="sub">
137     <a title="Program Interface: MagickWand" href="magick-wand.html">MagickWand</a>
138 </div>
139 <div class="sub">
140     <a title="Program Interface: MagickCore" href="magick-core.html">MagickCore</a>
141 </div>
142 <div class="sub">
143     <a title="Program Interface: PerlMagick" href="perl-magick.html">PerlMagick</a>
144 </div>
145 <div class="sub">
146     <a title="Program Interface: Magick++" href="magick++.html">Magick++</a>
147 </div>
148 <div class="sep"></div>
149 <div  class="menu">
150    <a title="Install from Source" href="install-source.html">Install from Source</a>
151 </div>
152 <div class="sub">
153     <a title="Install from Source: Unix" href="install-source.html#unix">Unix</a>
154 </div>
155 <div class="sub">
156     <a title="Install from Source: Windows" href="install-source.html#windows">Windows</a>
157  </div>
158 <div class="menu">
159   <a title="Resources" href="resources.html">Resources</a>
160 </div>
161 <div class="menu">
162   <a title="Architecture" href="architecture.html">Architecture</a>
163 </div>
164 <div class="menu">
165   <a title="Download" href="download.html">Download</a>
166 </div>
167 <div class="sep"></div>
168 <div class="menu">
169   <a title="Search" href="search.html">Search</a>
170 </div>
171 <div class="sep"></div>
172 <div class="menu">
173   <a title="Site Map" href="sitemap.html">Site Map</a>
174 </div>
175 <div  class="sub">
176   <a title="Site Map: Links" href="links.html">Links</a>
177 </div>
178 <div class="sep"></div>
179 <div class="menu">
180   <a title="Support ImageMagick Development" href="support.html">Support ImageMagick Development</a>
181 </div>
182 </div>
183
184 <div class="eastbar">
185   <script type="text/javascript">
186     /* <![CDATA[ */
187     (function() {
188         var po = document.createElement('offline-script'), t = document.getElementsByTagName('offline-script')[0];
189         po.type = 'text/javascript';
190         po.async = true;
191         po.src = 'http://api.flattr.com/js/0.6/load.js?mode=auto';
192         var script = document.getElementsByTagName('offline-script')[0];
193         script.parentNode.insertBefore(po, script);
194     })();
195     /* ]]> */
196   </script>
197   <div> <a class="FlattrButton" style="display:none;" rev="flattr;button:compact;" href="http://www.imagemagick.org/"></a></div>
198   <noscript>
199     <a href="http://flattr.com/thing/947300/Convert-Edit-And-Compose-Images" target="_blank">
200     <img src="http://api.flattr.com/button/flattr-badge-large.png" alt="Flattr this" title="Flattr this" width="93" height="20" border="0" /></a>
201   </noscript>
202     <div class="g-plusone" id="gplusone"></div>
203     <script type="text/javascript">
204       /* <![CDATA[ */
205       window.___gcfg = {
206         lang: 'en-US'
207       };
208
209       (function() {
210         var po = document.createElement('offline-script');
211         po.type = 'text/javascript';
212         po.async = true;
213         po.src = 'https://127.0.0.1/js/plusone.js';
214         var script = document.getElementsByTagName('offline-script')[0];
215         script.parentNode.insertBefore(po, script);
216       })();
217       var gplusone = document.getElementById("gplusone");
218       gplusone.setAttribute("data-size","medium");
219       gplusone.setAttribute("data-count","true");
220       /* ]]> */
221     </script>
222 </div>
223
224 <div class="main">
225
226 <h1>MagickCore C API</h1>
227
228 <div class="doc-section">
229
230 <p>The <a href="http://magick.imagemagick.org/api/MagickCore/index.html">MagickCore API</a> is a low-level interface between the C programming language and the ImageMagick image processing libraries and is recommended for wizard-level programmers only.  Unlike the <a href="magick-wand.html">MagickWand</a> C API which uses only a few opaque types and accessors, with MagickCore you almost exlusively access the structure members directly.  A description of the MagickCore public methods are found here:</p>
231
232 <ul>
233   <li><a href="../api/magick.html">Initialize or Destroy the ImageMagick Environment</a></li>
234   <li><a href="../api/constitute.html">Constitute an Image</a></li>
235   <li><a href="../api/composite.html">Composite an Image</a></li>
236   <li><a href="../api/image.html">Image Methods</a></li>
237   <li><a href="../api/channel.html">Image Channel Methods</a></li>
238   <li><a href="../api/color.html">Count the Colors in an Image</a></li>
239   <li><a href="../api/colormap.html">Colormap Methods</a></li>
240   <li><a href="../api/distort.html">Image Distortions</a></li>
241   <li><a href="../api/layer.html">Dealing with Image Layers</a></li>
242   <li><a href="../api/profile.html">Dealing with Image Profiles</a></li>
243   <li><a href="../api/quantize.html">Reduce the Number of Unique Colors in an Image</a></li>
244   <li><a href="../api/histogram.html">Image Histograms</a></li>
245   <li><a href="../api/segment.html">Segment an Image with Thresholding Fuzzy c-Means</a></li>
246   <li><a href="../api/resize.html">Resize an Image</a></li>
247   <li><a href="../api/transform.html">Transform an Image</a></li>
248   <li><a href="../api/shear.html">Shear or Rotate an Image by an Arbitrary Angle</a></li>
249   <li><a href="../api/enhance.html">Enhance an Image</a></li>
250   <li><a href="../api/effect.html">Add an Effect</a></li>
251   <li><a href="../api/morphology.html">Morphological Erosions, Dilations, Openings, and Closings</a></li>
252   <li><a href="../api/fx.html">Add a Special Effect</a></li>
253   <li><a href="../api/decorate.html">Decorate an Image</a></li>
254   <li><a href="../api/attribute.html">Get/Set an Image Attribute</a></li>
255   <li><a href="../api/property.html">Get/Set Image Properties</a></li>
256   <li><a href="../api/statistic.html">Get Image Statistics</a></li>
257   <li><a href="../api/feature.html">Get Image Features</a></li>
258   <li><a href="../api/annotate.html">Annotate an Image</a></li>
259   <li><a href="../api/paint.html">Paint on an Image</a></li>
260   <li><a href="../api/draw.html">Draw on an Image</a></li>
261   <li><a href="../api/montage.html">Create an Image Thumbnail</a></li>
262   <li><a href="../api/fourier.html">Compute the discrete Fourier transform (DFT)</a></li>
263   <li><a href="../api/compare.html">Compare an Image to a Reconstructed Image</a></li>
264   <li><a href="../api/display.html">Interactively Display and Edit an Image</a></li>
265   <li><a href="../api/animate.html">Interactively Animate an Image Sequence</a></li>
266   <li><a href="../api/cipher.html">Convert to and from Cipher Pixels</a></li>
267   <li><a href="../api/list.html">Working with Image Lists</a></li>
268   <li><a href="../api/image-view.html">Image View Methods</a></li>
269   <li><a href="../api/cache.html">Get or Set Image Pixels</a></li>
270   <li><a href="../api/cache-view.html">Working with Cache Views</a></li>
271   <li><a href="../api/stream.html">The Pixel FIFO</a></li>
272   <li><a href="../api/blob.html">Read or Write Binary Large OBjects</a></li>
273   <li><a href="../api/module.html">Loadable Modules</a></li>
274   <li><a href="../api/signature.html">Compute a Message Digest for an Image</a></li>
275   <li><a href="../api/registry.html">The Image Registry</a></li>
276   <li><a href="../api/exception.html">Dealing with Exceptions</a></li>
277   <li><a href="../api/memory.html">Memory Allocation</a></li>
278   <li><a href="../api/resource.html">Monitor or Limit Resource Consumption</a></li>
279   <li><a href="../api/monitor.html">Monitor the Progress of an Image Operation</a></li>
280   <li><a href="../api/version.html">Get the Version and Copyrights</a></li>
281   <li><a href="../api/deprecate.html">Deprecated Methods</a></li>
282   <li><a href="exception.html">Error and Warning Codes</a></li>
283 </ul>
284
285 <p>After you write your MagickCore program, compile it like this:</p>
286
287 <p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>cc -o core `pkg-config --cflags --libs MagickCore` core.c</span></p>
288 <p>Set the <code>PKG_CONFIG_PATH</code> environment variable if ImageMagick is not in your default system path:</p>
289 <p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig</span></p>
290 <p>Here is a example program that utilizes the MagickCore API to get you started, <a href="http://magick.imagemagick.org/source/core.c">core.c</a>. It reads a GIF image, creates a thumbnail, and writes it to disk in the PNG image format.</p>
291
292 <div class="viewport">
293   #include &lt;stdio.h>
294   #include &lt;stdlib.h>
295   #include &lt;string.h>
296   #include &lt;time.h>
297   #include &lt;magick/MagickCore.h>
298
299   int main(int argc,char **argv)
300   {
301     ExceptionInfo
302       *exception;
303
304     Image
305       *image,
306       *images,
307       *resize_image,
308       *thumbnails;
309
310     ImageInfo
311       *image_info;
312
313     if (argc != 3)
314       {
315         (void) fprintf(stdout,"Usage: %s image thumbnail\n",argv[0]);
316         exit(0);
317       }
318     /*
319       Initialize the image info structure and read an image.
320     */
321     MagickCoreGenesis(*argv,MagickTrue);
322     exception=AcquireExceptionInfo();
323     image_info=CloneImageInfo((ImageInfo *) NULL);
324     (void) strcpy(image_info-&gt;filename,argv[1]);
325     images=ReadImage(image_info,exception);
326     if (exception-&gt;severity != UndefinedException)
327       CatchException(exception);
328     if (images == (Image *) NULL)
329       exit(1);
330     /*
331       Convert the image to a thumbnail.
332     */
333     thumbnails=NewImageList();
334     while ((image=RemoveFirstImageFromList(&amp;images)) != (Image *) NULL)
335     {
336       resize_image=ResizeImage(image,106,80,LanczosFilter,1.0,exception);
337       if (resize_image == (Image *) NULL)
338         MagickError(exception-&gt;severity,exception-&gt;reason,exception-&gt;description);
339       (void) AppendImageToList(&amp;thumbnails,resize_image);
340       DestroyImage(image);
341     }
342     /*
343       Write the image thumbnail.
344     */
345     (void) strcpy(thumbnails-&gt;filename,argv[2]);
346     WriteImage(image_info,thumbnails);
347     /*
348       Destroy the image thumbnail and exit.
349     */
350     thumbnails=DestroyImageList(thumbnails);
351     image_info=DestroyImageInfo(image_info);
352     exception=DestroyExceptionInfo(exception);
353     MagickCoreTerminus();
354     return(0);
355   }
356 </div>
357 <p><a id="image-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/core/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>
358
359 <div class="viewport">
360 #include &lt;stdio.h>
361 #include &lt;stdlib.h>
362 #include &lt;math.h>
363 #include &lt;magick/MagickCore.h>
364
365 static MagickBooleanType SigmoidalContrast(ImageView *contrast_view,
366   const ssize_t y,const int id,void *context)
367 {
368 #define QuantumScale  ((MagickRealType) 1.0/(MagickRealType) QuantumRange)
369 #define SigmoidalContrast(x) \
370   (QuantumRange*(1.0/(1+exp(10.0*(0.5-QuantumScale*x)))-0.0066928509)*1.0092503)
371
372   RectangleInfo
373     extent;
374
375   register IndexPacket
376     *indexes;
377
378   register PixelPacket
379     *pixels;
380
381   register ssize_t
382     x;
383
384   extent=GetImageViewExtent(contrast_view);
385   pixels=GetImageViewAuthenticPixels(contrast_view);
386   for (x=0; x &lt; (ssize_t) (extent.width-extent.x); x++)
387   {
388     SetPixelRed(pixels,RoundToQuantum(SigmoidalContrast(GetPixelRed(pixels)));
389     SetPixelGreen(pixels,RoundToQuantum(SigmoidalContrast(GetPixelGreen(pixels)));
390     SetPixelBlue(pixels,RoundToQuantum(SigmoidalContrast(GetPixelBlue(pixels)));
391     SetPixelOpacity(pixels,RoundToQuantum(SigmoidalContrast(GetPixelOpacity(pixels)));
392     pixels++;
393   }
394   indexes=GetImageViewAuthenticIndexes(contrast_view);
395   if (indexes != (IndexPacket *) NULL)
396     for (x=0; x &lt; (ssize_t) (extent.width-extent.x); x++)
397       SetPixelIndex(indexes+x,RoundToQuantum(SigmoidalContrast(GetPixelIndex(indexes+x))));
398   return(MagickTrue);
399 }
400
401 int main(int argc,char **argv)
402 {
403 #define ThrowImageException(image) \
404 { \
405  \
406   CatchException(exception); \
407   if (contrast_image != (Image *) NULL) \
408     contrast_image=DestroyImage(contrast_image); \
409   exit(-1); \
410 }
411 #define ThrowViewException(view) \
412 { \
413   char \
414     *description; \
415  \
416   ExceptionType \
417     severity; \
418  \
419   description=GetImageViewException(view,&amp;severity); \
420   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
421   description=DestroyString(description); \
422   exit(-1); \
423 }
424
425   ExceptionInfo
426     *exception;
427
428   Image
429     *contrast_image;
430
431   ImageInfo
432     *image_info;
433
434   ImageView
435     *contrast_view;
436
437   MagickBooleanType
438     status;
439
440   if (argc != 3)
441     {
442       (void) fprintf(stdout,"Usage: %s image sigmoidal-image\n",argv[0]);
443       exit(0);
444     }
445   /*
446     Read an image.
447   */
448   MagickCoreGenesis(*argv,MagickTrue);
449   image_info=AcquireImageInfo();
450   (void) CopyMagickString(image_info->filename,argv[1],MaxTextExtent);
451   exception=AcquireExceptionInfo();
452   contrast_image=ReadImage(image_info,exception);
453   if (contrast_image == (Image *) NULL)
454     ThrowImageException(contrast_image);
455   /*
456     Sigmoidal non-linearity contrast control.
457   */
458   contrast_view=NewImageView(contrast_image);
459   if (contrast_view == (ImageView *) NULL)
460     ThrowImageException(contrast_image);
461   status=UpdateImageViewIterator(contrast_view,SigmoidalContrast,(void *) NULL);
462   if (status == MagickFalse)
463     ThrowImageException(contrast_image);
464   contrast_view=DestroyImageView(contrast_view);
465   /*
466     Write the image then destroy it.
467   */
468   status=WriteImages(image_info,contrast_image,argv[2],exception);
469   if (status == MagickFalse)
470     ThrowImageException(contrast_image);
471   contrast_image=DestroyImage(contrast_image);
472   exception=DestroyExceptionInfo(exception);
473   image_info=DestroyImageInfo(image_info);
474   MagickCoreTerminus();
475   return(0);
476 }
477 </div>
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://www.imagemagick.org/discourse-server/">Discourse Server</a> &#8226;
487       <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Studio</a> &#8226;
488       <a href="http://jqmagick.imagemagick.org/">JqMagick</a>
489     </span>
490     <span id="linkbar-east"> </span>
491   </div>
492   <div class="footer">
493     <span id="footer-west">©  1999-2013 ImageMagick Studio LLC</span>
494     <span id="footer-east"> <a href="contact.html">Contact the Wizards</a></span>
495   </div>
496   <div style="clear: both; margin: 0; width: 100%; "></div>
497 </body>
498 </html>