granicus.if.org Git - imagemagick/blob - www/magick-core.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 xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" dir="ltr">\r
   5 <head>\r
   6   <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>\r
   7   <meta name="verify-v1" content="g222frIIxcQTrvDR3NBRUSKP3AnMNoqxOkIniCEkV7U="/>\r
   8   <title>ImageMagick: MagickCore, Low-level C API for ImageMagick</title>
   9   <meta http-equiv="Content-Language" content="en-US"/>
  10   <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
  11   <meta http-equiv="Reply-to" content="magick-users@imagemagick.org"/>
  12   <meta name="Application-name" content="ImageMagick"/>
  13   <meta name="Description" content="ImageMagick is a software suite to create, edit, compose, or convert bitmap images in a variety of formats. Use ImageMagick to scale, rotate, shear, distort and transform images."/>
  14   <meta name="Application-url" content="http://www.imagemagick.org"/>
  15   <meta name="Generator" content="PHP"/>
  16   <meta name="Keywords" content="magickcore, low-level, c, api, for, imagemagick, ImageMagick, ImageMagic, MagickCore, MagickWand, PerlMagick, Magick++, RMagick, PythonMagick, JMagick, TclMagick, Image, Magick, Magic, Wand, ImageMagickObject, Swiss, Army, Knife, Image, Processing"/>
  17   <meta name="Rating" content="GENERAL"/>
  18   <meta name="Robots" content="INDEX, FOLLOW"/>
  19   <meta name="Generator" content="ImageMagick Studio LLC"/>
  20   <meta name="Author" content="ImageMagick Studio LLC"/>
  21   <meta name="Revisit-after" content="2 DAYS"/>
  22   <meta name="Resource-type" content="document"/>
  23   <meta name="Copyright" content="Copyright (c) 1999-2011 ImageMagick Studio LLC"/>
  24   <meta name="Distribution" content="Global"/>
  25   <link rel="icon" href="../images/wand.png"/>
  26   <link rel="shortcut icon" href="../images/wand.ico"  type="images/x-icon"/>
  27   <link rel="meta" type="application/rdf+xml" title="ICI" href="http://imagemagick.org/ici.rdf"/>\r
  28   <style type="text/css" media="all">\r
  29     @import url("../www/magick.css");\r
  30   </style>\r
  31   <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js"></script>\r
  32   <script type="text/javascript" src="../fancybox/jquery.fancybox-1.3.4.pack.js"></script>\r
  33   <link rel="stylesheet" type="text/css" href="../fancybox/jquery.fancybox-1.3.4.css" media="screen" />\r
  34   <script type="text/javascript">\r
  35     $(document).ready(function() {\r
  36       $("a[href$=.jpg],a[href$=.png],a[href$=.gif]").fancybox({\r
  37         'transitionIn'  : 'elastic',\r
  38         'transitionOut' : 'elastic',\r
  39         'overlayShow'   : false,\r
  40         'opacity'       : true\r
  41       });\r
  42     });\r
  43   </script>\r
  44 </head>\r
  45 \r
  46 <body id="www-imagemagick-org">\r
  47 <div class="titlebar">\r
  48 <a href="../index.html">\r
  49   <img src="../images/script.png" alt="[ImageMagick]"\r
  50   style="width: 350px; height: 60px; margin: 28px auto; float: left;" /></a>\r
  51 <a href="http://www.networkredux.com">\r
  52   <img src="../images/networkredux.png" alt="[sponsor]"\r
  53   style="margin: 45px auto; border: 0px; float: left;" /></a>\r
  54 <a href="http://www.imagemagick.org/discourse-server/">\r
  55   <img src="../images/logo.jpg" alt=""\r
  56   style="width: 114px; height: 118px; border: 0px; float: right;" /></a>\r
  57 <a href="../index.html">\r
  58   <img src="../images/sprite.jpg" alt=""\r
  59   style="width: 114px; height: 118px; border: 0px; float: right;" /></a>\r
  60 </div>\r
  61 \r
  62 <div class="westbar">\r
  63 \r
  64 <div class="menu">
  65   <a title="About ImageMagick" href="../index.html">About ImageMagick</a>
  66 </div>
  67 <div class="sep"></div>\r
  68 <div class="menu">
  69   <a title="Binary Releases" href="../www/binary-releases.html">Binary Releases</a>
  70 </div>
  71 <div class="sub">
  72     <a title="Binary Release: Unix" href="../www/binary-releases.html#unix">Unix</a>
  73 </div>
  74 <div class="sub">
  75     <a title="Binary Release: MacOS X" href="../www/binary-releases.html#macosx">Mac OS X</a>
  76 </div>
  77 <div class="sub">
  78     <a title="Binary Release: Windows" href="../www/binary-releases.html#windows">Windows</a>
  79 </div>
  80 <div class="sep"></div>\r
  81 <div class="menu">
  82   <a title="Command-line Tools" href="../www/command-line-tools.html">Command-line Tools</a>
  83 </div>
  84 <div class="sub">
  85     <a title="Command-line Tools: Processing" href="../www/command-line-processing.html">Processing</a>
  86 </div>
  87 <div class="sub">
  88     <a title="Command-line Tools: Options" href="../www/command-line-options.html">Options</a>
  89 </div>
  90 <div class="sub">
  91     <a title="Command-line Tools: Usage" href="http://www.imagemagick.org/Usage/">Usage</a>
  92 </div>
  93 <div class="menu">
  94   <a title="Program Interfaces" href="../www/api.html">Program Interfaces</a>
  95 </div>
  96 <div class="sub">
  97     <a title="Program Interface: MagickWand" href="../www/magick-wand.html">MagickWand</a>
  98 </div>
  99 <div class="sub">
 100     <a title="Program Interface: MagickCore" href="../www/magick-core.html">MagickCore</a>
 101 </div>
 102 <div class="sub">
 103     <a title="Program Interface: PerlMagick" href="../www/perl-magick.html">PerlMagick</a>
 104 </div>
 105 <div class="sub">
 106     <a title="Program Interface: Magick++" href="../www/magick++.html">Magick++</a>
 107 </div>
 108 <div class="sep"></div>\r
 109 <div  class="menu">
 110    <a title="Install from Source" href="../www/install-source.html">Install from Source</a>
 111 </div>
 112 <div class="sub">
 113     <a title="Install from Source: Unix" href="../www/install-source.html#unix">Unix</a>
 114 </div>
 115 <div class="sub">
 116     <a title="Install from Source: Windows" href="../www/install-source.html#windows">Windows</a>
 117  </div>
 118 <div class="menu">
 119   <a title="Resources" href="../www/resources.html">Resources</a>
 120 </div>
 121 <div class="menu">
 122   <a title="Architecture" href="../www/architecture.html">Architecture</a>
 123 </div>
 124 <div class="menu">
 125   <a title="Download" href="../www/download.html">Download</a>
 126 </div>
 127 <div class="sep"></div>\r
 128 <div class="menu">
 129   <a title="Search" href="http://www.imagemagick.org/script/search.php">Search</a>
 130 </div>
 131 <div class="sep"></div>\r
 132 <div class="menu">
 133   <a title="Site Map" href="../www/sitemap.html">Site Map</a>
 134 </div>
 135 <div  class="sub">
 136   <a title="Site Map: Links" href="../www/links.html">Links</a>
 137 </div>
 138 <div class="sep"></div>\r
 139 <div  class="menu">
 140   <a title="Sponsors" href="../www/sponsors.html">Sponsors:</a>
 141
 142 <div class="sponsbox">
 143 <div class="sponsor">
 144   <a title="Sponsor: Web Hosting" href="http://www.bodhost.com/hosting.html">Web Hosting</a><!-- 201104010090 -->
 145 </div>
 146 <div  class="sponsor">
 147   <a title="Sponsor: Druckerei" href="http://print24.com/de/">Druckerei</a><!-- 201110010720 -->
 148 </div>
 149 <div  class="sponsor">
 150   <a title="Sponsor: Image Converter" href="http://www.batchphoto.com">Image Converter</a><!-- 201103010900 Bits Coffee-->
 151 </div>
 152 <div  class="sponsor">
 153   <a title="Sponsor: Flyer drucken" href="http://www.online-druck.biz">Flyer drucken</a><!-- 201109010900 Floeter-->
 154 </div>
 155 <div  class="sponsor">
 156    <a title="Sponsor: Free Catalogs" href="http://www.who-sells-it.com/">Free Catalogs</a><!-- 20120801000600 -->
 157 </div>
 158 </div>
 159 </div>
 160 </div>\r
 161 \r
 162 <div class="eastbar">\r
 163   <script type="text/javascript">\r
 164   <!--\r
 165     google_ad_client = "pub-3129977114552745";\r
 166     google_ad_slot = "0574824969";\r
 167     google_ad_width = 160;\r
 168     google_ad_height = 600;\r
 169   //-->\r
 170   </script>\r
 171   <script type="text/javascript"\r
 172     src="http://pagead2.googlesyndication.com/pagead/show_ads.js">\r
 173   </script>\r
 174 </div>\r
 175 \r
 176 <div class="main">\r
 177 \r
 178 <h1>MagickCore C API</h1>
 179
 180 <div class="doc-section">
 181
 182 <p>The <a href="../www/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="../www/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>
 183
 184 <ul>
 185   <li><a href="../www/api/magick.html">Initialize or Destroy the ImageMagick Environment</a></li>
 186   <li><a href="../www/api/constitute.html">Constitute an Image</a></li>
 187   <li><a href="../www/api/composite.html">Composite an Image</a></li>
 188   <li><a href="../www/api/image.html">Image Methods</a></li>
 189   <li><a href="../www/api/color.html">Count the Colors in an Image</a></li>
 190   <li><a href="../www/api/colormap.html">Colormap Methods</a></li>
 191   <li><a href="../www/api/distort.html">Image Distortions</a></li>
 192   <li><a href="../www/api/layer.html">Dealing with Image Layers</a></li>
 193   <li><a href="../www/api/profile.html">Dealing with Image Profiles</a></li>
 194   <li><a href="../www/api/quantize.html">Reduce the Number of Unique Colors in an Image</a></li>
 195   <li><a href="../www/api/histogram.html">Image Histograms</a></li>
 196   <li><a href="../www/api/segment.html">Segment an Image with Thresholding Fuzzy c-Means</a></li>
 197   <li><a href="../www/api/resize.html">Resize an Image</a></li>
 198   <li><a href="../www/api/transform.html">Transform an Image</a></li>
 199   <li><a href="../www/api/shear.html">Shear or Rotate an Image by an Arbitrary Angle</a></li>
 200   <li><a href="../www/api/enhance.html">Enhance an Image</a></li>
 201   <li><a href="../www/api/effect.html">Add an Effect</a></li>
 202   <li><a href="../www/api/morphology.html">Morphological Erosions, Dilations, Openings, and Closings</a></li>
 203   <li><a href="../www/api/fx.html">Add a Special Effect</a></li>
 204   <li><a href="../www/api/decorate.html">Decorate an Image</a></li>
 205   <li><a href="../www/api/attribute.html">Get/Set an Image Attribute</a></li>
 206   <li><a href="../www/api/property.html">Get/Set Image Properties</a></li>
 207   <li><a href="../www/api/statistic.html">Get Image Statistics</a></li>
 208   <li><a href="../www/api/feature.html">Get Image Features</a></li>
 209   <li><a href="../www/api/annotate.html">Annotate an Image</a></li>
 210   <li><a href="../www/api/paint.html">Paint on an Image</a></li>
 211   <li><a href="../www/api/draw.html">Draw on an Image</a></li>
 212   <li><a href="../www/api/montage.html">Create an Image Thumbnail</a></li>
 213   <li><a href="../www/api/fourier.html">Compute the discrete Fourier transform (DFT)</a></li>
 214   <li><a href="../www/api/compare.html">Compare an Image to a Reconstructed Image</a></li>
 215   <li><a href="../www/api/display.html">Interactively Display and Edit an Image</a></li>
 216   <li><a href="../www/api/animate.html">Interactively Animate an Image Sequence</a></li>
 217   <li><a href="../www/api/cipher.html">Convert to and from Cipher Pixels</a></li>
 218   <li><a href="../www/api/list.html">Working with Image Lists</a></li>
 219   <li><a href="../www/api/image-view.html">Image View Methods</a></li>
 220   <li><a href="../www/api/cache.html">Get or Set Image Pixels</a></li>
 221   <li><a href="../www/api/cache-view.html">Working with Cache Views</a></li>
 222   <li><a href="../www/api/stream.html">The Pixel FIFO</a></li>
 223   <li><a href="../www/api/blob.html">Read or Write Binary Large OBjects</a></li>
 224   <li><a href="../www/api/module.html">Loadable Modules</a></li>
 225   <li><a href="../www/api/signature.html">Compute a Message Digest for an Image</a></li>
 226   <li><a href="../www/api/registry.html">The Image Registry</a></li>
 227   <li><a href="../www/api/exception.html">Dealing with Exceptions</a></li>
 228   <li><a href="../www/api/memory.html">Memory Allocation</a></li>
 229   <li><a href="../www/api/resource.html">Monitor or Limit Resource Consumption</a></li>
 230   <li><a href="../www/api/monitor.html">Monitor the Progress of an Image Operation</a></li>
 231   <li><a href="../www/api/version.html">Get the Version and Copyrights</a></li>
 232   <li><a href="../www/api/deprecate.html">Deprecated Methods</a></li>
 233   <li><a href="../www/exception.html">Error and Warning Codes</a></li>
 234 </ul>
 235
 236 <p>After you write your MagickCore program, compile it like this:</p>
 237
 238 <p class='crt'><span class="crtprompt"> $magick&gt; </span><span class='crtin'>cc `MagickCore-config --cflags --cppflags` -O2 core.c  \ <br/> `MagickCore-config --ldflags --libs`</span></p>
 239 <p>Here is a example program that utilizes the MagickCore API to get you started, <a href="../www/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>
 240
 241 <div class="viewport">
 242 <pre class="code">
 243   #include &lt;stdio.h>
 244   #include &lt;stdlib.h>
 245   #include &lt;string.h>
 246   #include &lt;time.h>
 247   #include &lt;magick/MagickCore.h>
 248
 249   int main(int argc,char **argv)
 250   {
 251     ExceptionInfo
 252       *exception;
 253
 254     Image
 255       *image,
 256       *images,
 257       *resize_image,
 258       *thumbnails;
 259
 260     ImageInfo
 261       *image_info;
 262
 263     if (argc != 3)
 264       {
 265         (void) fprintf(stdout,"Usage: %s image thumbnail\n",argv[0]);
 266         exit(0);
 267       }
 268     /*
 269       Initialize the image info structure and read an image.
 270     */
 271     MagickCoreGenesis(*argv,MagickTrue);
 272     exception=AcquireExceptionInfo();
 273     image_info=CloneImageInfo((ImageInfo *) NULL);
 274     (void) strcpy(image_info-&gt;filename,argv[1]);
 275     images=ReadImage(image_info,exception);
 276     if (exception-&gt;severity != UndefinedException)
 277       CatchException(exception);
 278     if (images == (Image *) NULL)
 279       exit(1);
 280     /*
 281       Convert the image to a thumbnail.
 282     */
 283     thumbnails=NewImageList();
 284     while ((image=RemoveFirstImageFromList(&amp;images)) != (Image *) NULL)
 285     {
 286       resize_image=ResizeImage(image,106,80,LanczosFilter,1.0,exception);
 287       if (resize_image == (Image *) NULL)
 288         MagickError(exception-&gt;severity,exception-&gt;reason,exception-&gt;description);
 289       (void) AppendImageToList(&amp;thumbnails,resize_image);
 290       DestroyImage(image);
 291     }
 292     /*
 293       Write the image thumbnail.
 294     */
 295     (void) strcpy(thumbnails-&gt;filename,argv[2]);
 296     WriteImage(image_info,thumbnails);
 297     /*
 298       Destroy the image thumbnail and exit.
 299     */
 300     thumbnails=DestroyImageList(thumbnails);
 301     image_info=DestroyImageInfo(image_info);
 302     exception=DestroyExceptionInfo(exception);
 303     MagickCoreTerminus();
 304     return(0);
 305   }
 306 </pre>
 307 </div>
 308 <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="../www/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>
 309
 310 <div class="viewport">
 311 <pre class="code">
 312 #include &lt;stdio.h>
 313 #include &lt;stdlib.h>
 314 #include &lt;math.h>
 315 #include &lt;magick/MagickCore.h>
 316
 317 static MagickBooleanType SigmoidalContrast(ImageView *contrast_view,
 318   const ssize_t y,const int id,void *context)
 319 {
 320 #define QuantumScale  ((MagickRealType) 1.0/(MagickRealType) QuantumRange)
 321 #define SigmoidalContrast(x) \
 322   (QuantumRange*(1.0/(1+exp(10.0*(0.5-QuantumScale*x)))-0.0066928509)*1.0092503)
 323
 324   RectangleInfo
 325     extent;
 326
 327   register IndexPacket
 328     *indexes;
 329
 330   register PixelPacket
 331     *pixels;
 332
 333   register ssize_t
 334     x;
 335
 336   extent=GetImageViewExtent(contrast_view);
 337   pixels=GetImageViewAuthenticPixels(contrast_view);
 338   for (x=0; x &lt; (ssize_t) (extent.width-extent.x); x++)
 339   {
 340     pixels[x].red=RoundToQuantum(SigmoidalContrast(pixels[x].red));
 341     pixels[x].green=RoundToQuantum(SigmoidalContrast(pixels[x].green));
 342     pixels[x].blue=RoundToQuantum(SigmoidalContrast(pixels[x].blue));
 343     pixels[x].opacity=RoundToQuantum(SigmoidalContrast(pixels[x].opacity));
 344   }
 345   indexes=GetImageViewAuthenticIndexes(contrast_view);
 346   if (indexes != (IndexPacket *) NULL)
 347     for (x=0; x &lt; (ssize_t) (extent.width-extent.x); x++)
 348       indexes[x]=(IndexPacket) RoundToQuantum(SigmoidalContrast(indexes[x]));
 349   return(MagickTrue);
 350 }
 351
 352 int main(int argc,char **argv)
 353 {
 354 #define ThrowImageException(image) \
 355 { \
 356  \
 357   CatchException(exception); \
 358   if (contrast_image != (Image *) NULL) \
 359     contrast_image=DestroyImage(contrast_image); \
 360   exit(-1); \
 361 }
 362 #define ThrowViewException(view) \
 363 { \
 364   char \
 365     *description; \
 366  \
 367   ExceptionType \
 368     severity; \
 369  \
 370   description=GetImageViewException(view,&amp;severity); \
 371   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
 372   description=DestroyString(description); \
 373   exit(-1); \
 374 }
 375
 376   ExceptionInfo
 377     *exception;
 378
 379   Image
 380     *contrast_image;
 381
 382   ImageInfo
 383     *image_info;
 384
 385   ImageView
 386     *contrast_view;
 387
 388   MagickBooleanType
 389     status;
 390
 391   if (argc != 3)
 392     {
 393       (void) fprintf(stdout,"Usage: %s image sigmoidal-image\n",argv[0]);
 394       exit(0);
 395     }
 396   /*
 397     Read an image.
 398   */
 399   MagickCoreGenesis(*argv,MagickTrue);
 400   image_info=AcquireImageInfo();
 401   (void) CopyMagickString(image_info->filename,argv[1],MaxTextExtent);
 402   exception=AcquireExceptionInfo();
 403   contrast_image=ReadImage(image_info,exception);
 404   if (contrast_image == (Image *) NULL)
 405     ThrowImageException(contrast_image);
 406   /*
 407     Sigmoidal non-linearity contrast control.
 408   */
 409   contrast_view=NewImageView(contrast_image);
 410   if (contrast_view == (ImageView *) NULL)
 411     ThrowImageException(contrast_image);
 412   status=UpdateImageViewIterator(contrast_view,SigmoidalContrast,(void *) NULL);
 413   if (status == MagickFalse)
 414     ThrowImageException(contrast_image);
 415   contrast_view=DestroyImageView(contrast_view);
 416   /*
 417     Write the image then destroy it.
 418   */
 419   status=WriteImages(image_info,contrast_image,argv[2],exception);
 420   if (status == MagickFalse)
 421     ThrowImageException(contrast_image);
 422   contrast_image=DestroyImage(contrast_image);
 423   exception=DestroyExceptionInfo(exception);
 424   image_info=DestroyImageInfo(image_info);
 425   MagickCoreTerminus();
 426   return(0);
 427 }
 428 </pre>
 429 </div>
 430 </div>
 431 \r
 432 </div>\r
 433 \r
 434 <div id="linkbar">\r
 435     <span id="linkbar-west">&nbsp;</span>\r
 436     <span id="linkbar-center">\r
 437       <a href="http://www.imagemagick.org/discourse-server/">Discourse Server</a> &bull;\r
 438       <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Studio</a>\r
 439     </span>\r
 440     <span id="linkbar-east">&nbsp;</span>\r
 441   </div>\r
 442   <div class="footer">\r
 443     <span id="footer-west">&copy; 1999-2011 ImageMagick Studio LLC</span>\r
 444     <span id="footer-east"> <a href="http://www.imagemagick.org/script/contact.php">Contact the Wizards</a></span>\r
 445   </div>\r
 446   <div style="clear: both; margin: 0; width: 100%; "></div>\r
 447   <script type="text/javascript">\r
 448     var _gaq = _gaq || [];\r
 449     _gaq.push(['_setAccount', 'UA-17690367-1']);\r
 450     _gaq.push(['_trackPageview']);\r
 451 \r
 452     (function() {\r
 453       var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;\r
 454       ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';\r
 455       var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);\r
 456     })();\r
 457   </script>\r
 458 </body>\r
 459 </html>\r