A Full-Featured Open-Source Framework for Image Processing

Basics

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-qt plug-in.

Alternatives

If you use a GNU/Linux distribution, the standalone G'MIC interpreter and gmic-qt 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, scroll down to "Teams" and, among the "Contributors" listing, look up those who have the ‘packaging’ 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 and Pixls.us.

gmic and gmic-qt

According to a recent survey, more than 85% of the people who use G'MIC at all use the gmic-qt 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 gmic-qt 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-qt and other plug-in variants stem. Every one of the nearly six 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, the command line interpreter ("CLI") interface, 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 pipeline tool is best or which has “more features” 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.

Running Commands

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 arguments. Some commands do not have arguments, so G'MIC relies on a leading hyphen to distinguish commands from other items on the command line.

Arguments consist of numbers, letters or words separated by commas, usually with no intervening white space. Occasionally, an argument 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:

if all goes well, G'MIC will respond with a series of summary lines.


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:

What happened?

In this simple invocation, input, glow and output are commands, distinguished by their leading hyphens. example.png, 10% and ex_glow.png are arguments for their respective commands. All in all, six items were on the command line, three commands and three arguments. Had any of these commands needed two or more arguments, these would have been separated by commas with no whitespace around the 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 argument, 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 an argument 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 argument, 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 arguments 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.

Summary Lines

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 arguments in effect. Often, G'MIC describes more arguments than what might have been entered. These additional arguments 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.

Further Explorations

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.

1.	Images
2.	Selections
3.	Math
4.	Beginner's Cookbook
5.	Command guide

Tutorial Style

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 a command's selected images at the end the pipeline, preserving originals. You might see an -- form in antique (crufty) tutorials. That is a deprecated form of +. Avoid the double-hyphen form; by the time you read this, -- won't 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.

Postscript

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 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

---

Updated: 07-May-2023 19:30 UTC Commit: 79f1223f76abc9d217cab05bf38ca89560b76ee6