Substitution Rules
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 index 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 if it is not defined).
The following reserved variables are predefined by the G'MIC interpreter:
$!: The current number of images in the list.
$> and $<: The increasing/decreasing index of the latest (currently running) repeat...done loop. $> goes from 0 (first loop iteration) to nb_iterations - 1 (last iteration). $< does the opposite.
$/: 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.
$_flags: The list of enabled flags when G'MIC interpreter has been compiled.
$_host: A string telling about the host running the G'MIC interpreter (e.g. cli or gimp).
$_os: A string describing the running operating system.
$_path_rc: The path to the G'MIC folder used to store 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).
$_path_commands: A list of all imported command files (stored as an image list).
$_pid: The current process identifier, as an integer.
$_pixeltype: The type of image pixels (default: float32).
$_prerelease: For pre-releases, the date of the pre-release as yymmdd. For stable releases, this variable is set to 0.
$_version: A 3-digits number telling about the current version of the G'MIC interpreter (e.g. 343).
$_vt100: Set to 1 if colored text output is allowed on the console. Otherwise, set to 0.
$$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'[:delimiter]} (between single quotes) is substituted by the sequence of character codes that composes the specified string, separated by specified delimiter. Possible delimiters are , (default), ;, /, ^ or . For instance, item {'foo'} is substituted by 102,111,111 and {'foo:;}' by 102;111;111.
{image,feature[:delimiter]} 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 character 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 character 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 }.
{*[index],feature1,...,featureN[:delimiter]} is substituted by a specific set of features of the instant display window #0 (or #index, if specified). Requested features can be:
u: screen width (actually independent on the window size).
v: screen height (actually independent on the window size).
uv: screen width*screen height.
d: window width (i.e. width of the window widget).
e: window height (i.e. height of the window widget).
de: window width*window height.
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*display height.
i: X-coordinate of the display window.
j: Y-coordinate of the display window.
f: current fullscreen state of the instant display.
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.