Introduction to the G'MIC command line tool 'gmic' - GreycLab/gmic-community GitHub Wiki

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.

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.

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.

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.

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.

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.

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:

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.

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.

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

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)[http://cimg.cvs.sourceforge.net/viewvc/cimg/CImg/examples/gmic_def.gmic]. You are also invited to share your problems and solutions at the forum.