Command Decorations

By default, commands operate on all images in the stack. Often that is not what we want.

The image list can, and often will, contain many items. As we -input or otherwise conjure images, the interpreter places them in sequence, assigning indices to them starting from zero as it goes along.

Non-negative indices designate images with respect to the beginning of the stack. That is, 0, 1, 3 designate the first, second and fourth image.

Negative indices designate images with respect to the end of the stack, i. e., -1, -2, -3 designate the last, penultimate and third from the last image. In a stack of four images, both -1 and 3 designate the same image, the last one in the stack. -4 and 0 designate the first image.

Image Selection

G'MIC allows us to decorate commands on their right hand sides with selections that restrict the scope of a command to a subset of items in the image list. Square brackets immediately to the right of the command, with no separating white space, may contain collections of image selecting indices. Thus, the pipeline:

-noise[0] 0.5,2 -blur[2] 10 -diffusiontensors[-1] 0,1,0.7,2.3

applies noise only to just the first image on the stack, then blurs just the third and generates diffusion tensors from the last.

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, through named collections, and all images except the ones designated by a selection. It is easy (and probably inevitable) to select images which are not on the stack, an error.

Here are the ways to restrict to selected images the action of some fictive command called '-foo':

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

It is also possible that images may be designated more than once, 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, unordered elements, so images are not selected twice, nor is there any relevance to the order of indices. -foo[0,1,2], -foo[2,1,0], -foo[2-0], -foo[0,1,0,2,1,2] all select the first three images on the stack. 

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'. The images designated by the selector are duplicated and the interpreter places the copies at the end of the pipeline, 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. The implicit presence of the -input command

Lefthand Decorations: Replace or Append

Items may be decorated on the lefthand side, which we have already seen: hyphens distinguish commands from other items. Apart from identifying commands, hyphens also have a copy/replace meaning.This matters with transformation commands, those that take selected images as inputs and then produce output images. Commands may be decorated on the left hand side with one or two hyphens, expressing replace or preserve semantics.

1. single hyphen commands will replace the selected images with the output images.
2. double hyphen commands will preserve the selected images, placing the output at the end of the pipeline.

Non-transformative commands are those which implement aspects of G'MIC program flow or management of the environment. We have seen one example already. '-name' labels a selection but does not otherwise operate on the images in the selection's collection. Thus:

$ gmic 256,256,1,3 -noise[-1] 0.05,2 --bandpass[-1] 0.0005,0.001 --threshold[-1] 30% --thinning[-1] -normalize[^0] 0,255

1. 256,256,1,3 conjures up a 256x256x1 pixel image with three channels, initially solid black establishing a stack with one image.
2. The '-noise[-1]' command, single hyphen, replaces this black image with a sparse, random scattering of red green and blue pixels, so the stack remains with one image.
3. The '- -bandpass[-1]' command, double hyphen, appends a new image at the end of the stack, the low-frequency components of the previous last image, leaving two images on the stack.
4. Similarly, '- -threshold[-1]' appends a new image at the end of the pipeline, with each channel a bilevel reduction of the channels of the previous last image on the stack. This leaves three images on the stack.
5. '- -thinning[-1] creates a morphologically thinned version of the last image, the 'spines' of contiguous, non-black regions residing in the various channels of the last image, appending the thinned version to the end of the stack. Four images are on the stack.
6. '-normalize[^0], single hyphen, replaces all images in the stack except the first with corresponding versions where the intensity range of each channel is remapped to the range 0 – 255. The stack still has four images. Had we decorated this command with two hyphens, the stack would have had seven images, the second, third and fourth images followed by their normalized versions in positions five, six and seven.

The four images on the stack look like this:

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 only as a command decoration, not in any other place where a selection might be used, as an implied copy or as an argument to another command. Nor do pips work in selection expressions. The fictive command -foo[0,...] will not operate on the first and third-from-last image.

Common Idiomata

It is not uncommon to see these repeating idiomata: