-input

-Input is the least written, most frequently used command in the G'MIC scripting language. It places images from some source onto the image list, on its end unless it has an selection decorator, and creating the list if necessary.

The input command has the following form:

gmic -input[<destination selection>] <external resource> |
<list selector> |
<image specification> |
<image streams>

-Input has an implied (invisible) form. If the G'MIC command parser cannot associate an item with a command (something beginning with a hyphen) or a parameter (something following a command) then it infers that the -input command precedes the item. It then classifies the item as a parameter for the -input command. Finally, the parser passes the (presumed) image to -input for processing.

To make best use of the -input command, one should become familar with the four variations that the input argument can take and how the command interprets its right hand selector decoration. Very broadly, the input argument, in one of four forms, specifies the source images. The right hand selecton decorator, if present, specifies their destination. The -input command must have a source specification. The destination is optional and if omitted implies an insertion point to the right of the last poisition on the list.

Source Specifications

Section 1.4 of The Handbook furnishes a terse, but complete list of methods which the -input command employs to sort out images from the true riff-raff. There are four broad approaches, each with numerous variants.

External Resources

-Input thinks the item is a resource locator. The item either identifies a file on the local machine, with, possibly, a path preceding the filename, the entire construct written according to the operating system's rules for identifying files, or it is an Uniform Resource Locator (URL) identifying an image somewhere on the Internet. In this case, -input will initiate an HTTP request to retrieve the image via the Hypertext Transfer Protocol.

Here are a few command lines which fetch external resources:

1. gmic gmicky.png (the resource is a file in the current working directory)

2. gmic /media/berthawork/webcontent/gmic/input/hollerith.png (Similar, but the resource has a full path written for a UNIX-like file system)

3. gmic http://upload.wikimedia.org/wikipedia/commons/d/df/Lullwater_south_from_Binnen-Bridge_Prospect_Park.jpg (The resource is at Wikimedia Commons, a FOSS media repository)

There are a few resource locators for special circumstances.

4. A single hyphen - indicates piped content from another process, a standard UNIX convention. To this convention, G'MIC permits a hyphen-dot-file extension construct. For example, -.png induces G'MIC to treat the piped input as a Portable Network Graphics file stream.

5. A prefix consisting of a standard file extension followed by a colon induces G'MIC to read the file according to the type dictated by the prefix, regardless of the file extension. In this case, the file may not even have an extension. For example, jpg:gmicky.png will be processed as a Joint Photographers Group file, not as a Portable Network Graphics file.

Image List Selections

-Input regards items withn square brackets as image selectors referencing positions of other items on the image list. This form begins with a right-pointing square bracket ([) and finishes with a left-pointing square bracket (]), which together encompass a selection specification (selectors). Depending on how they are written, selectors may reference the list positions of individual, enumerated, ranged, modulo subsets, sets of other than the cited (exception), or named images. Section 1.5 of The Handbook lists the complete selection syntax, as does “Command Decoration – Image Selection” on this site.

In the G'MIC scripting language this form implements image copying, as the language does not have an explicit -copy command. Appending a literal 'x' character followed by a numeral n after the closing square bracket of a selector will replicate the images referenced by the selector n times. Take heed that the selector itself may already reference many images! It is easy to make vast image lists with this form. Examples include:

1. gmic foo.png [0] ([0] copies the first image, foo.png, in the image list. The copy becomes the second and last image in the list.)

2. gmic ... [-2,-1] ... (copies the penultimate and last images in the image list. The copies are also placed on the end in of the list in the same order as the originals)

3. gmic ... [charley] ... (copies all the images referenced by the selection named “charley”. See the -name command)

4. gmic ... [^0]x2 ... (makes duplicates of all the images in the list, except the first, placing the copies at the end of the list, these in the same order as the originals on the list – this may involve a lot of images!)

Image Specification

The command line item is an image specification, a set of up to five parameters, separated by commas that collectively specify a new image and, possibly, its content (see Images). The five parameters list the new image's width, height, depth (number of slices), spectrum (number of channels) and either a list of intensities or a mathematical expression, specifying content. This -input command format underlies the method of conjuring images from the aether. These specifications take the form:

1. {width[%] ≥ 0 | [<selection>]},…

2. {height[%] > 0 | [<selection>]},…

3. {depth[%] > 0 | [<selection>]},…

4. {spectrum[%] > 0 | [<selection>]},…

5. {value_0, value_1, …, value_n | <procedural formula>}

The first parameter (a) specifies the width of the new image and is mandatory. Items (b…e) following are optional parameters and when omitted default to one pixel. The width parameter has a special form. The numeral zero (0), with no further parameters, creates an empty image. It is not a black image, but an image literally without data. In real life, there is almost no need for an image sans width, height, depth, and channels, but empty images accommodate a few obscure scripting needs.

Apart from the special width case, the first four parameters (a…d) may be similarly written.

1. The first way (i) is a specific number that explicitly states the dimension as a particular number of pixels. Apart from the special case of width = 0, this must be a positive number.

2. The second way (ii) is a relative dimension based on those of the preceding image on the list. '100%' indicates that the dimension is the same as the preceding image on the list. N% for N  ∈ {1.0 … 99.9̅} specifies that the dimension is a fractional percentage of the preceding image on the list. One may write a percentage with any degree of precision, but the value is rounded to the nearest whole pixel in any case. The relative form cannot be employed for the first image on the list, as there is no antecedent to furnish a basis for percentages.

3. The third way (iii) specifies that the dimension is the same as some other image on the list, referenced by a single image selector, to wit: a numeral in square brackets. It is an error to reference an image that does not exist, so this notation does not work for the first image in the list as there are no antecedents to reference.

4. Height, depth, and spectrum are optional parameters and default to one pixel unless width itself is zero. In that form, height, depth and spectrum are meaningless and specifying them raises an error.

5. The fifth parameter (e) is also optional and specifies image content. Without this parameter, images come into being with all channels set to zero. The image is black and transparent when an opacity channel is in the spectrum. Otherwise, when the fifth parameter is present, image content may take one of two forms:

   • it may be a literal image specification. Such is made from list of comma-separated intensities. The length of this list of must be exactly equal to the product of width × height × depth × spectral size or an error occurs. Data populate images first by column, then by row, then by spectrum and finally by depth.
   • it may be a procedural formula, written according to the syntax rules given in Section 1.8 of The Handbook for G'MIC mathematical expressions.

Here are a few image specifications:

1. gmic ... 512,256,1,3 ... (creates a 512 pixel by 256 pixel image that is one slice in depth and has a spectrum of three channels)
2. gmic ... 100%,100% ... (creates an image with the same width and height as the preceding image on the list. Since depth, spectral, and image content have not been specified, these default to a depth of one slice, a spectrum with one channel and channel content set to zero)
3. gmic ... 0 ... (an empty image, which is not black, white, transparent or anything at all, but an image without data store.)
4. gmic ... 345,37.5%,[-2],[-1],x ... (an image with a width of 345 pixels, a height that is 37.5% of the preceding image — which must exist — a depth that is the same as the penultimate image on the list — which must exist — a spectrum equal to the number of channels of the last image on the list — which generally exists unless the image list itself is empty — and with pixel intensities set by the mathematical expression 'x', a construct which assigns the column number of the image which a pixel occupies to the pixel's intensity. For an RGB color space, the image looks like a black to white horizontal ramp).
5. gmic ... 256,2,1,1,u ... (a rather long, stout image. In G'MIC, images are not exclusively harnessed to depict pictures but can also provide general purpose data storage. In this example, the image has been procedurally initialized with the mathematical expression 'u', a construct which sets pixel intensities with randomly distributed values taken from the semi-closed interval [0,…1). Among other things, we can provide such an 'image' to -pointcloud, which can create another image and seed it with white pixel dust
   
     gmic -input 256,2,1,1,u -*[-1] 1024 -round[-1] 1 -pointcloud 0,1024,1024 -normalize 0,255 -output[-1] stars.png
   
   In this example, the rather long, stout, randomly initialized 'image' was used by -pointcloud as a source of coordinates. This particular example could be implemented faster with a -noise variant, but had we wanted to tailor the distribution in a not quite random way, -pointcloud, coupled with our peculiar set of coordinates, would have been the way to go.)

Image Streams

The command line item is a formatted data stream. Almost always, this variation is not how humans specify images, except, perhaps for tiny data sets. Suppose you code an image generator in some other computer language, and it starts a G'MIC interpretor in a child process. Your image generator could output the entire command line for the child process, starting with 'gmic' and including an image stream as a command line parameter. Your script does not have to know a great deal about how G'MIC works. It only needs to be able to write images streams by these rules:

1. Since an image stream is, above all, a command line item, it cannot embed whitespace anywhere.
2. The stream starts with an open parenthesis, (, and finishes with a closed parenthesis.) '()' is disallowed. Something must appear between the parentheses.
3. Between parentheses, the stream consists of at least an initial floating point numeral.
4. This initial floating point numeral necessarily occupies column x=0, row y=0, slice z=0 and channel c=0.
5. If the next character is the closing parenthesis, then a complete, though very small, image has been fully specified. It has one column, row, slice and channel and consists of one pixel. That pixel's intensity is equal to the floating point numeral.
6. If the image is to be larger than this, then the next item will be one of four delimiters, each structuring the overall shape of the image in particular ways. These delimiters are: (i) Commas (,) which separate and link runs of pixels into columns, (ii) semicolons (;), which separate and link runs of columns into rows. (iii) carets (^) which separate and link blocks of columns and rows into channels, and (iv) slashes (/) which separate blocks of columns and rows stacked as channels into slices.
7. Once the interpreter receives the closing parenthesis, it can infer the image's dimensions:
   • The column count comes from the longest contiguous run of commas, plus one. If there are no commas anywhere in the stream, the image has one column.
   • The row count comes from the longest run of semicolons unbroken by carets or slashes, plus one. If there are no semicolons anywhere in the stream, the image has only one row.
   • The channel count comes from the longest run of carets unbroken by slashes, plus one. If there are no carets anywhere in the stream, the image has only single channel spectra.
   • The slice count comes from the total number of slashes in a stream, plus one. If there are no slashes anywhere in the stream, the image has only one slice.
8. This scheme allows one to specify only as much of an image as needed. Omitted entries default to pixels with zero value. That is, columns, rows, or channels with insufficient elements are padded as needed with zero so that all runs of a particular delimiter class equals the largest one observed in the stream.

Here are some examples:

A white cross on a black field

gmic '(0,0,0,255;0,0,0,255;0,0,0,255;255,255,255,255,255,255,255;0,0,0,255;0,0,0,255;0,0,0,255)'

St. George's Cross

gmic '(\
255,255,255,255,255,255,255,255,255,255,255,206,206,206,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,206,206,206,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,206,206,206,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,206,206,206,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,206,206,206,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,206,206,206,255,255,255,255,255,255,255,255,255,255,255;
206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206;
206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206;
206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206,206;
255,255,255,255,255,255,255,255,255,255,255,206,206,206,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,206,206,206,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,206,206,206,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,206,206,206,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,206,206,206,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,206,206,206,255,255,255,255,255,255,255,255,255,255,255^
255,255,255,255,255,255,255,255,255,255,255,17,17,17,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,17,17,17,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,17,17,17,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,17,17,17,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,17,17,17,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,17,17,17,255,255,255,255,255,255,255,255,255,255,255;
17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17;
17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17;
17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17;
255,255,255,255,255,255,255,255,255,255,255,17,17,17,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,17,17,17,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,17,17,17,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,17,17,17,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,17,17,17,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,17,17,17,255,255,255,255,255,255,255,255,255,255,255^
255,255,255,255,255,255,255,255,255,255,255,36,36,36,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,36,36,36,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,36,36,36,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,36,36,36,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,36,36,36,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,36,36,36,255,255,255,255,255,255,255,255,255,255,255;
36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36;
36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36;
36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36,36;
255,255,255,255,255,255,255,255,255,255,255,36,36,36,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,36,36,36,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,36,36,36,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,36,36,36,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,36,36,36,255,255,255,255,255,255,255,255,255,255,255;
255,255,255,255,255,255,255,255,255,255,255,36,36,36,255,255,255,255,255,255,255,255,255,255,255
)'

Input Decorators

As with nearly every G'MIC command, the -input command may be decorated on the right hand side with a selector, informally designating the image positions upon whose occupants the command operates; its omission signals that the command operates on every image on the list.

We don't usually worry too much over the very fine distinction that the numerals (or the names) within selectors directly reference image positions, and only by indirection, the images themselves. So while '[X]' typically induces us to think "The image X", strictly speaking we should think "The image at position X."

The slight mental elision rarely gets us into trouble, but with the particular interpretation that the -input command places on its right hand decorator, we should pinch ourselves (hard) and remember that essentially, selectors contain positional notations first, which reference images second.

Considering ourselves pinched, we proceed to the particular case which covers about 99 44/100% of the uses to which the -input command is put.

Almost always, the -input command has no right hand decoration whatsoever. Its absence tells -input to insert the images identified in its argument — the copy set — at the end of the list. Almost always, that's exactly what we want. Observe that if the -input command is implied (i.e., $gmic iaminput.jpg…), then it has no right hand decoration. 

Suppose, however, that we want -input to insert the copy set at some point other than the end.

In that case, we have to write the -input command explicitly, and we have to write a right hand decoration for it.

The right hand decoration is a selector of image list positions that mark where -input is to insert copy sets.

If the right hand decoration selector itemizes more than one position, then the input command will duplicate the copy set at each position.

The sign of the position matters.

1. If a position has no sign, it is taken to be counted from the beginning of the list and the -input command inserts the copy set at a point to the left (i.e. before) the indicated position.  
2. If a position has a negative sign, it is taken to be counted from the end of the list and the -input command inserts the copy set at a point to the right (i.e., after) the indicated position.

Some examples might help. Suppose images of the letters 'A', 'B', 'C', 'D', and 'E' are on an image list, these initially occupying positions 0, 1, 2, 3 and 4. The symbol <copy set> represents a (temporary) list that contains images which the -input command discovered when parsing its argument. The <copy set> could contain more than one image and may even contain items from the image list proper, as a selection is one of the types of input arguments. 

Right hand selection decorators on the -input command can be tricky to understand, particularly when the argument given to -input itself contains selectors; the command is then copying various elements of the list to itself. As tricky as that may seem, it is a highly efficient duplication scheme, in that the copying runs in compiled C++ code, and can replace many kinds of naive -repeat … -done copying loops.

The following G'MIC snippet:

gmic -repeat 5 100,100,1,1 -text[-1] '{$>}',50,50,30,1,255 -done -output numlst.cimg

writes out an image list to disk consisting of five 100x100x1x1 gray scale images of numerals '0' through '4', initially occupying those same positions on the image list. It may be used to examine the effects of different kinds of insertions. Indeed:

gmic -input numlst.cimg -input[0--1] [0--1]

generates this 35 element image list:

0 1 2 3 4 0 0 1 2 3 4 1 0 1 2 3 4 2 0 1 2 3 4 3 0 1 2 3 4 4 0 1 2 3 4

Readers who understand why this list has 35 elements and why they fall in this particular order have truly grasped the essence of the -input command in all of its varigated manifestations.

Top image: A Hollerith Tabulating Machine of the kind used in the 1890 United States Census. Example at Computer History Museum, Mountain View, CA, United States of America. Image by Jennifer, Wikimedia Commons

Garry Osgood