Archive for the ‘ en ’ Category

About the image stack

1.Initial stack

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


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

Custom command for the command line


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

G’mic : Making better custom filters


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

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 and format

0-Irrelevant introduction

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

G’mic: The command line behind the Gimp plug-in

0-Expendable introduction

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 :


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
gmic $i -gimp_mix_rgb 1,0,0,1,0,0,1,0,8.5,0,2,0 -o processed_$i

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

G’mic Command Line: First steps

0-Unnecessary introduction

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.

Every G’mic command line formally looks that way:

gmic -instruction1 arguments -instruction2 arguments etc...

Everything is explained in the official reference page. But anyone human would need some more developed explanations. Here are some.

1-A basic example

Before applying any treatment on an image, G’mic has to load it with the -input instruction. After any treatment being applied, you might want to unload the final result on your hard disk with the -output instruction.

Let’s use a basic example. To rotate 90° an image called image.jpg and get the result as a PNG file called image.png, you’d use the following command:

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

You’ll notice that G’mic returns in your terminal the details of all the operations that occurred. For the previous command line, you should have had something like:

[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.

So you won’t be able to say that you didn’t know what happened.


From Rantz, CC-by-nc-sa


In order to save typing time, the most common instructions have aliases. For example, -input can be replaced by -i and -output by -o. So, our basic example can be rewritten as:

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

In fact, the -input instruction is that common that an even faster way to invoke it has been implemented in G’mic: just type the image name directly without any instruction before. Indeed, the next command line is the exact equivalent to the previous one:

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

Don’t expect more, this is as fast as it can get.

3-Details about -output


You can get an output anytime in the command line (before or after an operation) and the name of the output file determine the format. For instance, with the following command line, you get 3 images in 3 different formats, the BMP one has not undergone any rotation, the other ones have.

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

By the way, by default, G’mic saves JPEG files with quality 100, which is probably more than what you’d want. To save at quality 95, use -o image.jpg,95


If you don’t specify any -output (or -o) instruction or if you explicitly give the -display instruction, then G’mic will display your image on the screen. The 2 next command lines do the same thing: they display the image after a 45° rotation:

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

press ‘q’ to quit the display screen.

There is actually a lot to say about the display screen, but it won’t be said now.

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:

-rotate angle,_borders,_interpolation,_cx[%],_cy[%],_zoom

This means that -rotate may have until 6 arguments. The first one (angle) has to be specified. The other ones begin by an underscore, it means that they are optional. Just make some tests and you’ll understand how it works. For example, try these lines:

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

You can also get that off-line with man gmic or gmic -h.

5-dealing with several images

5.1-Many just like one

You can deal with many images at a time, just load them all. For example, the following command lines load the images and display them:

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

If you write your command lines as in the previous chapter, then G’mic instructions are applied on every loaded images. By using the next command line:

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

you tell G’mic to rotate all the image*.jpg files and to save them as a png file. But it won’t save several images in one file called image.png, it will name them image_000001.png, image_000002.png, image_000003.png, etc.

5.2-Restricting an instruction to only some images

You can specify on what images applying an instruction by adding the image number, starting by 0 under brackets:

gmic image*.jpg -rotate[0] 90

only rotates the first loaded image.

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

saves only the second one as image.png.

If you use negative numbers, you start by the last one:

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

only rotates the last loaded image.

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

only rotates the second last one.
You can also select a set of images to manipulate:

gmic image*.jpg -rotate[0,2,-1] 90 rotates the first, the third and the last one.
gmic image*.jpg -rotate[0-9] 90 rotates the 10 first images.
gmic image*.jpg -rotate[0-9:3] 90 rotates every 3 images starting from the first one and finishing at the tenth one. It means the first, the fourth, the seventh and the tenth one.
gmic image*.jpg -rotate[0,-4--1] 90 rotates the first and the 4 last ones.
gmic image*.jpg -rotate[50%-100%] 90 rotates the second half of the image list.
gmic image*.jpg -rotate[0,50%--1] 90 rotates the first image and the second half of the image list.

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

As you have seen in the previous chapter, the image order is important. You can change that order at any time by using -move or -reverse:

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

moves the second half of the image list at the beginning

gmic image*.jpg -reverse

reverses the order of all the images.
You can also keep only some of the images in your list with -keep or get rid of some with -remove. If you feel lost sometime, check what G’mic returns in your terminal, it should tell you how many images are left.

6-Custom commands

Once you begin to play around with G’mic, command lines can become pretty long. A solution is to write things in a custom command file. Many custom commands already exist, you can study and learn from them. It would probably help to get some more explanation on the art of writing custom commands but you won’t find them here. All that will be said is that if you need to load your custom command file before using it.

This is done with the instruction -command or -m or even without any instruction if your file finishes by .gmic. So, the three followings lines do the same thing:

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