A Full-Featured Open-Source Framework for Image Processing

input (i)

A Hollerith Tabulating Machine, 1890 United States Census. Computer History Museum, Mountain View, CA, United States of America. Jennifer, Wikimedia Commons

input is the least written, most frequently used command in the G'MIC scripting language. It places images from various kinds of sources adjacent to one or more images on the list, creating the list if necessary and duplicating incoming imagery as necessary. The command's image selection decorator enumerates images next to which incoming images are placed. With positive selectors, incoming images go before enumerated images. Negative selectors place incoming images after enumerated images. input copies images as necessary to fill all placements. Without a selection decorator, [-1] is implied; incoming images go to the end of the image list, to the right of the last image.

It is unique among G'MIC commands in that input has an implied (invisible) shortcut. If the G'MIC command parser cannot associate an item with a command or a parameter then it infers that the input command precedes the item, classifying the item itself as a parameter to the input command. The parser then passes the (presumed) image to this command for processing.

The input argument specifies image sources. When present, the right hand selecton decorator specifies their destinations. The input command must have a source specification. The destination is optional and if omitted implies a [-1] decoration, an insertion point to the right of the last image on the list. See Selections in File and File-like Sources.

Source Specifications

Input Data Items furnishes a terse, but complete list of methods which input employs to sort out images from other command line items.

1. File and File-like Sources	2. Image Dimensions
3. Selectors	4. Prescribed Values
5. Strings	6. Stored Images
7. Empty Images

1.

File and File-like Sources: input always works with local file system sources. It can also work with hypertext resource locators so long as the underlying operating system offers wget- or curl- like capabilities. The item either identifies a local file, with, possibly, a path preceding the filename, the entire construct written according to the operating system's rules for identifying files, or – with wget or curl present – a 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. Selections: As with other commands, input may take a right hand selection decorator, but in this case, the selector indicates images next to which incoming imagery may be inserted, creating as many copies as necessary. Positive selectors position new imagery to the left of indicated images; negative selectors position new imagery to the right of indicated images. Unlike other commands, which default without selection decorators, input has a default of [-1]. Without an explicit decorator, input places new imagery to the right of the last image on the list. Image Type Overrides: One may override file extensions, which imply certain image types, with explicit left hand type declarations.

2.

Image Dimensions, With and Without Math Expressions: 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 through a mathematical expression. Absolute Sizing: The first four parameters are literal numerals that set the new image's width, height, depth (number of slices), and spectrum (number of channels). Except for the first, the second through fourth parameters are optional and may be omitted; omitted dimensions default to one pixel. The fifth parameter is also optional and may express a Mathematical Expression which computes content on the fly. Relative Sizing: Percentages may be employed to cite dimensions relative to the preceding image on the list. If there is no preceding image on the list, dimensions default to one.

3.

Selectors: A selector decorator, occuring in isolation in the pipeline, functions as an implicit copy command. The selection decorator picks the items on the image list to be copied. Multipliers on isolated decorators: Multiplier notation x<_N_> for a positive integer N places N copies of the items indicated by the selector decorator at the end of the image list. Dimensions from Decorators: Selectors may also be used to specify particular dimensions taken from other images. In the latter case, copying of image content does not take place, just image dimensions. Use commas between decorators.

4.

Prescribed Values: 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 useful for expanding into colormaps. Suppose you write an image generator 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 one pixel, then the next item will be one of four delimiters, each structuring the overall shape of the image in particular ways. These delimiters are:
a.	Commas (,) which separate and link runs of pixels into columns,
b.	semicolons (;), which separate and link runs of columns into rows,
c.	carets (^) which separate and link blocks of columns and rows into channels, and
d.	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:
a.	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.
b.	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.
c.	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 a single channel.
d.	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.

5.

Strings: The command line item is a single-quoted string within parentheses. Optionally, the single-quoted string may be followed by a colon and a single-character delimiter code. Also optionally, multiplier notation x<_N_> for a positive integer N may follow the parentheses, placing N consecutive copies of the image in the list. Thus: (string[:delimiter])[xN]: Insert one or N new images from specified string, by filling the images with the character codes composing the string. Delimiters: When specified, delimiter tells about the main orientation of the image. Delimiter can be x (eq. to , which is the default), y (eq. to ;), z (eq. to /) or c (eq. to ^).

6.	Stored Images: The command line item is an image previously committed to off-list storage via the -store command.

7.	Empty Images: The command line item is an image without any rows, columns, channels or slices. Not a black image; more like a "void" image. Such an image could be a while loop sentry at the end of a list of otherwise "real" images.

         [gmic]-0./ Start G'MIC interpreter.                          
         [gmic]-0./ Input empty image at position 0 (1 image 0x0x0x0).
         [gmic]-1./ Print image [0] = '[empty]'.                      
         [0] = '[empty]':                                             
           size = (0,0,0,0) [0 b of floats].                          
           data = () [float].                                         
         [gmic]-1./ End G'MIC interpreter.                            

         [gmic]-0./ Start G'MIC interpreter.                               
         [gmic]-0./ Input empty image at position 0 (1 image 0x0x0x0).     
         [gmic]-1./ Expand image [0] along the xy-axes with size 16        
                    and neumann boundary conditions.                       
         [gmic]-1./ Print image [0] = '[empty]'.                           
         [0] = '[empty]':                                                  
           size = (32,32,1,1) [4096 b of floats].                          
           data = (0,0,0,0,0,0,0,0,0,0,0,0,(...),0,0,0,0,0,0,0,0,0,0,0,0). 
           min = 0, max = 0, mean = 0, std = 0, coords_min = (0,0,0,0),    
           coords_max = (0,0,0,0).                                         
         [gmic]-1./ End G'MIC interpreter.                                 

Return Status

With G'MIC 2.98, -input returns the bit depth of Portable Network Graphics (.png) or Tagged Image File Format (.tif) files. G'MIC's -input command returns the bit depth as status, available through the command status substitution sequence: ${}
The return of such status permits a custom command to preserve the bit depth of .png or .tif files entering the image list and format output images with a matching bitmap depth, if so desired.

Command reference

Updated: 22-August-2021 22:10 UTC Commit: 838dc220be85