GraphicsMagick

- Home
- Project
- Download
- Install
- Source
- News
- Utilities
- Programming
- Reference

# 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
> - 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
> - 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.

Copyright © GraphicsMagick Group 2002 - 2012