## Introduction

G'MIC is an image processing framework, and as such it can be used for image
processing of many different kinds of images. Not all kinds of image
processing concerns photographic images, but this tutorial will deal with
photographic  images. Some examples will use a special type of photographic
images, images in  [raw image
format](http://en.wikipedia.org/wiki/Raw_image_format), as they can  be
captured in modern digital SLR cameras. Such images always requires special
processing before they can be displayed on the screen, and much of this
processing can be performed by G'MIC. Usually this processing is delegated to
a  category of programs called raw converters, and in this tutorial a command
line  raw converter called [dcraw](http://en.wikipedia.org/wiki/Dcraw) will be
used. 

This tutorial assumes that commands are given on a Unix shell command line.
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.

G'MIC is a project and the command line program is called gmic. It is a kind of 
command parser, which reads images and applies image commands to them. The 
easiest way to use it is simply applying it to an image:


	gmic image.jpg


This will display the file image.jpg given as argument, using a simple built-in 
image viewer. This viewer is good for many purposes because it shows the image 
as-is without interpolation - it is showing the actual pixels as you zoom in 
rather than smooth them out. The strength of gmic lies deeper though. For 
example, imagine you want to shrink the above image:


	gmic image.jpg -resize 400,400 -output resized-image-1.jpg

Here gmic will take image.jpg and resize it to a square 400 pixels wide.
`resize` is a gmic command, and the numbers following it, `400,400` are its
arguments. Commands are recognisable because they start with a dash. So, the
resize command will resize the image `image.jpg` to a square 400 pixels wide,
distorting it if not already squared. The new image will then be used by a
new command, called `output`. The output command will write the image to a new
file, called `resized-image-1.jpg`:

![Image resized without preserving aspect ratio][1]

If you want to keep the image proportions, it is easier to use another variant:

	gmic image.jpg -resize2dx 400,5 -o resized-image-2.jpg

The `resize2dx` command will resize the image in the x (width) dimension, while
keeping the aspect ratio. The argument after the comma, `5` is tells the
`resize2dx` command to use an interpolation method called bi-cubic interpolation
- in simple words, the interpolation method is a good one.

![Image resized preserving aspect ratio][2]

G'MIC can open and save many image formats. The list is long: JPG, PNG, GIF
and  TIFF are only some of the most common. While gmic also can open raw
images by  itself - by internally using dcraw - I prefer to let dcraw decode
them first  because I want some extra control. Especially, I want to be able
to apply the  camera [white
balance](http://en.wikipedia.org/wiki/White_balance) which is  encoded in the
raw file. This way the image will color-wise be similar to what  the camera
suggested. dcraw has an argument that will apply the white balance  the camera
selected, and that is probably the best default for most situation.  To pass
the image between dcraw and gmic, it is possible to use shell  redirection,
and now it gets a little more complicated:

	dcraw -c -w -4 image.cr2 | gmic -.ppm

Here, dcraw decodes the raw file image.cr2, which is a Canon raw file. It
applies camera white balance (the -w argument) and writes a 16 bit, linear
image  (the -4 argument) to standard out (the -c argument). This output, which
takes the  form of a stream in the PPM image format, is piped to gmic by the
shell. Dash  means read from standard input, and -.ppm means read a PPM image
stream from  standard input. The incoming image stream will be treated by gmic
just like as  if it was read from file : since no other commands are given,
the result will be shown in its image viewer.

![Linear image from dcraw][3]

Here we notice a few things though. The image is considerably darker than it
should be. That is because the image decoded by dcraw is in linear format - a
format that closely corresponds to the amount of light recorded by the camera
sensor. To get the contrast of the image more pleasant for the eyes we need to
apply gamma to it, to convert the image data to exponential form. So we can
evolve the command line as follows:

	dcraw -c -w -4 image.cr2 | gmic -.ppm -apply_gamma 2.2


![Image with gamma applied][4]

A gamma value of 2.2 is standard for many purposes, and now it looks more
natural. However, the colors and contrast still leaves something to be
desired.  Now it would be very easy to get lost among the options offered by
gmic. They  are plentyful and advanced but if you are not an imaging
researcher it is not so easy to understand what they do or how to put them
together. But there are ways to find out.. 


G'MIC provides a plugin to the Gimp imaging program. In this plugin you can do
many kinds of image operations using regular slide bars and clicking buttons,
which is intuitive and familiar. If the Gimp is started from the command line,
and you choose the "Output messages" option "Verbose", 
G'MIC will print the actual gmic operations to the console, so you can see
what it does beneath the shiny GUI. And then it is a simple matter to copy and
paste the image operations you have found that you prefer and apply them to
your gmic command line. So, after some experimentation I found that I wanted
to extend my command line as follows:

	dcraw -c -w -4 image.cr2 | gmic -.ppm -div 256 \
	-gimp_channel_processing 2.2,1,0,0,2,12,88,256,0,0 \
	-gimp_mix_lab 1,0,0,1.3,0,0,1.3,0,0,0,2 \
	-mul 256

![Image with additional processing][5]

Suddenly the picture is quite a bit more pleasant for the eyes! How did this
work? Well a couple of things are new here. First of all, there are two new
commands applied, `gimp_channel_processing` and
`gimp_mix_lab`. `gimp_channel_processing` actually does several things. It applies
gamma, and it normalizes values in the picture, so the darkest pixels becomes 
absolutely black, and the lightest pixels absolutely white. The `apply_gamma` 
command is therefore no longer necessary. It can do other things as well, but 
the above arguments worked well in this case, and were just copied them from 
the Gimp console. The `gimp_mix_lab` command provides what is often named "color 
boost", by converting the image to the 
[Lab color space](http://en.wikipedia.org/wiki/Lab_color_space), and push the
colors in direction of more red and blue without affecting the light
component. This often improves the appearance of a color image, if done with
some care.

Around these two Gimp commands (which are actually only called Gimp commands
by name, they are G'MIC commands that are called by the G'MIC Gimp plugin)
there are two mysterious commands `-div 256` and `-mul 256`. These are cryptic
but have a reason - the commands in between acts on colors in [RGB
colorspace](http://en.wikipedia.org/wiki/RGB_color_space), or performs
conversions between RGB colorspace and Lab colorspace. Such commands expect
the color values to be in an interval between 0 and 255, which is a familiar
scale for anyone that worked with color in imaging applications. However, the
color data that comes from dcraw is 16-bit (since we gave the `-4` option
above) and takes values between 0 and 65536. Therefore we need to scale down
these values to a range where the commands make sense. We do that by dividing
the color data with 256 since 65536 / 256 = 256.

This may seem like information is thrown away, but in fact it is not since
G'MIC works with floating point values internally. So a pixel that had one
color value of 1000 before now gets a value of approximately 3.92. This
does not matter so much, all values are affected relative each other and in
the end we multiply the data with 255 again to get back in the scale we began
- in a 16 bit image scale.

Now the only thing that is left is to write our new gamma adjusted, contrast
enhanced, color boosted image to disk:

	dcraw -c -w -4 image.cr2 | gmic -.ppm -div 256 \
	-gimp_channel_processing 2.2,1,0,0,2,12,88,256,0,0 \
	-gimp_mix_lab 1,0,0,1.3,0,0,1.3,0,0,0,2 \
	-mul 256 -c 0,65536 -type ushort -output image.tiff

More mysterious commands. First of all, we notice that in the end we write the
image data to a TIFF file. TIFF files are good for high-precision image
processing because they can contain 16 bit image data. However TIFF files also
can contain this data in many forms that other programs can't read. We want
the data to be in 16 bit integer format, so we need to assert the data in that
format prior to writing the file. That is what `-c 0,65536 -type uchar` is
about. Now you may understand why gmic is a tool developed at a university
research department!

However, the end result is a high quality image that could very well be better
than what the camera would have produced by itself. We can compare this. My
Canon camera embeds a jpg image in its raw files and this jpg image can be
retrieved from the raw file using dcraw:

	dcraw -e image.cr2

![Thumbnail stored in RAW][6]

This image has quite high resolution although not as high as if I the camera
was configured to to shoot directly in JPG using the highest possible
resolution. But it is good enough for comparison. Let's compare this with a
JPG created from the raw file itself, using a slightly adjusted command.

	dcraw -c -w -4 image.cr2 | gmic -.ppm -resize2dx 1936,5 \
	-div 256 \
	-gimp_channel_processing 2.2,1,0,0,2,12,88,256,0,0 \
	-gimp_mix_lab 1,0,0,1.3,0,0,1.3,0,0,0,2 \
	-c 0,255 -type uchar -output comparisonimage.jpg

Changes to the previous command line is a rescaling to the same resolution as
the embedded JPG, and some trickery to write a 8 bit JPG file rather than 16
bit TIFF. As you may notice, we don't multiply with 255 again - it is
unnecessary since we are already in the 8 bit range. And we perform a slightly
different assertion to prepare the data for writing a JPG file.

Crop from the thumbnail to the left, and the G'MIC-processed on the right:

![Comparison][7]

[1]: tutorialimages/resized-image-1.jpg
[2]: tutorialimages/resized-image-2.jpg
[3]: tutorialimages/dcraw-1.jpg
[4]: tutorialimages/dcraw-2.jpg
[5]: tutorialimages/dcraw-3.jpg
[6]: tutorialimages/thumb.jpg
[7]: tutorialimages/enlarged.jpg
