G'MIC - GREYC's Magic for Image Computing: A Full-Featured Open-Source Framework for Image Processing
GREYC CNRS ENSICAEN UNICAEN

A Full-Featured Open-Source Framework for Image Processing



Latest stable version: 3.4.3 (2024/10/11)

Tutorial

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:
$ gmic auntmay_oldphoto.png

[gmic]./ Start G'MIC interpreter (v.3.3.3).
[gmic]./ Input file 'auntmay_oldphoto.png' at position 0 (1 image 512x512x1x3).
[gmic]./ Display image [0] = 'auntmay_oldphoto.png'.
[0] = 'auntmay_oldphoto.png':
  size = (512,512,1,3) [3072 Kio of float32].
  data = (118,126,112,109,105,109,108,111,107,119,121,121,120,112,113,114,117,114,118,122,120,128,131,131,131,136,135,141,143,145,148,150,149,150,150,149,150,150,148,146,142,141,138,141,144,148,150,150,151,151,151,151,152,151,152,153,152,154,155,156,158,159,160,161, ... ,129,125,123,123,119,117,118,122,125,126,123,121,123,124,129,131,129,129,130,132,132,131,129,128,129,128,128,131,130,127,124,121,119,119,114,119,116,114,118,118,118,122,122,120,124,123,121,124,126,123,129,127,122,124,123,123,128,127,124,124,124,127,125,114).
  min = 46, max = 188, mean = 153.218, std = 17.6682, coords_min = (511,456,0,0), coords_max = (130,216,0,2).
images/auntmay_oldphoto.png r. 67%,67%,100%,100%,5
Imgcreator-AI — zmo.ai

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.

cmd
Some pipeline following the "gmic" command

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.

noplugindocs
No gmic-qt documentation here

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.

annotatedcmd
Commands, selections and arguments shall a pipeline make

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:
$ gmic -input auntmay_oldphoto.png -normalize[0] 0,255 -output[0] auntmay_normed.png

[gmic]./ Start G'MIC interpreter (v.3.3.3).
[gmic]./ Input file 'auntmay_oldphoto.png' at position 0 (1 image 512x512x1x3).
[gmic]./ Normalize image [0] in range [0,255], with constant-case ratio 0.
[gmic]./ Output image [0] as png file 'auntmay_normed.png' (1 image 512x512x1x3).
[gmic]./ End G'MIC interpreter.
images/auntmay_oldphoto.png r. 67%,67%,100%,100%,5 n. 0,255
Aunt May, normalized from zero to two hundred, fifty-five.

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:
$ gmic parse_cli print,apply
[gmic]./ Start G'MIC interpreter (v.3.3.3).
[gmic]./ Parse '#@cli' command(s) 'apply' and output in 'print' mode.
apply_camera3d
apply_camera
apply_channels
apply_curve
apply_files
apply_gamma
apply_matrix3d
apply_parallel
apply_parallel_channels
apply_parallel_overlap
apply_scales
apply_tiles
apply_timeout
apply_video
[gmic]./ End G'MIC interpreter.
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:

 $ gmic -help apply_curve

  apply_curve:
      0<=smoothness<=1,x0,y0,x1,y1,x2,y2,...,xN,yN

    Apply curve transformation to image values.

    Default values: 'smoothness=1', 'x0=0', 'y0=100'.

    Example:
      [#1] image.jpg +apply_curve 1,0,0,128,255,255,0

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

whatis: skip ${1}
   parse_cli print,$1

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:

$ gmic whatis blur
[gmic]./ Start G'MIC interpreter (v.3.3.3).
blur (+)
blur_angular
blur_bloom
blur_linear
blur_radial
blur_selective
blur_x
blur_xy
blur_xyz
blur_y
blur_z
deblur
deblur_goldmeinel
deblur_richardsonlucy
deblur_upscale_goldmeinel
deblur_upscale_richardsonlucy
frame_blur
gcd_blur_masked
gcd_blur_texture
mapblur
rep_blur_splinter
rep_fragment_blur
rep_frblur
rep_splinter_blur_convolve_map
[gmic]./ End G'MIC interpreter.

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

$ gmic -help deblur_goldmeinel

  deblur_goldmeinel:
      sigma>=0,_nb_iter>=0,_acceleration>=0,_kernel_type={ 0:deriche | 1:gaussian }.

    Deblur selected images using Gold-Meinel algorithm

    Default values: 'nb_iter=8', 'acceleration=1' and 'kernel_type=1'.

    Example:
      [#1] image.jpg +blur 1 +deblur_goldmeinel[-1] 1

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:

ampstampxor
How to stamp ampersands all over the place
Or any other shape. Turn the trick with a small binary image (an ampersand!) and a large, mostly black image, but with scattered pulses — non-zero pixels. The convolution of a pulse and a shape reproduces the shape — on the first pass. What happens with more passes?
XORing the Addressing
The exclusive OR (XOR) operator reports False on identical inputs and True on differing inputs. What if we set the value of every pixel in a 128×128 image with the XOR of its coordinates? Can we animate it??
cellsandroads
How to animate as if in a dream?
Anything that G'MIC can apply to a single image can apply to a sequence. Here: based on a slightly differing warp of an image, one after another, applied in not quite identical ways, to each channel, the lot changing over time. See the tvfritz script in the discuss.pixls.us G'MIC section.
How to make a network of roads?
Bandpass salt-and-pepper noise for a smooth-varying pattern that tiles vertically and horizontally. Off-center thresholding — something other than 50-50 — so that either white or black regions connect and the other forms islands. Morphologically thin on the island color so that islands expand to their limits. Blur-and-threshold to finish up. Roadways among the hills, perhaps, or biological cells.

Tutorial Land

If all else fails, read the manuals.

RiffsNew to G'MIC? This is your next step: Build your vocabulary with riffs and finger exercises.
IntroductionA historical introduction. Read it when you need a break from writing riffs.
BasicsEverything written here, but a deeper dive.
ImagesWhat an image looks like to G'MIC.
SelectionsLimit commands to work only on certain images.
MathIt started out as an image calculator. It became a programming language.
Beginner's CookbookFake 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 GuideTutorials written around not nearly enough commands.
Bouncing Balls TutorialDeploy 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
CheatsheetQuick recipes to get things done. Or maybe undone.
ContributeNone of this documentation wrote itself.

Updated: February 04, 2024 17:30 UTC Commit: ceda63b2867a
G'MIC - GREYC's Magic for Image Computing: A Full-Featured Open-Source Framework for Image Processing

G'MIC is an open-source software distributed under the CeCILL free software licenses (LGPL-like and/or
GPL-compatible). Copyrights (C) Since July 2008, David Tschumperlé - GREYC UMR CNRS 6072, Image Team.