Learn how easy it is to sync an existing GitHub or Google Code repo to a SourceForge project! See Demo

Close

Custom commands

David Tschumperlé Jerome Ferrari

0-Introduction

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.

1-The G’mic command file

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

2-Building that my_custom_command

2.1-Define it

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.

2.2-Give it orders

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%

2.3-Arguments

2.3.1-Just arguments

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%
2.3.2-Setting default arguments

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%
2.3.3-Checking arguments validity

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.

3-Polishing it

So far, the custom command does its job as it should, but it is still possible to improve it.

3.1-Comments in the code

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

3.2-Comments in the terminal

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]

3.3-Help message

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

4.And then

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.


Related

Wiki: Home