Adding Custom Commands

New custom commands can be added by the user, through the use of G'MIC custom commands files.

A command file is a simple text file, where each line starts either by

command_name: command_definition

command_definition (continuation)

At startup, G'MIC automatically includes user's command file $HOME/.gmic (on Unix) or %USERPROFILE%\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 verbatim copy of the specified string of arguments (do not include arguments set to default values).

$"*" is substituted by the sequence of specified arguments, separated by commas ,, each being double-quoted (include arguments set to default values).

$# is substituted by the maximum index 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 in 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 substituted 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 arguments have been indeed specified).

$=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.

It is possible to specialize the invocation of a +command by defining it as

+command_name: command_definition

A +-specialization takes priority over the regular command definition when the command is invoked with a prepended +.

When only a +-specialization of a command is defined, invoking command is actually equivalent to +command.

◀ Mathematical Expressions | List of Commands ▶

A Full-Featured Open-Source Framework for Image Processing

Latest stable version: 3.4.3 Current pre-release: 3.5.0 (2024/12/20)

Adding Custom Commands