Images and formats
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.
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
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
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 usually 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.
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
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 output. The previous example would become:
gmic my_image.jpg -unsharp_octave 2,2 -type uchar -o my_image.tiff
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
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
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
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:-