blob: 548dfcb08456d36c0bbc32e9845a2b986787d03b [file] [log] [blame]
cristyd2432012015-05-04 23:15:15 +00001<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
2<html lang="en">
cristyad41c0c2012-10-31 00:49:28 +00003<head>
cristyd2432012015-05-04 23:15:15 +00004 <meta charset="utf-8">
5 <meta http-equiv="X-UA-Compatible" content="IE=edge">
6 <meta name="viewport" content="width=device-width, initial-scale=1">
cristyffb69ed2010-12-25 00:06:48 +00007 <title>ImageMagick: MagickCore, Low-level C API for ImageMagick</title>
cristyd2432012015-05-04 23:15:15 +00008 <meta http-equiv="content-language" content="en-US">
9 <meta http-equiv="content-type" content="text/html; charset=utf-8">
10 <meta http-equiv="reply-to" content="magick-users@imagemagick.org">
11 <meta name="application-name" content="ImageMagick">
12 <meta name="description" content="ImageMagick® is a software suite to create, edit, compose, or convert bitmap images. It can read and write images in a variety of formats (over 200) including PNG, JPEG, JPEG-2000, GIF, WebP, Postscript, PDF, and SVG. Use ImageMagick to resize, flip, mirror, rotate, distort, shear and transform images, adjust image colors, apply various special effects, or draw text, lines, polygons, ellipses and Bézier curves.">
13 <meta name="application-url" content="http://www.imagemagick.org">
14 <meta name="generator" content="PHP">
15 <meta name="keywords" content="magickcore, low-level, c, api, for, imagemagick, 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-2012 ImageMagick Studio LLC">
23 <meta name="distribution" content="Global">
cristy44443b92015-05-05 00:06:07 +000024 <meta name="magick-serial" content="P131-S030410-R485315270133-P82224-A6668-G1245-1">
cristyd2432012015-05-04 23:15:15 +000025 <link rel="icon" href="../images/wand.png">
26 <link rel="shortcut icon" href="../images/wand.ico" type="images/x-icon">
cristy44443b92015-05-05 00:06:07 +000027 <link rel="stylesheet" href="css/bootstrap.min.css">
28 <link rel="stylesheet" href="css/magick.css">
cristyad41c0c2012-10-31 00:49:28 +000029</head>
30
cristyd2432012015-05-04 23:15:15 +000031<body>
cristyad41c0c2012-10-31 00:49:28 +000032<div class="main">
cristyd2432012015-05-04 23:15:15 +000033<div class="magick-masthead">
34 <div class="container">
35 <script type="text/javascript">
36 <!--
37 google_ad_client = "pub-3129977114552745";
38 google_ad_slot = "5439289906";
39 google_ad_width = 728;
40 google_ad_height = 90;
41 //-->
42 </script>
43 <center><script type="text/javascript" src="http://localhost/pagead/show_ads.js">
44 </script></center>
45 <nav class="magick-nav">
cristy44443b92015-05-05 00:06:07 +000046 <a class="magick-nav-item " href="../index.html">Home</a>
cristyd2432012015-05-04 23:15:15 +000047 <a class="magick-nav-item " href="binary-releases.html">Downloads</a>
48 <a class="magick-nav-item " href="command-line-tools.html">Tools</a>
49 <a class="magick-nav-item " href="command-line-options.html">Options</a>
50 <a class="magick-nav-item " href="api.html">Development</a>
cristy44443b92015-05-05 00:06:07 +000051 <a class="magick-nav-item" href="http://www.imagemagick.org/discourse-server/">Community</a>
cristyabed55c2015-05-06 17:07:00 +000052 <a class="magick-nav-item navbar-right " href="http://www.imagemagick.org/script/search.php">Search</a>
cristyd2432012015-05-04 23:15:15 +000053 </nav>
54 </div>
55</div>
56<div class="container">
57<div class="magick-header">
cristyad41c0c2012-10-31 00:49:28 +000058
cristy44443b92015-05-05 00:06:07 +000059<p class="lead magick-description">The <a href="http://www.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>
cristy3ed852e2009-09-05 21:47:34 +000060
61<ul>
cristy44443b92015-05-05 00:06:07 +000062 <li><a href="www/api/magick.html">Initialize or Destroy the ImageMagick Environment</a></li>
63 <li><a href="www/api/constitute.html">Constitute an Image</a></li>
64 <li><a href="www/api/composite.html">Composite an Image</a></li>
65 <li><a href="www/api/image.html">Image Methods</a></li>
66 <li><a href="www/api/channel.html">Image Channel Methods</a></li>
67 <li><a href="www/api/color.html">Count the Colors in an Image</a></li>
68 <li><a href="www/api/colormap.html">Colormap Methods</a></li>
69 <li><a href="www/api/colorspace.html">Colorspace Methods</a></li>
70 <li><a href="www/api/distort.html">Image Distortions</a></li>
71 <li><a href="www/api/layer.html">Dealing with Image Layers</a></li>
72 <li><a href="www/api/profile.html">Dealing with Image Profiles</a></li>
73 <li><a href="www/api/quantize.html">Reduce the Number of Unique Colors in an Image</a></li>
74 <li><a href="www/api/histogram.html">Image Histograms</a></li>
75 <li><a href="www/api/segment.html">Segment an Image with Thresholding Fuzzy c-Means</a></li>
76 <li><a href="www/api/resize.html">Resize an Image</a></li>
77 <li><a href="www/api/transform.html">Transform an Image</a></li>
78 <li><a href="www/api/shear.html">Shear or Rotate an Image by an Arbitrary Angle</a></li>
79 <li><a href="www/api/enhance.html">Enhance an Image</a></li>
80 <li><a href="www/api/effect.html">Add an Effect</a></li>
81 <li><a href="www/api/morphology.html">Morphological Erosions, Dilations, Openings, and Closings</a></li>
82 <li><a href="www/api/fx.html">Add a Special Effect</a></li>
83 <li><a href="www/api/decorate.html">Decorate an Image</a></li>
84 <li><a href="www/api/attribute.html">Get/Set an Image Attribute</a></li>
85 <li><a href="www/api/property.html">Get/Set Image Properties</a></li>
86 <li><a href="www/api/statistic.html">Get Image Statistics</a></li>
87 <li><a href="www/api/feature.html">Get Image Features</a></li>
88 <li><a href="www/api/annotate.html">Annotate an Image</a></li>
89 <li><a href="www/api/paint.html">Paint on an Image</a></li>
90 <li><a href="www/api/draw.html">Draw on an Image</a></li>
91 <li><a href="www/api/montage.html">Create an Image Thumbnail</a></li>
92 <li><a href="www/api/fourier.html">Compute the discrete Fourier transform (DFT)</a></li>
93 <li><a href="www/api/compare.html">Compare an Image to a Reconstructed Image</a></li>
94 <li><a href="www/api/display.html">Interactively Display and Edit an Image</a></li>
95 <li><a href="www/api/animate.html">Interactively Animate an Image Sequence</a></li>
96 <li><a href="www/api/cipher.html">Convert to and from Cipher Pixels</a></li>
97 <li><a href="www/api/list.html">Working with Image Lists</a></li>
98 <li><a href="www/api/image-view.html">Image View Methods</a></li>
99 <li><a href="www/api/cache.html">Get or Set Image Pixels</a></li>
100 <li><a href="www/api/cache-view.html">Working with Cache Views</a></li>
101 <li><a href="www/api/stream.html">The Pixel FIFO</a></li>
102 <li><a href="www/api/blob.html">Read or Write Binary Large OBjects</a></li>
103 <li><a href="www/api/module.html">Loadable Modules</a></li>
104 <li><a href="www/api/signature.html">Compute a Message Digest for an Image</a></li>
105 <li><a href="www/api/registry.html">The Image Registry</a></li>
106 <li><a href="www/api/exception.html">Dealing with Exceptions</a></li>
107 <li><a href="www/api/memory.html">Memory Allocation</a></li>
108 <li><a href="www/api/resource.html">Monitor or Limit Resource Consumption</a></li>
109 <li><a href="www/api/monitor.html">Monitor the Progress of an Image Operation</a></li>
110 <li><a href="www/api/version.html">Get the Version and Copyrights</a></li>
111 <li><a href="www/api/mime.html">Mime Methods</a></li>
112 <li><a href="www/api/deprecate.html">Deprecated Methods</a></li>
cristy751980d2012-06-03 23:18:35 +0000113 <li><a href="exception.html">Error and Warning Codes</a></li>
cristy3ed852e2009-09-05 21:47:34 +0000114</ul>
115
116<p>After you write your MagickCore program, compile it like this:</p>
117
cristy44443b92015-05-05 00:06:07 +0000118<pre><span class="crtprompt"> </span><span class="crtin">cc -o core core.c `pkg-config --cflags --libs MagickCore`</span></pre>
cristy8ee7f242013-06-20 16:08:44 +0000119<p>Set the <code>PKG_CONFIG_PATH</code> environment variable if ImageMagick is not in your default system path:</p>
cristy44443b92015-05-05 00:06:07 +0000120<pre><span class="crtprompt"> </span><span class="crtin">export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig</span></pre>
cristy149d58c2013-08-07 19:44:54 +0000121<p>Here is a example program that utilizes the MagickCore API to get you started, <a href="../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>
cristy3ed852e2009-09-05 21:47:34 +0000122
cristyd2432012015-05-04 23:15:15 +0000123<pre class="pre-scrollable">#include &lt;stdio.h&gt;
124#include &lt;stdlib.h&gt;
125#include &lt;string.h&gt;
126#include &lt;time.h&gt;
127#include &lt;magick/MagickCore.h&gt;
cristy3ed852e2009-09-05 21:47:34 +0000128
cristy91469932014-07-25 11:00:25 +0000129int main(int argc,char **argv)
130{
131 ExceptionInfo
132 *exception;
cristy3ed852e2009-09-05 21:47:34 +0000133
cristy91469932014-07-25 11:00:25 +0000134 Image
135 *image,
136 *images,
137 *resize_image,
138 *thumbnails;
cristy3ed852e2009-09-05 21:47:34 +0000139
cristy91469932014-07-25 11:00:25 +0000140 ImageInfo
141 *image_info;
cristy3ed852e2009-09-05 21:47:34 +0000142
cristy91469932014-07-25 11:00:25 +0000143 if (argc != 3)
cristy3ed852e2009-09-05 21:47:34 +0000144 {
cristy91469932014-07-25 11:00:25 +0000145 (void) fprintf(stdout,"Usage: %s image thumbnail\n",argv[0]);
146 exit(0);
cristy3ed852e2009-09-05 21:47:34 +0000147 }
cristy91469932014-07-25 11:00:25 +0000148 /*
149 Initialize the image info structure and read an image.
150 */
151 MagickCoreGenesis(*argv,MagickTrue);
152 exception=AcquireExceptionInfo();
153 image_info=CloneImageInfo((ImageInfo *) NULL);
154 (void) strcpy(image_info-&gt;filename,argv[1]);
155 images=ReadImage(image_info,exception);
156 if (exception-&gt;severity != UndefinedException)
157 CatchException(exception);
158 if (images == (Image *) NULL)
159 exit(1);
160 /*
161 Convert the image to a thumbnail.
162 */
163 thumbnails=NewImageList();
164 while ((image=RemoveFirstImageFromList(&amp;images)) != (Image *) NULL)
165 {
166 resize_image=ResizeImage(image,106,80,LanczosFilter,1.0,exception);
167 if (resize_image == (Image *) NULL)
168 MagickError(exception-&gt;severity,exception-&gt;reason,exception-&gt;description);
169 (void) AppendImageToList(&amp;thumbnails,resize_image);
170 DestroyImage(image);
cristy3ed852e2009-09-05 21:47:34 +0000171 }
cristy91469932014-07-25 11:00:25 +0000172 /*
173 Write the image thumbnail.
174 */
175 (void) strcpy(thumbnails-&gt;filename,argv[2]);
176 WriteImage(image_info,thumbnails);
177 /*
178 Destroy the image thumbnail and exit.
179 */
180 thumbnails=DestroyImageList(thumbnails);
181 image_info=DestroyImageInfo(image_info);
182 exception=DestroyExceptionInfo(exception);
183 MagickCoreTerminus();
184 return(0);
cristyd2432012015-05-04 23:15:15 +0000185}</pre>
cristy8ee7f242013-06-20 16:08:44 +0000186<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>
cristy10c87152010-06-26 16:12:21 +0000187
cristyd2432012015-05-04 23:15:15 +0000188<pre class="pre-scrollable">#include &lt;stdio.h&gt;
189#include &lt;stdlib.h&gt;
190#include &lt;math.h&gt;
191#include &lt;magick/MagickCore.h&gt;
cristy10c87152010-06-26 16:12:21 +0000192
cristy73b7d4c2010-06-27 00:31:00 +0000193static MagickBooleanType SigmoidalContrast(ImageView *contrast_view,
cristyc3ebda22010-06-27 17:11:57 +0000194 const ssize_t y,const int id,void *context)
cristy10c87152010-06-26 16:12:21 +0000195{
196#define QuantumScale ((MagickRealType) 1.0/(MagickRealType) QuantumRange)
197#define SigmoidalContrast(x) \
198 (QuantumRange*(1.0/(1+exp(10.0*(0.5-QuantumScale*x)))-0.0066928509)*1.0092503)
199
cristyc3ebda22010-06-27 17:11:57 +0000200 RectangleInfo
201 extent;
202
cristy73b7d4c2010-06-27 00:31:00 +0000203 register IndexPacket
204 *indexes;
cristy10c87152010-06-26 16:12:21 +0000205
cristy73b7d4c2010-06-27 00:31:00 +0000206 register PixelPacket
207 *pixels;
cristy10c87152010-06-26 16:12:21 +0000208
cristy73b7d4c2010-06-27 00:31:00 +0000209 register ssize_t
cristy10c87152010-06-26 16:12:21 +0000210 x;
211
cristyc3ebda22010-06-27 17:11:57 +0000212 extent=GetImageViewExtent(contrast_view);
cristy73b7d4c2010-06-27 00:31:00 +0000213 pixels=GetImageViewAuthenticPixels(contrast_view);
cristyc3ebda22010-06-27 17:11:57 +0000214 for (x=0; x &lt; (ssize_t) (extent.width-extent.x); x++)
cristy10c87152010-06-26 16:12:21 +0000215 {
cristy29c5c992011-06-25 13:58:49 +0000216 SetPixelRed(pixels,RoundToQuantum(SigmoidalContrast(GetPixelRed(pixels)));
217 SetPixelGreen(pixels,RoundToQuantum(SigmoidalContrast(GetPixelGreen(pixels)));
218 SetPixelBlue(pixels,RoundToQuantum(SigmoidalContrast(GetPixelBlue(pixels)));
219 SetPixelOpacity(pixels,RoundToQuantum(SigmoidalContrast(GetPixelOpacity(pixels)));
cristyacc04882011-05-04 23:03:43 +0000220 pixels++;
cristy10c87152010-06-26 16:12:21 +0000221 }
cristy73b7d4c2010-06-27 00:31:00 +0000222 indexes=GetImageViewAuthenticIndexes(contrast_view);
223 if (indexes != (IndexPacket *) NULL)
cristyc3ebda22010-06-27 17:11:57 +0000224 for (x=0; x &lt; (ssize_t) (extent.width-extent.x); x++)
cristy29c5c992011-06-25 13:58:49 +0000225 SetPixelIndex(indexes+x,RoundToQuantum(SigmoidalContrast(GetPixelIndex(indexes+x))));
cristy10c87152010-06-26 16:12:21 +0000226 return(MagickTrue);
227}
228
229int main(int argc,char **argv)
230{
231#define ThrowImageException(image) \
232{ \
cristy10c87152010-06-26 16:12:21 +0000233 \
cristy73b7d4c2010-06-27 00:31:00 +0000234 CatchException(exception); \
235 if (contrast_image != (Image *) NULL) \
236 contrast_image=DestroyImage(contrast_image); \
cristyc3ebda22010-06-27 17:11:57 +0000237 exit(-1); \
238}
239#define ThrowViewException(view) \
240{ \
241 char \
242 *description; \
243 \
244 ExceptionType \
245 severity; \
246 \
cristydcca3fa2010-12-29 21:50:07 +0000247 description=GetImageViewException(view,&amp;severity); \
cristyc3ebda22010-06-27 17:11:57 +0000248 (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
249 description=DestroyString(description); \
cristy10c87152010-06-26 16:12:21 +0000250 exit(-1); \
251}
252
cristy73b7d4c2010-06-27 00:31:00 +0000253 ExceptionInfo
254 *exception;
255
256 Image
257 *contrast_image;
258
259 ImageInfo
260 *image_info;
261
cristy10c87152010-06-26 16:12:21 +0000262 ImageView
263 *contrast_view;
264
265 MagickBooleanType
266 status;
267
cristy10c87152010-06-26 16:12:21 +0000268 if (argc != 3)
269 {
270 (void) fprintf(stdout,"Usage: %s image sigmoidal-image\n",argv[0]);
271 exit(0);
272 }
273 /*
274 Read an image.
275 */
cristy73b7d4c2010-06-27 00:31:00 +0000276 MagickCoreGenesis(*argv,MagickTrue);
277 image_info=AcquireImageInfo();
cristyd2432012015-05-04 23:15:15 +0000278 (void) CopyMagickString(image_info-&gt;filename,argv[1],MaxTextExtent);
cristy73b7d4c2010-06-27 00:31:00 +0000279 exception=AcquireExceptionInfo();
280 contrast_image=ReadImage(image_info,exception);
281 if (contrast_image == (Image *) NULL)
282 ThrowImageException(contrast_image);
cristy10c87152010-06-26 16:12:21 +0000283 /*
284 Sigmoidal non-linearity contrast control.
285 */
286 contrast_view=NewImageView(contrast_image);
287 if (contrast_view == (ImageView *) NULL)
cristy73b7d4c2010-06-27 00:31:00 +0000288 ThrowImageException(contrast_image);
cristy10c87152010-06-26 16:12:21 +0000289 status=UpdateImageViewIterator(contrast_view,SigmoidalContrast,(void *) NULL);
290 if (status == MagickFalse)
cristy73b7d4c2010-06-27 00:31:00 +0000291 ThrowImageException(contrast_image);
cristy10c87152010-06-26 16:12:21 +0000292 contrast_view=DestroyImageView(contrast_view);
293 /*
294 Write the image then destroy it.
295 */
cristy73b7d4c2010-06-27 00:31:00 +0000296 status=WriteImages(image_info,contrast_image,argv[2],exception);
cristy10c87152010-06-26 16:12:21 +0000297 if (status == MagickFalse)
cristy73b7d4c2010-06-27 00:31:00 +0000298 ThrowImageException(contrast_image);
299 contrast_image=DestroyImage(contrast_image);
300 exception=DestroyExceptionInfo(exception);
301 image_info=DestroyImageInfo(image_info);
cristy10c87152010-06-26 16:12:21 +0000302 MagickCoreTerminus();
303 return(0);
cristyd2432012015-05-04 23:15:15 +0000304}</pre>
cristydcca3fa2010-12-29 21:50:07 +0000305</div>
cristyd2432012015-05-04 23:15:15 +0000306 <footer class="magick-footer">
307 <div class="magick-nav-item navbar-left">
cristy85893d32015-05-06 13:44:09 +0000308 <a href="support.html">Donate</a>
cristyd2432012015-05-04 23:15:15 +0000309 </div>
310 <div class="magick-nav-item navbar-right">
cristy44443b92015-05-05 00:06:07 +0000311 <a class="FlattrButton" style="display:none;" rev="flattr;button:compact;" href="../index.html"></a>
cristyd2432012015-05-04 23:15:15 +0000312 <noscript>
313 <a href="http://flattr.com/thing/947300/Convert-Edit-And-Compose-Images" target="_blank">
314 <img src="http://api.flattr.com/button/flattr-badge-large.png" alt="Flattr this" title="Flattr this" border="0"></a>
315 </noscript>
316 </div>
317 <p><a href="sitemap.html">Sitemap</a>
318 <a href="links.html">Related</a>
319 <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Image Studio</a>
320 <a href="http://jqmagick.imagemagick.org/">JqMagick</a>
321 <a href="http://pgp.mit.edu:11371/pks/lookup?op=get&amp;search=0x89AB63D48277377A">Public Key</a>
322</p>
323 <p><a href="magick-core.html#">Back to top</a>
cristy85893d32015-05-06 13:44:09 +0000324 <a href="http://www.imagemagick.org/script/contact.php">Contact Us</a></p>
cristyd2432012015-05-04 23:15:15 +0000325 </footer>
326</div><!-- /.container -->
cristyad41c0c2012-10-31 00:49:28 +0000327
cristyd2432012015-05-04 23:15:15 +0000328 <script src="https://localhost/ajax/libs/jquery/1.11.2/jquery.min.js"></script>
329 <script src="../js/bootstrap.min.js"></script>
330 <script type="text/javascript">
331 /* */
332 (function() {
333 var s = document.createElement('offline-script'), t = document.getElementsByTagName('offline-script')[0];
334 s.type = 'text/javascript';
335 s.async = true;
336 s.src = 'http://api.flattr.com/js/0.6/load.js?mode=auto';
337 t.parentNode.insertBefore(s, t);
338 })();
339 /* */
340 </script>
cristyad41c0c2012-10-31 00:49:28 +0000341</div>
cristyad41c0c2012-10-31 00:49:28 +0000342</body>
cristy5a367e42015-05-05 12:39:18 +0000343</html>