A Full-Featured Open-Source Framework for Image Processing

Selections and Other Decorations

You. Yes. You. I do mean You.

By default, commands operate on all images on the image list, aka the stack. Often that is not what we want. What we want, most times, is to operate on select images. In G'MIC the basis for such discriminations are image indices, reflecting images' positions on the stack. As we input or otherwise conjure up images, G'MIC places them on the stack and assigns indices as it goes. These indices start from zero and increment by one. That said, both positive and negative indices can address images:  1.  Non-negative indices designate images from the beginning of the stack. 0, 1, 3 designate the first, second and fourth image.  2.  Negative indices designate images from the end of the stack.  –1, –2, –3 designate the last, penultimate and third from the last image. In a stack having four images, both –1 and 3 designate the last image on the stack; –4 and 0 designate the first image.

Image Selection

G'MIC recognizes decorations on a command's right hand side. Selections, restricting the scope of a command's operation, appear in square brackets immediately to the right of the command, with no separating white space from the command to the opening square bracket and no white space within the selection. Selections contain collections of image indices, either direct references, or — discussed later — indirect references coupling through names. This collection behaves like a set. By this, collections are not sequenced. While we may write indices in some order, such ordering has no significance. Nor does repeating indices have any effect. It is as if the recurring index is listed only once. Thus, in this pipeline fragment operating on an image list with five items:
G'MIC applies noise only to the first image on the stack, then blurs the third and generates diffusion tensors from the last. Note the last selection: it cites the same image twice, so the diffusiontensors command operates only on the last image.

This illustration notwithstanding, selection notation is extensive. Selection syntax has expressions for selecting single or multiple images, ranges of images, every other, every third, or, generally, every n-th image, relative to the beginning or end of the stack, relative to the size of the overall stack, relative to named collections, and all images except the ones designated by a selection. It is easy (and probably inevitable) to select images which don't exist, an error.

Here are the ways to restrict some fictive command called -foo to operate only on selected images:

Type	Template	Description
Everything	-foo	Operates on every image on the stack.
Left Single	-foo[n]	Operates on image n+1, counting from the beginning of the stack. [0] is a common idiom demarking the first image on the stack. Example: -foo[3] operates on the fourth image on the stack.
Right Single	-foo[–n]	Operates on image –n, counting from the end of the stack. [–1] is a common idiom demarking the last image on the stack. Example: -foo[–2] operates on the penultimate image in the stack.
Enumerated	-foo[a,–b,…z]	Comma separated indices. Operates on specific images. Indices may have negative signs and selections can be mixes of positive and negative indices. Example: -foo[0,2,–1] operates on the first, third and last image on the stack.
Range	-foo[a-b]	Hyphenated indices. Operates on images in the range from a to b inclusive. Example: -foo[3-5] operates on the fourth, fifth and sixth images. -foo[–3-–1] operates on the third from the last, next to the last and last images. Note that should a > b -foo[a-b] still works. -foo[5-3] still operates on the fourth, fifth and sixth images.
Relative Range	-foo[a%-b%]	Hyphenated percentages. Operates on image ranges specified through relative positions, with 100% designating the last position on the stack, however large it may be. Example: -foo[50%-100%] operates on images on the upper half of the stack.
Modulo n	-foo[<Range>:n]	Given a range of images, operates on every n-th image in the range. -foo[:n] is an error. Example: -foo[0-–1:3] operates on every third image on the stack. -foo[50%-100%:2] operates on every even-indexed image on the upper half of the stack.
Except	-foo[^<selection>]	Caret preceding a selection. Operates on all images except those in the selection. Example: -foo[^0] operates on all images except the first one. -foo[^0-–1:2] operates on every odd-indexed image on the stack.
Names	-foo[<label>]	Operates on images in the collection designated by the name <label>, an alphanumeric string which begins with a letter. Raises an error if <label> is not a defined collection. Use name[<selection>] <label> to establish an equivalence between <label> and the the collection of images chosen by <selection>. Observe that: (1) <selection> is significant only in enrolling images into collections; that selection has no lasting significance; and (2) an image can be enrolled in at most one collection. Images enrolled in one collection are removed from any others.
Enumerated Names	-foo[<label-1>,…]	Operates on the union of images enrolled in a series of collections. These collections must already be defined.

This pipeline paints only odd-numbered stack items with a kind of magenta, despite what the label Evens propounds; that label Spoke to Truth only in a moment; it fell out of step when -input[0] 1,1,1,3 ran and shifted the hitherto evenly indexed images to the odds.

It is possible to mix selection types, thus -foo[1,3,5-–1], mixing an enumeration and range, selecting the second, fourth, and sixth through the last image.

And, as previously noted, it is also possible that images may be designated more than once in some selection, as in -foo[0-–1:2,2,4,6], which selects all the images with even indices on the stack, then explicity selects the images corresponding to indices 2, 4 and 6.  G'MIC regards the collection of indices in selections as sets of distinct, unenumerated items. Images are not selected twice, nor is there any relevance to their order. -foo[0,1,2], -foo[2,1,0], -foo[2-0], -foo[0,1,0,2,1,2] all select the first three images.

Here are some common examples:

1.	-blur 20	Blur all images on the stack with a standard deviation of 20.
2.	-blur[0] 10	Blur the first image on  the stack with a standard deviation of 10.
3.	-blur[–1] 5	Blur the last image on the stack with a standard deviation of 5.
4.	-blur[0,2,5] 7	Blur the first, third, and sixth image on the stack with a standard deviation of 7.
5.	-blur[^3] 6	Blur all images on the stack except the fourth one with a standard deviation of 6.

Isolated Selections: Implied Copy Command

Selections in isolation, apparently not modifying any command, imply -copy (which, by this explicit name, doesn't actually exist). The images designated by the selector are duplicated and the interpreter places the copies at the end of the stack in the same relative order as their antecedents. Thus [0,3,5] by itself copies the first, fourth and sixth images; the copy of the first image becomes –3, the copy of the fourth becomes –2 and the copy of the sixth becomes –1.

Selections in isolation also support a multiplier postfix, the example already seen but hitherto left unexplained. gmic -input 1,1,1,3 [0]x3 conjures a one pixel image out of the aether and three copies are made of it, leaving four 1×1×3 pixel images on the stack.

Lefthand Decorations: Replace or Append

Commands may be decorated on the lefthand side. Hyphens optionally distinguish commands from other items. Omit them for brevity; include them for clarity. It so happens that the command line interpreter silently strips lefthand hyphens as an early step in command interpretation. Hyphens serve only the Goddess of Readability, but in the cause of diminishing command line confusion they serve her well. Lefthand + decorations, however, have "copy first" semantics and matter for transformative commands: those that take selected images as inputs, transform image content and then produce an output.

1.	Transformative commands without hyphens or with single hyphens will replace the images they select with versions having transformed content.
2.	Transformative commands decorated with + on the lefthand side first copy the images they select, the copies go to the end of the stack in the same relative order as their antecedents. The command then operates on those copies.
3.	Non-transformative commands, such as name or flow control commands — administrative in nature — throw an error when prefixed with lefthand + decorations.

Command Line Anatomy

Consider how this command line builds an image list:

1.	256,256,1,3 conjures up a 256x256x1x3 pixel image with three channels, initially solid black, establishing a stack with one image. The input command is implied.
2.	The noise[–1] command, no hyphen, two parameters, replaces this black image with a sparse, random scattering of red green and blue pixels ("Salt and Pepper Noise"), so the stack remains with one image.
3.	The +bandpass[–1] command, with a + left hand decorator, duplicates the image at the end of the stack and operates on that, leaving a new last image with the low-frequency components of the previous image. There are now two images on the stack.
4.	Similarly, +threshold[–1] copies the last image (+), then applies a bilevel reduction to each channel of what is now the last image. This leaves three images on the stack.
5.	+negate[–1] Again a copy-modify of the last image (+) inverting color-and-values. The stack now has four images.
6.	-thinning[–1] — with a - prefix — morphologically thins the last image, leaving behind the 'morphological spines' of the contiguous, non-black regions of the former version. Observe that the former version is gone, replaced by the thinned version now occupying the end of the stack. Four images remain on the stack. We could have done without the - prefix, but sometimes it helps to be reminded what pipeline items are.
7.	-normalize[^0], also with an optional (redundant) hyphen, replaces all images on the list, except the first one, with corresponding versions where the intensity range of each channel is remapped to the range 0 – 255, see normalize. The image list still has four images. Had we decorated this command with +, the stack would have acquired seven images, the second, third and fourth images followed by their normalized versions in positions five, six and seven.
8.	o is shortcut for -output. Frequently-used G'MIC commands have shortcut spellings; most are one character. With accumulating experience, G'MIC scripters gravitate to shortcuts. But shortcuts perplex beginners. Through most tutorials, we will avoid shortcuts. With this shortcut, we save the entire stack vian output command to the file mystack.cimg, where files of type .cimg are of the native G'MIC format. Just prior to this output, however, the four images on the stack look like this:

For practical purposes, mystack.cimg is the stack on ice. We may restore it minutes/days/months/years later and perform further operations on it:

Shorthand Selection Notation

It is very common to operate on the last, penultimate, and third-from-last images on the stack. Righthand command decorations such as [–1], [–2] and [–3] are so prevalent that they have an alternate shorthand form: one, two and three pips:


G'MIC supports this shorthand notation as a command decoration, as an implied copy or as an argument to another command. It does not work inside selection expressions. The fictive command -foo[0,...] will not operate on the first and third-from-last image.

---

Updated:  07 May 2023 19:15 UTC Commit: 79f1223f76abc9d217cab05bf38ca89560b76ee6