A Full-Featured Open-Source Framework for Image Processing

Well. There it is. The Prompt. Pregnant with possibilities, but — What the futz do you do with it??? Say you want to fix an old photograph. Get rid of scratches. Dust motes. The coffee (maybe tea) stain on the corner of the print. Made from setting a coffee cup down on a cluttered breakfast table — decades ago. And, it's the only print you have. The negative went into a box, and the box went into an attic, and the house to which the attic belonged was sold a long time ago. And the print — it's Aunt May, that dear, sweet woman who pretended not to notice when your hand slipped into the cookie jar, decades ago, before the house was sold. It's your last connection with her.

What you wouldn't give to sit down with Aunt May one more time, 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.

So. That's your visual goal: Fix Aunt May's print. You've got a scanned and archived copy, dirt and all, in case your edits fail in a catastrophic way.

And you've got G'MIC at The Prompt.

Now, here's the difficulty: you have no G'MIC vocabulary. You can't connect your visual goal with G'MIC commands.

You have no idea what to do. So you throw a Hail Mary! pass:
Imgcreator-AI — zmo.ai

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

Now, an older, wiser you, somewhat further along in the game, might pay attention to that bunch of text. But we haven't arrived at this version of you yet. You're young. Impetuous. You have Aunt May's picture! But you can't seem to do anything with it. Mouse over it and get a readout. Drag and select a box to magnify. Hit some keys. Nothing happens.

So — now what?

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. If you are not keen on shells, then you are going to have a tough time with G'MIC.

But — lets say you can get past that.

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

Put some pins in those. Image lists and pipelines live at G'MIC's very core. 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??!

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 and appends a display command at the end of the pipeline.

Oft times, these Hail Mary passes don't work.

But — in this case — everything did. You wrote your very first pipeline: -input auntmay_oldphoto.png -display, and stumbled onto your first success.

However, you don't want to stumble onto successes just when stars happen to align. You want to have successes every time. Every day. All the way!

Successes that become so commonplace that you don't think about them anymore.

So, lets pull the pins.

1.	Pipelines start with commands that, at the first go, put images on the image list.
2.	The image list (stack) is like a kitchen counter. You put stuff there until you can work on them.
3.	G'MIC assigns images positional numbers — indices — as they enter the stack.
4.	You can reference images with indices and direct commands to work on just those images by way of Selection Decorators.
5.	The G'MIC commands embody image processing work. In official distributions, there are a little over nine hundred of them. Maybe more than a thousand if you count community contributions.

At the moment, you know about two: input and display. It's a start.

Here's two more: output and normalize. output saves images. Even if saving images might not work. normalize pegs image intensities to new minima and maxima.

You now know enough for your first finger exercise. Let's fix up Aunt May — at least a little bit — by re-pegging the illumination range of the print. That is, normalize it. Type this at a shell prompt:

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

What do you think happened? No. We're not going to tell you. The purpose of finger exercises is to stretch yourself a little bit. Be curious. Snoop around. Look at the process log — those lines beginning with [gmic]. Aren't you curious about that constant case ratio? Google it, or go to G'MIC discuss.pixl.us and razz on about constant case ratios. That is — ask questions. Start a discussion. See who crops up with what.

Back here at Tutorial Land, notice that some words and phrases are in dark type. These link to other tutorials, reference documentation, Easter Eggs, whatever the tutorial authors think might be useful, given their crazed senses of humor. Follow these, but don't just read them — like some lump on a log. Above all else: do the finger exercises!

Finger exercises. Little pipelines that build command vocabulary. With a command vocabulary, you can better connect your visual goals to G'MIC pipelines.

What should be added to the command vocabulary? Commands with short names are good to start with. They are so oft-used that People Who Loathe To Type have made short names. That's a pointer to the more useful — or, at leat, the more frequently used — commands. The Technical Reference's List of Commands presents a Shortname table. Start looking up those commands.

Where do finger exercises come from? If you start looking up the short name commands — any command, really — in the Technical Reference, you will discover that most conclude with examples. Those are finger exercises. Look at them. Look at what they produce. Modify the parameters. Could a graphics program read the output? What would you have to do to make the results readable in your favorite paint program? Do the results align with any visual goals you may have?

How many finger execises? Lots and lots! Maybe three or four hundred per year — one finger exercise per day. Ah! You mean you have a — a — day job??? How unfortunate. But you have to eat, perhaps; pay rent and such. Then try for one finger exercise a week. Fifty or sixty in the next year.

Any slower than that and — don’t take this unkindly! — you’re not serious. That’s also fine. One of the best bits of education this writer ever earned, back in those halcyon college days — and, late again! with yet another assignment! — was the professor’s sigh. Then the lament: “You know? People always find time to do what they really want to do.”

Procrastination is instructive. It’s how your head tells you who you are.

So — if you are going to stick with this, do finger exercises. Don't wait around for people to give them to you. You are a digital artist now. In addition to getting finger exercises from the Technical Reference, seek them in the world. Look at textures, surfaces, The G'MIC Gallery, clothing fabric, Funny Oneliners, fields of grass. Tree bark. Concrete Textures. Can you write a pipeline that renders (maybe somewhat faux) versions of these? Yes you can. At first, keep the visual goals simple; challenge yourself to come up with pipelines that realize those goals. Then, up the ante. You'll get there.

And here is what we have in Tutorial Land. Some of the articles might help with decoding these finger exercises. At least a little, perhaps:

Introduction	A historical introduction. Read it when you need a break from finger exercises.
Basics	Everything written here, but a deeper dive.
Images	What an image looks like to G'MIC.
Command Decorations	Limit commands to work only on the images they are supposed to work on.
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.

Good luck. Have fun!

Updated: 07-May-2023 17:10 UTC Commit: 79f1223f76abc9d217cab05bf38ca89560b76ee6