G'MIC is an interpreter for the image processing language of the same name. It lives in terminal emulator command shells and has no GUI. It is never present on Windows or Mac systems unless you have already put it there. The G'MIC download page furnishes installation scripts and binaries for Windows, Mac, Debian, Ubuntu and generic Linux. These packages provide both the command line tool, gmic, and the gmic_gimp plug-in.
If you use a GNU/Linux distribution, the standalone G'MIC interpreter and Gimp G'MIC plugin are very likely in your distributor's repositories. These have been tuned and integrated with the distribution and could be a better fit than the generic binaries at the download site. Use 'apt-get', 'emerge', 'yum' or whatever else manages your distribution's repository.
There is also a small but very fine community of packagers who take great pains to integrate Gimp with its large train of plug-ins and extras, including G'MIC. They strive for installations that “just work.” Go to the G'MIC home page and, among the contributors, look up those who have the ‘packager’ specialty by their names. Many names in this list link to distribution web pages where you can find further pointers and instructions. I can't/won't say who is best; I don't think that is possible. Each packager brings a fine technical and aesthetic sense to his or her product and each product reflects that sensibility in its makeup. Just remember, if you experiment with a few packagers, to fully clean up one candidate installation before installing the next. Debris from one installation interfering with another is a common source of packaging misbehavior.
Finally, you can just get the sources and build, my personal favorite approach. You can get a tarball of the latest stable or development releases from the download page or fork from github.com. Gentoo is the Linux flavor to which I am partial, which renders source builds routine, but the gmic build environment is straightforward and builds take place on all manner of Linux, Mac, and Windows machines.
If you are absolutely new to G'MIC, I heartily recommend installing both Gimp and the Gimp G'MIC plug-in and putting in some time with those tools first. You're not ready to spend much time at this site yet. By and large, the plug-in “just works” and has strong supporting communities. Some of the more popular ones are GIMPChat/G'MIC, G'MIC at Google+, G'MIC at Flickr, and Pixls.us.
According to the survey, more than 85% of the people who use G'MIC at all use the gmic_gimp plug-in. That, of course, is the tip-of-the-iceberg of survey-respondents, resting on a much larger population of users beneath the surface, many of whom think that G'MIC is the plug-in and the plug-in is G'MIC. It probably seems contrary of me then to tell you up front, here and now, that there is hardly any documentation here at all about the plug-in. Outside of the few filters I've written myself, you will not find any Gimp G'MIC filter documentation here. Nada. Nihil. None. How churlish of me, going so against the grain.
Indeed, these pages are resolutely for the less than five percent of you who use the command line executable, gmic. The reason for this is plain (I think). It is from gmic that gmic_gimp stems. Every one of the four hundred and forty some filters in the plug-in are pipelines written in gmic, with a bit of UI wrapper code to solicit arguments and present some sort of preview. The future of good quality gmic_gimp filters depends on a community of people who know how to write gmic pipelines. That, to my mind, makes the case for gmic documentation before plug-in documentation. But there is one more good reason.
Quite apart from the plug-in, it so happens that gmic, stand alone, is a very nice tool for building image processing pipelines. In this regard, it goes toe-to-toe with its “friendly competitor” ImageMagick, or its more stability-conscious fork, GraphicsMagick. I have no desire to get into flamewars over which is best or which has “more.” I'm not even sure I can answer that question. It so happens that I find that gmic's pipeline construction rules are more consistent — and more to my taste. I spent a number of years with both ImageMagick and GraphicsMagick and, compared to gmic, I feel that both Magicks have some rather idiosyncratic commands. It seemed that I could never build much of a pipeline without having to spend hours with documentation. G'MIC pipeline construction rules enforce strong patterns which cast individual commands into just a few molds. There are fewer mechanics to remember. Over time, I found myself getting more done with gmic pipelines than with the Magick ones.
At some point, you might wish to extend the Gimp G'MIC plugin or filter a large number of images in some kind of image processing pipeline. At that point, you will want to become familiar with the G'MIC image processing languge itself and the interpreter that runs it. Then, we hope, you will find these pages useful.
In the following, we will make use of a standard image called example.png, the stained-glass image of an 'E' at the opening of this article.
Invoke the interpreter by typing 'gmic'. Follow this with a series of items, separated by white space. The items are generally G'MIC commands followed by their affiliated parameters. Some commands do not have parameters, so G'MIC relies on a leading hyphen to distinguish commands from other items on the command line.
Parameters consist of numbers, letters or words separated by commas, usually with no intervening white space. Occasionally, a parameter will embed white space; these need to be quoted.
Here is an invocation of the G'MIC interpreter that will apply the -glow filter to our example image:
$ gmic -input example.png -glow 10% -output ex_glow.png
If all goes well, G'MIC will respond with a series of summary lines.
[gmic]-0./ Start G'MIC parser.
[gmic]-0./ Input file 'example.png' at position [0] (1 image 250x250x1x3).
[gmic]-1./ Add soft glow on image [0], with amplitude 10%.
[gmic]-1./ Output image [0] as file 'ex_glow.png' (1 image 250x250x1x3).
[gmic]-1./ End G'MIC parser.
You should now have a new file in your current directory called 'ex_glow.png'. This Portable Network Graphic file should contain an image that looks like this:
In this simple invocation, -input, -glow and -output are commands, distinguished by their leading hyphens. 'example.png', '10%' and 'ex_glow.png' are parameters for their respective commands. All in all, six items were on the command line, three commands and three parameters. Had any of these commands needed two or more parameters, these would have been separated by commas.
Through these commands, we performed the following actions:
We created an image list (alternativly: stack), initially empty.
We invoked the -input command, giving it one parameter, a file. G'MIC placed the contents of this file, 'example.png', at the first image position in the list; this position has an index number of zero.
We invoked the -glow command, a filter which preserves details but otherwise blurs areas of relatively constant color and luminance. We gave it a parameter of ten percent and could have used any other percentage for a greater or lesser effect.
The -glow command replaced the original image on the list with the filtered image.
We invoked the -output command, giving it one parameter, a template name. The -output command typically copies all images in the list to a like set of output files. In this case, of course, there was only one image in the list, so G'MIC only wrote one output file. In this special case, the name of the output file exactly matches the template name. Generally, though, image lists contain many items, so G'MIC usually appends to the template name an identifying numeral, the position of the image in the list ensuring that all output files have unique names.
G'MIC then closed down, destroying the image list. Since we had invoked the -output command, nothing was lost.
Our commands (-input, -glow, -output) and their associated parameters formed an image processing pipeline which operates on the image list. Unadorned, pipeline commands operate on all images on a list, though right hand side command decorations limit the scope to various subsets of the list.
G'MIC always furnishes a list of summary lines documenting what it is doing, as it is doing it. These constitute at once a progress meter and a description of what is going on. It is worth one's while to become familiar with this precis and read it with care.
The count of images in the list follows the [gmic] tag, in this example, at most one image occupied the list, so only '1' followed the [gmic] tag. In principle, any number of images may be on the list and in practice it is not uncommon to have dozens of items.
Next, G'MIC presents a summary of the currently executing command and the parameters in effect. Often, G'MIC describes more parameters than what might have been entered. These additional parameters are usually ones with internally defaulted values and need not be entered on the command line. You might override these defaults with other values in subsequent invocations.
When an image moves onto the list or is output, G'MIC reports its shape using four dimensions. You are likely familiar with the width and height of an image, dimensions measured in pixels. G'MIC also considers depth, also measured in pixels. This dimension can represent time – think of frames in a video – or slices that, in aggregate, make up a volume – think of a CAT scan. Finally, as a fourth dimension, G'MIC considers the number of channels in each pixel. Red, green, and blue data channels (RGB) is a common case. Perhaps an additional opacity/transparency channel may be present as well (RGBA). Alternatively, cyan, magenta, yellow and black channels (CMYK) may be present. These constitute various kinds of color spaces. G'MIC can, in principle, support many more color spaces than the few mentioned here and G'MIC itself does not adhere to a hard-and-fast interpretation of what these channels are. For many G'MIC commands, channels simply contain data.
This list constitutes the interpreter's primary diagnostic tool; harbingers of the unexpected often show up in the summary, often taking the form of images with unexpected dimensions. The follow-on discussion of G'MIC's image structure goes into somewhat greater detail.
At this juncture, you can, in principle, build and execute a G'MIC image processing pipeline. The , -input, -glow and -output ' commands have nearly eight hundred siblings documented in the standard G'MIC Handbook. You might commence working your way through that tome with the knowledge you have now. In practice, such an exercise will likely drive you mad. There are additional details about G'MIC language which are worth knowing sooner rather than later and these will be taken up in the following sections.
We will conclude this section with a small gallery of commands, which, like -glow, are fairly simple to invoke. We also introduce the -display command, which, instead of writing files like -output, routes the content of the image list to a display window, where the items in the pipeline appear as a set of thumbnails. Your mouse can manipulate this pipeline display. Examine a particular image by clicking on it with the left mouse button; other images go away and the selected image becomes larger. Magnify portions of the selected image by a left-mouse-down, drag, left-mouse-up action; you will draw out a rectangle that, on mouse-up, expands to fill the entire window. Step out by single-clicking with the left mouse button without dragging out a rectangle. Exit the pipeline display command by pressing the 'ESC' key.
You cannot save files with the '-display' command, but when exploring, that is usually not a big concern. If saving images is a big concern, however, place an '-output' command after the '-display' command. When you dismiss the display window by pressing ESC, the follow-on '-output' command will write the contents of the image processing pipeline to a set of files.
Some simple G'MIC commands
 |
 |
|
|
|
 |
 |
|
|
|
 |
 |
$ gmic -input example.png -bandpass 0.005,0.01 -normalize 0,255 -display |
$ gmic -input example.png -edges 9% -normalize 0,255 -display |