Tutorial

# Command Line: First Steps

### 0-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 will have to adapt, and might want to install MinGW to be more confortable with command line use.
G'MIC works also with Windows, but the interaction with the shell might work a little different in that case. The tutorial assumes version 1.3.3.3 of G'MIC.
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.

### 2-Aliases

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`

#### 3.1-Formats

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, wich is probably more than what you'd want. To save at quality 95, use `-o image.jpg,95`

#### 3.2-Display

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`
Now, it should be a lot easier for you to use this official reference page. You can also get it 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 the 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.

#### 5.3-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%] 1` | 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-macros

`gmic -m my_macro-file image.jpg -my_rotate` `Many macros already exist:` http://cimg.cvs.sourceforge.net/*checkout*/cimg/CImg/examples/gmic_def.raw

#### 7-going further

check that:
http://gmic.sourceforge.net/gallery.shtml http://cimg.cvs.sourceforge.net/*checkout*/cimg/CImg/examples/gmic_def.raw
be careful that you should backslash special character in your terminal, thus "(" becomes "\(", ";" become "\;", "[" becomes "\[".
to test macros, you can put back the verbose mode by copying the custom command in a macro file and removing "-v -"
CC-BY-SA
bad English?
rough aesthetics?
less clear than unclear?
need to talk?
zonder #@# tuxfamily.org