G'MIC - GREYC's Magic for Image Computing: A Full-Featured Open-Source Framework for Image Processing
GREYC CNRS ENSICAEN UNICAEN

A Full-Featured Open-Source Framework for Image Processing



Latest stable version: 3.1.6        Current pre-release: 3.2.0

Tutorial

input (i)

hollerith A Hollerith Tabulating Machine, 1890 United States Census. Computer History Museum, Mountain View, CA, United States of America. Jennifer, Wikimedia Commonsinput 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 Sources2. Image Dimensions
3. Selectors4. Prescribed Values
5. Strings6. 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.   

images/Lullwater_south_from_Binnen-Bridge_Prospect_Park.jpg r2dx. 800
The Lullwater, Prospect Park, Brooklyn NY, c. 5 June, 2005. From Wikimedia Commons

Put an image of Prospect Park's Lullwater on the end of the image list, creating the image list, if necessary.
gmic -input images/Lullwater_south_from_Binnen-Bridge_Prospect_Park.jpg            

Declare an incoming image to be of a specific type, without regard to the filename or its extension. If the type specification is wrong, G'MIC will attempt to fall back to its own determination of an image type. If the fallback fails, G'MIC will post an error.   
gmic -input jpg:images/hollerith.png

Use -, with an optional trailing type specifier, to load an image from the shell's input stream. Here is an overly obtuse way in a bash shell to input an image from a file:  
cat images/hollerith.png | gmic -.png

 §§§

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.

-input 128,128,1,3,'c==0?x%17:c==1?x%7:x%11' -normalize. 0,255 -name stripes
 Stripes, any way you want them.
Input an image through specified image dimensions and fill with a math expression.
gmic -input 128,128,1,3,'c==0?x%17:c==1?x%7:x%11' -normalize. 0,255 -name stripes
Input a one pixel image. This form implicitly invokes the input command and the remaining three dimensions default to 1.
gmic 1
-input 128,128,1,3,'[255,0,63]' -input 60%,80%,100%,100%,[63,0,255]
 Red and blue
Input a reddish image with absolute dimensions; a math expression denoting a single reddish pixel fills the entire image. Input a second bluish image with dimensions relative to the first.
gmic -input 128,128,1,3,'[255,0,63]' -input 60%,80%,100%,100%,[63,0,255]

§§§

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.

-input images/fish.jpg -r2dx. 50%,5 [-1] -r2dx. 50%,5
  New Orleans Festival of Fins, by whole and by half. c. 2005
Input an image. Shrink it by half. Make a copy. Shrink that by half again.
gmic -input images/fish.jpg -r2dx. 50%,5 [-1] -r2dx. 50%,5

-input images/usdoj_1892.jpg -r2dx. 50%,5 [-1] -r2dx. 50%,5 [-2],[-1],[-2],[-1],'[255,220,75]'
   Paperwork with yellow
Input an image. Shrink it by half (twice). Make a yellowish image with mixed dimensions from the preceding images.
gmic -input images/usdoj_1892.jpg -r2dx. 50%,5 [-1] -r2dx. 50%,5 [-2],[-1],[-2],[-1],'[255,220,75]'

-input images/hollerith.png r2dx. 34.5% -input[0] images/fish.jpg r2dx.. 10.5%,5 [0,1]x3
   Copying two images three times
Put three copies each of the first and second images on the list at the end of the list.
gmic -input images/hollerith.png r2dx. 34.5% -input[0] images/fish.jpg r2dx.. 10.5%,5 [0,1]x3

 §§§

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.

(240,200,150^200,130,46^0,180,23) r2dx. 256,5
  A 256 colormap made from a tiny, 3,1,1,3 image
Input a three by one pixel RGB image and expand it into a color map.
gmic  (240,200,150^200,130,46^0,180,23) r2dx. 256,5
(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) r2dx. 49,1
 A 7 × 7 white cross on a black field
Input a 7 × 7 white cross on a black field. Instead of specifying all 49 pixels, let many default to black
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)

 §§§

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 ^).
-input ('bubbaboy') -r2dy 32,1
  'bubbaboy'
Input a sinqle-quoted string. Pel values equal the character code. The pel in channel zero, column zero and row zero is decimal 98, hexadecimal 0x62, the character code for lowercase b in UTF-8.
gmic  -input ('bubbaboy') 
-input ('columnvector':y)x4 -r2dx 32,1
  Four column vectors
Input four 1 × 12 column vectors.
gmic -input ('columnvector':y)x4
-input ('boy':c) -r2dx 32,1
  One pale blue pixel
Input a sinqle pale blue pixel, equivalent to -input 1,1,1,3,[98,111,121].
gmic  -input ('boy':c)

 §§§

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

images/hollerith.png -r2dx 50%,5 -store smallcounter -repeat 5 -input $smallcounter -adjust_colors. 0,0,0,{20*$>} -done -append x
  Step through the hue parameter five times, +20 per step.  

Investigate the behavior of the adjust_colors command's hue_shift parameter using a five-step sampler.
gmic -input images/hollerith.png -r2dx 50%,5 -store smallcounter -repeat 5 -input $smallcounter -adjust_colors. 0,0,0,{20*$>} -done -append x

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.                            

Input an empty image
gmic -input 0 -print.
-input 0 expand_xy. 16
  Summon an image from the void. Make it a 32 × 32 image.
         [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.                                 

Input an empty image, create a 32 × 32 image giving it a data area.
gmic -input 0 expand_xy. 16 -print.
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: ${}
gmic -input images/e_letter.png -echo "Bit Depth: "'${}'
[gmic]-0./ Start G'MIC interpreter.
[gmic]-0./ Input file 'images/e_letter.png' at position 0 (1 image 1024x1024x1x4).
[gmic]-1./ Bit Depth: 16
[gmic]-1./ Display image [0] = 'e_letter.png'.
[0] = 'images/e_letter.png':
  size = (1024,1024,1,4) [16 Mio of floats].
  data = (0,0,0,0,0,0,0,0,0,0,0,0,(...),54484,34438,4112,0,0,0,0,0,0,0,0,0).
  min = 0, max = 65535, mean = 39666.9, std = 25952.3, coords_min = (0,0,0,0), coords_max = (221,92,0,0).
[gmic]-1./ End G'MIC interpreter.
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
$ gmic -h input

input (+):
[type:]filename |
[type:]http://URL |
[selection]x_nb_copies>0 |
{ width>0[%] | [image_w] },{ _height>0[%] | [image_h] },{ _depth>0[%] | [image_d] },{ _spectrum>0[%] | [image_s] },_{ value1,_value2,... | 'formula' } |
(value1{,|;|/|^}value2{,|;|/|^}...[:{x|y|z|c|,|;|/|^}]) |
0

Insert a new image taken from a filename or from a copy of an existing image [index],
or insert new image with specified dimensions and values. Single quotes may be omitted in
'formula'. Specifying argument '0' inserts an 'empty' image.
(equivalent to shortcut command 'i').

Default values: 'nb_copies=1', 'height=depth=spectrum=1' and 'value1=0'.

Example:
[#1] input image.jpg
[#2] input (1,2,3;4,5,6;7,8,9^9,8,7;6,5,4;3,2,1)
[#3] image.jpg (1,2,3;4,5,6;7,8,9) (255^128^64) 400,400,1,3,'(x>w/2?x:y)*c'

Tutorial: https://gmic.eu/tutorial/input
Updated: 22-August-2021 22:10 UTC Commit: 838dc220be85
G'MIC - GREYC's Magic for Image Computing: A Full-Featured Open-Source Framework for Image Processing

G'MIC is an open-source software distributed under the CeCILL free software licenses (LGPL-like and/or
GPL-compatible). Copyrights (C) Since July 2008, David Tschumperlé - GREYC UMR CNRS 6072, Image Team.