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
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
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
gmic and gmic_gimp
According to a recent survey, more than 85% of the people who use G'MIC at all use a plug-in for Gimp, Krita, or applications supporting .8bf
. 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
and other plug-in variants stem. Every one of the five hundred or so 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 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 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 images/example.png -glow 10% -output img/ex_glow.png
if all goes well, G'MIC will respond with a series of summary lines.
$ gmic input images/example.png glow 10% output img/ex_glow.png
[gmic]-0./ Start G'MIC interpreter.
[gmic]-0./ Input file 'images/example.png' at position 0 (1 image 250x250x1x3).
[gmic]-1./ Add soft glow on image , with amplitude 10%.
[gmic]-1./ Output image  as png file 'img/ex_glow.png' (1 image 250x250x1x3).
[gmic]-1./ End G'MIC interpreter.
You should now have a new file in your img
directory called ex_glow.png
. This Portable Network Graphic file should contain an image that looks like this:
In this simple invocation, -input
are commands, distinguished by their leading hyphens. example.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:
|1.||We created an image list (alternativly: stack), initially empty.|
|2.||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.|
|3.||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.|
|4.||The -glow command replaced the original image on the list with the filtered image.|
|5.||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.|
|6.||G'MIC then closed down, destroying the image list. Since we had invoked the -output command, nothing was lost.|
|7.||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.
|1.||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.|
|2.||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.|
|3.||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 and G'MIC is agnostic to their purposes.|
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
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.
The G'MIC command line parser is quite versatile and forgiving, but for purposes of the tutorials here, the writers have assumed that it has been coded for a circa 1977 VAX-11/780 running under VMS: My Very First Parser! (mvfp)
The tutorials use a verbose Tutorial Style
that is almost never seen in daily use. The difference is one of syncopation. The gist of it is that one may leave out a lot of command line furniture and G'MIC will still get it. That is on purpose, by design. As you gain experience, you'll discover what can be left out of command lines -- and you'll leave them out because typing is tiresome.
In the transition to Production Style
, broadly, most commands don't need a -
hyphen prefix; put one in for clarity if needed. The +
prefix is necessary only when you want to implicity -input
the last image on the pipeline. You may see a --
form in some of the older tutorials. That is a deprecated form of +.
Avoid the double-hyphen form; by the time you read this, it probably won't even parse. Regarding -input:
in production it is mostly invisible: its short-cut is the empty string. G'MIC almost always can figure out where the -input
command is needed and assumes it is there. Regarding shortcuts see Command Shortcuts:
in the reference manual. You'll be using them sooner rather than later.
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
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 example.png boxfitting 2,0|
|$ gmic example.png fx_circle_transform 50,50,75,50,-2,-2,0,1,3,1|
|$ gmic example.png hardsketchbw 300,40,0.05,10,1|
|$ gmic example.png rodilius 20,5,200,17,2,1|
|$ gmic example.png bandpass 0.005,0.01 normalize 0,255|
|$ gmic images/example.png edges 9% normalize 0,255|