Custom commands
It is possible and easy to make your own custom command in G’mic. It is written in a file that has to be called when needed.
The custom commands you define have to be written in a text file. Its name is supposed to finish by the .gmic extension, but it isn’t mandatory. It is called using the command -command or its shortcut -m or by no command at all if its extension is indeed .gmic.
So, let’s say you want to use your own command called my_custom_command that you wrote in a file called macros.gmic on a picture called image.jpg. Then the 3 following commands are valid and equivalent:
gmic image.jpg -command macros.gmic -my_custom_command
gmic image.jpg -m macros.gmic -my_custom_command
gmic image.jpg macros.gmic -my_custom_command
If you have already made some custom filters for the plugin, you can use them by calling the file named .gmic in your home directory. In linux, this is done for example this way:
gmic image.jpg ~/.gmic -my_custom_command
To define a custom command, just write the command name followed by a space and a colon in your G’mic file. So if you write the line below :
my_custom_command :
it is defined. And if you use it:
gmic image.jpg macros.gmic -my_custom_command
It won’t return any error, even if it doesn’t do anything so far.
To have your custom command do something, just write what it should do below in a usual G’mic language, ex:
my_custom_command :
-rotate 45
-resize 50%,50%
Arguments can be used in your custom command, for example, it can become:
my_custom_command :
-rotate $1
-resize $2,$2
But from now on, you should not forget to specify arguments when you call it:
gmic image.jpg macros.gmic -my_custom_command 45,50%
So far, if you forget to specify one argument, you get an error message. It might be better to propose some default setting. It is usually done using the -skip command like this:
my_custom_command : -skip ${1=45},${2=50%}
-rotate $1
-resize $2,$2
Now, you don’t have to specify any argument, you can, but if you don’t, the default ones are applied. The 3 lines below now thus produce the same output:
gmic image.jpg macros.gmic -my_custom_command
gmic image.jpg macros.gmic -my_custom_command 45
gmic image.jpg macros.gmic -my_custom_command 45,50%
To avoid weird behavior and for cleanliness, it is sometime better to check the validity of an argument. For instance, it is wise to avoid a negative argument for the -resize function. This is done with -check:
my_custom_command : -skip ${1=45} -check ${2=50%}>0
-rotate $1
-resize $2,$2
Like this, in case of negative second argument:
gmic image.jpg macros.gmic -my_custom_command 45,-400
you get an explicit error message:
[gmic]-1./my_custom_command/ *** Error in ./my_custom_command/ *** Command 'check' : expression '-400>0' is false.
So far, the custom command does its job as it should, but it is still possible to improve it.
You can add comments in the code with the hash (#) :
my_custom_command : -skip ${1=45} -check ${2=50%}>0
-rotate $1 # to make it rotate
# and then it will be resized!
-resize $2,$2
So far, if you look at your terminal, you get to know every steps of your custom command:
[gmic]-1./my_custom_command/ Rotate image [0] of 45 degree, dirichlet borders and linear interpolation.
[gmic]-1./my_custom_command/ Resize image [0] to 50%x50%x100%x100% , with nearest neighbor interpolation, dirichlet borders and centering (0,0,0,0).
But you might feel it lighter if you only get one line considering your custom command as a whole. This is done by reducing the verbosity during the execution of you command, using -v - at the start and -v + at the end. Then add your own comment before everything with -echo[^-1] (or its shortcut -e[^-1]). For example:
my_custom_command : -skip ${1=45} -check ${2=50%}>0
-e[^1] "My rotate-resize of $1 and $2 on image$?"
-v -
-rotate $1
-resize $2,$2
-v +
lets in the terminal:
[gmic]-1./ My rotate-resize of 45 and 50% on image [0]
To make everything slicker, it is also possible to add some help message meant to be displayed in case of error. For that, start the command description with:
#@gmic my_custom_command
and then add informations with lines starting this way:
#@gmic :
At the end, the code might look:
#@gmic my_custom_command : _angle, pixel size
#@gmic : This crappy custom command
#@gmic : just rotate and resize
my_custom_command : -check "${2=50%}>0"
-e[^1] "My rotate-resize of $1 and $2 on image$?"
-v -
-rotate $1
-resize $2,$2
-v +
Now if you type something wrong:
gmic image.jpg macros.gmic -my_custom_command 45,-400
You get some help:
[gmic] Command 'my_custom_command' has the following description :
-my_custom_command _angle, pixel size
This crappy custom command
just rotate and resize
You can put as many custom command as you want in one G’mic file. You can now easily make loops (-repeat … -done), if statement (-if … -elif … -else … -endif), use variables (foo=”bar” … -e $foo) and so on.