As you’ll see, they are no slides, the lessons are just series of G’mic basic commands that, with the lecturer speech, show to the audience the different concepts of G’mic. And from time to time, there are exercises adapted to the level.

The intended audience was a group of 10 scientist in materials ranging from the soon to be graduate to the senior researcher. The G’mic lesson took the whole day. I wanted the difficulty level to raise steeply so that nobody could get asleep and so that we had time to see all that can be done with G’mic. This might have been an error, to progress in G’mic, one should get to know the many commands, and this requires time. The latest exercises are anyway well too difficult for beginners and are just here as a demo. The end of the day was spent discussing about the students own problems.

however, at the end, the main objective was fulfilled. They knew what they could do with G’mic, they knew where to search to continue.

If you feel curious, download the tarball and check all that out.

When several images are loaded in G’mic, they are ordered in a stack. It is then possible to refer to them by using either positive (starting from the first image as [0]) or negative numbers (starting from the last image as [-1]).

For example, if 3 images A, B and C are loaded:

gmic A.png B.png C.png

It creates a stack that you can picture like that:

You can refer to A as image [0] or image [-3], B as [1] or [-2] and C as [2] or [-1]. So both commands below do exactly the same thing, they display B:

gmic A.png B.png C.png -display[1]
gmic A.png B.png C.png -display[-2]

2.Command with one dash

If, in your command line, you add an instruction using a single dash, it replaces the images to which the instruction applies by the result. Thus, to split the different channels of B, the 2 commands below could be used is added to our first command:

gmic A.png B.png C.png -split[1] c
gmic A.png B.png C.png -split[-2] c

And they would modified the stack as shown below:

As you can see, the image A is still [0], but not [-3] anymore, it has become [-5].

3.Command with two dashes

To keep the original image, instruction are called using 2 dashes. The original image is indeed kept in place and the result is added at the end of the stack.
So commands below:

gmic A.png B.png C.png --split[1] c
gmic A.png B.png C.png --split[-2] c

would modify the stack as below:

4.Stack order matters, not invoking order

When you apply a command to several images, sometimes, order matters. But be careful, stack order matters, not invoking order.
For example, both commands below have the same result:

gmic A.png B.png -append[0,1] y
gmic A.png B.png -append[1,0] y

If you want to apply your command in another order, you have to play with the image stack, such as:

gmic A.png B.png -reverse[0,1] -append[0,1] y

or

gmic A.png B.png -move[1] 0 -append[1,0] y

Ce tutoriel a pour but de montrer comment créer un filtre personnalisé pour le greffon G’mic pour Gimp. Il part du principe que le lecteur ne connaît pas du tout le langage en ligne de commande G’mic.

Vous pouvez trouver des informations sur la façon de faire un filtre au début du fichier de commandes personnalisées par défaut et directement dans le greffon dans A propos > Création de filtres et aussi ci-dessous.

Ici, vous serez d’abord invité à créer un filtre très simple afin de comprendre les bases puis il s’agira d’assembler différents filtres afin d’en créer un meilleur.

1-Mon premier filtre

1.1-Le fichier des filtres personnalisés

Tous les filtres personnalisés que vous faites doivent être écrits dans un unique fichier texte appelé “.gmic“, n’oubliez pas le point au début du nom et n’ajouter rien d’autre, le nom de votre fichier texte n’est constitué que d’un point et de 4 lettres:: “.gmic“. Vous devez créer ce fichier dans votre répertoire “home” si vous êtes sous Linux, dans votre répertoire Application Data si vous êtes sous Windows et dans votre User Home folder si vous êtes sous MacOS. Ces 2 derniers systèmes d’exploitations peuvent rendre difficile la création de fichier commençant par un point: notepad or TextEdit peuvent vous aider au besoin.

1.2-Le filtre apparaît

Pour apparaître dans le greffon, vous devez inclure une ligne qui commence par #@gimp donnant le nom de votre filtre, la commande associée à ce filtre et optionnellement, la commande pour créer l’aperçu. Quelque chose comme:

#@gimp Mon premier filtre: mon_premier_filtre_commande, mon_premier_filtre_commande_preview

Vous pouvez essayer, mettez cette ligne dans votre fichier .gmic, rafraichissez les filtres G’mic et il devrait apparaître en haut de vos Filtres disponibles.

1.3-Le filtre dit quelque chose

Dans la partie droite de la fenêtre du greffon, vous pouvez mettre du texte et proposer différentes sortes de variables utilisables par le filtre. Pour cela, vous devez encore ajouter des lignes commençant par #@gimp. Vous pouvez par exemple recopier les lignes ci-dessous dans votre fichier .gmic et rafraîchir les filtres.

#@gimp Mon premier filtre: mon_premier_filtre_commande, mon_premier_filtre_commande
#@gimp : note = note("C'est mon premier filtre, je suis tellement excité!")
#@gimp : sep = separator()
#@gimp : Angle = float(45,0,360)
#@gimp : Remplir l'espace vide = choice("en noir","comme les bords","en répétant l'image")

1.4-Le filtre fait quelque chose

Jusqu’ici, votre filtre ne marche pas, si vous cliquer sur Valider, une erreur apparaîtra. C’est parce qu’aucune commande ne s’appelle “mon_premier_filtre_commande“, elle doit être créée en utilisant le langage G’mic. Donc, notre premier filtre peut être fini avec 2 lignes supplémentaires pour devenir:

#@gimp Mon premier filtre: mon_premier_filtre_commande, mon_premier_filtre_commande
#@gimp : note = note("C'est mon premier filtre, je suis tellement excité!")
#@gimp : sep = separator()
#@gimp : Angle = float(45,0,360)
#@gimp : Remplir l'espace vide = choice("en noir","comme les bords","en répétant l'image")
mon_premier_filtre_commande :
  -rotate $1,$2

si vous mettez ceci dans votre fichier .gmic et rafraichissez les filtres une fois de plus, vous avez un filtre pleinement fonctionnel capable de tourner une image. Vous pouvez ajuster l’angle de rotation de 0 à 360° et la valeur proposée par défaut est 45. Vous avez 3 choix pour “remplir l’espace vide”.
La commande utilisée par votre filtre est “mon_premier_filtre_commande” et c’est une commande très simple qui utilise l’instruction -rotate et les 2 variables $1 et $2 font référence à celles proposées au-dessus: “Angle” et “Remplir l’espace vide”.

1.5-Le filtre fait ce que vous voulez

Maintenant, vous avez les bases, vous avez juste besoin de vous inspirer des filtres déjà disponibles et de leur code source et si vous ne le connaissez pas encore, apprenez le langage de programmation G’mic. Pour ceux encore réticents à son apprentissage, il est possible d’assembler des filtres déjà existant en connaissant juste quelques trucs en plus.

2-Assembler des filtres

Après avoir utilisé le greffon, vous trouvez peut-être que ce serait bien si certains de vos filtres favoris pouvaient être assemblés afin de minimiser le nombre de clics. C’est d’une certaine façon possible.

2.1-Mimer un travail séquentiel

Si votre travail est purement séquentiel, c.à.d. si vous appliquez votre premier filtre sur une image, puis vous appliquez votre second filtre sur le résultat obtenu, etc. il est alors relativement facile de créer un filtre qui effectue les deux en un seul clic. Pour ça, vous devez récupérer les lignes de commandes exécutées par le greffon et les utiliser pour recréer un filtre comme expliqué au premier chapitre.
Par exemple, imaginons que vous vouliez assembler B&W pencil suivi de Soft glow (tous deux dans le répertoire Artistic folder). Pour récupérer la ligne de commande, la façon la plus facile est d’exécuter Gimp depuis un terminal et de régler les messages de sortie du greffon sur verbeux. Pour les 2 filtres en questions, vous obtiendriez dans votre console (ou votre fichier log) des lignes intéressantes comme:

[gmic_gimp]./apply/ -v -99 -gimp_pencilbw 0.3,60,0,0,0
[gmic_gimp]./apply/ -v -99 -gimp_glow 1,0,0

Votre nouveau filtre peut alors être écrit:

#@gimp BWpencil et Glow: bwpencil_glow, bwpencil_glow
bwpencil_glow :
  -gimp_pencilbw 0.3,60,0,0,0
  -gimp_glow 1,0,0

Et cela marche de la même façon avec 3, 4 et plus de filtres.

2.2-Proposer des réglages

Mais vous aurez remarqué (si vous l’avez essayé), il n’y a pas de réglages proposés dans l’assemblage de filtres. Pour en ajouter, vous devez faire comme expliqué ci-dessus. Ainsi, si vous voulez pouvoir régler la taille et l’amplitude pour B&W pencil et l’amplitude pour Soft glow, vous adapterez de cette façon:

#@gimp BWpencil and Glow: bwpencil_glow, bwpencil_glow
#@gimp : taillle = float(0.3,0,5)
#@gimp : Amplitude pour B&W pencil= float(60,0,200)
#@gimp : Amplitude pour Soft glow = float(1,0,20)
bwpencil_glow :
  -gimp_pencilbw $1,$2,0,0,0
  -gimp_glow $3,0,0

2.3-Assemblage complexe

Les choses deviennent plus compliquées quand vous gérer plusieurs images pendant la séquence de filtres que vous voulez assembler. Cela arrive, par exemple, si vous conservez l’original en réglant le Mode de sortie sur Nouveau(x) calque(s) (ou Nouveau(x) quoique ce soit) ou si un de vos filtres initiaux créent plusieurs images (comme Layers > Tiles to layers ou Layers > Split tones). Vous pouvez maitrisez cela en apprenant 2 autres petits trucs faciles du langage G’mic.

2.3.1-Conserver l’original

Jusqu’à maintenant, pour appeler une commande G’mic, vous mettiez un tiret (-) suivi du nom de la commande, par exemple:

  -gimp_pencilbw 0.3,60,0,0,0

Et bien, si vous mettez 2 tirets à la place, G’mic procède de la même façon avec les images, mais il conservera aussi l’original. Si vous essayez le filtre ci-dessous, même si vous réglez le Mode de sortie sur Sur place, vous obtenez votre résultats dans un nouveau calque:

#@gimp Keep BWpencil : keep_bwpencil, keep_bwpencil
keep_bwpencil :
  --gimp_pencilbw 0.3,60,0,0,0

2.3.2-Gérer plusieurs images

Pour gérer plusieurs images, G’mic leur donne des numéros commençant par 0. Donc, dans l’exemple précédent, votre image originale serait la numéro 0 et celle créée par le B&W pencil serait la numéro 1.
Si vous ne spécifiez rien, par défaut, la commande suivante est appliquée à toutes les images. Par exemple, dans le filtre qui suit, Soft glow est appliqué sur l’originale et sur celle provenant de B&W pencil.

#@gimp Keep BWpencil plus glow : keep_bwpencil_glow, keep_bwpencil_glow
keep_bwpencil_glow :
  --gimp_pencilbw 0.3,60,0,0,0
  -gimp_glow 1,0,0

Mais, si vous accolez le numéro de l’image entre crochets à votre nom de commande, alors le filtre ne sera appliqué qu’à l’image spécifiée. Ainsi, si vous modifiez le filtre précédent comme ci-dessous, le Soft glow n’est exécuté que sur l’image résultant de B&W pencil, laissant l’originale intacte:

#@gimp Keep BWpencil plus glow : keep_bwpencil_glow, keep_bwpencil_glow
keep_bwpencil_glow :
  --gimp_pencilbw 0.3,60,0,0,0
  -gimp_glow[1] 1,0,0

Vous pouvez spécifiquement demander à un filtre de s’exécuter sur plusieurs images en ajoutant d’autres nombres séparés par une virgule. Pour filtrer la première, la troisième et la cinquième, vous accoleriez [0,2,4] au nom de votre commande. Il y en plus à savoir à ce sujet.

2.3.2-Finissions ce machin

Au point où on en est, ce filtre me semble non-fini. J’ai l’impression qu’il pourrait être utile à quelqu’un si les 2 calques obtenus étaient recomposés ensemble avec une sorte de Layers Multiply et si quelques possibilités de réglage étaient offertes à l’utilisateur. Et puisque 2 filtres ont été construits pendant ce tutoriel, mettons-les tous les deux dans le fichier .gmic afin qu’ils puissent tous deux être utilisés dans le greffon. En totalité, cela ressemblera à quelque chose comme:

#@gimp Mon premier filtre: mon_premier_filtre_commande, mon_premier_filtre_commande
#@gimp : note = note("C'est mon premier filtre, je suis tellement excité!")
#@gimp : sep = separator()
#@gimp : Angle = float(45,0,360)
#@gimp : Remplir l'espace vide = choice("en noir","comme les bords","en répétant l'image")
mon_premier_filtre_commande :
  -rotate $1,$2

#@gimp Filtre du tutoriel  : filtre_tuto, filtre_tuto
#@gimp : Size = float(0.3,0,5)
#@gimp : Amplitude pour B&W pencil= float(60,0,200)
#@gimp : Amplitude pour Soft glow = float(1,0,20)
filtre_tuto :
  --gimp_pencilbw $1,$2,0,0,0
  -gimp_glow[1] $3,0,0
  -compose_multiply

2.4-Pour aller plus loin

Puisque qu’il s’agit de programmation, il est probable que vous rencontriez quelques bugs. Pour debugger, penser à régler les Messages de sortie sur Mode verbeux ou Très verbeux. Et ne restez pas bloqués seuls venez trouver inspiration et aide et partager ce que vous avez fait.
Une fois que vous aurez un peu jouer, vous voudrez peut-être apprendre quelques trucs en plus.

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 compulsory. 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.1-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.2-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.

Here, it is supposed that you read the previous article on the subject and are ready for more. The official goal is give tricks to make slicker and more reliable filters.

1-Better preview

1.1-Default zoom

You can specify what should be the default zoom for your preview by pasting a float number between parenthesis to the preview command at the first line end of your custom filter. Ex:

#@gimp Better Filter  : better_filter, better_filter_preview(0)

(0) means 1:1 preview, (1) means previewing the whole image, (2) means 1/2 image and so on…

1.2-Split preview

You must have seen that some filters propose a split preview, so you can accurately compare the existing image with the future filtered one. You can add this functionality to your filter if you:

1. add a new choice option dedicated to the preview type and
2. embed your filter command inside the -gimp_split_preview command.

The filter from the previous article would become:

#@gimp Better Filter  : better_filter, better_filter_preview(0)
#@gimp : Size = float(0.3,0,5)
#@gimp : Amplitude for B&W pencil= float(60,0,200)
#@gimp : Amplitude for Soft glow = float(1,0,20)
#@gimp : sep = separator()
#@gimp : Preview type = choice("Full","Forward horizontal","Forward vertical","Backward horizontal","Backward vertical")
better_filter :
  --gimp_pencilbw $1,$2,0,0,0
  -gimp_glow[1] $3,0,0
  -compose_multiply
better_filter_preview :
  -gimp_split_preview "-better_filter ${1--2}",$-1

Thanks to Editor B, CC-by

2-Multiple input management

2.1-A possible issue

As a user, if you have several layers and want to apply the filter above on each of them, you might feel natural to just set the Input layer option to All and proceed. But with the filter as it is right now, you won’t get the expected result.
This is because the -gimp_pencilbw and the -compose_multiply commands are applied on every layers without discernment. To address this issue, one solution is to create a loop inside which, each layer is considered one by one.

2.2-The saving loop

For that, you create a “-repeat ... -done” loop that runs as many times as you have layers. Then, inside that loop, you isolate the layer that has to be processed this time with a “-local ... -endlocal” block. The filter then becomes:

#@gimp Better Filter  : better_filter, better_filter_preview(0)
#@gimp : Size = float(0.3,0,5)
#@gimp : Amplitude for B&W pencil= float(60,0,200)
#@gimp : Amplitude for Soft glow = float(1,0,20)
#@gimp : sep = separator(), Preview type = choice("Full","Forward horizontal","Forward vertical","Backward horizontal","Backward vertical")
better_filter :
  -repeat @# -local[@{>,-1}]
  --gimp_pencilbw $1,$2,0,0,0
  -gimp_glow[1] $3,0,0
  -compose_multiply
  -endlocal -done
better_filter_preview :
  -gimp_split_preview "-better_filter ${1--2}",$-1

The variable @# returns the number of layers. If you have 3 layers the code inside the loop will be run 3 times.
The variable ~> is the counter telling you how many times the loop has been run so far. So, for 3 layers, it takes successively the values 0,1,2.
Only one layer enter the “-local[~>] ... -endlocal” block, and inside that block, it is considered as being number [0].

3-Sort out your filters

Having many custom filters in your .gmic file can create a mess in your plug-in window. To sort out that, you can create directories! The next line means : “everything that follows will be placed in the directory called: My Directory”

#@gimp My Directory

Whereas that one means : “everything that follows will be in the parent directory”

#@gimp _

So put the first one at the top of your .gmic file and the second one at the bottom and things are sorted out.

This tutorial intends to show how to create a so called user-defined filter in the G’mic plug-in for Gimp. It supposes that you don’t know anything in the G’mic command line language.

You can find some quick informations on how to make such a filter close to the beginning of the default custom command file and directly in the plug-in at About > Filters design and here below.

Below, you will be first invited to create a pretty simple filter to understand the basis and then the purpose will be to assemble different filters in order to create a better one.

1-My first filter

1.1-The user-defined filter file

All the user-defined filters that you make have to be written in one single text file called “.gmic” under linux or MacOS and only “gmic” under Windows (there’s a dot at the start of the filename under linux or MacOS, not under Windows). You need to create that file in your home directory if you are under linux or MacOS and in your Application Data folder if your are under Windows. For those having difficulties to create a file beginning with a dot under MacOS, use TextEdit.

1.2-The filter appears

To appear in the plug-in, you should include a line starting by #@gimp giving your filter’s name, the command name associated with that filter and optionally, a command name to create the preview. Something like that:

#@gimp My first filter: my_first_filter_command, my_first_filter_command_preview

You can try, put it in your .gmic file, refresh the G’mic filter and it should appear at the top of the available filters.

1.3-The filter says something

In the right part of the plug-in window, you can put text and propose different kinds of variables that can be used by the filter command. For that you need again lines beginning by #@gimp. As an example, you can paste the lines below in your .gmic file and refresh your filter.

#@gimp My first filter: my_first_filter_command, my_first_filter_command
#@gimp : note = note("It is my first filter, I am so excited!")
#@gimp : sep = separator()
#@gimp : Angle = float(45,0,360)
#@gimp : Fill the empty space = choice("in black","like the borders","by repeating the image")

1.4-The filter does something

So far, your filter doesn’t work, If you click on apply, an error message will appear. It is because no command is called “my_first_filter_command“, it has to be created using the G’mic command line language. So, our first filter can be completed with 2 more lines to become:

#@gimp My first filter: my_first_filter_command, my_first_filter_command
#@gimp : note = note("It is my first filter, I am so excited!")
#@gimp : sep = separator()
#@gimp : Angle = float(45,0,360)
#@gimp : Fill the empty space = choice("in black","like the borders","by repeating the image")
my_first_filter_command :
  -rotate $1,$2

if you put that in your .gmic file and refresh once again the filter, you now have a fully functional filter able to rotate an image. You can adjust the rotation angle from 0 to 360° and the default proposed value is 45. You have 3 choices to “fill the empty space”.

The command used for your filter is called “my_first_filter_command” and it is a quite simple command that use the -rotate instruction and the two variables $1 and $2 refer to the 2 ones proposed above: “angle” and “fill the empty space”.

1.5-The filter does what you want

Now you know the basis, you just have to get inspired by the already available filters and their source code and if you don’t already know it, learn the G’mic programming language. For those of you still reluctant to learn it, by just knowing a few more things, it is possible to assemble already existing filters.

2-Assembling filters

After some use of the G’mic plug-in, you might feel that it would be great if some of your favorite filters would be assembled together in order to minimize the number of click. It is somehow possible.

2.1-Mimic a sequential work

If your work is purely sequential, i.e. you apply the first filter on an image, then you apply the second filter on the result etc. then it is relatively easy to create a filter that do both in just one click. For that, you need to get the command lines run in the background of the plug-in and use them to recreate a filter as explained in the first chapter.

For example, let’s imagine that you want to assemble B&W pencil followed by Soft glow (both in the Artistic folder). To get the command lines run for those filters, the easiest way is to run gimp from a terminal and to set the plug-in to verbose. For the 2 filters, you would get in your terminal some interesting lines like:

[gmic_gimp]./apply/ -v -99 -gimp_pencilbw 0.3,60,0,0,0
[gmic_gimp]./apply/ -v -99 -gimp_glow 1,0,0

Then your new filter can be written:

#@gimp BWpencil and Glow: bwpencil_glow, bwpencil_glow
bwpencil_glow :
  -gimp_pencilbw 0.3,60,0,0,0
  -gimp_glow 1,0,0

And it works the same with 3, 4 and more filters.

2.2-Propose some settings

But you might have noticed (if you tried it), there is no setting proposed in the assembled filter. To add some, you need to do as explained above. Thus if you want to be able to set the size and amplitude for the B&W pencil and the amplitude for the Soft glow, you would adapt the filter this way:

#@gimp BWpencil and Glow: bwpencil_glow, bwpencil_glow
#@gimp : Size = float(0.3,0,5)
#@gimp : Amplitude for B&W pencil= float(60,0,200)
#@gimp : Amplitude for Soft glow = float(1,0,20)
bwpencil_glow :
  -gimp_pencilbw $1,$2,0,0,0
  -gimp_glow $3,0,0

2.3-Complex assembling

Things become more complex when you have to deal with several images during the filter sequence that you want to assemble. It happens if you keep the original by setting the Output mode to New layer (or New whatever) or if one of your original filters creates several images (as Layers > Tiles to layers or Layers > Split tones). You can master that by just learning 2 easy more things from the G’mic language.

2.3.1-Keeping the original

So far, to call a G’mic command, you write a dash (-) followed by the command name, for example:

  -gimp_pencilbw 0.3,60,0,0,0

Well, if you put 2 dashes instead, G’mic processes the image the same way, but it also keeps the original. If you try the filter below, even if you set the Output mode to In place, you get your result in a new layer:

#@gimp Keep BWpencil : keep_bwpencil, keep_bwpencil
keep_bwpencil :
  --gimp_pencilbw 0.3,60,0,0,0

2.3.2-Dealing with several images

When it deals with multiple images, G’mic gives them numbers starting from 0. So in the previous example, your original image would be the number 0 and the B&W pencil processed one would be the number 1.

If you don’t specify anything, by default, the next command apply to every images. For instance, in the next filter, Soft glow is applied to the original and to the B&W pencil processed ones.

#@gimp Keep BWpencil plus glow : keep_bwpencil_glow, keep_bwpencil_glow
keep_bwpencil_glow :
  --gimp_pencilbw 0.3,60,0,0,0
  -gimp_glow 1,0,0

But, if you paste the image number into square brackets to your command name, then the process will apply only to the specified image. Thus, if you modify the previous filter as below, the glow is only performed on the B&W pencil processed image, leaving the original untouched:

#@gimp Keep BWpencil plus glow : keep_bwpencil_glow, keep_bwpencil_glow
keep_bwpencil_glow :
  --gimp_pencilbw 0.3,60,0,0,0
  -gimp_glow[1] 1,0,0

You can ask to specifically process several images by adding numbers separated by a comma. To process the first, the third and the fifth one, you would paste [0,2,4] to the command name. There is more you might want to know about that.

2.3.2-Let’s finish that

This last filter seems so far unfinished to me, I feel that it could be useful to someone if the two layers obtained were composed together with some kind of Layers Multiply and if some tweaking possibilities was offered to the user. And since 2 filters were built during this tutorial, let’s place them both in the .gmic file, so that both can be used in the plug-in. The whole thing becomes then something like:

#@gimp My first filter: my_first_filter_command, my_first_filter_command
#@gimp : note = note("It is my first filter, I am so excited!")
#@gimp : sep = separator()
#@gimp : Angle = float(45,0,360)
#@gimp : Fill the empty space = choice("in black","like the borders","by repeating the image")
my_first_filter_command :
  -rotate $1,$2

#@gimp Filter tutorial : filter_tuto, filter_tuto
#@gimp : Size = float(0.3,0,5)
#@gimp : Amplitude for B&W pencil= float(60,0,200)
#@gimp : Amplitude for Soft glow = float(1,0,20)
filter_tuto :
  --gimp_pencilbw $1,$2,0,0,0
  -gimp_glow[1] $3,0,0
  -compose_multiply

2.4-Further

Since this is programming, you are ought to meet some bugs. To debug, think about running gimp from the terminal and set the Output messages to Verbose or Very verbose. And don’t stay stuck alone, get inspired, get help and share what you’ve made.
Once you’ll have played a bit, you might want to learn a few more tricks for your filters.

Une image matricielle est matrice de pixels qui suit les règles de son format. Avec jusqu’à 4 canaux définissant la couleur d’après l’espace de couleur (RVB, CMJN, …) et des entiers de 0 à 255 ou à 65535, cela dépend du nombre de bits.
Mais une fois que G’mic prend l’image en charge, elle devient une matrice 4D de nombres à virgule sans réelle limitation. Cela signifie que durant la manipulation G’mic, vous pouvez avoir des nombres négatifs, des valeurs extrêmement hautes ou basses, des canaux par douzain, etc. Sensations de liberté…
Mais vous aurez peut-être aussi parfois la sensation d’être perdu, parce que vous aurez des difficultés à faire rerentrer votre image dans le monde contraignant des formats d’image, à moins que vous ne soyez au courant de ce qui suit.

1-Les canaux

1.1-Trois canaux dans le visionneur

Le visionneur de G’mic n’est pas pensé pour l’affichage de l’image, mais pour l’affichage d’informations de cette matrice 4D. Il ne montre que les 3 premiers canaux et considère que l’image est en RVB. Donc, si vous manipulez une image en CMJN, le canal N est ignoré et le reste aura l’air plutôt étrange. Si vous chargez une image avec transparence, vous ne la verrez pas.
Vous pouvez visualiser le quatrième canal en utilisant, par exemple, la commande -channels:

gmic mon_image.jpg -channels 3

Vous pouvez aussi demander à G’mic de simuler la transparence du quatrième canal sous forme de damier:

gmic mon_image.jpg -display_rgba

1.2-Combien de canaux dans quel format?

La façon dont vous arriverez à faire rentrer tous les canaux dans le fichier que vous avez l’intention de créer dépend du format d’image utilisé. G’mic tente de placer autant de canaux que le format peut en contenir et fait disparaître les autres. Et la signification des différents canaux dépend du format utilisé. Par exemple, 4 canaux dans un JPEG sera interprété comme une image CMJN alors que 4 canaux dans un PNG constituera un RGBA. Pour être sûr de ce que vous obtenez finalement, utilisez un visionneur « conventionnel » ou utilisez ImageMagick:

identify -verbose mon_image.jpg |grep Colorspace

récupérez Tux avec gmic tux_rgb.png -split x,3 -+, LGPL

2-Les nombres

2.1-Montrer n’importe quel nombre

Puisque virtuellement, n’importe quel nombre peut être contenu dans la matrice, le visionneur G’mic gère ce point en considérant le plus grand nombre comme le plus lumineux et le plus petit comme le plus sombre, puis il étire linéairement ce qu’il reste entre les 2. Il faut donc faire attention quand vous utilisez des algorithmes qui retournent des valeurs non conventionnelles. Par exemple:

gmic mon_image.jpg -luminance -threshold 120

affichera une image en noir et blanc, mais comme la commande -threshold ne retourne que des 0 ou des 1, si vous exportez ça dans un format conventionnel, vous obtiendrez une image très foncée. Ça se gère habituellement en étirant les valeurs entre 0 et 255 avec -normalize:

gmic mon_image.jpg -luminance -threshold 120 -normalize 0,255

D’autres manipulations peuvent localement introduire des valeurs extrêmes. Si vous faites:

gmic mon_image.jpg -unsharp_octave 2,2

Vous obtiendrez des valeurs comme -250 ou 450 sur un très faible nombre de pixels, votre image apparaîtra donc bien grise dans le visionneur G’mic. Rasez tout ça avec -cut:

gmic mon_image.jpg -unsharp_octave 2,2 -cut 0,255

Encore un commentaire sur le sujet, il est possible d’éviter l’étirement des valeurs dans le visionneur G’mic: -display0.

2.2-Ce que ça devient dans le fichier

Si toutes les valeurs sont contenues dans l’intervalle [0,255], G’mic se contentera d’arrondir à l’entier le plus proche et produira une image 8 bits. Mais si une seule valeur sort de ces limites, il produira une image 16 bits si le format le permet et/ou transformera les mauvaises valeurs en brouillard parasite afin que ça rentre dans les limites. ImageMagick peut vous aider à savoir ce qu’il s’est passé:

identify -verbose mon_image.jpg |grep bit

A partir de Troy Holden, CC-by-nc-nd

3-Encore quelques petites choses à propos de formats

3.1-A propos de Tiff

Le format TIFF est supposé accepter les nombres réels, donc G’mic n’hésite pas à les en mettre dedans. Mais en pratique, il est difficile de trouver un visionneur capable de lire de tels TIFF. Pour éviter les soucis de ce genre, vous devriez ajouter -type uchar avant d’exporter en TIFF. La commande précédente deviendrait:

gmic mon_image.jpg -unsharp_octave 2,2 -type uchar -o mon_image.tiff

3.2-About Raw

G’mic sait gérer le raw, mais vous devez faire attention au type et aux dimensions vous-même. Par exemple, pour charger une image 8 bit de dimension 1000x1000x200, utilisez la commande:

gmic -type uchar mon_image.raw,1000,1000,200

3.3-Formats natifs: CIMG et CIMGZ

Les formats natifs de G’mic sont le CIMG et son analogue compressé, le CIMGZ. Donc, si vous avez besoin de stocker votre image au cours d’une manipulation, il est conseillé de le faire dans l’un de ces formats pour éviter de perdre des informations à travers les contraintes habituelles. Ex:

gmic mon_image.jpg -unsharp_octave 2,2 -o mon_image.cimg

gmic mon_image.jpg -unsharp_octave 2,2 -o mon_image.cimgz

3.4-Formats texte

Una autre façon de conserver toutes les informations est d’utiliser un format texte (TXT ou DLM). De cette façon, vous serez même capable d’utiliser un éditeur de texte pour modifier votre image:

gmic mon_image.jpg -unsharp_octave 2,2 -o mon_image.txt

gmic mon_image.jpg -unsharp_octave 2,2 -o mon_image.dlm

3.5-Entrée/sortie standard

Vous pouvez aussi lire à partir de l’entrée standard ou écrire sur la sortie standard. Les deux commandes ci-dessous sont identiques. Elle demandent à G’mic de lire l’entrée standard au format texte:

echo -e "1 2 3\n4 5 6" | gmic -.txt
echo -e "1 2 3\n4 5 6" | gmic txt:-

Les deux commandes ci-dessous écrivent sur la sortie standard au format texte:

gmic image.jpg -o -.txt
gmic image.jpg -o txt:-

Avant d’être un populaire greffon pour Gimp, G’mic est un logiciel en ligne de commande dédié au traitement d’images. Ce tutoriel suppose que les lignes de commande sont tapées dans un terminal Unix. Les utilisateurs de Windows devront s’adapter et voudront peut-être installer MinGW. Il est aussi possible de tester les notions développées ici dans un filtre prévu pour le greffon.

gmic -instruction1 arguments -instruction2 arguments etc...

gmic -input image.jpg -rotate 90 -output image.png

[gmic]-0./ Start G'MIC instance.
[gmic]-0./ Input file 'image.jpg' at position [0] (1 image 512x384x1x3).
[gmic]-1./ Rotate image [0] of 90 deg., black borders and linear interpolation.
[gmic]-1./ Output image [0] as file 'image.png'.
[gmic]-1./ End G'MIC instance.

gmic -i image.jpg -rotate 90 -o image.png

gmic image.jpg -rotate 90 -o image.png

gmic image.jpg -o image.bmp -rotate 90 -o image.png -o image.tga

gmic image.jpg -rotate 45
gmic image.jpg -rotate 45 -display

4-Les arguments de l’instruction

Depuis le début, l’image effectue des rotations, uniquement des rotations. Mais comme la plupart des instructions G’mic, l’instruction -rotate possède de nombreux arguments afin de spécifier la façon dont doit se passer cette la rotation. Si vous regardez, la page de documentation officielle, vous trouverez la ligne expliquant comment -rotate fonctionne. Ça commence par:

gmic image.jpg -rotate 30,1
gmic image.jpg -rotate 30,0,0,50%,50%
gmic image.jpg -rotate 30,0,0,0%,0%,0.5

5-Gestion de plusieurs images

5.1-Toutes comme une

gmic image1.jpg image2.jpg image3.jpg
gmic image*.jpg

gmic image*.jpg -rotate 90 -o image.png

5.2-Restreindre l’instruction à seulement quelques images

gmic image*.jpg -rotate[0] 90

gmic image*.jpg -o[1] image.png

gmic image*.jpg -rotate[-1] 90

gmic image*.jpg -rotate[-2] 90

Modifié de Rantz, CC-by-nc-sa

5.3-Conserver l’original

Par défaut, une instruction remplace l’image originale by celle manipulée. il y a une façon de conserver l’originale: utiliser le double tiret (- -). Ex:

gmic image.jpg --rotate 90

produit 2 images: image.jpg et image.jpg tournée de 90°. Plus de détails sont disponibles ici.

5.4-Manipuler la liste d’images

gmic image*.jpg -move[50%-100%] 0

gmic image*.jpg -reverse

gmic -command mon_fichier_de_commande_personnalisee.gmic image.jpg -my_command
gmic -m mon_fichier_de_commande_personnalisee.gmic image.jpg -my_command
gmic mon_fichier_de_commande_personnalisee.gmic image.jpg -my_command

7-Aller plus loin

Pour aller plus loin, il peut sembler logique de consulter cet article. Puis, pour augmenter votre culture G’mic, vous devriez sans doute cliquer sur les images de la galerie et pour maitriser la technique, n’oubliez pas le fichier de commandes personnalisées.
Vous êtes aussi invités à partager vos problèmes et vos solutions au forum(en).

De Rantz, CC-by-nc-sa

A raster image is a pixel matrix, that follows its format rules, with up to 4 channels setting the color according to the colorspace (RGB, CMYK, …) and with integers from 0 to 255 or to 65535, it depends on the number of bits.

But once an image enter G’mic, it becomes a 4D floating-point number matrix with no real limitation. It means that during the G’mic process, you can have negative numbers, extremely high or low values, dozens of channels… feel the freedom.

And then you might feel lost, because you might have difficulties to have your picture reenter the constrained world of image formats, unless you are aware of what is said below.

1-Channels

1.1-Three channels in the viewer

The G’mic viewer isn’t meant to show the picture, it is meant to show information about this 4D matrix. It only shows the 3 first channels and considers them as RGB. So, if you play with a CMYK picture, the K value will be ignored and the rest will look weird. If you had loaded an image with transparency, you would not see it. You can visualize the fourth channel using, for example, the -channels command:

gmic my_image.jpg -channels 3

You can also specifically ask the viewer to mimic transparency for the fourth channel by adding some checker board:

gmic my_image.jpg -display_rgba

1.2-How many channels in that format?

The way all your channels fits in the file you intend to create depends on the format used. G’mic tries to fit as many channels as the format accepts and discard the others and what means the channels that fit depends on the format. For example, 4 channels into a JPEG are understood as a CMYK file whereas 4 inside a PNG are understood as RGBA. To be sure of what you finally get, use a « conventional » viewer or use ImageMagick:

identify -verbose my_image.jpg |grep Colorspace

get Tux back with gmic tux_rgb.png -split x,3 -+, LGPL

2-Numbers

2.1-Show any number

Since virtually any number can be contained in the matrix, the G’mic viewer is dealing with that by considering the highest value as the brightest and the lowest one as the darkest and by stretching linearly all the rest in between. So be careful when you use algorithms that return unconventional values. For instance:

gmic my_image.jpg -luminance -threshold 120

will display a black and white picture, but since the -threshold command returns only 1 or 0, if you output that in any conventional image format, you’ll get a pretty dark image. The usual way to circumvent this is to stretch values from 0 to 255 with -normalize:

gmic my_image.jpg -luminance -threshold 120 -normalize 0,255

Some other processing might introduce localized extreme values. If you do:

gmic my_image.jpg -unsharp_octave 2,2

You’ll get values such as -250 or 450 in very few pixels, your image will thus appear quite gray in the G’mic viewer. Shave this with -cut:

gmic my_image.jpg -unsharp_octave 2,2 -cut 0,255

Last comment on this, there is a way to avoid G’mic viewer stretching: -display0.

2.2-What it becomes in the file

If everything belongs to the [0,255] interval, then G’mic will just round all that to get integers and produce an 8 bit image. But if any number exits these limits, it will produce a 16 bit image if the format allows it and/or transform wrong numbers in garbage to fit into the limits. ImageMagick can tell you what happened:

identify -verbose my_image.jpg |grep bit

From Troy Holden, CC-by-nc-nd

3-A few other things about formats

3.1-About Tiff

The TIFF format is supposed to accept floating point numbers, so G’mic doesn’t hesitate to stuff them in it. But in practice, it is difficult to find a viewer that can read such TIFF. To avoid issues about it, you should add -type uchar before outputing. The previous example would become:

gmic my_image.jpg -unsharp_octave 2,2 -type uchar -o my_image.tiff

3.2-About Raw

G’mic is able to deal with raw format, but you should take care of type and image dimensions yourself. For example, to load an 8 bit with dimensions 1000x1000x200, you would do:

gmic -type uchar my_image.raw,1000,1000,200

3.3-Native formats: CIMG and CIMGZ

The native G’mic format is CIMG and its analogous compressed CIMGZ. So, if you need to store your image in a middle of a process, it is advised to store it in one of these formats to avoid loosing information via usual formats constraints. Ex:

gmic my_image.jpg -unsharp_octave 2,2 -o my_image.cimg

gmic my_image.jpg -unsharp_octave 2,2 -o my_image.cimgz

3.4-Text formats

Another way to keep all informations is to use a text format (TXT or DLM). This way, you will even be able to use text editor to modify your picture:

gmic my_image.jpg -unsharp_octave 2,2 -o my_image.txt

gmic my_image.jpg -unsharp_octave 2,2 -o my_image.dlm

3.5-Standard input/output

You can also read from the standard input or write to the standard output. Both commands below are identical. They tell G’mic to read from the standard input in text format:

echo -e "1 2 3\n4 5 6" | gmic -.txt
echo -e "1 2 3\n4 5 6" | gmic txt:-

To tell G’mic to write an image to the standard output in text format, it would one of those:

gmic image.jpg -o -.txt
gmic image.jpg -o txt:-

The G’mic plug-in for Gimp is based on the G’mic language. Each filter proposed in the plug-in corresponds to a G’mic command line, each setting is just a parameter of that command line. And command lines are great because :

1. it is a way to remember settings and filter sequences,
2. it allows to (almost) effortlessly apply on a large set of images what you just did graphically.

Anything said below supposes that you run some kind of linux, but the spirit of it apply under other OS too.

1-How to get the command lines?

To have the plug-in tells you what you do graphically in the command line language, you just have to start Gimp from a terminal and to set it to “verbose mode”.

To start from a terminal, just open a terminal and type :

gimp

To set it to “verbose mode”, once you have open the plug-in, set the “ouput messages…” menu on the left to “Verbose”.

From now on, you’ll see text appearing in the terminal each time G’mic adapt the preview to your new setting and each time you apply a filter on your image.

Image from PhotoComiX, CC-by-nc

2-What it looks like?

Two kind of lines appear in the terminal. The ones telling what command is used to create the preview (containing the /preview/ sequence) and the ones telling what command is really applied on the picture (containing the /apply/ sequence). You are probably only interested in the last kind.

For example, the line:

[gmic_gimp]./apply/ -v -99 -gimp_mix_rgb 1,0,0,1,0,0,1,0,0,0,2,0

tells that the command called was gimp_mix_rgb and all the numbers behind correspond to the settings.

3-What to do with it?

You could just be happy to know what happens and to be able to keep everything in a text file with a simple copy/paste, but you could also want to apply it in a terminal. Just go to the directory where your file (say image.jpg) is and type:

gmic image.jpg -gimp_mix_rgb 1,0,0,1,0,0,1,0,8.5,0,2,0

Your processed image will be displayed, but not saved.
To save it instead of displaying it:

gmic image.jpg -gimp_mix_rgb 1,0,0,1,0,0,1,0,8.5,0,2,0 -o processed_image.jpg

If you have many images (whose names finish by jpg) that you want to be processed, a script like that should do it:

for i in *jpg
do
gmic $i -gimp_mix_rgb 1,0,0,1,0,0,1,0,8.5,0,2,0 -o processed_$i
done

Image Wikimedia

4-By the way

If you only want the “interested” lines to appear in your terminal, you should run Gimp with this command instead:

gimp |grep apply

Before being a popular Gimp plugin, G’mic is a command line tool devoted to image manipulation. This tutorial assumes that commands are given on a Unix shell command line. Windows user will have to adapt, and might want to install MinGW to be more comfortable with command line use. It is also possible to test notions explained here below in a script built for the plug-in.

gmic -instruction1 arguments -instruction2 arguments etc...

gmic -input image.jpg -rotate 90 -output image.png

[gmic]-0./ Start G'MIC instance.
[gmic]-0./ Input file 'image.jpg' at position [0] (1 image 512x384x1x3).
[gmic]-1./ Rotate image [0] of 90 deg., black borders and linear interpolation.
[gmic]-1./ Output image [0] as file 'image.png'.
[gmic]-1./ End G'MIC instance.

gmic -i image.jpg -rotate 90 -o image.png

gmic image.jpg -rotate 90 -o image.png

gmic image.jpg -o image.bmp -rotate 90 -o image.png -o image.tga

gmic image.jpg -rotate 45
gmic image.jpg -rotate 45 -display

4-The arguments of the instruction

Since the beginning, the image is rotated, just rotated, but like most G’mic instructions, the -rotate instruction possesses many arguments to rotate in a specific way. If you look at the official reference page, you’ll find the lines explaining how -rotate works. It begins by:

gmic image.jpg -rotate 30,1
gmic image.jpg -rotate 30,0,0,50%,50%
gmic image.jpg -rotate 30,0,0,0%,0%,0.5

5-dealing with several images

5.1-Many just like one

gmic image1.jpg image2.jpg image3.jpg
gmic image*.jpg

gmic image*.jpg -rotate 90 -o image.png

5.2-Restricting an instruction to only some images

gmic image*.jpg -rotate[0] 90

gmic image*.jpg -o[1] image.png

gmic image*.jpg -rotate[-1] 90

gmic image*.jpg -rotate[-2] 90

Modified from Rantz, CC-by-nc-sa

5.3-Keeping the original with double dash

By default, an instruction replace the original image by the processed one. There is a way to keep the original: use a double dash (- -). Ex:

gmic image.jpg --rotate 90

produces 2 images: the untouched image.jpg and the rotated image.jpg. More details are avalaible.

5.4-Manipulating the image list

gmic image*.jpg -move[50%-100%] 0

gmic image*.jpg -reverse

gmic -command my_custom_command_file.gmic image.jpg -my_command
gmic -m my_custom_command_file.gmic image.jpg -my_command
gmic my_custom_command_file.gmic image.jpg -my_command

7-Going further

Logically following this tutorial is that article. Then, to increase your G’mic culture, you should probably click on gallery’s images and to master the technique, don’t forget the custom command file.
You are also invited to share your problems and solutions at the forum.

From Rantz, CC-by-nc-sa