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: Image Converter" href="http://www.batchphoto.com">Image Converter</a><!-- 201103010900 Bits Coffee-->
 135 </div>
 136 <div  class="sponsor">
 137   <a title="Sponsor: Flyer drucken" href="http://www.online-druck.biz">Flyer drucken</a><!-- 201109010900 Floeter-->
 138 </div>
 139 <div  class="sponsor">
 140   <a title="Sponsor: Webdesign Agentur" href="http://www.ventzke-partner.de">Webdesign Agentur</a><!-- 201101010480 invendio.de-->
 141 </div>
 142 <div  class="sponsor">
 143   <a title="Sponsor: LVM Versicherung" href="http://www.neu-reich.de">LVM Versicherung</a><!-- 201101010480 -->
 144 </div>
 145 <div  class="sponsor">
 146   <a title="Sponsor: Diamonds are a Girls Best Friend" href="http://www.schmuck.org">Diamonds are a Girls Best Friend</a><!-- 201101010600 Peterssen-->
 147 </div>
 148 <div  class="sponsor">
 149    <a title="Sponsor: Druckerei Online" href="http://www.allesdruck.de">Druckerei Online</a><!-- 201012011200 allesdruck.de-->
 150 </div>
 151 </div>
 152 </div>
 153 </div>\r
 154 \r
 155 <div class="eastbar">\r
 156   <script type="text/javascript">\r
 157   <!--\r
 158     google_ad_client = "pub-3129977114552745";\r
 159     google_ad_slot = "0574824969";\r
 160     google_ad_width = 160;\r
 161     google_ad_height = 600;\r
 162   //-->\r
 163   </script>\r
 164   <script type="text/javascript"\r
 165     src="http://pagead2.googlesyndication.com/pagead/show_ads.js">\r
 166   </script>\r
 167 </div>\r
 168 \r
 169 <div class="main">\r
 170 \r
 171 <p class="navigation-index"></p>
 172
 173 <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>
 174
 175 <ul>
 176   <li><a href="../www/api/magick.html">Initialize or Destroy the ImageMagick Environment</a></li>
 177   <li><a href="../www/api/constitute.html">Constitute an Image</a></li>
 178   <li><a href="../www/api/composite.html">Composite an Image</a></li>
 179   <li><a href="../www/api/image.html">Image Methods</a></li>
 180   <li><a href="../www/api/color.html">Count the Colors in an Image</a></li>
 181   <li><a href="../www/api/colormap.html">Colormap Methods</a></li>
 182   <li><a href="../www/api/distort.html">Image Distortions</a></li>
 183   <li><a href="../www/api/layer.html">Dealing with Image Layers</a></li>
 184   <li><a href="../www/api/profile.html">Dealing with Image Profiles</a></li>
 185   <li><a href="../www/api/quantize.html">Reduce the Number of Unique Colors in an Image</a></li>
 186   <li><a href="../www/api/histogram.html">Image Histograms</a></li>
 187   <li><a href="../www/api/segment.html">Segment an Image with Thresholding Fuzzy c-Means</a></li>
 188   <li><a href="../www/api/resize.html">Resize an Image</a></li>
 189   <li><a href="../www/api/transform.html">Transform an Image</a></li>
 190   <li><a href="../www/api/shear.html">Shear or Rotate an Image by an Arbitrary Angle</a></li>
 191   <li><a href="../www/api/enhance.html">Enhance an Image</a></li>
 192   <li><a href="../www/api/effect.html">Add an Effect</a></li>
 193   <li><a href="../www/api/morphology.html">Morphological Erosions, Dilations, Openings, and Closings</a></li>
 194   <li><a href="../www/api/fx.html">Add a Special Effect</a></li>
 195   <li><a href="../www/api/decorate.html">Decorate an Image</a></li>
 196   <li><a href="../www/api/attribute.html">Get/Set an Image Attribute</a></li>
 197   <li><a href="../www/api/property.html">Get/Set Image Properties</a></li>
 198   <li><a href="../www/api/statistic.html">Get Image Statistics</a></li>
 199   <li><a href="../www/api/feature.html">Get Image Features</a></li>
 200   <li><a href="../www/api/annotate.html">Annotate an Image</a></li>
 201   <li><a href="../www/api/paint.html">Paint on an Image</a></li>
 202   <li><a href="../www/api/draw.html">Draw on an Image</a></li>
 203   <li><a href="../www/api/montage.html">Create an Image Thumbnail</a></li>
 204   <li><a href="../www/api/fourier.html">Compute the discrete Fourier transform (DFT)</a></li>
 205   <li><a href="../www/api/compare.html">Compare an Image to a Reconstructed Image</a></li>
 206   <li><a href="../www/api/display.html">Interactively Display and Edit an Image</a></li>
 207   <li><a href="../www/api/animate.html">Interactively Animate an Image Sequence</a></li>
 208   <li><a href="../www/api/cipher.html">Convert to and from Cipher Pixels</a></li>
 209   <li><a href="../www/api/list.html">Working with Image Lists</a></li>
 210   <li><a href="../www/api/image-view.html">Image View Methods</a></li>
 211   <li><a href="../www/api/cache.html">Get or Set Image Pixels</a></li>
 212   <li><a href="../www/api/cache-view.html">Working with Cache Views</a></li>
 213   <li><a href="../www/api/stream.html">The Pixel FIFO</a></li>
 214   <li><a href="../www/api/blob.html">Read or Write Binary Large OBjects</a></li>
 215   <li><a href="../www/api/module.html">Loadable Modules</a></li>
 216   <li><a href="../www/api/signature.html">Compute a Message Digest for an Image</a></li>
 217   <li><a href="../www/api/registry.html">The Image Registry</a></li>
 218   <li><a href="../www/api/exception.html">Dealing with Exceptions</a></li>
 219   <li><a href="../www/api/memory.html">Memory Allocation</a></li>
 220   <li><a href="../www/api/resource.html">Monitor or Limit Resource Consumption</a></li>
 221   <li><a href="../www/api/monitor.html">Monitor the Progress of an Image Operation</a></li>
 222   <li><a href="../www/api/version.html">Get the Version and Copyrights</a></li>
 223   <li><a href="../www/api/deprecate.html">Deprecated Methods</a></li>
 224   <li><a href="../www/exception.html">Error and Warning Codes</a></li>
 225 </ul>
 226
 227 <p>After you write your MagickCore program, compile it like this:</p>
 228
 229 <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>
 230 <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>
 231
 232 <div class="viewport">
 233 <pre class="code">
 234   #include &lt;stdio.h>
 235   #include &lt;stdlib.h>
 236   #include &lt;string.h>
 237   #include &lt;time.h>
 238   #include &lt;magick/MagickCore.h>
 239
 240   int main(int argc,char **argv)
 241   {
 242     ExceptionInfo
 243       *exception;
 244
 245     Image
 246       *image,
 247       *images,
 248       *resize_image,
 249       *thumbnails;
 250
 251     ImageInfo
 252       *image_info;
 253
 254     if (argc != 3)
 255       {
 256         (void) fprintf(stdout,"Usage: %s image thumbnail\n",argv[0]);
 257         exit(0);
 258       }
 259     /*
 260       Initialize the image info structure and read an image.
 261     */
 262     MagickCoreGenesis(*argv,MagickTrue);
 263     exception=AcquireExceptionInfo();
 264     image_info=CloneImageInfo((ImageInfo *) NULL);
 265     (void) strcpy(image_info-&gt;filename,argv[1]);
 266     images=ReadImage(image_info,exception);
 267     if (exception-&gt;severity != UndefinedException)
 268       CatchException(exception);
 269     if (images == (Image *) NULL)
 270       exit(1);
 271     /*
 272       Convert the image to a thumbnail.
 273     */
 274     thumbnails=NewImageList();
 275     while ((image=RemoveFirstImageFromList(&amp;images)) != (Image *) NULL)
 276     {
 277       resize_image=ResizeImage(image,106,80,LanczosFilter,1.0,exception);
 278       if (resize_image == (Image *) NULL)
 279         MagickError(exception-&gt;severity,exception-&gt;reason,exception-&gt;description);
 280       (void) AppendImageToList(&amp;thumbnails,resize_image);
 281       DestroyImage(image);
 282     }
 283     /*
 284       Write the image thumbnail.
 285     */
 286     (void) strcpy(thumbnails-&gt;filename,argv[2]);
 287     WriteImage(image_info,thumbnails);
 288     /*
 289       Destroy the image thumbnail and exit.
 290     */
 291     thumbnails=DestroyImageList(thumbnails);
 292     image_info=DestroyImageInfo(image_info);
 293     exception=DestroyExceptionInfo(exception);
 294     MagickCoreTerminus();
 295     return(0);
 296   }
 297 </pre>
 298 </div>
 299 <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>
 300
 301 <div class="viewport">
 302 <pre class="code">
 303 #include &lt;stdio.h>
 304 #include &lt;stdlib.h>
 305 #include &lt;math.h>
 306 #include &lt;magick/MagickCore.h>
 307
 308 static MagickBooleanType SigmoidalContrast(ImageView *contrast_view,
 309   const ssize_t y,const int id,void *context)
 310 {
 311 #define QuantumScale  ((MagickRealType) 1.0/(MagickRealType) QuantumRange)
 312 #define SigmoidalContrast(x) \
 313   (QuantumRange*(1.0/(1+exp(10.0*(0.5-QuantumScale*x)))-0.0066928509)*1.0092503)
 314
 315   RectangleInfo
 316     extent;
 317
 318   register IndexPacket
 319     *indexes;
 320
 321   register PixelPacket
 322     *pixels;
 323
 324   register ssize_t
 325     x;
 326
 327   extent=GetImageViewExtent(contrast_view);
 328   pixels=GetImageViewAuthenticPixels(contrast_view);
 329   for (x=0; x &lt; (ssize_t) (extent.width-extent.x); x++)
 330   {
 331     pixels[x].red=RoundToQuantum(SigmoidalContrast(pixels[x].red));
 332     pixels[x].green=RoundToQuantum(SigmoidalContrast(pixels[x].green));
 333     pixels[x].blue=RoundToQuantum(SigmoidalContrast(pixels[x].blue));
 334     pixels[x].opacity=RoundToQuantum(SigmoidalContrast(pixels[x].opacity));
 335   }
 336   indexes=GetImageViewAuthenticIndexes(contrast_view);
 337   if (indexes != (IndexPacket *) NULL)
 338     for (x=0; x &lt; (ssize_t) (extent.width-extent.x); x++)
 339       indexes[x]=(IndexPacket) RoundToQuantum(SigmoidalContrast(indexes[x]));
 340   return(MagickTrue);
 341 }
 342
 343 int main(int argc,char **argv)
 344 {
 345 #define ThrowImageException(image) \
 346 { \
 347  \
 348   CatchException(exception); \
 349   if (contrast_image != (Image *) NULL) \
 350     contrast_image=DestroyImage(contrast_image); \
 351   exit(-1); \
 352 }
 353 #define ThrowViewException(view) \
 354 { \
 355   char \
 356     *description; \
 357  \
 358   ExceptionType \
 359     severity; \
 360  \
 361   description=GetImageViewException(view,&severity); \
 362   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
 363   description=DestroyString(description); \
 364   exit(-1); \
 365 }
 366
 367   ExceptionInfo
 368     *exception;
 369
 370   Image
 371     *contrast_image;
 372
 373   ImageInfo
 374     *image_info;
 375
 376   ImageView
 377     *contrast_view;
 378
 379   MagickBooleanType
 380     status;
 381
 382   if (argc != 3)
 383     {
 384       (void) fprintf(stdout,"Usage: %s image sigmoidal-image\n",argv[0]);
 385       exit(0);
 386     }
 387   /*
 388     Read an image.
 389   */
 390   MagickCoreGenesis(*argv,MagickTrue);
 391   image_info=AcquireImageInfo();
 392   (void) CopyMagickString(image_info->filename,argv[1],MaxTextExtent);
 393   exception=AcquireExceptionInfo();
 394   contrast_image=ReadImage(image_info,exception);
 395   if (contrast_image == (Image *) NULL)
 396     ThrowImageException(contrast_image);
 397   /*
 398     Sigmoidal non-linearity contrast control.
 399   */
 400   contrast_view=NewImageView(contrast_image);
 401   if (contrast_view == (ImageView *) NULL)
 402     ThrowImageException(contrast_image);
 403   status=UpdateImageViewIterator(contrast_view,SigmoidalContrast,(void *) NULL);
 404   if (status == MagickFalse)
 405     ThrowImageException(contrast_image);
 406   contrast_view=DestroyImageView(contrast_view);
 407   /*
 408     Write the image then destroy it.
 409   */
 410   status=WriteImages(image_info,contrast_image,argv[2],exception);
 411   if (status == MagickFalse)
 412     ThrowImageException(contrast_image);
 413   contrast_image=DestroyImage(contrast_image);
 414   exception=DestroyExceptionInfo(exception);
 415   image_info=DestroyImageInfo(image_info);
 416   MagickCoreTerminus();
 417   return(0);
 418 }
 419 </pre>
 420 </div>
 421 \r
 422 </div>\r
 423 \r
 424 <div id="linkbar">\r
 425     <span id="linkbar-west">&nbsp;</span>\r
 426     <span id="linkbar-center">\r
 427       <a href="http://www.imagemagick.org/discourse-server/">Discourse Server</a> &bull;\r
 428       <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Studio</a>\r
 429     </span>\r
 430     <span id="linkbar-east">&nbsp;</span>\r
 431   </div>\r
 432   <div class="footer">\r
 433     <span id="footer-west">&copy; 1999-2010 ImageMagick Studio LLC</span>\r
 434     <span id="footer-east"> <a href="http://www.imagemagick.org/script/contact.php">Contact the Wizards</a></span>\r
 435   </div>\r
 436   <div style="clear: both; margin: 0; width: 100%; "></div>\r
 437   <script type="text/javascript">\r
 438     var _gaq = _gaq || [];\r
 439     _gaq.push(['_setAccount', 'UA-17690367-1']);\r
 440     _gaq.push(['_trackPageview']);\r
 441 \r
 442     (function() {\r
 443       var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;\r
 444       ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';\r
 445       var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);\r
 446     })();\r
 447   </script>\r
 448 </body>\r
 449 </html>\r