ImageMagick Command-Line Option Order (and Categories of Command-Line Parameters)

Question

My supervisor has asked me to convert the parts of our Perl scripts that use PerlMagick to instead pipe and use the command line version of ImageMagick (for various unrelated reasons).

Using the our existing interface (crop, scale, save, etc) I'm building up a list of operations the user wants to perform on an image, constructing the statement to pipe and then executing it.

What I would like to know is:

1. Are convert operations performed from left to right? ie the order I pass them
2. What happens if I pass the same option twice? Are they performed separately?

Obviously the order in which operations are performed on an image is vital, so I'm trying to work out if I can perform all of the operations in one go (possibly gaining efficiency?) or if it I'm going to have to perform each operation separately. Thanks

Answer 1

Unfortunately, the accepted answer to this question is not yet complete... :-)

Three (major) classes of parameters

Assuming, your ImageMagick version is a recent one, here is an important amendment to it:

• you should differentiate between 3 major classes of command line parameters:

  1. Image Settings
  2. Image Operators
  3. Image Sequence Operators
      

These three classes do behave differently:

1. Image Settings

   1. An image setting persists as it appears on the command line. It may affect all subsequent processing (but not previous processing):

      • processing such as reading an image or more images later in the command line;
      • processing done by a following image operator;
      • processing conducted by writing an image as output.
         

   2. An image setting stays in effect...

      • ...either until it is reset or replaced by a different setting of the same type,
      • ...or until the command line terminates.
         

2. Image Operators

   1. An image operator is applied to a (single) image and forgotten. It differs from an image setting because it affects the image immediately as it appears on the command line. (Remember: an image setting which persists until the command line terminates, or until it is reset.)

   2. If you need to apply the same image operator to a second image in the same commandline, you have to repeat that exact operator on the commandline.

   3. Strictly speaking, in compliance with the new architecture of ImageMagick command lines, all image operators should be written after the loading of the image it is meant for. However, the IM developers compromised: in the interest of backward compatibility, image operators can still appear before loading an image -- they will then be applied to the first image that is available to them.

3. Image Sequence Operators

   1. An image sequence operator is applied to all currently loaded images (and then forgotten).

   2. It differs from a simple image operator in that it does not only affect a single image. (Some operators only make sense if their operation has multiple images for consumption: think of -append, -combine, -composite, -morph...)

From above principles you can already conclude: the order of the command line parameters is significant in most cases. (If you know what they do, you also know which order you need to use applying them.)

(For completeness' sake I should add: there is another class of miscellanious, or other parameters, which do not fall into any of the above listed categories. Think -debug, -verbose or -version.)

Unfortunately, the clear distinction between the 3 classes of IM command line paramaters is not yet common knowledge among (otherwise quite savvy) IM users. So it merits to get much more exposure.

This clear differentiation was introduced with ImageMagick major version 6. Before, it was more confusing: some settings' semantics changed with context and also with the order they were given. Results from complex commands were not always predictable and sometimes surprising and illogical. (Now they may be surprising too sometimes, but when you closely look at them, understanding the above, they are always quite logical.)

Which is which ?!?

Whenever you are not sure, which class one particular parameter belongs to, run

 convert -help | less

Search for your parameter. Once found, scroll back: you should then find the "heading" under which it appears. Now you can be sure which type it is: an Image Setting, an Image Operator, or an Image Sequence Operator -- and take into account what I've said about them above.

Some more advice

If your job is to port your ImageMagick interface from PerlMagick to CLI, you should be aware of one other trick: You can insert

 +write output-destination

anywhere on the command line (even multiple times). This will then write out the currently loaded image (or the currently loaded image sequence) in its currently processed state to the given output destination. (Think of it as something similar as the tee-command for shell/terminal usage, which re-directs a copy of <stdout> into a file.) Output destination can be a file, or show: or whatever else is valid for IM outputs. After writing to the output, processing of the complete command will continue.

Of course, it only makes sense to insert +write after the first (or any other) image operator -- otherwise the current image list will not have changed.

Should there by multiple output images (because the current image list consists of more than one image), then ImageMagick will automatically assign index numbers to the respective filename.

This is a great help with debugging (or optimizing, streamlining, simplifying...) complex command setups.

Answer 2

Are convert operations performed from left to right? ie the order I pass them

Yes. If I take the following two examples, which are identical except for the operations order, I can expect different results based on the left to right.

convert rose: -sample 300% -wave 5x10 rose_post_wave.png
convert rose: -wave 5x10 -sample 300% rose_pre_wave.png

You can see the effects of the wave operation impact the image after, or before the sampling of the image.

What happens if I pass the same option twice? Are they performed separately?

The will be executed twice. No special locking, or automatic operation counting exists.

convert rose: -blur 0.5x0.5 -scale 300% rose_blur1.png
convert rose: -blur 0.5x0.5 -blur 0.5x0.5 -scale 300% rose_blur2.png