Confusion regarding percent escape handling

Questions and postings pertaining to the usage of ImageMagick regardless of the interface. This includes the command-line utilities, as well as the C and C++ APIs. Usage questions are like "How do I use ImageMagick to create drop shadows?".
Post Reply
kpmartin
Posts: 2
Joined: 2020-02-16T09:51:09-07:00
Authentication code: 1152

Confusion regarding percent escape handling

Post by kpmartin »

In the help for Percent Escape Handling, there are several lists of predefined escapes, such as %[t] (aka %t or %[basename]) which refers to the input filename without its suffix or directory (folder), and %d which refers to the directory part of the input filename.

On the other hand, there is the ability to put %d or something like %5d in an output filename, which just inserts sequential numbers for multiple output files (assuming the output format isn't just able to pack several images into the same file).

In an output filename you can also refer to %[xxx] to refer to something set using -set, but you can't e.g. use %[t] or %t directly to refer to the input filename (instead you just get a literal %[t] in the output filename). Instead examples suggest you must do something like

Code: Select all

convert infile*.jpg -set filename: %[t] (tranformations) output%[filename:].jpg
which seems rather clumsy, and also leaves me wondering if my output file now contains an unwanted stored property called filename:
It also isn't clear from the examples if there is something magical about the name 'filename' or the presence of the colon.

These two uses seem to be separate but somehow related and I can't find any clear explanation. The only mention of using %d to get sequentially-numbered output files is in the Output Filename section of the main Command Line page at https://imagemagick.org/script/command- ... php#output and there does not seem to be any link from this tutorial/example styled page to a formal description of this feature.

The page (https://imagemagick.org/script/escape.php) describing the Percent Escape Sequences states "You can utilize percent escapes in a number of options, for example..." which sounds like there is a specific but nowhere near universal set of contexts where they can be used but I could not find any definitive list of such contexts. If they can actually be used in any non-keyword part of a command line (except, clearly, output filenames), this wording is confusing.

So I guess I'm seeking some clarification on what things with percent-escape-like syntax can be used in output filenames, and what do they mean? Can %x be used to get sequential numbers in hexadecimal? Why can %[blart] in an output filename refer to a -set value but not to %[t] %t or %[basename]? A better and more complete description (rather than just a couple of examples) of contexts where Percent Escape Sequences can be used would also be useful.

More pawing through the help found, under the documentation for "-set", the statement
Some 'properties' must be defined in a specific way to be used. For example only 'properties' prefixed with "filename:" can be used to modify the output filename of an image
. So, yes, there is something magical about the word 'filename'. Again, that "some xxx do something, for example yyy" with no reference to a definitive list of the special cases. Well, gosh, it would be really nice if this were stated somewhere a little more obvious, like on the Percent Escape Handling page, or where output filenames and their peculiar use of %d are described...

And although "filename" is an artifact (as shown using Identify -verbose) containing the filename, trying to refer to it in the output file without using -set first clearly doesn't expand anything either; I ended up with a single output file called "blart%[filename" which contained 6 windows file system streams called "]-0.jpg" "]-1,jpg" and so on. Now that's confusing (even though I'm well aware of windows file streams).

snibgo
Posts: 12897
Joined: 2010-01-23T23:01:33-07:00
Authentication code: 1151
Location: England, UK

Re: Confusion regarding percent escape handling

Post by snibgo »

What version of IM? If v7, I suggest you use "magick", not "convert". "convert" is v6 syntax, which is more restrictive.

As far as I know, the only escapes that IM will interpret in output filenames are:

1: %d, %04d, %o, %04o, %x, %04x etc: a sequential number, base 10 or 8 or 16, optionally with leading zeros.

2: %[filename:abcd] where abcd is any sequence of characters (including no characters). This needs a property "filename:abcd" to have been defined. Although it can be used with no suffix, I think that's a bad idea.

The characters "filename:" are all needed, but can be any case, eg "FileNamE:" will work.

You can "-set" properties with any names you want, but the only ones you can use in output filenames must start with "filename:".
kpmartin wrote:...and there does not seem to be any link from this tutorial/example styled page to a formal description of this feature.
The formal description is the C code. For example, image.c InterpretImageFilename() for output filenames. Yeah, I know that's not the answer you (or I) would like.
kpmartin wrote: ... "You can utilize percent escapes in a number of options, for example..." which sounds like there is a specific but nowhere near universal set of contexts where they can be used but I could not find any definitive list of such contexts.
The set of contexts is much wider in v7 than in v6. For example, in v7, most options that need a number (eg "-crop") can accept "%[fx:...]" instead of the number. No, there is no definitive list (except embedded in the C code). One annoying restriction is that "%[fx:...]" can't contain user-defined properties.
snibgo's IM pages: im.snibgo.com

User avatar
fmw42
Posts: 26261
Joined: 2007-07-02T17:14:51-07:00
Authentication code: 1152
Location: Sunnyvale, California, USA

Re: Confusion regarding percent escape handling

Post by fmw42 »

fx:[...] are listed at https://imagemagick.org/script/fx.php

other percent escapes are listed at https://imagemagick.org/script/escape.php

Post Reply