The Anatomy of the Command-line • Input Filename • Command-line Options • Output Filename
The ImageMagick command-line tools can be as simple as this:
magick image.jpg image.png
Or it can be complex with a plethora of options, as in the following:
magick label.gif -alpha Set \ \( +clone -shade 110x90 -normalize -negate +clone -compose Plus -composite \) \ \( -clone 0 -shade 110x50 -normalize -channel BG -fx 0 +channel -alpha Off \) \ -delete 0 +swap -compose Multiply -composite button.gif
This example command is long enough that the command must be written across several lines, so we formatted it for clarity by inserting backslashes (\). The backslash is the Linux line-continuation character. In the Windows shell, use a caret character (^) for line-continuation. We use the Linux style on these web pages, as above. Sometimes, however, the lines are wrapped by your browser if the browser window is small enough, but the command-lines, shown in white, are still intended to be typed as one line. Line continuation characters need not be entered. The parentheses that are escaped above using the backslash are not escaped in Windows. There are some other differences between Windows and Linux (involving quotation marks, for instance), but we'll discuss some of those issues later, as they arise.
For most command line examples on this site, if there is an equivalent translation to run on windows there will be a dropdown in the bottom right, letting you switch which operating system you are previewing the command for.
Without knowing much about the ImageMagick command-line, you can probably surmise that the first command above 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:
Here we show percent completion of a task as a shaded cylinder:
Given the complexity of the rendering, you might be surprised it is accomplished by a single command-line:
magick -size 320x90 canvas:none -stroke snow4 -size 1x90 -tile gradient:white-snow4 \ -draw 'roundrectangle 16, 5, 304, 85 20,40' +tile -fill snow \ -draw 'roundrectangle 264, 5, 304, 85 20,40' -tile gradient:chartreuse-green \ -draw 'roundrectangle 16, 5, 180, 85 20,40' -tile gradient:chartreuse1-chartreuse3 \ -draw 'roundrectangle 140, 5, 180, 85 20,40' +tile -fill none \ -draw 'roundrectangle 264, 5, 304, 85 20,40' -strokewidth 2 \ -draw 'roundrectangle 16, 5, 304, 85 20,40' \( +clone -background snow4 \ -shadow 80x3+3+3 \) +swap -background none -layers merge \( +size -pointsize 90 \ -strokewidth 1 -fill red label:'50 %' -trim +repage \( +clone -background firebrick3 \ -shadow 80x3+3+3 \) +swap -background none -layers merge \) -insert 0 -gravity center \ -append -background white -gravity center -extent 320x200 cylinder_shaded.png
Run this script contributed by Geemack. You'll get a glimpse of the power and versatility of the ImageMagick command-line:
magick -background none -size 960x960 xc:black \( xc:darkred -duplicate 1 +append \) \ xc:gold \( xc:teal -duplicate 2 +append \) -modulate 100,100,"%[fx:rand()*200]" \ xc:white -scale x1 +append -write mpr:clut +delete radial-gradient: mpr:clut \ -clut -scale 100x4% -wave "%[fx:rand()*24+24]"x"%[fx:w/ceil(rand()*4+1)]" -extent "%[w]x%[w]" \ -roll +0+"%[fx:(rand()*w*0.05)+(w*0.51)]" \( +clone -blur 0x4 \) -insert 0 -composite \ -duplicate "%[fx:floor(rand()*3+3)*2-1]" -set option:rot "%[fx:180/n]" -virtual-pixel tile \ -virtual-pixel none -distort SRT "%[fx:t*360/n]" +repage -flatten -extent 100x50% \ \( +clone -rotate 180 \) -append +channel -virtual-pixel none -distort SRT "0.96 %[fx:rand()*360]" \ \( +clone -flop \) +repage -insert "%[fx:round(rand())]" -background black \ -flatten -brightness-contrast 20,20 -normalize dragonFire.png
To ensure the script can run under Windows, change any backslash-parens (\() to just parens, the backslash (\) to ^, and double-up the percent (%) signs.
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 ImageMagick command-line consists of
You can find a detailed explanation of each of the constituent parts of the command-line in the sections that follow.
ImageMagick extends the concept of an input filename to include:
These extensions are explained in the next few paragraphs.
Note, by default, if a command-line option is also a filename (e.g., -quality), it is interpreted as a filename. Use -define registry:option:pedantic=true to instead interpret it as an option.
In Linux shells, certain characters such as the asterisk (*) and question mark (?) automagically cause lists of filenames to be generated based on pattern matches. This feature is known as globbing. ImageMagick supports filename globbing for systems, such as Windows, that does not natively support it. For example, suppose you want to convert 1.jpg, 2.jpg, 3.jpg, 4.jpg, and 5.jpg in your current directory to a GIF animation. You can conveniently refer to all of the JPEG files with this command:
magick *.jpg images.gif
Images are stored in a myriad of image formats including the better known JPEG, PNG, TIFF and others. ImageMagick must know the format of the image before it can be read and processed. Most formats have a signature within the image that uniquely identifies the format. Failing that, ImageMagick leverages the filename extension to determine the format. For example, image.jpg or image.JPG tells ImageMagick it is reading an image in the JPEG format.
In some cases the image may not contain a signature and/or the filename does not identify the image format. In these cases an explicit image format must be specified. For example, suppose our image is named image and contains raw red, green, and blue intensity values. ImageMagick has no way to automagically determine the image format so we explicitly set one:
magick -size 640x480 -depth 8 rgb:image image.png
ImageMagick has a number of built-in images and patterns. To utilize the checkerboard pattern, for example, use:
magick -size 640x480 pattern:checkerboard checkerboard.png
Linux and Windows permit the output of one command to be piped to the input of another. ImageMagick permits image data to be read and written from the standard streams STDIN (standard in) and STDOUT (standard out), respectively, using a pseudo-filename of -. In this example we pipe the output of magick to the display program:
magick logo: gif:- | magick display gif:-
The second explicit format "gif:" is optional in the preceding example. The GIF image format has a unique signature within the image so ImageMagick's display command can readily recognize the format as GIF. The magick program also accepts STDIN as input in this way:
magick rose: gif:- | magick - -resize "200%" bigrose.jpg'
Other pipes can be accessed via their file descriptors (as of version 6.4.9-3). The file descriptors 0, 1, and 2 are reserved for the standard streams STDIN, STDOUT, and STDERR, respectively, but a pipe associated with a file descriptor number N>2 can be accessed using the pseudonym fd:N. (The pseudonyms fd:0 and fd:1 can be used for STDIN and STDOUT.) The next example shows how to append image data piped from files with descriptors 3 and 4 and direct the result to the file with descriptor number 5.
magick fd:3 fd:4 -append fd:5
When needed, explicit image formats can be given as mentioned earlier, as in the following.
magick gif:fd:3 jpg:fd:4 -append tif:fd:5
Some images formats contain more than one image frame. Perhaps you only want the first image, or the last, or some number of images in-between. You can specify which image frames to read by appending the image filename with the frame range enclosed in brackets. Here our image (an animated GIF) contains more than one frame but we only want the first:
magick 'images.gif[0]' image.png
Linux shells generally interpret brackets so we enclosed the filename in quotes above. In a Windows command shell the brackets are not interpreted but using quotes doesn't hurt. However, in most cases the roles of single-quotes and double-quotes are reversed with respect to Linux and Windows, so Windows users should usually try double-quotes where we display single-quotes, and vice versa.
You can read more than one image from a sequence with a frame range. For example, you can extract the first four frames of an image sequence:
magick 'images.gif[0-3]' images.mng
The default is to step one frame at a time so frames 0, 1, 2, and 3 are returned. Set the step to 2 with -define frames:step=2 and we instead get frames 0 and 2.
Finally, you can read more than one image from a sequence, out-of-order. The next command gets the fourth image in the sequence, followed by the third, and then the fifth:
magick 'images.gif[3,2,4]' images.mng
Notice that in the last two commands, a single image is written. The output in this case, where the image type is MNG, is a multi-frame file because the MNG format supports multiple frames. Had the output format been JPG, which only supports single frames, the output would have consisted of separate frames. More about that below, in the section about the Output Filename.
Raw images are a sequence of color intensities without additional meta information such as width, height, or image signature. With raw image formats, you must specify the image width and height but you can also specify a region of the image to read. In our example, the image is in the raw 8-bit RGB format and is 6000 pixels wide and 4000 pixels high. However, we only want a region of 600 by 400 near the center of the image:
magick -size 6000x4000 -depth 8 'rgb:image[600x400+1900+2900]' image.jpg
You can get the same results with the