gmic [command1 [arg1_1,arg1_2,..]] .. [commandN [argN_1,argN_2,..]]
'gmic' is the open-source interpreter of the G'MIC language, a script-based programming
language dedicated to the design of possibly complex image processing pipelines and operators.
It can be used to convert, manipulate, filter and visualize image datasets made of one
or several 1d/2d or 3d multi-spectral images.
This reference documentation describes all the technical rules governing the G'MIC language.
As a starting point, you may want to visit our detailed tutorial pages, at:
https://gmic.eu/tutorial/

- At any time, G'MIC manages one list of numbered (and optionally named) pixel-based images,
entirely stored in computer memory (uncompressed).
- The first image of the list has indice '0' and is denoted by '[0]'. The second image of the
list is denoted by '[1]', the third by '[2]' and so on.
- Negative indices are treated in a periodic way: '[-1]' refers to the last image of the list,
'[-2]' to the penultimate one, etc. Thus, if the list has 4 images, '[1]' and '[-3]' both
designate the second image of the list.
- A named image may be also indicated by '[name]', if 'name' uses the character set [a-zA-Z0-9_]
and does not start with a number. Image names can be set or reassigned at any moment during
the processing pipeline (see command 'name' for this purpose).
- G'MIC defines a set of various commands and substitution mechanisms to allow the design of
complex pipelines and operators managing this list of images, in a very flexible way:
You can insert or remove images in the list, rearrange image order, process images
(individually or grouped), merge image data together, display and output image files, etc.
- Such a pipeline can be then added as a new custom G'MIC command (stored in a user
command file), so it can be re-used afterwards in a larger pipeline if necessary.

- In G'MIC, each image is modeled as a 1d, 2d, 3d or 4d array of scalar values, uniformly
discretized on a rectangular/parallelepipedic domain.
- The four dimensions of this array are respectively denoted by:
. 'width', the number of image columns (size along the 'x'-axis).
. 'height', the number of image rows (size along the 'y'-axis).
. 'depth', the number of image slices (size along the 'z'-axis).
(the depth is equal to 1 for usual color or grayscale 2d images).
. 'spectrum', the number of image channels (size along the 'c'-axis).
(the spectrum is respectively equal to 3 and 4 for usual RGB and RGBA color images).
- There are no hard limitations on the size of the image along each dimension. For instance,
the number of image slices or channels can be of arbitrary size within the limits of
the available memory.
- The width, height and depth of an image are considered as spatial dimensions, while the
spectrum has a multi-spectral meaning. Thus, a 4d image in G'MIC should be most often
regarded as a 3d dataset of multi-spectral voxels. Most of the G'MIC commands will stick with
this idea (e.g. command 'blur' blurs images only along the spatial 'xyz'-axes).
- G'MIC stores all the image data as buffers of 'float' values (32 bits, value range
[-3.4E38,+3.4E38]). It performs all its image processing operations with floating point
numbers. Each image pixel takes then 32bits/channel (except if double-precision buffers have
been enabled during the compilation of the software, in which case 64bits/channel can be the
default).
- Considering 'float'-valued pixels ensure to keep the numerical precision when executing
image processing pipelines. For image input/output operations, you may want to prescribe the
image datatype to be different than 'float' (like 'bool', 'char', 'int', etc...).
This is possible by specifying it as a file option when using I/O commands.
(see section 'Input/output properties' to learn more about file options).

- In G'MIC, an image processing pipeline is described as a sequence of items separated by the
space character ' '. Such items are interpreted and executed from the left to the right.
For instance, the expression:
filename.jpg blur 3,0 sharpen 10 resize 200%,200% output file_out.jpg
defines a valid pipeline composed of nine G'MIC items.
- Each G'MIC item is a string that is either a command, a list of command arguments,
a filename, or a special input string.
- Escape characters '\' and double quotes '"' can be used to define items containing spaces or
other special characters. For instance, the two strings 'single\ item' and '"single item"'
both define the same single item, with a space in it.

- If a specified G'MIC item appears to be an existing filename, the corresponding image data
are loaded and inserted at the end of the image list (which is equivalent to the use of
'input filename').
- Special filenames '-' and '-.ext' stand for the standard input/output streams, optionally
forced to be in a specific 'ext' file format (e.g. '-.jpg' or '-.png').
- The following special input strings may be used as G'MIC items to create and insert new
images with prescribed values, at the end of the image list:
. '[selection]' or '[selection]xN': Insert 1 or N copies of already existing images.
'selection' may represent one or several images
(see section 'Command items and selections' to learn more about selections).
. 'width[%],_height[%],_depth[%],_spectrum[%],_values': Insert a new image with specified
size and values (adding '%' to a dimension means 'percentage of the size along the same
axis, taken from the last image '[-1]''). Any specified dimension can be also written as
'[image]', and is then set to the size (along the same axis) of the existing specified image
[image]. 'values' can be either a sequence of numbers separated by commas ',', or a
mathematical expression, as e.g. in input item '256,256,1,3,[x,y,128]' which
creates a 256x256 RGB color image with a spatial shading on the red and green channels.
(see section 'Mathematical expressions' to learn more about mathematical expressions).
. '(v1,v2,..)': Insert a new image from specified prescribed values. Value separator inside
parentheses can be ',' (column separator), ';' (row separator), '/' (slice separator) or
'^' (channel separator). For instance, expression '(1,2,3;4,5,6;7,8,9)' creates a 3x3 matrix
(scalar image), with values running from 1 to 9.
. '0': Insert a new 'empty' image, containing no pixel data. Empty images are used only in rare
occasions.
- Input item 'name=value' declares a new variable 'name', or assign a new value
to an existing variable. Variable names must use the character set [a-zA-Z0-9_] and cannot
start with a number.
- A variable definition is always local to the current command except when it starts by the
underscore character '_'. In that case, it becomes also accessible by any command invoked
outside the current command scope (global variable).
- If a variable name starts with two underscores '__', the global variable is also shared among
different threads and can be read/set by commands running in parallel (see command 'parallel'
for this purpose). Otherwise, it remains local to the thread that defined it.
- Numerical variables can be updated with the use of these special operators:
'+=' (addition), '-=' (subtraction), '*=' (multiplication), '/=' (division), '%=' (modulo),
'&=' (bitwise and), '|=' (bitwise or), '^=' (power), '<<=' and '>>=' (bitwise left and right
shifts). For instance, 'foo=1 foo+=3'.
- Input item 'name.=string' concatenates specified 'string' to the end of variable 'name'.
- Multiple variable assignments and updates are allowed, with expressions:
'name1,name2,...,nameN=value' or 'name1,name2,...,nameN=value1,value2,...,valueN'
where assignment operator '=' can be replaced by one of the allowed operators
(e.g. '+=').

- A G'MIC item that is not a filename nor a special input string designates a command,
most of the time. Generally, commands perform image processing operations on one or several
available images of the list.
- Reccurent commands have two equivalent names (regular and short). For instance, command names
'resize' and 'r' refer to the same image resizing action.
- A G'MIC command may have mandatory or optional arguments. Command arguments must be specified
in the next item on the command line. Commas ',' are used to separate multiple arguments of a
single command, when required.
- The execution of a G'MIC command may be restricted only to a subset of the image list, by
appending '[selection]' to the command name. Examples of valid syntaxes for 'selection' are:
. 'command[-2]': Apply command only on the penultimate image [-2] of the list.
. 'command[0,1,3]': Apply command only on images [0],[1] and [3].
. 'command[3-6]': Apply command only on images [3] to [6] (i.e, [3],[4],[5] and [6]).
. 'command[50%-100%]': Apply command only on the second half of the image list.
. 'command[0,-4--1]': Apply command only on the first image and the last four images.
. 'command[0-9:3]': Apply command only on images [0] to [9], with a step of 3
(i.e. on images [0], [3], [6] and [9]).
. 'command[0--1:2]': Apply command only on images of the list with even indices.
. 'command[0,2-4,50%--1]': Apply command on images [0],[2],[3],[4] and on the second half of
the image list.
. 'command[^0,1]': Apply command on all images except the first two.
. 'command[name1,name2]': Apply command on named images 'name1' and 'name2'.
- Indices in selections are always sorted in increasing order, and duplicate indices are
discarded. For instance, selections '[3-1,1-3]' and '[1,1,1,3,2]' are both equivalent to
'[1-3]'. If you want to repeat a single command multiple times on an image, use a
'repeat..done' loop instead. Inverting the order of images for a command is achieved by
explicitly inverting the order of the images in the list, with command 'reverse[selection]'.
- Command selections '[-1]','[-2]' and '[-3]' are so often used that they have their own
shortcuts, respectively '.', '..' and '...'. For instance, command 'blur..' is equivalent to
'blur[-2]'. These shortcuts work also when specifying command arguments.
- G'MIC commands invoked without '[selection]' are applied on all images of the list, i.e. the
default selection is '[0--1]' (except for command 'input' whose default selection is '[-1]').
- Prepending a single hyphen '-' to a G'MIC command is allowed. This may be useful to recognize
command items more easily in a one-liner pipeline (typically invoked from a shell).
- A G'MIC command prepended with a plus sign '+' or a double hyphen '--' does not act 'in-place'
but inserts its result as one or several new images at the end of the image list.
- There are two different types of commands that can be run by the G'MIC interpreter:
. Builtin commands, are the hard-coded functionalities in the interpreter core. They are thus
compiled as binary code and run fast, most of the time. Omitting an argument when invoking a
builtin command is not permitted, except if all following arguments are also omitted.
For instance, invoking 'plasma 10,,5' is invalid but 'plasma 10' is correct.
. Custom commands, are defined as G'MIC pipelines of builtin or other custom commands.
They are interpreted by the G'MIC interpreter, and thus run a bit slower than builtin commands.
Omitting arguments when invoking a custom command is permitted. For instance, expressions
'flower ,,,100,,2' or 'flower ,' are correct.
- Most of the existing commands in G'MIC are actually defined as custom commands.
- A user can easily add its own custom commands to the G'MIC interpreter (see section
'Adding custom commands' for more details). New builtin commands cannot be added
(unless you modify the G'MIC interpreter source code and recompile it).

- G'MIC is able to read/write most of the classical image file formats, including:
. 2d grayscale/color files: .png, .jpeg, .gif, .pnm, .tif, .bmp, ...
. 3d volumetric files: .dcm, .hdr, .nii, .pan, .inr, .pnk, ...
. video files: .mpeg, .avi, .mov, .ogg, .flv, ...
. Generic ascii or binary data files: .gmz, .cimg, .cimgz, .dlm, .asc, .pfm, .raw, .txt, .h.
. 3d object files: .off.
- When dealing with color images, G'MIC generally reads, writes and displays data using the usual
sRGB color space.
- G'MIC is able to manage 3d objects that may be read from files or generated by G'MIC commands.
A 3d object is stored as a one-column scalar image containing the object data, in the
following order: { magic_number; sizes; vertices; primitives; colors; opacities }.
These 3d representations can be then processed as regular images.
(see command 'split3d' for accessing each of these 3d object data separately).
- Be aware that usual file formats may be sometimes not adapted to store all the available image
data, since G'MIC uses float-valued image buffers. For instance, saving an image that was
initially loaded as a 16bits/channel image, as a .jpg file will result in a loss of
information. Use the G'MIC-specific file extension .gmz to ensure that all data
precision is preserved when saving images.
- Sometimes, file options may/must be set for file formats:
. Video files: Only sub-frames of an image sequence may be loaded, using the input expression
'filename.ext,[first_frame[,last_frame[,step]]]'. Set 'last_frame==-1' to tell it must be
the last frame of the video. Set 'step' to 0 to force an opened video file to be
opened/closed. Output framerate and codec can be also set by using the output expression
'filename.avi,_fps,_codec,_keep_open={ 0 | 1 }'. 'codec' is a 4-char string
(see http://www.fourcc.org/codecs.php) or '0' for the default codec. 'keep_open' tells if
the output video file must be kept open for appending new frames afterwards.
. .cimg[z] files: Only crops and sub-images of .cimg files can be loaded, using the input
expressions 'filename.cimg,N0,N1', 'filename.cimg,N0,N1,x0,x1',
'filename.cimg,N0,N1,x0,y0,x1,y1', 'filename.cimg,N0,N1,x0,y0,z0,x1,y1,z1' or
'filename.cimg,N0,N1,x0,y0,z0,c0,x1,y1,z1,c1'.
Specifying '-1' for one coordinates stands for the maximum possible value. Output expression
'filename.cimg[z][,datatype]' can be used to force the output pixel type. 'datatype' can be
{ uchar | char | ushort | short | uint | int | uint64 | int64 | float | double }.
. .raw binary files: Image dimensions and input pixel type may be specified when loading .raw
files with input expression
'filename.raw[,datatype][,width][,height[,depth[,dim[,offset]]]]]'. If no dimensions are
specified, the resulting image is a one-column vector with maximum possible height. Pixel
type can also be specified with the output expression 'filename.raw[,datatype]'.
'datatype' can be the same as for .cimg[z] files.
. .yuv files: Image dimensions must be specified when loading, and only sub-frames of an image sequence
may be loaded, using the input expression
'filename.yuv,width,height[,chroma_subsampling[,first_frame[,last_frame[,step]]]'.
'chroma_subsampling' can be { 420 | 422 | 444 }.
When saving, chroma subsampling mode can be specified with output expression
'filename.yuv[,chroma_subsampling]'.
. .tiff files: Only sub-images of multi-pages tiff files can be loaded, using the input
expression 'filename.tif,_first_frame,_last_frame,_step'.
Output expression 'filename.tiff,_datatype,_compression,_force_multipage,_use_bigtiff' can
be used to specify the output pixel type, as well as the compression method.
'datatype' can be the same as for .cimg[z] files. 'compression' can be
{ none (default) | lzw | jpeg }. 'force_multipage can be { 0=no (default) | 1=yes }.
'use_bigtiff can be { 0=no | 1=yes (default) }.
. .gif files: Animated gif files can be saved, using the input expression
'filename.gif,fps>0,nb_loops'. Specify 'nb_loops=0' to get an infinite number of animation
loops (this is the default behavior).
. .jpeg files: The output quality may be specified (in %), using the output expression
'filename.jpg,30' (here, to get a 30% quality output). '100' is the default.
. .mnc files: The output header can set from another file, using the output expression
'filename.mnc,header_template.mnc'.
. .pan, .cpp, .hpp, .c and .h files: The output datatype can be selected with output expression
'filename[,datatype]'. 'datatype' can be the same as for .cimg[z] files.
. .gmic files: These filenames are assumed to be G'MIC custom commands files. Loading such a
file will add the commands it defines to the interpreter. Debug information can be
enabled/disabled by the input expression 'filename.gmic[,add_debug_info={ 0 | 1 }]'.
. Inserting 'ext:' on the beginning of a filename (e.g. 'jpg:filename') forces G'MIC to
read/write the file as it would have been done if it had the specified extension '.ext'.
- Some input/output formats and options may not be supported, depending on the configuration
flags that have been set during the build of the G'MIC software.

- G'MIC items containing '$' or '{}' are substituted before being interpreted. Use these
substituting expressions to access various data from the interpreter environment.
- '$name' and '${name}' are both substituted by the value of the specified named variable
(set previously by the item 'name=value'). If this variable has not been already set, the
expression is substituted by the highest positive indice of the named image '[name]'. If no
image has this name, the expression is substituted by the value of the OS environment variable
with same name (it may be thus an empty string).
The following reserved variables are predefined by the G'MIC interpreter:
. '$!': The current number of images in the list.
. '$>' and '$<': The increasing/decreasing indice of the latest (currently running)
'repeat...done' loop.
. '$/': The current call stack. Stack items are separated by slashes '/'.
. '$|': The current value (expressed in seconds) of a millisecond precision timer.
. '$^': The current verbosity level.
. '$_cpus': The number of computation cores available on your machine.
. '$_pid': The current process identifier, as an integer.
. '$_prerelease': For pre-releases only, the date of the pre-release as 'yymmdd'.
For stable releases, this variable is not defined.
. '$_version': A 3-digits number telling about the current version of the G'MIC interpreter
(e.g. '234').
. '$_vt100': Set to 1 (default value) if colored text output is allowed on the console.
. '$_path_rc': The path to the G'MIC folder used to store resources and configuration files
(its value is OS-dependent).
. '$_path_user': The path to the G'MIC user file .gmic or user.gmic (its value is
OS-dependent).
- '$$name' and '$${name}' are both substituted by the G'MIC script code of the specified named
custom command, or by an empty string if no custom command with specified name exists.
- '${"-pipeline"}' is substituted by the status value after the execution of the specified
G'MIC pipeline (see command 'status'). Expression '${}' thus stands for the
current status value.
- '{``string}' (starting with two backquotes) is substituted by a double-quoted version of the
specified string.
- '{/string}' is substituted by the escaped version of the specified string.
- '{'string'}' (between single quotes) is substituted by the sequence of ascii codes that compose
the specified string, separated by commas ','. For instance, item '{'foo'}' is substituted
by '102,111,111'.
- '{image,feature}' is substituted by a specific feature of the image [image]. 'image' can be
either an image number or an image name. It can be also eluded, in which case, the last image
'[-1]' of the list is considered for the requested feature.
Specified 'feature' can be one of:
. 'b': The image basename (i.e. filename without the folder path nor extension).
. 'f': The image folder name.
. 'n': The image name or filename (if the image has been read from a file).
. 't': The text string from the image values regarded as ascii codes.
. 'x': The image extension (i.e the characters after the last '.' in the image name).
. '^ : The sequence of all image values, separated by commas ','.
. '@subset': The sequence of image values corresponding to the specified subset, and
separated by commas ','.
. Any other 'feature' is considered as a mathematical expression associated to the image
[image] and is substituted by the result of its evaluation (float value). For instance,
expression '{0,w+h}' is substituted by the sum of the width and height of the first image
(see section 'Mathematical expressions' for more details). If a mathematical expression
starts with an underscore '_', the resulting value is truncated to a readable format.
For instance, item '{_pi}' is substituted by '3.14159' (while '{pi}' is substituted by
'3.141592653589793').
. A 'feature' delimited by backquotes is replaced by a string whose ascii codes correspond
to the list of values resulting from the evaluation of the specified mathematical
expression. For instance, item '{`[102,111,111]`}' is substituted by 'foo' and item
'{`vector8(65)`}' by 'AAAAAAAA'.
- '{*}' is substituted by the visibility state of the instant display window [0] (can be
{ 0=closed | 1=visible }).
- '{*,feature}' or '{*indice,feature}' is substituted by a specific feature of the instant
display window #0 (or #indice, if specified). Requested 'feature' can be:
. 'w': display width (i.e. width of the display area managed by the window).
. 'h': display height (i.e. height of the display area managed by the window).
. 'wh': display width x display height.
. 'd': window width (i.e. width of the window widget).
. 'e': window height (i.e. height of the window widget).
. 'de': window width x window height.
. 'u': screen width (actually independent on the window size).
.' v': screen height (actually independent on the window size).
. 'uv': screen width x screen height.
. 'n': current normalization type of the instant display.
. 't': window title of the instant display.
. 'x': X-coordinate of the mouse position (or -1, if outside the display area).
. 'y': Y-coordinate of the mouse position (or -1, if outside the display area).
. 'b': state of the mouse buttons { 1=left-but. | 2=right-but. | 4=middle-but. }.
. 'o': state of the mouse wheel.
. 'k': decimal code of the pressed key if any, 0 otherwise.
. 'c': boolean (0 or 1) telling if the instant display has been closed recently.
. 'r': boolean telling if the instant display has been resized recently.
. 'm': boolean telling if the instant display has been moved recently.
. Any other 'feature' stands for a keycode name (in capital letters), and is substituted by
a boolean describing the current key state { 0=pressed | 1=released }.
. You can also prepend a hyphen '-' to a 'feature' (that supports it) to flush the
corresponding event immediately after reading its state (works for keys, mouse and
window events).
- Item substitution is never performed in items between double quotes. One must break the quotes
to enable substitution if needed, as in "3+8 kg = "{3+8}" kg". Using double quotes is then
a convenient way to disable the substitutions mechanism in items, when necessary.
- One can also disable the substitution mechanism on items outside double quotes, by escaping the
'{','}' or '$' characters, as in '\{3+4\}\ doesn't\ evaluate'.

- G'MIC has an embedded mathematical parser. It is used to evaluate (possibly complex) expressions
inside braces '{}', or formulas in commands that may take one as an argument (e.g. 'fill').
- When the context allows it, a formula is evaluated for each pixel of the selected images
(e.g. 'fill').
- A math expression may return a scalar or vector-valued result (with a fixed number of
components).
- The mathematical parser understands the following set of functions, operators and variables:
_ Usual operators:|| (logical or), && (logical and), | (bitwise or), & (bitwise and),
!=, ==, <=, >=, , << (left bitwise shift), >> (right bitwise shift), -, +, *, /,
% (modulo), ^ (power), ! (logical not), ~ (bitwise not),
++, --, +=, -=, *=, /=, %=, &=, |=, ^=, >>=, <<= (in-place operators).
_ Usual math functions:abs(), acos(), acosh(), arg(), argkth(), argmax(), argmin(), asin(),
asinh(), atan(), atan2(), atanh(), avg(), bool(), cbrt(), ceil(), cos(), cosh(), cut(), exp(), fact(),
fibo(), floor(), gauss(), int(), isval(), isnan(), isinf(), isint(), isbool(), isfile(), isdir(), isin(),
kth(), log(), log2(), log10(), max(), med(), min(), narg(), prod(), rol() (left bit rotation),
ror() (right bit rotation), round(), sign(), sin(), sinc(), sinh(), sqrt(), std(),
srand(_seed), sum(), tan(), tanh(), var(), xor().
. 'atan2(y,x)' is the version of 'atan()' with two arguments 'y' and 'x' (as in C/C++).
. 'permut(k,n,with_order)' computes the number of permutations of k objects from a set of
n objects.
. 'gauss(x,_sigma,_is_normalized)' returns 'exp(-x^2/(2*s^2))/(is_normalized?sqrt(2*pi*sigma^2):1)'.
. 'cut(value,min,max)' returns value if it is in range [min,max], or min or max otherwise.
. 'narg(a_1,...,a_N)' returns the number of specified arguments (here, N).
. 'arg(i,a_1,..,a_N)' returns the ith argument a_i.
. 'isval()', 'isnan()', 'isinf()', 'isint()', 'isbool()' test the type of the given
number or expression, and return 0 (false) or 1 (true).
. 'isfile()' (resp. 'isdir()') returns 0 (false) or 1 (true) whether its argument is a
path to an existing file (resp. to a directory) or not.
. 'isin(v,a_1,...,a_n)' returns 0 (false) or 1 (true) whether the first value 'v' appears
in the set of other values 'a_i'.
. 'argmin()', 'argmax()', 'avg()', 'kth()', 'max()', 'med()', 'min()', 'std()', 'sum()'
and 'var()' can be called with an arbitrary number of scalar/vector arguments.
. 'round(value,rounding_value,direction)' returns a rounded value. 'direction' can be
{ -1=to-lowest | 0=to-nearest | 1=to-highest }.
_ Variable names below are pre-defined. They can be overridden.
. 'l': length of the associated list of images.
. 'w': width of the associated image, if any (0 otherwise).
. 'h': height of the associated image, if any (0 otherwise).
. 'd': depth of the associated image, if any (0 otherwise).
. 's': spectrum of the associated image, if any (0 otherwise).
. 'r': shared state of the associated image, if any (0 otherwise).
. 'wh': shortcut for width x height.
. 'whd': shortcut for width x height x depth.
. 'whds': shortcut for width x height x depth x spectrum (i.e. number of image values).
. 'im','iM','ia','iv','is','ip','ic': Respectively the minimum, maximum, average,
variance, sum, product and median value of the associated image, if any (0 otherwise).
. 'xm','ym','zm','cm': The pixel coordinates of the minimum value in the associated
image, if any (0 otherwise).
. 'xM','yM','zM','cM': The pixel coordinates of the maximum value in the associated
image, if any (0 otherwise).
. All these variables are considered as constant values by the math parser (for optimization
purposes) which is indeed the case most of the time. Anyway, this might not be the case,
if function 'resize(#ind,..)' is used in the math expression.
If so, it is safer to invoke functions 'l()', 'w(_#ind)', 'h(_#ind)', ... 's(_#ind)'
and 'ic(_#ind)' instead of the corresponding named variables.
. 'i': current processed pixel value (i.e. value located at (x,y,z,c)) in the associated
image, if any (0 otherwise).
. 'iN': Nth channel value of current processed pixel (i.e. value located at (x,y,z,N)) in
the associated image, if any (0 otherwise). 'N' must be an integer in range [0,9].
. 'R','G','B' and 'A' are equivalent to 'i0', 'i1', 'i2' and 'i3' respectively.
. 'I': current vector-valued processed pixel in the associated image, if any (0 otherwise).
The number of vector components is equal to the number of image channels
(e.g. I = [ R,G,B ] for a RGB image).
. You may add '#ind' to any of the variable name above to retrieve the information for any
numbered image [ind] of the list (when this makes sense). For instance 'ia#0' denotes the
average value of the first image of the list).
. 'x': current processed column of the associated image, if any (0 otherwise).
. 'y': current processed row of the associated image, if any (0 otherwise).
. 'z': current processed slice of the associated image, if any (0 otherwise).
. 'c': current processed channel of the associated image, if any (0 otherwise).
. 't': thread id when an expression is evaluated with multiple threads (0 means
'master thread').
. 'e': value of e, i.e. 2.71828...
. 'pi': value of pi, i.e. 3.1415926...
. 'u': a random value between [0,1], following a uniform distribution.
. 'g': a random value, following a gaussian distribution of variance 1
(roughly in [-6,6]).
. 'interpolation': value of the default interpolation mode used when reading pixel values
with the pixel access operators (i.e. when the interpolation argument is not explicitly
specified, see below for more details on pixel access operators). Its initial default
value is 0.
. 'boundary': value of the default boundary conditions used when reading pixel values with
the pixel access operators (i.e. when the boundary condition argument is not explicitly
specified, see below for more details on pixel access operators). Its initial default
value is 0.
_ Vector calculus: Most operators are also able to work with vector-valued elements.
. '[ a0,a1,...,aN ]' defines a (N+1)-dimensional vector with scalar coefficients ak.
. 'vectorN(a0,a1,,...,)' does the same, with the ak being repeated periodically if only a
few are specified.
. In both previous expressions, the ak can be vectors themselves, to be concatenated into a
single vector.
. The scalar element ak of a vector X is retrieved by 'X[k]'.
. The sub-vector [ X[p]...X[p+q-1] ] (of size q) of a vector X is retrieved by 'X[p,q]'.
. Equality/inequality comparisons between two vectors is done with operators '==' and '!='.
. Some vector-specific functions can be used on vector values:
'cross(X,Y)' (cross product), 'dot(X,Y)' (dot product), 'size(X)' (vector dimension),
'sort(X,_is_increasing,_chunk_size)' (sorting values), 'reverse(A)' (reverse order of
components), 'shift(A,_length,_boundary_conditions)' and
'same(A,B,_nb_vals,_is_case_sensitive)' (vector equality test).
. Function 'normP(u1,...,un)' computes the LP-norm of the specified vector
(P being an unsigned integer constant or 'inf'). If P is omitted, the L2 norm is used.
. Function 'resize(A,size,_interpolation,_boundary_conditions)' returns a resized version of
a vector 'A' with specified interpolation mode. 'interpolation' can be { -1=none
(memory content) | 0=none | 1=nearest | 2=average | 3=linear | 4=grid | 5=bicubic |
6=lanczos }, and 'boundary_conditions' can be { 0=dirichlet | 1=neumann | 2=periodic | 3=mirror }.
. Function 'find(A,B,_is_forward,_starting_indice)' returns the index where sub-vector B
appears in vector A, (or -1 if B is not found in A). Argument A can be also replaced by
an image indice #ind.
. A 2-dimensional vector may be seen as a complex number and used in those particular
functions/operators:
'**' (complex multiplication), '//' (complex division), '^^' (complex exponentiation),
'**=' (complex self-multiplication), '//=' (complex self-division), '^^=' (complex
self-exponentiation), 'cabs()' (complex modulus), 'carg()' (complex argument), 'cconj()'
(complex conjugate), 'cexp()' (complex exponential) and 'clog()' (complex logarithm).
. A MN-dimensional vector may be seen as a M x N matrix and used in those particular
functions/operators:
'*' (matrix-vector multiplication), 'det(A)' (determinant), 'diag(V)' (diagonal matrix
from a vector), 'eig(A)' (eigenvalues/eigenvectors), 'eye(n)' (n x n identity matrix),
'inv(A)' (matrix inverse), 'mul(A,B,_nb_colsB)' (matrix-matrix multiplication),
'pseudoinv(A,_nb_colsA)', 'rot(u,v,w,angle)' (3d rotation matrix), 'rot(angle)' (2d
rotation matrix), 'solve(A,B,_nb_colsB)' (least-square solver of linear system A.X = B),
'svd(A,_nb_colsA)' (singular value decomposition), 'trace(A)' (matrix trace) and
'transp(A,nb_colsA)' (matrix transpose). Argument 'nb_colsB' may be omitted if it is
equal to 1.
. Specifying a vector-valued math expression as an argument of a command that operates on
image values (e.g. 'fill') modifies the whole spectrum range of the processed image(s),
for each spatial coordinates (x,y,z). The command does not loop over the C-axis in this
case.
_ String manipulation: Character strings are defined and managed as vectors objects.
Dedicated functions and initializers to manage strings are
. [ 'string' ] and 'string' define a vector whose values are the ascii codes of the
specified character string (e.g. 'foo' is equal to [ 102,111,111 ]).
. _'character' returns the (scalar) ascii code of the specified character (e.g. _'A' is
equal to 65).
. A special case happens for empty strings: Values of both expressions [ '' ] and '' are 0.
. Functions 'lowercase()' and 'uppercase()' return string with all string characters
lowercased or uppercased.
. Function 'stov(str,_starting_indice,_is_strict)' parses specified string 'str' and returns the value
contained in it.
. Function 'vtos(expr,_nb_digits,_siz)' returns a vector of size 'siz' which contains
the ascii representation of values described by expression 'expr'.
'nb_digits' can be { -1=auto-reduced | 0=all | >0=max number of digits }.
. Function 'echo(str1,str2,...,strN)' prints the concatenation of given string arguments
on the console.
. Function 'cats(str1,str2,...,strN,siz)' returns the concatenation of given string arguments
as a new vector of size 'siz'.
_ Special operators can be used:
. ';': expression separator. The returned value is always the last encountered expression.
For instance expression '1;2;pi' is evaluated as 'pi'.
. '=': variable assignment. Variables in mathematical parser can only refer to numerical
values (vectors or scalars). Variable names are case-sensitive. Use this operator in
conjunction with ';' to define more complex evaluable expressions, such as
't=cos(x);3*t^2+2*t+1'.
These variables remain local to the mathematical parser and cannot be accessed outside
the evaluated expression.
. Variables defined in math parser may have a constant property, by specifying keyword const
before the variable name (e.g. const foo = pi/4;). The value set to such a variable must
be indeed a constant scalar. Constant variables allows certain types of optimizations in
the math JIT compiler.
_ The following specific functions are also defined:
. 'u(max)' or 'u(min,max)': return a random value between [0,max] or [min,max], following
a uniform distribution.
. 'i(_a,_b,_c,_d,_interpolation_type,_boundary_conditions)': return the value of the pixel
located at position (a,b,c,d) in the associated image, if any (0 otherwise).
'interpolation_type' can be { 0=nearest neighbor | other=linear }.
'boundary_conditions' can be { 0=dirichlet | 1=neumann | 2=periodic | 3=mirror }.
Omitted coordinates are replaced by their default values which are respectively
x, y, z, c, interpolation and boundary.
For instance command 'fill 0.5*(i(x+1)-i(x-1))' will estimate the X-derivative of an
image with a classical finite difference scheme.
. 'j(_dx,_dy,_dz,_dc,_interpolation_type,_boundary_conditions)' does the same for the pixel
located at position (x+dx,y+dy,z+dz,c+dc) (pixel access relative to the current
coordinates).
. 'i[offset,_boundary_conditions]' returns the value of the pixel located at specified
'offset' in the associated image buffer (or 0 if offset is out-of-bounds).
. 'j[offset,_boundary_conditions]' does the same for an offset relative to the current pixel
coordinates (x,y,z,c).
. 'i(#ind,_x,_y,_z,_c,_interpolation,_boundary_conditions)',
'j(#ind,_dx,_dy,_dz,_dc,_interpolation,_boundary_conditions)',
'i[#ind,offset,_boundary_conditions]' and 'i[offset,_boundary_conditions]' are similar expressions used to
access pixel values for any numbered image [ind] of the list.
. 'I/J[offset,_boundary_conditions]' and 'I/J(#ind,_x,_y,_z,_interpolation,_boundary_conditions)' do
the same as 'i/j[offset,_boundary_conditions]' and
'i/j(#ind,_x,_y,_z,_c,_interpolation,_boundary_conditions)' but return a vector instead of a scalar
(e.g. a vector [ R,G,B ] for a pixel at (a,b,c) in a color image).
. 'sort(#ind,_is_increasing,_axis)' sorts the values in the specified image [ind].
. 'crop(_#ind,_x,_y,_z,_c,_dx,_dy,_dz,_dc,_boundary_conditions)' returns a vector whose values come
from the cropped region of image [ind] (or from default image selected if 'ind' is not
specified). Cropped region starts from point (x,y,z,c) and has a size of
dx x dy x dz x dc. Arguments for coordinates and sizes can be omitted if they are not
ambiguous (e.g. 'crop(#ind,x,y,dx,dy)' is a valid invocation of this function).
. 'draw(_#ind,S,x,y,z,c,dx,_dy,_dz,_dc,_opacity,_M,_max_M)' draws a sprite S in image [ind]
(or in default image selected if 'ind' is not specified) at coordinates (x,y,z,c).
The size of the sprite dx x dy x dz x dc must be specified. You can also specify a
corresponding opacity mask M if its size matches S.
. 'polygon(_#ind,nb_vertices,coords,_opacity,_color)' draws a filled polygon in image [ind]
(or in default image selected if 'ind' is not specified) at specified coordinates.
It draws a single line if 'nb_vertices' is set to 2.
. 'ellipse(_#ind,xc,yc,radius1,_radius2,_angle,_opacity,_color)' draws a filled ellipse in image [ind]
(or in default image selected if 'ind' is not specified) with specified coordinates and geometry.
. 'resize(#ind,w,_h,_d,_s,_interp,_boundary_conditions,cx,_cy,_cz,_cc)' resizes an image of the
associated list with specified dimension and interpolation method. When using this,
function, you should consider retrieving the (non-constant) image dimensions using the
dynamic functions 'w(_#ind)', 'h(_#ind)', 'd(_#ind)', 's(_#ind)', 'wh(_#ind)',
'whd(_#ind)' and 'whds(_#ind)' instead of the corresponding constant variables.
. 'if(condition,expr_then,_expr_else)': return value of 'expr_then' or 'expr_else',
depending on the value of 'condition' (0=false, other=true). 'expr_else' can be omitted
in which case 0 is returned if the condition does not hold. Using the ternary operator
'condition?expr_then[:expr_else]' gives an equivalent expression.
For instance, G'MIC commands 'fill if(x%10==0,255,i)' and 'fill x%10?i:255' both draw
blank vertical lines on every 10th column of an image.
. 'dowhile(expression,_condition)' repeats the evaluation of 'expression' until 'condition'
vanishes (or until 'expression' vanishes if no 'condition' is specified). For instance,
the expression: 'if(N<2,N,n=N-1;F0=0;F1=1;dowhile(F2=F0+F1;F0=F1;F1=F2,n=n-1))' returns
the Nth value of the Fibonacci sequence, for N>=0 (e.g., 46368 for N=24).
'dowhile(expression,condition)' always evaluates the specified expression at least once,
then check for the loop condition. When done, it returns the last value of 'expression'.
. 'for(init,condition,_procedure,body)' first evaluates the expression 'init', then
iteratively evaluates 'body' (followed by 'procedure' if specified) while 'condition'
is verified (i.e. not zero). It may happen that no iteration is done, in which case the
function returns nan. Otherwise, it returns the last value of 'body'.
For instance, the expression: 'if(N<2,N,for(n=N;F0=0;F1=1,n=n-1,F2=F0+F1;F0=F1;F1=F2))'
returns the Nth value of the Fibonacci sequence, for N>=0 (e.g., 46368 for N=24).
. 'whiledo(condition,expression)' is exactly the same as 'for(init,condition,expression)'
without the specification of an initializing expression.
. 'break()' and 'continue()' respectively breaks and continues the current running bloc
(loop, init or main environment).
. 'fsize(filename)' returns the size of the specified 'filename' (or '-1' if file does not exist).
. 'date(attr,path)' returns the date attribute for the given 'path' (file or directory),
with 'attr' being { 0=year | 1=month | 2=day | 3=day of week | 4=hour | 5=minute |
6=second }, or a vector of those values.
. 'date(_attr) returns the specified attribute for the current (locale) date.
. 'print(expr1,expr2,...) or 'print(#ind) prints the value of the specified expressions
(or image information) on the console, and returns the value of the last expression
(or nan in case of an image). Function 'prints(expr)' also prints the string composed
of the ascii characters defined by the vector-valued expression (e.g. 'prints('Hello')').
. 'debug(expression) prints detailed debug information about the sequence of operations done
by the math parser to evaluate the expression (and returns its value).
. 'display(_X,_w,_h,_d,_s) or 'display(#ind) display the contents of the vector 'X'
(or specified image) and wait for user events. if no arguments are provided, a memory
snapshot of the math parser environment is displayed instead.
. 'init(expression) and 'end(expression) evaluates the specified expressions only once,
respectively at the beginning and end of the evaluation procedure, and this,
even when multiple evaluations are required (e.g. in 'fill init(foo=0);++foo').
. 'copy(dest,src,_nb_elts,_inc_d,_inc_s,_opacity) copies an entire memory block of 'nb_elts'
elements starting from a source value 'src' to a specified destination 'dest', with
increments defined by 'inc_d' and 'inc_s' respectively for the destination and source
pointers.
. 'stats(_#ind) returns the statistics vector of the running image '[ind]', i.e the vector
[ im,iM,ia,iv,xm,ym,zm,cm,xM,yM,zM,cM,is,ip ] (14 values).
. 'unref(a,b,...) destroys references to the named variable given as arguments.
. 'breakpoint() inserts a possible computation breakpoint (not supported by the cli interface).
. '_(expr) just ignores its arguments (mainly useful for debugging).
. 'ext('pipeline') executes the specified G'MIC pipeline as if it was called outside
the currently evaluated expression.
- User-defined macros:
. Custom macro functions can be defined in a math expression, using the assignment operator
'=', e.g. 'foo(x,y) = cos(x + y); result = foo(1,2) + foo(2,3)'.
. Trying to override a built-in function (e.g. 'abs()') has no effect.
. Overloading macros with different number of arguments is possible. Re-defining a
previously defined macro with the same number of arguments discards its previous
definition.
. Macro functions are indeed processed as macros by the mathematical evaluator. You should
avoid invoking them with arguments that are themselves results of assignments or
self-operations. For instance, 'foo(x) = x + x; z = 0; foo(++z)' returns '4' rather
than expected value '2'.
. When substituted, macro arguments are placed inside parentheses, except if a number sign
'#' is located just before or after the argument name. For instance, expression
'foo(x,y) = x*y; foo(1+2,3)' returns '9' (being substituted as '(1+2)*(3)'), while
expression 'foo(x,y) = x#*y#; foo(1+2,3)' returns '7' (being substituted as '1+2*3').
. Number signs appearing between macro arguments function actually count for 'empty'
separators. They may be used to force the substitution of macro arguments in unusual
places, e.g. as in 'str(N) = ['I like N#'];'.
- Multi-threaded and in-place evaluation:
. If your image data are large enough and you have several CPUs available, it is likely that
the math expression passed to a 'fill' or 'input' command is evaluated in parallel,
using multiple computation threads.
. Starting an expression with ':' or '*' forces the evaluations required for an image to be
run in parallel, even if the amount of data to process is small (beware, it may be slower
to evaluate in this case!). Specify ':' (instead of '*') to avoid possible image copy
done before evaluating the expression (this saves memory, but do this only if you are
sure this step is not required!)
. If the specified expression starts with '>' or '<', the pixel access operators
'i(), i[], j()' and 'j[]' return values of the image being currently modified,
in forward ('>') or backward ('<') order. The multi-threading evaluation of the
expression is also disabled in this case.
. Function 'critical(operands)' forces the execution of the given operands in a single thread at a
time.
_ Expressions 'i(_#ind,x,_y,_z,_c)=value', 'j(_#ind,x,_y,_z,_c)=value', 'i[_#ind,offset]=value'
and 'j[_#ind,offset]=value' set a pixel value at a different location than the running one
in the image [ind] (or in the associated image if argument '#ind' is omitted), either with
global coordinates/offsets (with 'i(...)' and 'i[...]'), or relatively to the current
position (x,y,z,c) (with 'j(...)' and 'j[...]'). These expressions always return 'value'.
- The last image of the list is always associated to the evaluations of '{expressions}',
e.g. G'MIC sequence '256,128 fill {w}' will create a 256x128 image filled with value 256.

- New custom commands can be added by the user, through the use of G'MICcustom commands files.
- A command file is a simple ascii text file, where each line starts either by
'command_name: command_definition' or 'command_definition (continuation)'.
- At startup, G'MIC automatically includes user's command file $HOME/.gmic (on Unix) or
%APPDATA%/user.gmic (on Windows). The CLI tool 'gmic' automatically runs the command
'cli_start' if defined.
- Custom command names must use character set [a-zA-Z0-9_] and cannot start with a number.
- Any ' # comment' expression found in a custom commands file is discarded by the G'MIC parser,
wherever it is located in a line.
- In a custom command, the following $-expressions are recognized and substituted:
. '$*' is substituted by a copy of the specified string of arguments.
. '$"*"' is substituted by a copy of the specified string of arguments, each being
double-quoted.
. '$#' is substituted by the maximum indice of known arguments (either specified by the user
or set to a default value in the custom command).
. '$[]' is substituted by the list of selected image indices that have been specified during the
command invocation.
. '$?' is substituted by a printable version of '$[]' to be used in command descriptions.
. '$i' and '${i}' are both substituted by the i^th specified argument. Negative indices such as
'${-j}' are allowed and refer to the j^th latest argument. '$0' is substituted by the
custom command name.
. '${i=default}' is substituted by the value of $i (if defined) or by its new value set to
'default' otherwise ('default' may be a $-expression as well).
. '${subset}' is substituted by the argument values (separated by commas ',') of a specified
argument subset. For instance expression '${2--2}' is substitued by all specified command
arguments except the first and the last one. Expression '${^0}' is then substituted by all
arguments of the invoked command (eq. to '$*' if all specified arguments have indeed a
value).
. '$=var' is substituted by the set of instructions that will assign each argument $i to the
named variable 'var$i' (for i in [0...$#]). This is particularly useful when a custom
command want to manage variable numbers of arguments. Variables names must use character set
[a-zA-Z0-9_] and cannot start with a number.
- These particular $-expressions for custom commands are always substituted, even in
double-quoted items or when the dollar sign '$' is escaped with a backslash '\'. To avoid
substitution, place an empty double quoted string just after the '$' (as in '$""1').
- Specifying arguments may be skipped when invoking a custom command, by replacing them by commas
',' as in expression 'flower ,,3'. Omitted arguments are set to their default values, which
must be thus explicitly defined in the code of the corresponding custom command (using
default argument expressions as '${1=default}').
- If one numbered argument required by a custom command misses a value, an error is thrown by the
G'MIC interpreter.

All available G'MIC commands are listed below, classified by themes. When several choices of
command arguments are possible, they appear separated by '|'. An argument specified inside '[]'
or starting by '_' is optional except when standing for an existing image [image], where 'image'
can be either an indice number or an image name. In this case, the '[]' characters are mandatory
when writing the item. A command marked with '(+)' is one of the builtin commands. Note also that
all images that serve as illustrations in this reference documentation are normalized in [0,255]
before being displayed. You may need to do this explicitly (command 'normalize 0,255') if you
want to save and view images with the same aspect than those illustrated in the example codes.

Activate debug mode.
When activated, the G'MIC interpreter becomes very verbose and outputs additional log
messages about its internal state on the standard output (stdout).
This option is useful for developers or to report possible bugs of the interpreter.

Render a channel-by-channel histogram.
If selected image has several slices, the rendering is performed for all input slices.
'expression' is a mathematical expression used to transform the histogram data for visualization purpose.
(equivalent to shorcut command 'dh'). if specified 'width' or 'height' is '0', then image size is set to half the screen size.

Render 2d or 3d parametric curve or point clouds from selected image data.
Curve points are defined as pixels of a 2 or 3-channel image.
If the point image contains more than 3 channels, additional channels define the (R,G,B) color for each vertex.
If 'outline_opacity>1', the outline is colored according to the specified vertex colors and 'outline_opacity-1' is used
as the actual drawing opacity.

Insert a new image taken from a filename or from a copy of an existing image [indice],
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 shorcut command 'i' | (no arg)).

Insert images from parent context of a custom command or a local environment.
Command selection (if any) stands for a selection of images in the parent context.
By default (adaptive shared state), selected images are inserted in a shared state if they do not belong to the context (selection) of the current custom command or local environment as well.
Typical use of command 'pass' concerns the design of custom commands that take images as arguments.

Serialize selected list of images into a single image, optionnally in a compressed form.
'datatype' can be { uchar | char | ushort | short | uint | int | uint64 | int64 | float | double }.
Specify 'datatype' if all selected images have a range of values constrained to a particular datatype, in order to minimize the memory footprint.
The resulting image has only integers values in [0,255] and can then be saved as a raw image of
unsigned chars (doing so will output a valid .cimg[z] or .gmz file).
If 'store_names' is set to '1', serialization uses the .gmz format to store data in memory (otherwise the .cimg[z] format).

Wait for a given delay (in ms), optionally since the last call to 'wait'.
or wait for a user event occurring on the selected instant display windows.
'delay' can be { <0=delay+flush events | 0=event | >0=delay }.
Command selection (if any) stands for instant display window indices instead of image indices.
If no window indices are specified and if 'delay' is positive, the command results
in a 'hard' sleep during specified delay.

If 'width' or 'height' is set to -1, the corresponding dimension is adjusted to the window
or image size.
When arguments 'pos_x' and 'pos_y' are both different than -1, the window is moved to
the specified coordinates.
'width'=0 or 'height'=0 closes the instant display window.
'normalization' can be { -1=keep same | 0=none | 1=always | 2=1st-time | 3=auto }.
'fullscreen' can be { -1=keep same | 0=no | 1=yes }.
You can manage up to 10 different instant display windows by using the numbered variants
'w0' (default, eq. to 'w'),'w1',...,'w9' of the command 'w'.
Invoke 'window' with no selection to make the window visible, if is has been closed by the user.

Set names of selected images.
- If the selection contains a single image, then it is assumed the command has a single name argument (possibly containing multiple comas).
- If the selection contains more than one image, each command argument defines a single image name for each image of the selection.
(equivalent to shorcut command 'nm').

Compute the bitwise AND of selected images with specified value, image or mathematical
expression, or compute the pointwise sequential bitwise AND of selected images.
(equivalent to shorcut command '&').

Compute the pointwise oriented arctangent of selected images.
Each selected image is regarded as the y-argument of the arctangent function, while the
specified image gives the corresponding x-argument.

Compute the bitwise left shift of selected images with specified value, image or
mathematical expression, or compute the pointwise sequential bitwise left shift of
selected images.
(equivalent to shorcut command '<<').

Perform division of the selected complex pairs (real1,imag1,...,realN,imagN) of images by specified complex pair of images (divider_real,divider_imag).
In complex pairs, the real image must be always located before the imaginary image in the image list.

Compute the matrix right multiplication of selected matrices/vectors by specified value, image or
mathematical expression, or compute the matrix right multiplication of selected images.
(equivalent to shorcut command 'm*').

Perform multiplication of the selected complex pairs (real1,imag1,...,realN,imagN) of images by specified complex pair of images (multiplier_real,multiplier_imag).
In complex pairs, the real image must be always located before the imaginary image in the image list.

Compute the bitwise OR of selected images with specified value, image or mathematical
expression, or compute the pointwise sequential bitwise OR of selected images.
(equivalent to shorcut command '|').

Discard specified values in selected images or discard neighboring duplicate values,
optionally only for the values along the first of a specified axis.
If no values are specified, neighboring duplicate values are discarded.
If all pixels of a selected image are discarded, an empty image is returned.

Perform a global adjustment of colors on selected images.
Range of correct image values are considered to be in [value_min,value_max] (e.g. [0,255]).
If 'value_min==value_max==0', value range is estimated from min/max values of selected images.
Processed images have pixel values constrained in [value_min,value_max].

Argument 'channels' refers to a colorspace, and can be basically one of { all | rgba | rgb | lrgb | ycbcr | lab | lch | hsv | hsi | hsl | cmy | cmyk | yiq }.
You can also make the processing focus on one particular channel of this colorspace, by setting 'channels' as 'colorspace_channel' (e.g. 'hsv_h' for the hue).
All channel values are considered to be in the [0,255] range.

Split selected images as several image containing a single color.
One selected image can be split as at most 'max_nb_outputs' images.
Output images are sorted by decreasing area of extracted color regions and have an additional alpha-channel.

Convert selected scalar images ([0-255]-valued) to pseudo-gray color images.
Default parameters : 'max_step=5', 'is_perceptual_constraint=1' and 'bits_depth=8'.
The original pseudo-gray technique has been introduced by Rich Franzen [http://r0k.us/graphics/pseudoGrey.html].
Extension of this technique to arbitrary increments for more tones, has been done by David Tschumperle.

Transfer colors from selected source images to selected reference image (given as argument).
'gamma' determines the importance of color occurrences in the matching process (0=none to 1=huge).
'regularization' determines the number of guided filter iterations to remove quantization effects.
'luminosity_constraints' tells if luminosity constraints must be applied on non-confident matched colors.
'is_constraints' tells if additional hard color constraints must be set (opens an interactive window).

Append MxN selected tiles as new images.
If 'N' is set to 0, number of rows is estimated automatically.
If 'M' is set to 0, number of columns is estimated automatically.
If 'M' and 'N' are both set to '0', auto-mode is used.
If 'M' or 'N' is set to 0, only a single image is produced.
'centering_x' and 'centering_y' tells about the centering of tiles when they have different sizes.

Create a single image montage from selected images, according to specified layout code :
- 'X' to assemble all images using an automatically estimated layout.
- 'H' to assemble all images horizontally.
- 'V' to assemble all images vertically.
- 'A' to assemble all images as an horizontal array.
- 'B' to assemble all images as a vertical array.
- 'Ha:b' to assemble two blocks 'a' and 'b' horizontally.
- 'Va:b' to assemble two blocks 'a' and 'b' vertically.
- 'Ra' to rotate a block 'a' by 90 deg. ('RRa' for 180 deg. and 'RRRa' for 270 deg.).
- 'Ma' to mirror a block 'a' along the X-axis ('MRRa' for the Y-axis).
A block 'a' can be an image indice (treated periodically) or a nested layout expression 'Hb:c','Vb:c','Rb' or 'Mb' itself.
For example, layout code 'H0:V1:2' creates an image where image [0] is on the left, and images [1] and [2] vertically packed on the right.

Blur selected images by anisotropic (eventually joint/cross) bilateral filtering.
If a guide image is provided, it is used for drive the smoothing filter.
A guide image must be of the same xyz-size as the selected images.
Set 'sampling' arguments to '0' for automatic adjustment.

Blur selected images by guided image filtering.
If a guide image is provided, it is used to drive the smoothing process.
A guide image must be of the same xyz-size as the selected images.
This command implements the filtering algorithm described in:
He, Kaiming; Sun, Jian; Tang, Xiaoou, "Guided Image Filtering," Pattern Analysis and Machine Intelligence,
IEEE Transactions on , vol.35, no.6, pp.1397,1409, June 2013

Inpaint selected images by specified mask.
If no patch size (or 0) is specified, inpainting is done using a fast average or median algorithm.
Otherwise, it used a patch-based reconstruction method, that can be very time consuming.
'fast_method' can be { 0=low-connectivity average | 1=high-connectivity average | 2=low-connectivity median | 3=high-connectivity median }.

Inpaint selected images by specified mask using a multiscale transport-diffusion algorithm.
If 'diffusion type==3', non-zero values of the mask (e.g. a distance function) are used to guide the diffusion process.

Apply non local means denoising of Buades et al, 2005. on selected images.
The patch is a gaussian function of 'std _patch_radius'.
The spatial kernel is a rectangle of radius 'spatial_bandwidth'.
The tonal kernel is exponential (exp(-d^2/_tonal_bandwidth^2))
with d the euclidiean distance between image patches.

Solve Poisson equation so that applying 'laplacian[n]' is close to the result of 'laplacian_command[n]'.
Solving is performed using a multi-scale gradient descent algorithm.
If 'nb_scales=0', the number of scales is automatically determined.

Resynthetize 'width'x'height' versions of selected micro-textures by phase randomization.
The texture synthesis algorithm is a straightforward implementation of the method described in :
http://www.ipol.im/pub/art/2011/ggm_rpn/

Generate discrete 2d Delaunay triangulation of non-zero pixels in selected images.
Input images must be scalar.
Each pixel of the output image is a triplet (a,b,c) meaning the pixel belongs to
the Delaunay triangle 'ABC' where 'a','b','c' are the labels of the pixels 'A','B','C'.

Detect skin in selected color images and output an appartenance probability map.
Detection is performed using CbCr chromaticity data of skin pixels.
If arguments 'skin_x', 'skin_y' and 'skin_radius' are provided, skin pixels are learnt
from the sample pixels inside the circle located at ('skin_x','skin_y') with radius 'skin_radius'.

Estimate displacement field between specified source and selected target images.
If 'smoothness>=0', regularization type is set to isotropic, else to anisotropic.
If 'nbscales==0', the number of scales used is estimated from the image size.

Estimate correspondence map between selected images and specified patch image, using
the patchmatch algorithm, as described in the paper :
"PatchMatch: A Randomized Correspondence Algorithm for Structural Image Editing", by
Connelly Barnes, Eli Shechtman, Adam Finkelstein, Dan B Goldman(2009).
Each pixel of the returned correspondence map gives the location (p,q) of the closest patch in
the specified patch image. If 'output_score=1', the third channel gives the corresponding
matching score for each patch as well.

Convert a Nx1, Nx2, Nx3 or NxM image as a point cloud in a 1d/2d or 3d binary image.
If 'M'>3, the 3-to-M lines sets the (M-3)-dimensional color at each point.
Parameters 'width','height' and 'depth' are related to the size of the final image :
- If set to 0, the size is automatically set along the specified axis.
- If set to N>0, the size along the specified axis is N.
- If set to N<0, the size along the specified axis is at most N.
Points with coordinates that are negative or higher than specified ('width','height','depth')
are not plotted.

Try to solve the 'travelling salesman' problem, using a combination of greedy search and 2-opt algorithms.
Selected images must have dimensions Nx1x1xC to represent N cities each with C-dimensional coordinates.
This command re-order the selected data along the x-axis so that the point sequence becomes a shortest path.

Draw specified arrow on selected images.
'pattern' is an hexadecimal number starting with '0x' which can be omitted
even if a color is specified. If a pattern is specified, the arrow is
drawn outlined instead of filled.

Draw xy-axes on selected images.
'pattern' is an hexadecimal number starting with '0x' which can be omitted
even if a color is specified.
To draw only one x-axis at row Y, set both 'y0' and 'y1' to Y.
To draw only one y-axis at column X, set both 'x0' and 'x1' to X.

Draw specified colored circle on selected images.
A radius of '100%' stands for 'sqrt(width^2+height^2)'.
'pattern' is an hexadecimal number starting with '0x' which can be omitted
even if a color is specified. If a pattern is specified, the circle is
drawn outlined instead of filled.

Automatically close open shapes in binary images (defining white strokes on black background).
Parameter names starting with 'hd_' are related to the hatch detection algorithm. Set 'hd_detection_rate>0' to disable this module.

Draw specified colored ellipse on selected images.
A radius of '100%' stands for 'sqrt(width^2+height^2)'.
'pattern' is an hexadecimal number starting with '0x' which can be omitted
even if a color is specified. If a pattern is specified, the ellipse is
drawn outlined instead of filled.

Try to randomly pack as many sprites as possible onto the 'empty' areas of an image.
Sprites can be eventually rotated and scaled during the packing process.
First selected image is the canvas that will be filled with the sprites.
Its last channel must be a binary mask whose zero values represent potential locations for drawing the sprites.
All other selected images represent the sprites considered for packing.
Their last channel must be a binary mask that represents the sprite shape (i.e. a 8-connected component).
The order of sprite packing follows the order of specified sprites in the image list.
Sprite packing is done on random locations and iteratively with decreasing scales.
'nb_scales' sets the number of decreasing scales considered for all specified sprites to be packed.
'min_scale' (in %) sets the minimal size considered for packing (specified as a percentage of the original sprite size).
'spacing' can be positive or negative.
'precision' tells about the desired number of failed trials before ending the filling process.

Draw specified colored N-vertices polygon on selected images.
'pattern' is an hexadecimal number starting with '0x' which can be omitted
even if a color is specified. If a pattern is specified, the polygon is
drawn outlined instead of filled.

Draw specified colored rectangle on selected images.
'pattern' is an hexadecimal number starting with '0x' which can be omitted
even if a color is specified. If a pattern is specified, the rectangle is
drawn outlined instead of filled.

Exact pre-defined sizes are '13','23','53' and '103'. Using these sizes ensures you draw binary letters without anti-aliasing.
Any other font size is interpolated from an exact size (the upper when possible).
Specifying an empty target image resizes it to new dimensions such that the image contains
the entire text string.

Compute the eigenvalues and eigenvectors of selected symmetric matrices or matrix fields.
If one selected image has 3 or 6 channels, it is regarded as a field of 2x2 or 3x3 symmetric matrices,
whose eigen elements are computed at each point of the field.

Solve tridiagonal system AX = B for selected B-vectors and specified tridiagonal A-matrix.
Tridiagonal matrix must be stored as a 3 column vector, where 2nd column contains the
diagonal coefficients, while 1st and 3rd columns contain the left and right coefficients.

Generate 3d delaunay triangulations from selected images.
One assumes that the selected input images are binary images containing the set of points to mesh.
The output 3d object is a mesh composed of non-oriented triangles.

Build 3d elevation of selected images, with a specified elevation map.
When invoked with (no arg) or 'z-factor', the elevation map is computed as the pointwise L2 norm of the
pixel values. Otherwise, the elevation map is taken from the specified image or formula.

Start a 'elif...[else]...fi' block if previous 'if' was not verified
and test if specified boolean is true, or if specified filename exists.
'boolean' can be a float number standing for { 0=false | other=true }.

Execute external command using a system call.
The status value is then set to the error code returned by the system call.
If 'is_verbose=1', the executed command is allowed to output on stdout/stderr.
(equivalent to shorcut command 'x').

Lock or unlock specified mutex for multi-threaded programming.
A locked mutex can be unlocked only by the same thread. All mutexes are unlocked by default.
'indice' designates the mutex indice, in [0,255].

Used in a custom command, 'noarg' tells the command that its argument list have not been used
finally, and so they must be evaluated next in the G'MIC pipeline, just as if the custom
command takes no arguments at all.
Use this command to write a custom command which can decide if it takes arguments or not.

Pack selected images into a single image.
The returned status contains the list of new (x,y) offsets for each input image.
Parameter 'is_ratio_constraint' tells if the resulting image must tend to a square image.

Compute the minimal alpha-channel difference (opposite of alpha blending) between the selected images and the specified base image.
The alpha difference A-B is defined as the image having minimal opacity, such that alpha_blend(B,A-B) = A.

Apply a G'MIC command on specified input image files, in a streamed way.
If a display window is opened, rendered frames are displayed in it during processing.
The output filename may have extension '.avi' (saved as a video), or any other usual image file extension (saved as a sequence of images).

Apply a G'MIC command on all frames of the specified input video file, in a streamed way.
If a display window is opened, rendered frames are displayed in it during processing.
The output filename may have extension '.avi' (saved as a video), or any other usual image file extension (saved as a sequence of images).

Average specified input image files, in a streamed way.
If a display window is opened, rendered frames are displayed in it during processing.
The output filename may have extension '.avi' (saved as a video), or any other usual image file extension (saved as a sequence of images).

Average frames of specified input video file, in a streamed way.
If a display window is opened, rendered frames are displayed in it during processing.
The output filename may have extension '.avi' (saved as a video), or any other usual image file extension (saved as a sequence of images).

Generate a temporal fading from specified input image files, in a streamed way.
If a display window is opened, rendered frames are displayed in it during processing.
The output filename may have extension 'avi' (saved as a video), or any other usual image file extension (saved as a sequence of images).

Generate a temporal morphing from specified input image files, in a streamed way.
If a display window is opened, rendered frames are displayed in it during processing.
The output filename may have extension '.avi' (saved as a video), or any other usual image file extension (saved as a sequence of images).

Generate a temporal morphing from specified input video file, in a streamed way.
If a display window is opened, rendered frames are displayed in it during processing.
The output filename may have extension '.avi' (saved as a video), or any other usual image file extension (saved as a sequence of images).

Return the list of files and/or subfolders from specified path.
'path' can be eventually a matching pattern.
'mode' can be { 0=files only | 1=folders only | 2=files + folders }.
Add '3' to 'mode' to return full paths instead of filenames only.

Return the covariance matrix of the vector-valued colors in the latest of the selected images (for arbitrary number of channels).
Parameter 'avg_outvarname' is used as a variable name that takes the value of the average vector-value.

Open a color grabber widget from the first selected image.
Argument 'variable_name' specifies the variable that contains the selected color values at any time.
Assigning '-1' to it forces the interactive window to close.

Display a RGB or RGBA color selector.
Argument 'variable_name' specifies the variable that contains the selected color values (as R,G,B,[A]) at any time.
Its value specifies the initial selected color. Assigning '-1' to it forces the interactive window to close.

Open an interactive window, where the user can defined its own 1d function.
If an image is selected, it is used to display additional information :
- The first row defines the values of a background curve displayed on the window (e.g. an histogram).
- The 2nd, 3rd and 4th rows define the R,G,B color components displayed beside the X and Y axes.
Argument 'variable_name' specifies the variable that contains the selected function keypoints at any time.
Assigning '-1' to it forces the interactive window to close.

Open a RGB or RGBA color selector widget from a palette.
The palette is given as a selected image.
Argument 'variable_name' specifies the variable that contains the selected color values (as R,G,B,[A]) at any time.
Assigning '-1' to it forces the interactive window to close.