Archive for November, 2010

How to create a custom filter in the G’mic plug-in


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


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.


G’mic: Image et format


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:-