A Full-Featured Open-Source Framework for Image Processing

Start Here

Well. There it is. The Prompt. Pregnant with possibilities, but — What the futz do you do with it??? Well, how about fixing up some old photograph? Remove scratches. Dust motes. A coffee (maybe tea) stain. This from a cup, set down on a cluttered breakfast table, during a long ago chat. And the photograph? It's Aunt May. The only photograph you have of her. The negative went into a box, and the box went into an attic, and the house to which the attic belonged was sold back when childhood would last forever, or so it seemed. Aunt May. That dear sweet woman who never noticed your hand stealing into in the cookie jar. The old photograph. It's your last connection to her, that place, that time.

What you wouldn't give to sit down with Aunt May again, some sunny Sunday morning, and talk about — oh, maybe nothing at all. Talk about nothing at all while the kitchen fills with the warm smell of baking cookies. The kitchen of that quaint, old Victorian gingerbread, now long ago gone.

Well. You've got G'MIC at The Prompt.

And you've got a visual goal: Fix Aunt May's old photograph.

Now — here's the problem: you lack a vocabulary to connect your visual goals to G'MIC commands.

You have no idea what to do. So you throw a Hail Mary! pass:

Hey, presto! Stuff happens! A bunch of text. And Aunt May!

Except — you can't seem to do much with it. Mouse over: get read outs. Left or middle mouse buttons: drag. Right: zooms.


What else?  C,E,H. Re-positioners. Z. Zooms. G. Makes grids appear. Sometimes.

OK. But this is presentation stuff. What about fixing stuff?


So. Here's the first bit: G'MIC doesn't do Windows, Icons, and Mouse Pointers (WIMP). At least, not much. It mostly does Old School Shell. Like Uncle Ken Olsen hunched over the VT-100, back in the days of DEC.

Not keen on shells? Oh. My. Then you have a bit of a learning curve. But — let's say you can get past that.


Here's the next bit: What you write after gmic is a pipeline. Pipelines are ordered command sequences which operate on image lists. Some people call image lists stacks.


And a third bit: If — instead — you're looking for how sliders or buttons work in the gmic-qt plug-in — the G'MIC inside of paint programs — Sorry. That's Not Here. Nada. Zilch. But! if you want to write such things, you are on the right page. Here, we weigh up the G'MIC command line interpreter and the pipelines you write for that go inside gmic-qt plug-ins too. Get pipelines down and it's just writing the user interface, a kind of a big, fancy comment preceding your pipeline in some command file.

Does any of that pique your interest? Then Start Here.

You write pipelines with the interpreter. Pipelines operate on image lists. Put some pins in that. Pipelines and image lists live at the very core of G'MIC. The Intro Cheat takes a deeper dive, but you've written a pipeline already. You got Aunt May on the stack. She got there because you entered the input command.

Wait — What? Never typed input, you say??!

Ah. That's because G'MIC throws its own Hail Mary passes. Should it encounter an incomplete pipeline — such as the one you wrote — it sticks an implied input command in front of what it guesses to be an image argument. Ditto with output. If G'MIC can't find anything that looks like an output command, it punts, appending a display command to the end of the pipeline.

Hail Mary passes don't always work. These did. You wrote a pipeline: -input auntmay_oldphoto.png -display, and stumbled onto your first success.

But. You don't want to — just — stumble onto successes. Success only when stars align — Pffft! You want turn-key successes. Successes so common that — you don't even think about them anymore.


Now. Lets pull the pins. Commands. Image selections. Arguments. Substitution variables. $-expressions. These are what a pipeline makes. A run-down:

1.	Pipelines start with commands that, at the first go, put images on the stack.
2.	The stack is like a kitchen counter. You put images there until you can work on them.
3.	G'MIC assigns images position numbers — indices — as they enter the stack.
4.	Image Selections in square brackets, like <some command> [-1,-2,-3] or <some other command> [4], tag images. The command works on just those. Negative counts from the end of the stack, Positive counts from the beginning of the stack.
a.	Commands without selections operate on every image.
b.	Commands with empty selections don't operate on any image. What's the point in that? Sometimes the game is an administrative side effect. This peculiar notation insulates all images from such.
5.	Arguments adjust command behavior, items separated by commas, no spaces, altogether a block following its command. What kind of arguments? gmic -help <some command> tells you.
6.	Specialization prefixes: (+) on commands induce duplication. Duplicates change, not originals. (–) on commands induce replacement. Omit prefixes for default replacement behavior.
7.	Variable definitions: var= <value> , or dereferencing: $var, stash values. Define variables once; dereference as needed.
8.	$-expressions: dollar signs followed by numerals, mark places where arguments can be substituted. Seen in custom commands but not on command lines. Put a pin in that for now.

There are exceptions. In certain contexts, what look like images selections are selecting things other than images — but that gets ahead of the game. gmic help <some command> catalogs any such peculiarity.

Mainly, G'MIC commands do image processing. In official distributions, there are a little over nine hundred of them. More than a thousand counting community contributions.

At present you know about two: input and display. It's a start.

Here are two more: output and normalize.

1.	output saves images. Even if that might not work.
2.	normalize pegs image intensities to new minima and maxima.

That's enough for a riff. Let's fix up Aunt May — at least a little bit — by re-pegging the illumination range. That is, normalizing it. Type this pipeline at a shell prompt:

Now the old girl has a little more punch. And color! Though still a mess. Yet — progress. A little victory.

Take a look at the text dump. That's the G'MIC shell log: it consists of lines beginning with [gmic] (Official Messages), or sometimes <gmic> (internal minutiae ). It's straightforward: Input. Process (normalize). Output. Typical lines of action. Of course, choosing lines of action may be a bit sketchy for you at the moment. You still know (almost) next to nothing. But the steps forward are plain.

You need to increase your G'MIC vocabulary.

And, as you increase your G'MIC vocabulary, the ways to reach visual goals becomes clearer. So here's the plan:

1.	First, you need to make peace with your shell's command line interpreter. That way you can run G'MIC commands without the shell's "help".
2.	Next, cease being an adult (at least for awhile). Rediscover childhood. Climb into sandboxes and do riffs.
3.	Then, from time to time, translate the more interesting riffs into finger exercises. These elementary custom commands work like "walled gardens" for structured experimentation. At the end of the day, you may very well have a new G'MIC command of your very own design.
4.	Go back to step 2 and repeat. Forever.

I want to run the — you know! — the — the — whatchamacallit command. The apply something command. You know. That command.

As you increase your G'MIC vocabulary, you will reach a point where you will have some grasp of maybe a few dozen commands, but many — if not most — are rattling around your head in some half-remembered way. You want to use color_adjust — or is it adjust_color? — command. Or something to do with blur.

G'MIC's help command routinely has to sort out such things, and that command has an internal piece which builds directories from fragments. You can use it too:
Here, following the "print" piece, is the fragment: "apply." G'MIC takes that fragment and gathers together all the command line interpreter ("cli") definitions which has the supplied fragment somewhere in the collected commands' names — that's the "parse_cli" part. It then prints out that list — that's the "print" part. With that list now in front of you, you might recall that it was some apply_curve command which you read about somewhere in some tutorial about programmatically adjusting arguments. So reminded, you can now get specific help:


And while you know (as of yet) only a few commands, you may as well start — right now! — defining your own: say, an easier-to-use version of parse_cli.

Start by creating a file in your home folder (or directory) called:

1.	on Linux: or MacOS:	$HOME/.gmic
2.	on Windows:	%USERPROFILE%/user.gmic

This file contains your own personal extensions to the G'MIC language. G'MIC reads it every time you use the gmic command and adds whatever custom definitions it finds within. Let your first definition be this (write it inside of your .gmic or user.gmic file):


Apart from observing that this definition is a kind of a template for a new, custom whatis command, we're not going to take you off into the weeds with descriptions of how all the parts and pieces operate. (for that, go to A First Custom Command ). Just save the file in your home directory and — later — when you want to know what kind of blur commands are around, type:


and then get further help on any one of them, say:

An Empyreal Journey

Of course, it's more than vocabulary. It's also grammar, of having G'MIC's whole structure at your beck and call. Sucessions of riffs and finger exercises carry you forward until, one day, an enthralling sense of alchemy overtakes you. You'll grasp the whole from its parts, and never again will you size up an image without having a collateral assay of G'MIC commands rush into your head — it becomes just a part of everyday perception.

In any case, you are now a digital artist. Seek inspiration from the world around you. Look at textures, surfaces, The G'MIC Gallery, clothing fabric, Funny Oneliners, fields of grass. Tree bark. Concrete Textures.

Can you write pipelines that render (maybe somewhat faux) versions of these? Yes you can. At first, keep it simple. Can you make a ramp? Seems probable. How about a diffusion tensor field? Uh. That last one may be a bit of a reach. But keep calm and carry on. With each step toward the more complicated cases, futher riffs and finger exercises suggest themselves. Scrounge around the tutorials. Post questions at Discuss Pixls: G'MIC or gamble a day away on writing one-liners. Always set challenges for yourself. Here are a few to get started:

Tutorial Land

If all else fails, read the manuals.

Riffs	New to G'MIC? This is your next step: Build your vocabulary with riffs and finger exercises.
Introduction	A historical introduction. Read it when you need a break from writing riffs.
Basics	Everything written here, but a deeper dive.
Images	What an image looks like to G'MIC.
Selections	Limit commands to work only on certain images.
Math	It started out as an image calculator. It became a programming language.
Beginner's Cookbook	Fake hair. Crazy blurs. Tiles. Arabesques. Thing is, you have to be fairly advanced before you reach the Beginner's level. Welcome to G'MIC, by the way.
Command Guide	Tutorials written around not nearly enough commands.
Bouncing Balls Tutorial	Deploy a G'MIC animated loop that exemplifies evolving or changing imagery. Comes with a behind-the-scenes look at how the script came to be: Live G'MIC script coding
Cheatsheet	Quick recipes to get things done. Or maybe undone.
Contribute	None of this documentation wrote itself.

Updated: February 04, 2024 17:30 UTC Commit: ceda63b2867a