GraphicsMagick Core C API
The GraphicsMagick core C library constitutes the implementation of GraphicsMagick and provides the lowest-level C language programming interface for GraphicsMagick. The core C API provides many functions to read, manipulate, write, or display an image. To invoke the functions, write your program in C (or C++) language while making calls to the core library functions and link with libGraphicsMagick.a, libGraphicsMagick.so, or GraphicsMagick.dll depending on your system.
The API is divided into a number of categories. While reading this documentation, please reference the types documentation as required:
Animate: Interactively animate an image sequence
Annotate: Annotate an image with text
Attribute: Access key, value image attributes
Average: Average several images together
ASC CDL : Apply ASC CDL to image
Blob: Read and write images to memory
Channel: Import and export image channels as well as compute channel depth
Color: Methods to deal with image colors
Colormap: Methods to deal with image colormaps
Compare: Compare images
Composite: Composite images
Confirm Access : Confirm access to files and URLs.
Constitute: Read, write, import, and export images
Decorate: Add fancy borders to images
Describe: Describe an image
Display: Interactively display and edit an image
Draw: Convenient methods to draw vectors and text
Effect:Threshold (various), blur, despeckle, edge, emboss, enhance, gaussian blur ...
Enhance: Contrast, equalize, gamma, level, level channel, modulate, negate, and normalize
Error: Error reporting methods
Export : Export image pixels to common representations
FX: Special effects methods
Hald CLUT : Apply Hald CLUT to image
Image: Miscellaneous image methods
Import : Import image pixels from common representations
List: Manage image lists
Log: Event logging support
Magick: Image format support interfaces
Memory: Memory allocation methods
Monitor: Progress monitor callbacks
Montage: Create a montage of image thumbnails
Operator: Methods to apply mathematic or boolean operators to pixels
Paint: Fill pixel regions
Pixel Cache: Low-level access to image pixels
Pixel Iterator: Pixel iterator design pattern support functions
Plasma: Plasma fractal image generator
Profile: Attached profile access
Quantize: Reduce image colors or assign image colors from colormap
Registry: Store and retrieve images in memory by ID
Render: Render vector graphics
Resize: Resize an Image
Resource: Set and get resource limits
Segment: Coalese similar image colors
Shear: Rotate image, shear image, or apply a 2D affine transformation
Signature: Compute an image signature (checksum)
Statistics: Compute image statistics
Texture: Create a tiled texture image or tile an image with a texture.
Transform: Chop, coalesce, deconstruct, flatten, flip, flop, mosiac, roll, or shave image
Here are a few sample programs to get you started.
This example program (convert.c) simply converts from one file name to another (and will automatically change formats based on file extension):
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>
#include <sys/types.h>
#include <magick/api.h>
int main ( int argc, char **argv )
{
  Image
    *image = (Image *) NULL;
  char
    infile[MaxTextExtent],
    outfile[MaxTextExtent];
  int
    arg = 1,
    exit_status = 0;
  ImageInfo
    *imageInfo;
  ExceptionInfo
    exception;
  InitializeMagick(NULL);
  imageInfo=CloneImageInfo(0);
  GetExceptionInfo(&exception);
  if (argc != 3)
    {
      (void) fprintf ( stderr, "Usage: %s infile outfile\n", argv[0] );
      (void) fflush(stderr);
      exit_status = 1;
      goto program_exit;
    }
  (void) strncpy(infile, argv[arg], MaxTextExtent-1 );
  arg++;
  (void) strncpy(outfile, argv[arg], MaxTextExtent-1 );
  (void) strcpy(imageInfo->filename, infile);
  image = ReadImage(imageInfo, &exception);
  if (image == (Image *) NULL)
    {
      CatchException(&exception);
      exit_status = 1;
      goto program_exit;
    }
  (void) strcpy(image->filename, outfile);
  if (!WriteImage (imageInfo,image))
    {
      CatchException(&image->exception);
      exit_status = 1;
      goto program_exit;
    }
 program_exit:
  if (image != (Image *) NULL)
    DestroyImage(image);
  if (imageInfo != (ImageInfo *) NULL)
    DestroyImageInfo(imageInfo);
  DestroyMagick();
  return exit_status;
}
This example program (demo.c) which reads multiple input files (possibly animation files) specified on the command line, resizes the image frames to 106x80, and writes the resulting animation to disk:
#include <stdio.h>
#include <string.h>
#include <time.h>
#include <sys/types.h>
#include <magick/api.h>
int main(int argc,char **argv)
{
  ExceptionInfo
    exception;
  Image
    *image,
    *images,
    *resize_image,
    *thumbnails;
  ImageInfo
    *image_info;
  int
    i;
  /*
    Initialize the image info structure and read the list of files
    provided by the user as a image sequence
  */
  InitializeMagick(*argv);
  GetExceptionInfo(&exception);
  image_info=CloneImageInfo((ImageInfo *) NULL);
  images=NewImageList();
  for (i=1; i< argc-1; i++)
    {
      (void) strcpy(image_info->filename,argv[i]);
      printf("Reading %s ...", image_info->filename);
      image=ReadImage(image_info,&exception);
      printf(" %lu frames\n", GetImageListLength(image));
      if (exception.severity != UndefinedException)
        CatchException(&exception);
      if (image)
        (void) AppendImageToList(&images,image);
    }
  if (!images)
    {
      printf("Failed to read any images!\n");
      exit(1);
    }
  /*
    Create a thumbnail image sequence
  */
  thumbnails=NewImageList();
  while ((image=RemoveFirstImageFromList(&images)) != (Image *) NULL)
    {
      resize_image=ResizeImage(image,106,80,LanczosFilter,1.0,&exception);
      DestroyImage(image);
      if (resize_image == (Image *) NULL)
        {
          CatchException(&exception);
          continue;
        }
      (void) AppendImageToList(&thumbnails,resize_image);
    }
  /*
    Write the thumbnail image sequence to file
  */
  if (thumbnails)
    {
      (void) strcpy(thumbnails->filename,argv[argc-1]);
      image_info->adjoin=MagickTrue;
      printf("Writing %s ... %lu frames\n", thumbnails->filename,
             GetImageListLength(thumbnails));
      WriteImage(image_info,thumbnails);
    }
  /*
    Release resources
  */
  DestroyImageList(thumbnails);
  DestroyImageInfo(image_info);
  DestroyExceptionInfo(&exception);
  DestroyMagick();
  return(0);
}
To compile on Unix, the command would look something like this:
gcc -o demo demo.c -O `GraphicsMagick-config --cppflags --ldflags --libs`
As a usage example, with the input files in1.gif, in2.png, and in3.jpg, create the animation file out.miff:
demo in1.gif in2.png in3.jpg out.miff
The resulting animation may be played on an X11 display using 'gm animate out.miff'.
The GraphicsMagick-config script reproduces the options which were used to compile the GraphicsMagick utilities. Using compatible options ensures that your program will compile and run.
