[ImageMagick] [sponsor]
Processing
Options
Usage
MagickWand
MagickCore
PerlMagick
Magick++
Unix
Windows
Unix
Mac OS X
Windows
Links

The ImageMagick command line can be as simple as

  convert image.jpg image.png

or as complex as

  convert label.gif +matte \
    \( +clone  -shade 110x90 -normalize -negate +clone  -compose Plus -composite \) \
    \( -clone 0 -shade 110x50 -normalize -channel BG -fx 0 +channel -matte \) \
    -delete 0 +swap  -compose Multiply -composite  button.gif

Without knowing much about the ImageMagick command line, you can probably figure out that the first command converts an image in the JPEG format to one in the PNG format. However, very few may realize the second, more complex command, gives a flat two-dimensional label a three-dimensional look with rich textures and simulated depth:

label ==> button

In the next sections we dissect the anatomy of the ImageMagick command line. Hopefully, after carefully reading and better understanding how the command line works, you should be able to accomplish complex image-processing tasks without resorting to the sometimes daunting program interfaces.

See Examples of ImageMagick Usage for additional help when using ImageMagick from the command-line.

The Anatomy of the Command Line

The ImageMagick command line consists of

  1. one or more required input filenames.
  2. zero, one, or more image settings.
  3. zero, one, or more image operators.
  4. zero, one, or more image sequence operators.
  5. zero, one, or more image stacks.
  6. zero or one output image filenames (required by convert, composite, montage, compare, import, and conjure).

You can find a detailed explanation of each of the constituent parts of the command line in the sections that follow.

Input Filename

ImageMagick extends the concept of an input filename to include: 1) filename globbing; 2) an explicit image format; 3) using built-in images and patterns; 4) reading an image from standard in; 5) selecting certain frames from an image; and 6) selecting a region of an image. Each of these extensions are explained in the next few paragraphs.

Image Setting

An image setting persists as it appears on the command line and may affect subsequent processing such as reading an image, an image operator, or when writing an image as appropriate. An image setting stays in effect until it is reset or the command line terminates. The image settings include:

In this example, -channel applies to each of the images since as we mentioned, settings persist:

  convert -channel RGB wand.png wizard.png images.png

Image Operator

An image operator differs from a setting in that it affects the image immediately as it appears on the command line. An operator is any command line option not listed as a image setting or image sequence operator. Unlike an image setting, which persists until the command line terminates, an operator is applied to an image and forgotten. Choose from these image operators:

In this example, -negate negates the wand image but not the wizard:

  convert wand.png -negate wizard.png images.png

Image Sequence Operator

An image sequence operator differs from a setting in that it affects an image sequence immediately as it appears on the command line. Choose from these image sequence operators:

Image Geometry

Many command-line options take a geometry argument to specify such things as the desired width and height of an image and other dimensional quantities. Because users want so many variations on the resulting dimensions, sizes, and positions of images (and because ImageMagick wants to provide them), the geometry argument can take many forms. We describe many of these in this section.

The image options and settings that take some form of a geometry argument include the following. Keep in mind that some of these parse their arguments in slightly different ways. See the documentation for the individual option or setting for more specifics.

The geometry argument might take any of the forms listed in the table below. These will described in more detail in the subsections following the table. The usual form is size[offset], meaning size is required and offset is optional. Occasionally, [size]offset is possible. In no cases are spaces permitted within the geometry argument.

Image Stack

In school, your teacher probably permitted you to work on problems on a scrap of paper and then copy the results to your test paper. An image stack is similar. It permits you to work on an image or image sequence in isolation and subsequently introduce the results back into the command line. The image stack is delineated with parenthesis. Image operators only affect images in the current stack. For example, we can limit the image rotation to just the wizard image like this:

  convert wand.gif \( wizard.gif -rotate 30 \) +append images.gif

Notice that the parentheses are escaped by preceding them with backslashes. This is required under Unix, where parentheses are special shell characters. The backslash tells the shell not to interpret these characters, but to pass them directly to the command being executed. Do not escape the parentheses under Windows. Each parenthesis (or escaped parenthesis) must have spaces on either side, as in the example shown above.

In addition to the image operators already discussed, the following image operators are most useful when processing images in an image stack:

The arguments to these operators are indexes into the image sequence by number, starting with zero, for the first image, and so on. However if you give a negative index, the images are indexed from the end (last image added). That is, an index of -1 is the last image in the current image sequence, -2 gives the second-to-last, and so on.

Output Filename

ImageMagick extends the concept of an output filename to include:

  1. an explicit image format
  2. write to standard out
  3. filename references

Each of these extensions are explained in the next few paragraphs.