granicus.if.org Git - imagemagick/blob - www/magick-core.html

   1 \r
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"\r
   3     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">\r
   4 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" 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, and compose bitmap images. It can read, convert and write images in a variety of formats (about 100) including GIF, JPEG, JPEG-2000, PNG, PDF, PhotoCD, TIFF, and DPX. Use ImageMagick to translate, flip, mirror, rotate, scale, shear and transform images, adjust image colors, apply various special effects, or draw text, lines, polygons, ellipses and Bézier curves.  ImageMagick is free software delivered as a ready-to-run binary distribution or as source code that you can freely use, copy, modify, and distribute. Its license is compatible with the GPL. It runs on all major operating systems.  The functionality of ImageMagick is typically utilized from the command line or you can use the features from programs written in your favorite programming language. Choose from these interfaces: MagickCore (C), MagickWand (C), ChMagick (Ch), Magick++ (C++), JMagick (Java), L-Magick (Lisp), PascalMagick (Pascal), PerlMagick (Perl), MagickWand for PHP (PHP), PythonMagick (Python), RMagick (Ruby), or TclMagick (Tcl/TK). With a language interface, use ImageMagick to modify or create images automagically and dynamically."/>
  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-2010 ImageMagick Studio LLC"/>
  24   <meta name="Distribution" content="Global"/>
  25   <link rel="icon" href="../images/wand.png"  sizes="32x32"/>
  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 </head>\r
  32 \r
  33 <body id="www-imagemagick-org">\r
  34 <div class="titlebar">\r
  35 <a href="../index.html">\r
  36   <img src="../images/script.png" alt="[ImageMagick]"\r
  37   style="width: 350px; height: 60px; margin: 28px auto; float: left;" /></a>\r
  38 <a href="http://www.networkredux.com">\r
  39   <img src="../images/networkredux.png" alt="[sponsor]"\r
  40   style="margin: 45px auto; border: 0px; float: left;" /></a>\r
  41 <a href="http://www.imagemagick.org/discourse-server/">\r
  42   <img src="../images/logo.jpg" alt=""\r
  43   style="width: 114px; height: 118px; border: 0px; float: right;" /></a>\r
  44 <a href="../index.html">\r
  45   <img src="../images/sprite.jpg" alt=""\r
  46   style="width: 114px; height: 118px; border: 0px; float: right;" /></a>\r
  47 </div>\r
  48 \r
  49 <div class="westbar">\r
  50 \r
  51 <div class="menu">
  52   <a title="About ImageMagick" href="../index.html">About ImageMagick</a>
  53 </div>
  54 <div class="sep"></div>\r
  55 <div class="menu">
  56   <a title="Binary Releases" href="../www/binary-releases.html">Binary Releases</a>
  57 </div>
  58 <div class="sub">
  59     <a title="Binary Release: Unix" href="../www/binary-releases.html#unix">Unix</a>
  60 </div>
  61 <div class="sub">
  62     <a title="Binary Release: MacOS X" href="../www/binary-releases.html#macosx">Mac OS X</a>
  63 </div>
  64 <div class="sub">
  65     <a title="Binary Release: Windows" href="../www/binary-releases.html#windows">Windows</a>
  66 </div>
  67 <div class="sep"></div>\r
  68 <div class="menu">
  69   <a title="Command-line Tools" href="../www/command-line-tools.html">Command-line Tools</a>
  70 </div>
  71 <div class="sub">
  72     <a title="Command-line Tools: Processing" href="../www/command-line-processing.html">Processing</a>
  73 </div>
  74 <div class="sub">
  75     <a title="Command-line Tools: Options" href="../www/command-line-options.html">Options</a>
  76 </div>
  77 <div class="sub">
  78     <a title="Command-line Tools: Usage" href="http://www.imagemagick.org/Usage/">Usage</a>
  79 </div>
  80 <div class="menu">
  81   <a title="Program Interfaces" href="../www/api.html">Program Interfaces</a>
  82 </div>
  83 <div class="sub">
  84     <a title="Program Interface: MagickWand" href="../www/magick-wand.html">MagickWand</a>
  85 </div>
  86 <div class="sub">
  87     <a title="Program Interface: MagickCore" href="../www/magick-core.html">MagickCore</a>
  88 </div>
  89 <div class="sub">
  90     <a title="Program Interface: PerlMagick" href="../www/perl-magick.html">PerlMagick</a>
  91 </div>
  92 <div class="sub">
  93     <a title="Program Interface: Magick++" href="../Magick++/">Magick++</a>
  94 </div>
  95 <div class="sep"></div>\r
  96 <div  class="menu">
  97    <a title="Install from Source" href="../www/install-source.html">Install from Source</a>
  98 </div>
  99 <div class="sub">
 100     <a title="Install from Source: Unix" href="../www/install-source.html#unix">Unix</a>
 101 </div>
 102 <div class="sub">
 103     <a title="Install from Source: Windows" href="../www/install-source.html#windows">Windows</a>
 104  </div>
 105 <div class="menu">
 106   <a title="Resources" href="../www/resources.html">Resources</a>
 107 </div>
 108 <div class="menu">
 109   <a title="Architecture" href="../www/architecture.html">Architecture</a>
 110 </div>
 111 <div class="menu">
 112   <a title="Download" href="../www/download.html">Download</a>
 113 </div>
 114 <div class="sep"></div>\r
 115 <div class="menu">
 116   <a title="Search" href="http://www.imagemagick.org/script/search.php">Search</a>
 117 </div>
 118 <div class="sep"></div>\r
 119 <div class="menu">
 120   <a title="Site Map"href="../www/sitemap.html">Site Map</a>
 121 </div>
 122 <div  class="sub">
 123     <a title="Site Map: Links"href="../www/links.html">Links</a>
 124 </div>
 125 <div class="sep"></div>\r
 126 <div  class="menu">
 127   <a title="Sponsors" href="../www/sponsors.html">Sponsors:</a>
 128
 129 <div class="sponsbox">
 130 <div  class="sponsor">
 131    <a title="Sponsor: Webdesign" href="http://www.renehornig.com/">Webdesign</a><!-- 20111001000240 -->
 132 </div>
 133 <div  class="sponsor">
 134   <a title="Sponsor: Druckerei" href="http://print24.com/de/">Druckerei</a><!-- 201110010720 -->
 135 </div>
 136 <div  class="sponsor">
 137   <a title="Sponsor: Image Converter" href="http://www.batchphoto.com">Image Converter</a><!-- 201103010900 Bits Coffee-->
 138 </div>
 139 <div  class="sponsor">
 140   <a title="Sponsor: Flyer drucken" href="http://www.online-druck.biz">Flyer drucken</a><!-- 201109010900 Floeter-->
 141 </div>
 142 <div  class="sponsor">
 143   <a title="Sponsor: Webdesign Agentur" href="http://www.ventzke-partner.de">Webdesign Agentur</a><!-- 201101010480 invendio.de-->
 144 </div>
 145 <div  class="sponsor">
 146   <a title="Sponsor: LVM Versicherung" href="http://www.neu-reich.de">LVM Versicherung</a><!-- 201101010480 -->
 147 </div>
 148 <div  class="sponsor">
 149   <a title="Sponsor: Diamonds are a Girls Best Friend" href="http://www.schmuck.org">Diamonds are a Girls Best Friend</a><!-- 201101010600 Peterssen-->
 150 </div>
 151 <div  class="sponsor">
 152    <a title="Sponsor: Druckerei Online" href="http://www.allesdruck.de">Druckerei Online</a><!-- 201012011200 allesdruck.de-->
 153 </div>
 154 </div>
 155 </div>
 156 </div>\r
 157 \r
 158 <div class="eastbar">\r
 159   <script type="text/javascript">\r
 160   <!--\r
 161     google_ad_client = "pub-3129977114552745";\r
 162     google_ad_slot = "0574824969";\r
 163     google_ad_width = 160;\r
 164     google_ad_height = 600;\r
 165   //-->\r
 166   </script>\r
 167   <script type="text/javascript"\r
 168     src="http://pagead2.googlesyndication.com/pagead/show_ads.js">\r
 169   </script>\r
 170 </div>\r
 171 \r
 172 <div class="main">\r
 173 \r
 174 <p class="navigation-index"></p>
 175
 176 <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>
 177
 178 <ul>
 179   <li><a href="../www/api/magick.html">Initialize or Destroy the ImageMagick Environment</a></li>
 180   <li><a href="../www/api/constitute.html">Constitute an Image</a></li>
 181   <li><a href="../www/api/composite.html">Composite an Image</a></li>
 182   <li><a href="../www/api/image.html">Image Methods</a></li>
 183   <li><a href="../www/api/color.html">Count the Colors in an Image</a></li>
 184   <li><a href="../www/api/colormap.html">Colormap Methods</a></li>
 185   <li><a href="../www/api/distort.html">Image Distortions</a></li>
 186   <li><a href="../www/api/layer.html">Dealing with Image Layers</a></li>
 187   <li><a href="../www/api/profile.html">Dealing with Image Profiles</a></li>
 188   <li><a href="../www/api/quantize.html">Reduce the Number of Unique Colors in an Image</a></li>
 189   <li><a href="../www/api/histogram.html">Image Histograms</a></li>
 190   <li><a href="../www/api/segment.html">Segment an Image with Thresholding Fuzzy c-Means</a></li>
 191   <li><a href="../www/api/resize.html">Resize an Image</a></li>
 192   <li><a href="../www/api/transform.html">Transform an Image</a></li>
 193   <li><a href="../www/api/shear.html">Shear or Rotate an Image by an Arbitrary Angle</a></li>
 194   <li><a href="../www/api/enhance.html">Enhance an Image</a></li>
 195   <li><a href="../www/api/effect.html">Add an Effect</a></li>
 196   <li><a href="../www/api/morphology.html">Morphological Erosions, Dilations, Openings, and Closings</a></li>
 197   <li><a href="../www/api/fx.html">Add a Special Effect</a></li>
 198   <li><a href="../www/api/decorate.html">Decorate an Image</a></li>
 199   <li><a href="../www/api/attribute.html">Get/Set an Image Attribute</a></li>
 200   <li><a href="../www/api/property.html">Get/Set Image Properties</a></li>
 201   <li><a href="../www/api/statistic.html">Get Image Statistics</a></li>
 202   <li><a href="../www/api/feature.html">Get Image Features</a></li>
 203   <li><a href="../www/api/annotate.html">Annotate an Image</a></li>
 204   <li><a href="../www/api/paint.html">Paint on an Image</a></li>
 205   <li><a href="../www/api/draw.html">Draw on an Image</a></li>
 206   <li><a href="../www/api/montage.html">Create an Image Thumbnail</a></li>
 207   <li><a href="../www/api/fourier.html">Compute the discrete Fourier transform (DFT)</a></li>
 208   <li><a href="../www/api/compare.html">Compare an Image to a Reconstructed Image</a></li>
 209   <li><a href="../www/api/display.html">Interactively Display and Edit an Image</a></li>
 210   <li><a href="../www/api/animate.html">Interactively Animate an Image Sequence</a></li>
 211   <li><a href="../www/api/cipher.html">Convert to and from Cipher Pixels</a></li>
 212   <li><a href="../www/api/list.html">Working with Image Lists</a></li>
 213   <li><a href="../www/api/image-view.html">Image View Methods</a></li>
 214   <li><a href="../www/api/cache.html">Get or Set Image Pixels</a></li>
 215   <li><a href="../www/api/cache-view.html">Working with Cache Views</a></li>
 216   <li><a href="../www/api/stream.html">The Pixel FIFO</a></li>
 217   <li><a href="../www/api/blob.html">Read or Write Binary Large OBjects</a></li>
 218   <li><a href="../www/api/module.html">Loadable Modules</a></li>
 219   <li><a href="../www/api/signature.html">Compute a Message Digest for an Image</a></li>
 220   <li><a href="../www/api/registry.html">The Image Registry</a></li>
 221   <li><a href="../www/api/exception.html">Dealing with Exceptions</a></li>
 222   <li><a href="../www/api/memory.html">Memory Allocation</a></li>
 223   <li><a href="../www/api/resource.html">Monitor or Limit Resource Consumption</a></li>
 224   <li><a href="../www/api/monitor.html">Monitor the Progress of an Image Operation</a></li>
 225   <li><a href="../www/api/version.html">Get the Version and Copyrights</a></li>
 226   <li><a href="../www/api/deprecate.html">Deprecated Methods</a></li>
 227   <li><a href="../www/exception.html">Error and Warning Codes</a></li>
 228 </ul>
 229
 230 <p>After you write your MagickCore program, compile it like this:</p>
 231
 232 <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>
 233 <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>
 234
 235 <div class="viewport">
 236 <pre class="code">
 237   #include &lt;stdio.h>
 238   #include &lt;stdlib.h>
 239   #include &lt;string.h>
 240   #include &lt;time.h>
 241   #include &lt;magick/MagickCore.h>
 242
 243   int main(int argc,char **argv)
 244   {
 245     ExceptionInfo
 246       *exception;
 247
 248     Image
 249       *image,
 250       *images,
 251       *resize_image,
 252       *thumbnails;
 253
 254     ImageInfo
 255       *image_info;
 256
 257     if (argc != 3)
 258       {
 259         (void) fprintf(stdout,"Usage: %s image thumbnail\n",argv[0]);
 260         exit(0);
 261       }
 262     /*
 263       Initialize the image info structure and read an image.
 264     */
 265     MagickCoreGenesis(*argv,MagickTrue);
 266     exception=AcquireExceptionInfo();
 267     image_info=CloneImageInfo((ImageInfo *) NULL);
 268     (void) strcpy(image_info-&gt;filename,argv[1]);
 269     images=ReadImage(image_info,exception);
 270     if (exception-&gt;severity != UndefinedException)
 271       CatchException(exception);
 272     if (images == (Image *) NULL)
 273       exit(1);
 274     /*
 275       Convert the image to a thumbnail.
 276     */
 277     thumbnails=NewImageList();
 278     while ((image=RemoveFirstImageFromList(&amp;images)) != (Image *) NULL)
 279     {
 280       resize_image=ResizeImage(image,106,80,LanczosFilter,1.0,exception);
 281       if (resize_image == (Image *) NULL)
 282         MagickError(exception-&gt;severity,exception-&gt;reason,exception-&gt;description);
 283       (void) AppendImageToList(&amp;thumbnails,resize_image);
 284       DestroyImage(image);
 285     }
 286     /*
 287       Write the image thumbnail.
 288     */
 289     (void) strcpy(thumbnails-&gt;filename,argv[2]);
 290     WriteImage(image_info,thumbnails);
 291     /*
 292       Destroy the image thumbnail and exit.
 293     */
 294     thumbnails=DestroyImageList(thumbnails);
 295     image_info=DestroyImageInfo(image_info);
 296     exception=DestroyExceptionInfo(exception);
 297     MagickCoreTerminus();
 298     return(0);
 299   }
 300 </pre>
 301 </div>
 302 <p><a name="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>
 303
 304 <div class="viewport">
 305 <pre class="code">
 306 #include &lt;stdio.h>
 307 #include &lt;stdlib.h>
 308 #include &lt;math.h>
 309 #include &lt;magick/MagickCore.h>
 310
 311 static MagickBooleanType SigmoidalContrast(ImageView *contrast_view,
 312   const ssize_t y,const int id,void *context)
 313 {
 314 #define QuantumScale  ((MagickRealType) 1.0/(MagickRealType) QuantumRange)
 315 #define SigmoidalContrast(x) \
 316   (QuantumRange*(1.0/(1+exp(10.0*(0.5-QuantumScale*x)))-0.0066928509)*1.0092503)
 317
 318   RectangleInfo
 319     extent;
 320
 321   register IndexPacket
 322     *indexes;
 323
 324   register PixelPacket
 325     *pixels;
 326
 327   register ssize_t
 328     x;
 329
 330   extent=GetImageViewExtent(contrast_view);
 331   pixels=GetImageViewAuthenticPixels(contrast_view);
 332   for (x=0; x &lt; (ssize_t) (extent.width-extent.x); x++)
 333   {
 334     pixels[x].red=RoundToQuantum(SigmoidalContrast(pixels[x].red));
 335     pixels[x].green=RoundToQuantum(SigmoidalContrast(pixels[x].green));
 336     pixels[x].blue=RoundToQuantum(SigmoidalContrast(pixels[x].blue));
 337     pixels[x].opacity=RoundToQuantum(SigmoidalContrast(pixels[x].opacity));
 338   }
 339   indexes=GetImageViewAuthenticIndexes(contrast_view);
 340   if (indexes != (IndexPacket *) NULL)
 341     for (x=0; x &lt; (ssize_t) (extent.width-extent.x); x++)
 342       indexes[x]=(IndexPacket) RoundToQuantum(SigmoidalContrast(indexes[x]));
 343   return(MagickTrue);
 344 }
 345
 346 int main(int argc,char **argv)
 347 {
 348 #define ThrowImageException(image) \
 349 { \
 350  \
 351   CatchException(exception); \
 352   if (contrast_image != (Image *) NULL) \
 353     contrast_image=DestroyImage(contrast_image); \
 354   exit(-1); \
 355 }
 356 #define ThrowViewException(view) \
 357 { \
 358   char \
 359     *description; \
 360  \
 361   ExceptionType \
 362     severity; \
 363  \
 364   description=GetImageViewException(view,&severity); \
 365   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
 366   description=DestroyString(description); \
 367   exit(-1); \
 368 }
 369
 370   ExceptionInfo
 371     *exception;
 372
 373   Image
 374     *contrast_image;
 375
 376   ImageInfo
 377     *image_info;
 378
 379   ImageView
 380     *contrast_view;
 381
 382   MagickBooleanType
 383     status;
 384
 385   if (argc != 3)
 386     {
 387       (void) fprintf(stdout,"Usage: %s image sigmoidal-image\n",argv[0]);
 388       exit(0);
 389     }
 390   /*
 391     Read an image.
 392   */
 393   MagickCoreGenesis(*argv,MagickTrue);
 394   image_info=AcquireImageInfo();
 395   (void) CopyMagickString(image_info->filename,argv[1],MaxTextExtent);
 396   exception=AcquireExceptionInfo();
 397   contrast_image=ReadImage(image_info,exception);
 398   if (contrast_image == (Image *) NULL)
 399     ThrowImageException(contrast_image);
 400   /*
 401     Sigmoidal non-linearity contrast control.
 402   */
 403   contrast_view=NewImageView(contrast_image);
 404   if (contrast_view == (ImageView *) NULL)
 405     ThrowImageException(contrast_image);
 406   status=UpdateImageViewIterator(contrast_view,SigmoidalContrast,(void *) NULL);
 407   if (status == MagickFalse)
 408     ThrowImageException(contrast_image);
 409   contrast_view=DestroyImageView(contrast_view);
 410   /*
 411     Write the image then destroy it.
 412   */
 413   status=WriteImages(image_info,contrast_image,argv[2],exception);
 414   if (status == MagickFalse)
 415     ThrowImageException(contrast_image);
 416   contrast_image=DestroyImage(contrast_image);
 417   exception=DestroyExceptionInfo(exception);
 418   image_info=DestroyImageInfo(image_info);
 419   MagickCoreTerminus();
 420   return(0);
 421 }
 422 </pre>
 423 </div>
 424 \r
 425 </div>\r
 426 \r
 427 <div id="linkbar">\r
 428     <span id="linkbar-west">&nbsp;</span>\r
 429     <span id="linkbar-center">\r
 430       <a href="http://www.imagemagick.org/discourse-server/">Discourse Server</a> &bull;\r
 431       <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Studio</a>\r
 432     </span>\r
 433     <span id="linkbar-east">&nbsp;</span>\r
 434   </div>\r
 435   <div class="footer">\r
 436     <span id="footer-west">&copy; 1999-2010 ImageMagick Studio LLC</span>\r
 437     <span id="footer-east"> <a href="http://www.imagemagick.org/script/contact.php">Contact the Wizards</a></span>\r
 438   </div>\r
 439   <div style="clear: both; margin: 0; width: 100%; "></div>\r
 440   <script type="text/javascript">\r
 441     var _gaq = _gaq || [];\r
 442     _gaq.push(['_setAccount', 'UA-17690367-1']);\r
 443     _gaq.push(['_trackPageview']);\r
 444 \r
 445     (function() {\r
 446       var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;\r
 447       ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';\r
 448       var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);\r
 449     })();\r
 450   </script>\r
 451 </body>\r
 452 </html>\r