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

   1
   2
   3
   4
   5 <!DOCTYPE html>
   6 <html lang="en">
   7 <head>
   8   <meta charset="utf-8" />
   9   <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  10   <meta http-equiv="x-ua-compatible" content="ie=edge" />
  11   <title>MagickCore, Low-level C API @ ImageMagick</title>
  12   <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
  13   <meta name="application-name" content="ImageMagick"/>
  14   <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."/>
  15   <meta name="application-url" content="https://www.imagemagick.org"/>
  16   <meta name="generator" content="PHP"/>
  17   <meta name="keywords" content="magickcore, low-level, c, api, ImageMagick, PerlMagick, image processing, image, photo, software, Magick++, OpenMP, convert"/>
  18   <meta name="rating" content="GENERAL"/>
  19   <meta name="robots" content="INDEX, FOLLOW"/>
  20   <meta name="generator" content="ImageMagick Studio LLC"/>
  21   <meta name="author" content="ImageMagick Studio LLC"/>
  22   <meta name="revisit-after" content="2 DAYS"/>
  23   <meta name="resource-type" content="document"/>
  24   <meta name="copyright" content="Copyright (c) 1999-2017 ImageMagick Studio LLC"/>
  25   <meta name="distribution" content="Global"/>
  26   <meta name="magick-serial" content="P131-S030410-R485315270133-P82224-A6668-G1245-1"/>
  27   <meta name="google-site-verification" content="_bMOCDpkx9ZAzBwb2kF3PRHbfUUdFj2uO8Jd1AXArz4" />
  28   <link rel="canonical" href="https://www.imagemagick.org/script/magick-core.html" />
  29   <link rel="icon" href="../images/wand.png" />
  30   <link rel="shortcut icon" href="../images/wand.ico" />
  31   <link rel="stylesheet" type="text/css" href="http://fonts.googleapis.com/css?family=Roboto:900,400,400italic,700,700italic,300,300italic|Open+Sans:300italic,400italic,700italic,300,400,600,700" />
  32   <link rel="stylesheet" href="css/magick.css" />
  33 </head>
  34 <body>
  35 <div class="magick-header">
  36   <div class="container">
  37     <script async="async" src="http://localhost/pagead/js/adsbygoogle.js"></script>    <ins class="adsbygoogle"
  38          style="display:block"
  39          data-ad-client="ca-pub-3129977114552745"
  40          data-ad-slot="6345125851"
  41          data-ad-format="auto"></ins>
  42     <script>
  43       (adsbygoogle = window.adsbygoogle || []).push({});
  44     </script>
  45     <nav class="nav magick-nav">
  46       <a class="nav-link " href="../index.html">Home</a>
  47       <a class="nav-link " href="download.html">Download</a>
  48       <a class="nav-link " href="command-line-tools.html">Tools</a>
  49       <a class="nav-link " href="command-line-processing.html">Command-line</a>
  50       <a class="nav-link " href="resources.html">Resources</a>
  51       <a class="nav-link " href="develop.html">Develop</a>
  52       <a class="nav-link " href="https://www.imagemagick.org/script/search.php">Search</a>
  53       <a class="nav-link float-right" href="https://www.imagemagick.org/discourse-server/">Community</a>
  54     </nav>
  55   </div>
  56 </div>
  57 <div class="container">
  58 <div class="magick-main">
  59 <div class="magick-header">
  60
  61 <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>
  62
  63 <ul>
  64   <li><a href="http://www.imagemagick.org/api/magick.html">Initialize or Destroy the ImageMagick Environment</a></li>
  65   <li><a href="http://www.imagemagick.org/api/constitute.html">Constitute an Image</a></li>
  66   <li><a href="api/composite.html">Composite an Image</a></li>
  67   <li><a href="http://www.imagemagick.org/api/image.html">Image Methods</a></li>
  68   <li><a href="http://www.imagemagick.org/api/channel.html">Image Channel Methods</a></li>
  69   <li><a href="http://www.imagemagick.org/api/color.html">Count the Colors in an Image</a></li>
  70   <li><a href="http://www.imagemagick.org/api/colormap.html">Colormap Methods</a></li>
  71   <li><a href="http://www.imagemagick.org/api/colorspace.html">Colorspace Methods</a></li>
  72   <li><a href="http://www.imagemagick.org/api/distort.html">Image Distortions</a></li>
  73   <li><a href="http://www.imagemagick.org/api/layer.html">Dealing with Image Layers</a></li>
  74   <li><a href="api/profile.html">Dealing with Image Profiles</a></li>
  75   <li><a href="http://www.imagemagick.org/api/quantize.html">Reduce the Number of Unique Colors in an Image</a></li>
  76   <li><a href="http://www.imagemagick.org/api/histogram.html">Image Histograms</a></li>
  77   <li><a href="http://www.imagemagick.org/api/segment.html">Segment an Image with Thresholding Fuzzy c-Means</a></li>
  78   <li><a href="http://www.imagemagick.org/api/resize.html">Resize an Image</a></li>
  79   <li><a href="http://www.imagemagick.org/api/transform.html">Transform an Image</a></li>
  80   <li><a href="http://www.imagemagick.org/api/shear.html">Shear or Rotate an Image by an Arbitrary Angle</a></li>
  81   <li><a href="http://www.imagemagick.org/api/enhance.html">Enhance an Image</a></li>
  82   <li><a href="http://www.imagemagick.org/api/effect.html">Add an Effect</a></li>
  83   <li><a href="http://www.imagemagick.org/api/morphology.html">Morphological Erosions, Dilations, Openings, and Closings</a></li>
  84   <li><a href="http://www.imagemagick.org/api/fx.html">Add a Special Effect</a></li>
  85   <li><a href="http://www.imagemagick.org/api/decorate.html">Decorate an Image</a></li>
  86   <li><a href="http://www.imagemagick.org/api/attribute.html">Get/Set an Image Attribute</a></li>
  87   <li><a href="api/property.html">Get/Set Image Properties</a></li>
  88   <li><a href="http://www.imagemagick.org/api/statistic.html">Get Image Statistics</a></li>
  89   <li><a href="http://www.imagemagick.org/api/feature.html">Get Image Features</a></li>
  90   <li><a href="http://www.imagemagick.org/api/annotate.html">Annotate an Image</a></li>
  91   <li><a href="http://www.imagemagick.org/api/paint.html">Paint on an Image</a></li>
  92   <li><a href="http://www.imagemagick.org/api/draw.html">Draw on an Image</a></li>
  93   <li><a href="http://www.imagemagick.org/api/montage.html">Create an Image Thumbnail</a></li>
  94   <li><a href="http://www.imagemagick.org/api/fourier.html">Compute the discrete Fourier transform (DFT)</a></li>
  95   <li><a href="http://www.imagemagick.org/api/compare.html">Compare an Image to a Reconstructed Image</a></li>
  96   <li><a href="http://www.imagemagick.org/api/display.html">Interactively Display and Edit an Image</a></li>
  97   <li><a href="http://www.imagemagick.org/api/animate.html">Interactively Animate an Image Sequence</a></li>
  98   <li><a href="http://www.imagemagick.org/api/cipher.html">Convert to and from Cipher Pixels</a></li>
  99   <li><a href="http://www.imagemagick.org/api/list.html">Working with Image Lists</a></li>
 100   <li><a href="api/image-view.html">Image View Methods</a></li>
 101   <li><a href="api/cache.html">Get or Set Image Pixels</a></li>
 102   <li><a href="api/cache-view.html">Working with Cache Views</a></li>
 103   <li><a href="api/stream.html">The Pixel FIFO</a></li>
 104   <li><a href="http://www.imagemagick.org/api/blob.html">Read or Write Binary Large OBjects</a></li>
 105   <li><a href="api/module.html">Loadable Modules</a></li>
 106   <li><a href="http://www.imagemagick.org/api/signature.html">Compute a Message Digest for an Image</a></li>
 107   <li><a href="http://www.imagemagick.org/api/registry.html">The Image Registry</a></li>
 108   <li><a href="http://www.imagemagick.org/api/exception.html">Dealing with Exceptions</a></li>
 109   <li><a href="http://www.imagemagick.org/api/memory.html">Memory Allocation</a></li>
 110   <li><a href="api/resource.html">Monitor or Limit Resource Consumption</a></li>
 111   <li><a href="http://www.imagemagick.org/api/monitor.html">Monitor the Progress of an Image Operation</a></li>
 112   <li><a href="http://www.imagemagick.org/api/version.html">Get the Version and Copyrights</a></li>
 113   <li><a href="http://www.imagemagick.org/api/mime.html">Mime Methods</a></li>
 114   <li><a href="http://www.imagemagick.org/api/deprecate.html">Deprecated Methods</a></li>
 115   <li><a href="exception.html">Error and Warning Codes</a></li>
 116 </ul>
 117
 118 <p>After you write your MagickCore program, compile it like this:</p>
 119
 120 <pre><code>
 121 cc -o core core.c `pkg-config --cflags --libs MagickWand`
 122 </code></pre>
 123
 124 <p>Set the <code>PKG_CONFIG_PATH</code> environment variable if ImageMagick is not in your default system path:</p>
 125
 126 <pre><code>
 127 export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
 128 </code></pre>
 129
 130 <p>Here is a example program that utilizes the MagickCore API to get you started, <a href="http://www.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>
 131
 132 <pre class="pre-scrollable"><code>#include &lt;stdio.h>
 133 #include &lt;stdlib.h>
 134 #include &lt;string.h>
 135 #include &lt;time.h>
 136 #include &lt;MagickCore/MagickCore.h>
 137
 138 int main(int argc,char **argv)
 139 {
 140   ExceptionInfo
 141     *exception;
 142
 143   Image
 144     *image,
 145     *images,
 146     *resize_image,
 147     *thumbnails;
 148
 149   ImageInfo
 150     *image_info;
 151
 152   if (argc != 3)
 153     {
 154       (void) fprintf(stdout,"Usage: %s image thumbnail\n",argv[0]);
 155       exit(0);
 156     }
 157   /*
 158     Initialize the image info structure and read an image.
 159   */
 160   MagickCoreGenesis(*argv,MagickTrue);
 161   exception=AcquireExceptionInfo();
 162   image_info=CloneImageInfo((ImageInfo *) NULL);
 163   (void) strcpy(image_info-&gt;filename,argv[1]);
 164   images=ReadImage(image_info,exception);
 165   if (exception-&gt;severity != UndefinedException)
 166     CatchException(exception);
 167   if (images == (Image *) NULL)
 168     exit(1);
 169   /*
 170     Convert the image to a thumbnail.
 171   */
 172   thumbnails=NewImageList();
 173   while ((image=RemoveFirstImageFromList(&amp;images)) != (Image *) NULL)
 174   {
 175     resize_image=ResizeImage(image,106,80,LanczosFilter,exception);
 176     if (resize_image == (Image *) NULL)
 177       MagickError(exception-&gt;severity,exception-&gt;reason,exception-&gt;description);
 178     (void) AppendImageToList(&amp;thumbnails,resize_image);
 179     DestroyImage(image);
 180   }
 181   /*
 182     Write the image thumbnail.
 183   */
 184   (void) strcpy(thumbnails-&gt;filename,argv[2]);
 185   WriteImage(image_info,thumbnails,exception);
 186   /*
 187     Destroy the image thumbnail and exit.
 188   */
 189   thumbnails=DestroyImageList(thumbnails);
 190   image_info=DestroyImageInfo(image_info);
 191   exception=DestroyExceptionInfo(exception);
 192   MagickCoreTerminus();
 193   return(0);
 194 }</code></pre>
 195 <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="http://www.imagemagick.org/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>
 196
 197 <pre class="pre-scrollable"><code>#include &lt;stdio.h>
 198 #include &lt;stdlib.h>
 199 #include &lt;math.h>
 200 #include &lt;MagickCore/MagickCore.h>
 201
 202 static MagickBooleanType SigmoidalContrast(ImageView *contrast_view,
 203   const ssize_t y,const int id,void *context)
 204 {
 205 #define QuantumScale  ((MagickRealType) 1.0/(MagickRealType) QuantumRange)
 206 #define SigmoidalContrast(x) \
 207   (QuantumRange*(1.0/(1+exp(10.0*(0.5-QuantumScale*x)))-0.0066928509)*1.0092503)
 208
 209   RectangleInfo
 210     extent;
 211
 212   register IndexPacket
 213     *indexes;
 214
 215   register PixelPacket
 216     *pixels;
 217
 218   register ssize_t
 219     x;
 220
 221   extent=GetImageViewExtent(contrast_view);
 222   pixels=GetImageViewAuthenticPixels(contrast_view);
 223   for (x=0; x &lt; (ssize_t) (extent.width-extent.x); x++)
 224   {
 225     SetPixelRed(pixels,RoundToQuantum(SigmoidalContrast(GetPixelRed(pixels)));
 226     SetPixelGreen(pixels,RoundToQuantum(SigmoidalContrast(GetPixelGreen(pixels)));
 227     SetPixelBlue(pixels,RoundToQuantum(SigmoidalContrast(GetPixelBlue(pixels)));
 228     SetPixelOpacity(pixels,RoundToQuantum(SigmoidalContrast(GetPixelOpacity(pixels)));
 229     pixels++;
 230   }
 231   indexes=GetImageViewAuthenticIndexes(contrast_view);
 232   if (indexes != (IndexPacket *) NULL)
 233     for (x=0; x &lt; (ssize_t) (extent.width-extent.x); x++)
 234       SetPixelIndex(indexes+x,RoundToQuantum(SigmoidalContrast(GetPixelIndex(indexes+x))));
 235   return(MagickTrue);
 236 }
 237
 238 int main(int argc,char **argv)
 239 {
 240 #define ThrowImageException(image) \
 241 { \
 242  \
 243   CatchException(exception); \
 244   if (contrast_image != (Image *) NULL) \
 245     contrast_image=DestroyImage(contrast_image); \
 246   exit(-1); \
 247 }
 248 #define ThrowViewException(view) \
 249 { \
 250   char \
 251     *description; \
 252  \
 253   ExceptionType \
 254     severity; \
 255  \
 256   description=GetImageViewException(view,&amp;severity); \
 257   (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
 258   description=DestroyString(description); \
 259   exit(-1); \
 260 }
 261
 262   ExceptionInfo
 263     *exception;
 264
 265   Image
 266     *contrast_image;
 267
 268   ImageInfo
 269     *image_info;
 270
 271   ImageView
 272     *contrast_view;
 273
 274   MagickBooleanType
 275     status;
 276
 277   if (argc != 3)
 278     {
 279       (void) fprintf(stdout,"Usage: %s image sigmoidal-image\n",argv[0]);
 280       exit(0);
 281     }
 282   /*
 283     Read an image.
 284   */
 285   MagickCoreGenesis(*argv,MagickTrue);
 286   image_info=AcquireImageInfo();
 287   (void) CopyMagickString(image_info->filename,argv[1],MaxTextExtent);
 288   exception=AcquireExceptionInfo();
 289   contrast_image=ReadImage(image_info,exception);
 290   if (contrast_image == (Image *) NULL)
 291     ThrowImageException(contrast_image);
 292   /*
 293     Sigmoidal non-linearity contrast control.
 294   */
 295   contrast_view=NewImageView(contrast_image);
 296   if (contrast_view == (ImageView *) NULL)
 297     ThrowImageException(contrast_image);
 298   status=UpdateImageViewIterator(contrast_view,SigmoidalContrast,(void *) NULL);
 299   if (status == MagickFalse)
 300     ThrowImageException(contrast_image);
 301   contrast_view=DestroyImageView(contrast_view);
 302   /*
 303     Write the image then destroy it.
 304   */
 305   status=WriteImages(image_info,contrast_image,argv[2],exception);
 306   if (status == MagickFalse)
 307     ThrowImageException(contrast_image);
 308   contrast_image=DestroyImage(contrast_image);
 309   exception=DestroyExceptionInfo(exception);
 310   image_info=DestroyImageInfo(image_info);
 311   MagickCoreTerminus();
 312   return(0);
 313 }</code></pre>
 314 </div>
 315   <footer class="magick-footer">
 316     <p><a href="support.html">Donate</a> •
 317      <a href="sitemap.html">Sitemap</a> •
 318     <a href="links.html">Related</a> •
 319     <a href="security-policy.html">Security</a> •
 320     <a href="architecture.html">Architecture</a>
 321 </p>
 322     <p><a href="magick-core.html#">Back to top</a> •
 323     <a href="http://pgp.mit.edu:11371/pks/lookup?op=get&amp;search=0x89AB63D48277377A">Public Key</a> •
 324     <a href="https://www.imagemagick.org/script/contact.php">Contact Us</a></p>
 325         <p><small>© 1999-2017 ImageMagick Studio LLC</small></p>
 326   </footer>
 327 </div><!-- /.container -->
 328
 329   <script src="https://localhost/ajax/libs/jquery/1.12.4/jquery.min.js"></script>
 330   <script src="../js/magick.html"></script>
 331 </div>
 332 </body>
 333 </html>
 334 <!-- Magick Cache 29th June 2017 11:07 -->