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