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

0-Introduction

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.

About these ads
  1. Near perfect ! as always…

    • PhotoComix
    • November 17th, 2010

    Thank a lot Zonderr
    It is really clear, this said by a old artist that has not any confidence with command line, that never used command line if not when strictly needed, and then only to paste.

    I just finished to fight with the terminal 1 hour fight to discover that “verbose” need 2″–” with only 1″-” does something else.

    Anyway everything is ready now (even a screen recorder)
    ..i will let you know the result

    Thank again

    PhotoComix

  2. Thanks everyone.

    @ PhotoComix : i don’t really understand you issue, but I guess it’s all right.

    • mahvin
    • November 23rd, 2010

    Thanks a ton, zonderr! It was really helpful!

    • PhotoComix
    • March 21st, 2011

    i was just looking in the -rotate command ,the same used in your very first example

    i saw in the reference that .rotate took 5 arguments ” why your command works with only 1 command

    (i know it works i would like know why or more exactly i would like to know when arguments may be facultative and not compulsory

  3. @Photocomix: actually -rotate takes 6 arguments:
    angle,_boundary,_interpolation,_cx[%],_cy[%],_zoom

    but arguments with underscore are not compulsory, there are default value: ‘boundary=0′, ‘interpolation=1′, ‘cx=cy=(undefined)’ and ‘zoom=1′.

    • PhotoComix
    • March 21st, 2011

    ahh maybe i guess it , if there is indicate a “default” the corresponding argument may be optional

    • lousiewhei
    • January 21st, 2013

    I am using GIMP 2.8.2, installed G’MIC 1.5, running in Windows 7 32 bits environment. So where should place the ‘.gmic’ file? I have problem placing the dot ‘.’ in front of a filename in AppData\Roaming.

  4. Hi lousiewhei,

    there is mistake: under windows, the file should be called ‘gmic’ without any dot and be placed in the %APPDATA directory. I don’t know where is that directory in your version of Windows.

    I will update the page asaic.
    Update: updated.

  1. January 2nd, 2011
  2. February 7th, 2011
  3. February 11th, 2011
  4. February 11th, 2011

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

%d bloggers like this: