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

by

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.

More Related Contents:

  1. @ARGV is empty using ActivePerl in Windows 7
  2. Data consolidation using Perl [closed]
  3. How can i do this in perl, shortcut truthtable [closed]
  4. How to retrieve the values of required keys in Perl [closed]
  5. Perl: Meaning of double squared brackets after a string?
  6. What does this HTML::Parser() code do in Perl? [closed]
  7. Why use strict and warnings?
  8. Why does modern Perl avoid UTF-8 by default?
  9. Why is three-argument open calls with autovivified filehandles a Perl best practice?
  10. What’s the difference between Perl’s backticks, system, and exec?
  11. How can I parse dates and convert time zones in Perl?
  12. Which one is good practice, a lexical filehandle or a typeglob?
  13. convert:not authorized `aaaa` @ error/constitute.c/ReadImage/453
  14. How do I tell if a variable has a numeric value in Perl?
  15. Perl memory usage profiling and leak detection?
  16. How should I use the “my” keyword in Perl?
  17. Global symbol requires explicit package name
  18. How do I include functions from another file in my Perl script?
  19. How can I start an interactive console for Perl?
  20. What does =~ do in Perl? [closed]
  21. How to convert letters with accents, umlauts, etc to their ASCII counterparts in Perl?
  22. Do you use an exception class in your Perl programs? Why or why not?
  23. How do I tell what type of value is in a Perl variable?
  24. What should I use for a Perl script’s shebang line?
  25. How can I find memory leaks in long-running Perl program?
  26. Why do Perl variables need to start with $, %,@ (sigils)?
  27. Print lines from one file that are not contained in another file
  28. Perl DBD::Oracle Module installation
  29. Explain the deviousness of the Perl “preamble”
  30. Why doesn’t Perl’s each() iterate through the entire hash the second time?

Leave a Comment