G'MIC Tutorial Fragments

I have no idea what ‘chocolate exams’ are. I think I would enjoy taking them. That is, until my aorta clogs. That would probably, likely, put a crease in my tutorial writing, I think, among other things.

In general, I congratulate you in seizing life by the horns and riding the beast wherever it takes you. Don’t ever stop doing that, from time to time.

I still owe you some writing. Real Soon Now (I think).

1 Like

I’m done with gtutor_tileit for the time being, and it is probably done with me. For those interested in the full script — instead of the syncopated version in Tiled Art — find it below, from commit 9153a5c9ec3d, Saturday, May 29 16:45:28 2021 UTC. There are some text buglets in the tutorial proper, along with some passages that could be phrased more aptly. Those, and perhaps some less-performant aspects of the script itself, will be dealt with when they annoy me enough, I think in a week’s time. For now, I’m working my way through my end-of-month remit, noted above.

gtutor_tileit — 9153a5c9ec3d: Sat May 29 12:45:28 2021 -0400
#@gui __
#@gui <b>Testing</b>
#@gui <i>Gmic Tutorials</i>
#@gui Rectangular Tiling : _rec_tileit, gtutor_rectangular_tiling_preview
#@gui : documentation  = note("Generate a mosaic from an image. Works best with line art cartoons with flat color.")
#@gui : sep                 = separator()
#@gui : Tile Size           = float(1.0,0.05,5.0)
#@gui : Disrupt Orientation = float(5.0,0.0,10.0)
#@gui : Spread Tiles Apart  = float(1.5,0.25,5.0)
#@gui : Fill Holes          = bool(1)
#@gui : Color Count         = int(4,2,32)
#@gui : Flat Color          = bool(0)
#@gui : Light Angle         = float(45.0,-180,180)
#@gui : Soften Lighting     = float(0.5,0.0,5.0)
#@gui : note           = note(<small>Author: <i>Garry R. Osgood</i>. Latest Update: <i>2021/29/05</i></small>)
#@gui : url            = link("Technical Notes",https://gmic.eu/tutorial/tiled_art.html)

gtutor_rectangular_tiling_preview :
    gui_split_preview "gtutor_tileit ${2},${1},${3},${8},${4},${7},${5},${6}",0
    u "{$1}{$2}{$3}{$4}{$5}{$6}"\
    gtutor_tileit ${2},${1},${3},${8},${4},${7},${5},${6}

#@cli gtutor_tileit : 0<=_disrupt<=10,0.05<_tsize,0.25<=_spread,0<=_soft,_fillholes:True,-180<=_lightangle<=180,2<=_ccount<=32,_fcolor:False
#@cli : Generate a mosaic from an image. Works best with line art cartoons with flat color. 
#@cli : disrupt=5      Rotates, scales and displaces tiles. Suggest 0-10.
#@cli : tsize=1.0      Tile size relative to image. 1.0 → tile diagonal is 2.5% of the image diagonal.
#@cli : spread=1.5     Increasing promotes dropped tiles, gaps at junctions and runs. Suggest 0-3.
#@cli : soft=0.5       Soften and dull shadows and highlights. Suggest 0-5.
#@cli : fillholes=1    True:  Fill gaps and holes. No alpha channel.
#@cli :                False: Leave gaps and holes. Image has alpha channel.
#@cli : lightangle=45° Degrees: -180° – 180°. Lighting angle.
#@cli :                45°: Light appears to stream from viewer's upper left.
#@cli : ccount=4       Set number of dominant colors, taken from those most frequently occuring in source.
#@cli : fcolor=0       True:  Flat color tiling without lighting and shading.
#@cli :                False: Do tile lighting and shading.
gtutor_tileit : -check "${1=5}>=0 && $1<=10 && ${2=1.0}>=0.05 && ${3=1.5}>=0.25 && ${4=0.5}>=0 && isbool(${5=1}) && ${6=45}>=-180 && ${6}<=180 && ${7=4}>=2 && ${7}<=32 && isbool(${8=0})"
-echo[^-1] "Applying faux tiling to selected images. Disruption: "${1}". Tile size: "${2}". Tile spread: "${3}". Highlight softening: "${4}". Holes: "${arg\ 1+!$5,filling,leaving}". Light angle: "${6}"°. Color count: "${7}", and "${arg\ 1+!$8,unshaded,shaded}" color."
# Parameters


-repeat $!
      # Color quantization + black
      +colormap. ${ccount},1,2
      -index.. .,0,1
      -round 1
      -append[-2,-1] x
      -name. pallette
      -move[pallette] 0
      -name. qcolor
      -name. qlumin
      -normalize[qlumin] 0.6,1

      # Outline qcolor
      -input 100%,100%,1,1,'I(#-2,x,y)==I(#-3,0,0)?1:0'
      -fill. ">abs(
      -name[-1] outline

      # Cost: perturbs distance to outline measure, a basis of tile irregularity
      -input 100%,100%,1,1
      -name[-1] cost
      -plasma[cost] 4,4,{$disrupt}
      -normalize[cost] 0,{$disrupt/4.0}

      # Distance to outline + distance perturbation
      +distance[outline] 1,[cost],1
      -name. distvar
      +distance[outline] 1

      # True distance: basis for marking off distance by tile height
      -name[-1] truedistance

      # Orient: source of tile rotation
      -name[-2] orienter

      # Make Warper: distorts tiles
      -gradient[cost] xy
      -append[-4,-3] c
      -blur[-3] 1,1,1
      -normalize... {-1.5*$disrupt},{1.5*$disrupt}
      -name... warper

      #  Measure out and scribe tile center-to-center lines
      -round[truedistance] {$spread*$tsize}
      -fill[truedistance] ">

      # Compute orientation field
      -gradient[orienter] xy
      -append[-3,-2] c

      # Plotting field:
      -name. plottingfield

      # Draw tiles on a plotting field:
      # (1) xfrm: encodes tile translations and rotations
      # for tile corner points. (2) tl, tr, bl, br:
      # tile corners, expressed in homogeneous
      # coordinates.
      -fill[plottingfield] ">if(
                                 0<i#-2 && I#-1==[-1,-1,-1,0],
                                 tl=xfrm*[-"$tsize", "$tsize"/2.0,1];
                                 tr=xfrm*[ "$tsize", "$tsize"/2.0,1];
                                 br=xfrm*[ "$tsize",-"$tsize"/2.0,1];

      -cut[plottingfield] 0,255

      # Make isovalue targets for lighting height map
      -name. heightmap

      # Distort artwork
      -warp[plottingfield,heightmap] [warper],1,2,2

      # Clean up
      -index[plottingfield] [pallette],0,1
      -fill.. 'i>=127?255:0'
      -fill. 'i>0.05?1:0'
      -fill. 'i#-2==0?0:i'
      -if $fcolor # Do light and shade?
         -if $fillholes
            # Fill holes in the plotting field
            -fill[plottingfield] 'i#-2==0?I#-5*i#-4:I'
 	    -append[-3,-2] c
         # Distance from edges: proxy for
         # tile height. Shape height with
         # power function
         -distance[heightmap] 1
         -normalize[heightmap] 0,1
         -pow. 0.25
         -blur. 0.875,1,1
         -normalize[heightmap] 0,1
         -if {$fillholes==0}
            # Poke holes in the height map
            -fill[heightmap] 'i#-2==0?0:i'
            # Fill holes in the plotting field
            -fill[plottingfield] 'i#-2==0?I#-5*i#-4:I'
         # Cheap Fingerpaint Lighting
         # Derive shadow, hightlight, color
         -normalize[plottingfield] 0,1

         # Light
         +gradient[heightmap] xy
         -append[-2,-1] c
         -resize. [-2],[-2],[-1],[-1],1
         -compose_channels. add
         -name. light
         -cut. {ia},{iM}
         -normalize. 0,1
         -pow. 0.5
         if $soft>0
            -blur. {$soft},1,1

         # Shadow
         -mul.. -1
         -compose_channels.. add
         -name.. shadow
         -cut.. {ia#-2},{iM#-2}
         -normalize.. 0,1
         -pow.. 2

         # Composite
         -mul[light] '{iM#0}'
         -normalize[plottingfield] 0,255
         -if {$fillholes==0}
            -append[-3,-2] c
      -fi # else doing light and shade

Radial Basis Function tutorial Real Soon Now. Going through the push check list…

    -srand 5823619

    # Make a field of orientation angles through RBF interpolation
    -rbf. 2048,2048 
    -name. orient

    # Markers to place ellipses
    -input 100%,100%,1,1
    -noise_poissondisk. 20
    -name. markers

    # Plotting field. Give it a shadow
    # of the orientation field
    -input 100%,100%,1,3,'[90,30,40]'
    -name. plottingfield
    # Plot the ellipses themselves, aligned
    # with the orientation field.
    -r2dx. 50%,5
    -normalize. 0,255
1 Like

I haven’t done flowfield yet, but that is admittedly not so explored as in what one can see in P5js, openprocessing community. Definitely will look forward to tutorials on flowfield in gmic. I had some ideas on how to do flowfield in mind like emulating an area of liquid, and then letting the image dictate the direction of the flow.

On that note, imaginary-number low-level commands are not that explored either. I’m actually translating this into a new filter named Complex Popcorn Fractal - https://citeseerx.ist.psu.edu/viewdoc/download?doi= .

Could be “Ellipseflow” is click-bait: Such infâme was not among my aims; just a name I pulled up — without much thought on how it would be read. But there are no dynamics in play here, flow or otherwise. Just ellipses turned to orient themselves in the direction of the local gradient, that from from an orientation field conjured from the aether by -rbf, working from a mere handful of random two-channel points: that conjure, of course, is in keeping with the aims of the tutorial.

That said, dynamics are not far to be found: at least playful dynamics, the kind not keyed to any physical phenomena like fluid simulations. Two timing loops suggest themselves, each operating at different scales but otherwise grounded on numbers drawn from randomness.

  1. Small-scale: Inner loop. On the tick, markers take a pixel-and-a-fragment step at their current orientation and then resample the orientation field at the new location. Redraw the ellipse at the new orientation. Next tick. And so on. And so forth… This gives rise to a scurry of ellipses barreling over the orientation field.
  2. Large-scale: After some tens-of-ticks, the outer loop wakes up for a step and subjects the handful of keypoints that -rbf consumes to a Brownian motion kick. -rbf updates the orientation field which shifts slightly — or maybe, in some places, not so slightly. The thin plate spline could snap from time-to-time. In any case, the orientation field upon which the markers are grounded exhibits a local earthquake, usually minor — sometimes major. Drop back into the inner loop and the markers do their reorientation dance on somewhat altered ground.

All the field generation and rendering bits are in place. Need vectors to track the markers and the random samples underlying the orientation field. Add those structures, the two timing loops and we have, methinks, a Beginner’s Cookbook topic of some worth, duly registered here and to be completed when I get a round tuit. The only ones I’ve been finding of late are square, and have fur all over them…

“I juni måned” (In the Month of June) Laurits Andersen Ring

James Russell Lowell’s paean “And what is so rare as a day in June?” reveals this poet, literary critic and Atlantic editor, as a native of the upper latitudes of North America, for June on this part of the seaboard, my home, takes one’s breath away. Lowell spent most his life here. In the latter decades of the nineteenth century, he circulated almost exclusively in the environs between New York City and Boston.

Here above the horse latitudes, on the American eastern seaboard, these rare June days of crystalline air and low dew points straddle the summer solstice, and soon give way to a conveyor belt of Gulf Stream sogginess that persists, with intermittent relief, for the balance of the summer, propelled by an anti-cyclonic high pressure system known formally the North Atlantic (Subtropical) Anticyclone, and informally as the Bermuda High. I hope that it leads to pleasantness in Bermuda; its effects are imperfectly welcome here.

June sped by quickly, but a few tutorial pieces came to the fore. The effort to bring antique program control tutorials to a 2.9x setting has come to past:

  1. The “iffis” lead the way on May 31:-if…-fi…-elif…-else…-endif. I think the tutorial was one of the earliest written of the 1.6x series (2013) and all of the old examples utilized file or directory existence conditions, a scheme no longer supported after 2.6.; it was this that set off radioactivity alarms in the control flow realm.
  2. -repeat…-done was pulled into th 2.9x realm on Sunday June 6 and was largely re-written. The 1.6x examples were no longer workable, so the example was re-tooled.
  3. -local…-endlocal was similarly dragged into the 2.9x on June 12, much of it also re-written from scratch. The old tutorial had no working examples and was not complete; methinks it was published before it was finished. The most missing discussion was, to my mind, what happens when G’MIC merges local and global numeration.
  4. -rbf a new tutorial on Radial Basis Functions, rounds out June. Longish, but somehow just scratching the surface. How could I have left out generating warping vector fields on-the-fly, à la Interactive deformation and morphing. Well, -warp_rbf awaits in the wings for a future tutorial play, as does morph_rbf, the animated version… a great deal in store for extrapolators along a curve.

July, a steamy month in this locale, threatens anyone’s desire to Get Things Done: It’s Too Darn Hot. That said, there are still many basic, fundamental control flow commands that have never had benefit of any tutorial. Expect work along that course.

Along the lines of addressing the extreme basics, I have been given much thought to how rank beginners get through the very basic learning curve of the G’MIC command tool. Part of this is motivated by the collaboration with @myselfhimself in conveying to pythonistas what to feed the run() command. Part of this is also knowing that those who get initial success in obtaining what they set out to do have a rewarding sense of accomplishment — and so they set out to do more. Conversely, those who hit brick walls are just motivated to use something else. The game is to improve the success rate on those very early, rank-beginner explorations, but I don’t wish to duck the issue by presenting a portfolio of easy commands, as done here as they bypass the heart of the matter. Rather, I want to get to the heart of the matter, which is — I think — coping with the broad (and difficult) image manipulation freedom that the command line tool offers. It overwhelms. So I have been going though many old discuss.pixl.us and gimpchat.com posts in a forensic frame of mind, wondering how best to ease people into this. Not sure where something like this will wind up in the tutorial tree. Stay tuned.


Hi Gary,
that was pure pleasure to read your intro of new tutorial fragments.

I think I have to learn better English and to look into Lowell. Still I had recently some similar experience reading “Levines Mühle” from Johannes Bobrowski in German. Possibly, you can manage that. J. B. was a baltic Lithuanian German in the last century, my parents generation.

@grosgood : Now I have another idea for you. I have made a sample code that actually performs the same operation on multiple threads at once, and this beats apply_tiles, apply_parallel as you’re not restricted to a image, and you can do things like dynamic array, and insert into a image.

Reptorian's Sample Code which allows a very much non-standard multithreaded operation


 +s. x
 r[^0] 100%,100%,100%,2
 store[^0] dla_ref



repeat $n_threads

 length_const_line.="const v"
 if ($>!=$mt) 


echo $length_const_line
echo $xp_line

set 1,50%,50%,0

repeat $! l[$>]
 +rep_noise_poissondisk_to_coordinates 8
 l[0] $dla_ref endl
 s. y,$n_threads
 eval[1] :${-math_lib}$length_const_line$xp_line
endl done

The reason this works is that first, you generate the string which is dependent the number of threads that you have. And then, it will compile based on the string given.

This is the generated 12-threads code

 const v0=h#14;
 const v1=h#15;
 const v2=h#16;
 const v3=h#17;
 const v4=h#18;
 const v5=h#19;
 const v6=h#20;
 const v7=h#21;
 const v8=h#22;
 const v9=h#23;
 const v10=h#24;
 const v11=h#25;
1 Like

Some more awesome stuffs by @grosgood ! :beers: :+1:



Busy boxes presage a tutorial:


gmic -m busybox.gmic -busyboxes 512,0.008,98,-0.75,20 

This on the -for-done conditional — I believe such a construct is in the busybox script somewhere… I am sure of it!

busyboxes: check "isint(${1=128}) && ${1}>=128 && \ # Square image sz, pixels
                  isnum(${2=0.02})             && \ # Seeding
                  0.001<${2}&&${2}<=0.5        && \ # • Larger → more boxes
                  isnum(${3=96.5})             && \ # Limit spread
                  0<${3}&&${3}<100             && \ # • Smaller → more limited
                  isnum(${4=0})                && \ # Color
                  -1<=${4}&&${4}<=1            && \ # • Pink(-1) to Green(1)
                  isnum(${5=20})  && ${5} >0"       # Sharpness: Larger → +edginess
    # Render image
    -input $busybx_1,$busybx_1,1,3
    -name. boxplots
    -noise $busybx_2,2
    # Convolution kernels
    -input 3,3,1,1,-0.125
    -set. 1,1,1
    -name. neg
    -input 3,3,1,1,0.125
    -set. 1,1,1
    -name. pos
    # Convolve and spread
    -for abs(im#-3)<=$lbound&&$cnt<1000
        -if $cnt%2
           -convolve[boxplots] [pos],2,1
           -convolve[boxplots] [neg],2,1
    # Colorize
    -normalize 0,1
    -fill[boxplots] ">begin(rv=[1.0,0.23,0.1157]);
    -sharpen $busybx_5
    -normalize[boxplots] 0,255
1 Like


Two three things.

  1. You don’t need to use ‘-’. If you note my commands, I never use - next to their commands.

  2. input isn’t necessary. Just 3,3,1,1,-.125 would do for example.

Also I find this interesting:


What was the point of $=…? I only use it to access a specified argument. For example:

#@cli rep_mn: eq. to 'rep_multinormalize' : (+)
rep_mn: rep_multinormalize $*
#@cli rep_multinormalize: values
#@cli : Normalize based on channels using values.
#@cli : (eq. to 'rep_mn').\n
#@cli : Author: Reptorian.
repeat $! l[$>]
 repeat s
  sh $>
  normalize. $val_a,$val_b
endl done
1 Like

Voynich Manuscript
[Detail of the nymphs on folio 78r of the Voynich Manuscript Beinecke Rare Book & Manuscript Library, Yale University, New Haven, Connecticut, USA.

And so July is done, and the dog days of August are upon us, here on the Eastern Seaboard of North America. July was not as steamy as she could be, the latter two weeks being rather mild, and for some days with dew points in the mid to low 60°s Fahrenheit, ‘Fahrenheit,’ children, one of the many measures from the days of yore that we Americans still treasure.
I have been more sketching and planning than writing: getting grist for the mill. Thus, little came out through the door in July:

*do…while was unearthed from the 1.6x antiquities; I retained, but updated, its extended example on lightning bolts.
*for…done slipped past the door in the waning hours of 31 July. It freights a sidebar on Variance. One might notice a pattern in these workaday control flow commands: they are a good setting to slip in a little image theory. Not much, but a little. G’MIC does not operate in a vacuum; where possible, making home for an interesting or vital concept is intent on connecting the language with its world. Hopefully, this is not too painful.

@KaRo made an interesting remark on documenting when a document comes into being. Still uncomfortably aware of how much 1.6x documentation is still being taken seriously, I felt it responsible for me to begin dating these tutorials, now that Git so nicely records their development histories. Going forward, I will date the new and retrodate the older in the 2.9x series. There’s little to be done about the 1.6x series but rewrite them out of existence, for they are pure HTML with no backing originals.

It may not have been his intention, but in post 60 of this thread @Reptorian bought to the fore a responsibility where I have been remiss, so it seems worth my while to address that shortcoming now in these lackadaisical dog days of August, before the quickening press of September is upon us: by what principles am I guided to write these tutorials, in particular, a script coding style that I term “Tutorial writing?”

In fact, I have quite strong opinions on the matter, ones that favor redundancy over reduction, and I don’t want the vigour to which I hold these principles to translate in anyway to a seeming rebuff of the good @Reptorian, who is going about around here as he often does by being helpful. First and foremost, I want to make clear that I appreciate his helpfulness, hope to benefit more from it, and generally celebrate his being around.

That said, I should like to express my intent that explicit -input notation, hyphen-and-all, will be part of G’MIC tutorials so long as I have any part in the endeavor. The reasons, I think, are unassailable — but I have made no effort to advance what those reasons are, for which I have been remiss. So thank you @Reptorian, for bringing the matter to the fore, and what better place to do it than here in Tutorial Fragments?

To the rest of you developing twitches in the face of exciting discussions on Documentation Standards, I bid you a fair adieu, but before you drop entirely from the thread allow me to leave you with this: Clarity matters. In writing code, it is bearing in mind that someone will be reading it. Presuming you’ve done anything useful at all, it will be read, and if it is to serve as an agent to advance this particular craft, then it should be as readable as your skills can make it. That may entail coding in a style not quite so reduced as personal habit leads. That’s it. Drop now, and fair thee well.

One or two still here. Gee. Must be a slow day at the Krusty Krab. Very well then. Last March I went to some length about the process of tutorial writing Post 28, Instructions to help writing reference documentation, somewhat centered on how hard it is to get out of bed and find the bathroom, let alone write anything useful. What I didn’t address over there, but will here, is G’MIC’s recondite coding style, at once its strength and encroaching weakness. Fortunately, G’MIC’s design has a great deal of influence on coding style, such that one can, with deliberation and foresight, code in a way that avoids the allure of reduction in favor of redundancy. The trick, I think, turns on the realization that code can be read. Realizing that, one can then proceed to have her code deliberately read. It is a sociable thing to do, which is more than being pleasant. As I noted last month, those who have an initial success in steering G’MIC to do something useful enjoy a rewarding sense of accomplishment — and so they set out to do more. Conversely, those who hit brick walls are just motivated to use something else. G’MIC’s survival in the Darwinist world of open source depends on lots of little successes just like that. The key then, is engineering successes just like that.

Some time ago, @David_Tschumperle made clear his design goals for the G’MIC command line interpreter. See Looking back at 10 years of development. The two design goals were conciseness and coherence. By implementing highly consistent parsing rules, the G’MIC team in the days of yore achieved coherence, which furnishes a foundation for conciseness. With conciseness, we may routinely omit -input, say, and, given the coherent parsing rules that underlie command line parsing, nothing untoward happens: the command line parser quietly infers -input where it could have been and, if the pipeline is not too infested with typos, misconstructions or malapropisms, proceeds on its merry way. Through its substitution rules, G’MIC consolidates at levels approaching Forth: normalizen, set=, input → , among others, and if the out-of-the-box syncopations do not suffice, one may write <shortname> : <long form> substitutions — Adding Custom Commands in a nutshell — reducing, say, turbulence to mxup via a mxup : turbulence $* customization or some such.

In very short order, many sense the Game: consolidating code as a kind of solitaire, one that engenders enormous satisfaction in puzzling out how little one may write to do a lot.

This Game is not peculiar to G’MIC. It may be played with any language, computer or natural, and to serve pragmatic ends. I am sure many of you have heard the writers’ lament: “I am sorry I wrote you such a long letter; I did not have time to write a short one.” There is much time consumed in clarifying ideas so that words don’t get in the way: pouring through dictionaries to find that one nugget which dissolves a phrase, crafting apt transitions to burn down bridging paragraphs, sifting through similes and metaphores for just those that crystalize ideas shimmering on the edge of perception. It is a labor writers must do in the service of their readers, who, like all souls, live with time-and-space constraints and cannot spend forever reading a ramble. But it is also a labor in which writers take a great deal of pleasure, for it is again just the Game, and the Game’s condense-and-consolidate puzzles exercise our intellects and provide the thrill of the chase. Truth be told, I wouldn’t have it any other way. It would be churlish of me, therefore, to lodge any sort of complaint against the reduced-form of G’MIC coding, especially since I practice it myself, with all the childish delight of a chimpanzee in a poo fight. But — Alas! — The road to Hell is paved with good intentions. For all the good intentions behind the sophisticated and varied substitution rules underlying the most abbreviated, yet effective, G’MIC command, these very rules raise not an inconsiderable barrier to newcomers, whose oft-time response is this:

[quote=“punchcard, post:29, topic:9966”]
Did you ever create a filter or other GMic method to create these tilings? I’m having trouble figuring out the GMic commands because everyone uses single letter commands and no comments.[/quote]

The flip side of Reduction is Redundancy — pehaps the Anti-Game. Those who train themselves on writing a little to do a lot look upon Redundancy with not a little displeasure. Among cognoscenti conversing in the cloister there is indeed an ingrained resistance to perceived excess. However, the Hubble Space Telescope is still useful as of this writing because of triply-redundant systems. Commercial twin-engine aircraft can still get to an airport with just one engine. No one is suggesting, however, that this one engine suffices, because getting to an airport with no engines is hard.

The triply-redunant regimen taught to me is in pyramid form: “Tell 'em what you’re going to tell them. Tell 'em. Then, tell 'em what you told 'em.” The first part, the pinnacle, is a very concise précis about ‘Foo’, calibrated at just below the TL;DR tripwire. For semi-seasoned readers needing reminders, the first part triggers: “Ah! Foo! I remember Foo. I just need to get the Bar piece and then I’m good to go.” So the semi-seasoned peel away, leaving those still at sea with the middle part of the pyramid. In the middle part, we unpack Foo, present its relation to Bar, go over why Foo needs Bar while Bar may not need Foo, but heaven help you if you try to go through life without Foo, only Bar. At this juncture we hope to have cleared the hall but there are still stragglers in the cheap seats, way up in God’s Country, and the blank expressions on their faces tell you they Just Don’t Get It. Knowledge has a chiral character and a right-handed unpacking of Foo only works for some. So in the bottom part of the pyramid we unpack Foo again, only left-handedly: different words, new similes, slower unwindings and at a finer grain, and we leave Determinants to the last: the folk with left-handed brains always seem to struggle with Determinants.

There are more than a few Darwinists around perfectly willing to tell those at the bottom of the pyramid to just bugger off; pay people to give you the basics and come back here when you know how to ask a question. There is an economic side to how much time one can invest in walking people up a curve and it is a question with which I constantly struggle, for it has no clean resolution. My judgements in this matter tend to be provisional and are case-specific. For G’MIC, from which I took about a five year hiatus, my provisional judgement is grounded upon sobering observations when I came back: a community that has grown not that much in the intervening years — maybe it has shrunk! — and that withall suffers from the stress assailing many open-source projects: the participants are highly skilled and, for the talented, the commercial world has plenty of money. That, and the tendency of more experienced participants for acquiring greater responsibilities as their careers progress. So @David_Tschumperle’s cautionaries in Some news from the G’MIC developers’ corner! are unsettling but not surprising. These, too, are Darwinist pressures: a project either takes up new people to assume the load from those being drawn away — or it doesn’t. Full stop.

These issues are far larger than I am, so it comes to the piece that I can manage. It is this: technical communication, harnessed to draw in newcomers. It is what I do best and I can be at it as long as my health holds up and the City of New York doesn’t roll off the Eastern Seaboard. I find it quite remarkable, and very much to the credit of G’MIC development, that the language can be written at a variety of compression levels, from verbose to terse. Its curse is its salvation, the twain in ways depends upon intent. Any mature and intelligent practitioner of a craft knows when it is time to pick the right kit for the job.

For private experimentation, and perhaps communication with fellow cognoscenti, terse is fine, and, in fact, is the proper and polite way to go. One does not bore friends with redundancy. But in a more public sphere, with the aim to establish and advance acceptance for a craft, then clarity matters, and clarity is necessary for any active intent to communicate. Lacking that, the work becomes a latter day Voynich Manuscript, its somber mystery of little practical use in the advance of craft. So in the Tutorial sphere, I shall be the curmudgeonly guardian for the verbose Tutorial style, insistent on hyphens, full command spellings, named images and descriptive variable names, for all these offer clues of intent and engender readability. In time, perhaps, the student discovers the allure of syncopation, senses the Game, sees how little she can get away in typing and still pull off the trick. I will pretend not to notice. And if I think no one is looking, may hazard a smile.


Verbosity makes my eyes sting dry.
input is indispensable here:

gmic sample tiger input[0] 100%,50%,1,1


gmic sample tiger 100%,50%,1,1 move[-1] 0

Certainly. You’ve read the Post 61 rant on curmudgeonly opinions, so leave it at that.

Ditto here, no? We are both using the same $-expression mechanism. See Adding Custom Commands, ninth and last sub-bullet. Perhaps this is not immediately obvious because our notations superficially differ: you are harnessing a double-substitution mechanism, because your choice of argument index depends on the channel to which you have iterated. Say, at the second iteration with $> == 1 (‘G’ channel):

rep_mn.  40,100,5,200,0,255 # De-emphasize selected’s red channel
$=a # $-expression generates an assignment sequence with the base name `a`
    # for however many elements on the command line there may be
val_a=${a{$>*2+1}} → val_a=${a3} → val_a=5

At the second stage of this double-substitution, the inner expression resolves to a3, referencing a variable created by the $=a $-expression and assigned 3, Substituting again sets val_a to the third command line argument: 5. That selects the lower boundary of the normalization to be applied to the green channel of the currently selected image.


-busyboxes 512,0.008,98,-0.75,20
$=busybx_  # $-expression generates an assignment sequence with the base name
           # `busybx_` for however many elements on the command line there may be.
lbound={exp(($busybx_3/100)-1)} → lbound={exp((98/100)-1)} → lbound=0.9801987…

selects the third argument 98 directly, establishing a lower boundary with which the user is content. I see no fundamental difference in how we both harness $-expressions; we are both selecting elements from a (virtual, pseudo) argument ‘vector’.
For readers dropping in from search engines, G`MIC $-expressions permit pseudo-array actions with the G’MIC command line processor, which has no intrinsic array construct. Consider ssub.gmic:

ssub :
 -repeat $#+1
    -echo[] "Argument No. "$>" and its value: "${a{$>}}"."

To observe how the G’MIC manages $-expressions, run this command with a boosted verbosity:

gosgood@bertha ~ $ gmic -verbose 3 -command ssub.gmic ssub 45,192,dog,800A,1-800-555-1212,"Now is the time for every good boy to eat fudge!"
[gmic]-0./ Start G'MIC interpreter.
[gmic]-0./ Set verbosity level to 3.
[gmic]-0./ Import commands from file 'ssub.gmic' (2 new, 2 replaced, total: 4379).
[gmic]-0./ssub/ Set local variable 'a0=ssub'.
[gmic]-0./ssub/ Set local variable 'a1=45'.
[gmic]-0./ssub/ Set local variable 'a2=192'.
[gmic]-0./ssub/ Set local variable 'a3=dog'.
[gmic]-0./ssub/ Set local variable 'a4=800A'.
[gmic]-0./ssub/ Set local variable 'a5=1-800-555-1212'.
[gmic]-0./ssub/ Set local variable 'a6=Now is the time for every good boy to eat fudge!'.
[gmic]-0./ssub/*repeat/ Start 'repeat...done' block (7 iterations).
Argument No. 0 and its value: ssub.
Argument No. 1 and its value: 45.
Argument No. 2 and its value: 192.
Argument No. 3 and its value: dog.
Argument No. 4 and its value: 800A.
Argument No. 5 and its value: 1-800-555-1212.
Argument No. 6 and its value: Now is the time for every good boy to eat fudge!.
[gmic]-0./ssub/*repeat/ End 'repeat...done' block.
[gmic]-0./ssub/ Quit G'MIC interpreter.

The G’MIC command line parser replaces the pseudo-assignment $=var with a series of local variable assignments, var0=<first argument> var1=<second argument>… , equal to the number of elements on the command line — seven, in the example, enumerated from [0 – 6]. The first local assignment, enumerated zero, contains the name of the invoked command. The remaining assignments contain the command’s arguments in the order written.

This is a pretty little thing — normalizing channels independently — as in colorshifting footage:

Raw cauldron footage:

 $ gmic -input 256,256,600,3 -noise. 3,2 -bandpass. 0.01,0.02 o. bpass.cimg

Blue version:

$ gmic -command ssub.gmic -input bpass.cimg -rep_mn. 40,100,5,200,0,255 -split. z o bpass_bluish.mp4

Red version:

$ gmic -command ssub.gmic -input bpass.cimg -rep_mn. 0,255,5,200,40,120 -split. z o bpass_reddish.mp4

Though, perhaps, you might consider:

gtutor_mn: gtutor_multinormalize $*
#@cli gtutor_multinormalize: values
#@cli : Normalize based on channels using values.
#@cli : (eq. to 'gtutor_mn').\n
#@cli : Author: Reptorian.
repeat $! l[$>]
 repeat s
  sh $>
  normalize. $val_a,$val_b
endl done

because in the original:


the $-expressions (1) expand to an identical series of assignments, as they each necessarily operate on the same command line (there is only one), and (2) being in the innermost loop, these $-expression expansions are invoked 2 ($=a and $=b) × 3 (number of channels in each image) = 6 times per image. A bit of a shuffle. However, moving the $-expression $=a out of both loops and reusing the same $-expression series assignment for both val_a and val_b cuts down on the back-and-forth, no?

A quibble perhaps, as in the larger pipeline, ffmpeg encoding consumes the majority of time. In any case, a nice utility. Thank you!


It is not well known, but when writing out the -input command explicitly, the selector acquires a special meaning: it indicates what position in the image list an incoming image should go. See the Selection section, -input tutorial. With care, an incoming image can even be placed in more than one location.

  gmic -input[0] amp_y.png -input[0,-1] amp_c.png

Yes, I do that sometimes. My example was incomplete. That is why you are the tutorial writer. :stuck_out_tongue:

gmic seekbetter.gmic seekbetter 1024,576,256,1024,25,1.0625,50,40,50
 $1 → width                    →      1024
 $2 → height                   →       576
 $3 → slices                   →       256
 $4 → sprite count             →      1024
 $5 → acceleration attenuation →        25 (0: no attenuation (frantic animation) 100: attenuated to zero (languid animation))
 $6 → Velocity dampening       →    1.0625 (0: no dampening 100: dampens rapidly to zero)
 $7 → Microtiks per tik        →        50 (Lower, faster background paging. 50: microtik (50÷100) × slice count before advancing to next slice).
 $8 → Spectral turbulence      →        40 (0: Low frequency background gradient. 100: High frequency background gradient).
 $9 → Blend background         →        50 (0: Spectral field; 100: solid blue-gray. 50: 50-50 blend).
$10 → Recording mode           →  False(0) (True: start in recording mode. 's' on keyboard stops recording. Otherwise 'r' starts recording).


Sprites seek better homes. Bottom gradients with just teeny-tiny acceleration vectors, A place where a weary sprite can nestle down and get some sleep. Bliss! But, Alas! Water-shedding down an acceleration gradient develops velocity, maybe too much, and too often the poor sprite shoots past an inviting bottom gradient, only to fly up on the opposite slope — maybe even past it! With luck, with time, a sprite may slide into a bottom gradient without a lot of velocity, and with a bit of oscillation, settles in. Maybe other sprites can slide in on low delta too so that one and all become a part of a nice, squiggly pile of sprites. Then too, sometimes stability comes from being on the go: the nudging acceleration vectors do so just periodically enough to settle the sprites into circular paths, or along latitude/longitude lines of the torus.

And over the eons, plate tectonics happen. Mountains fall. Oceans rise. Bottom gradients shift and become inhospitable, sometimes cataclysmically, sending sprites off, yet again, to seek better homes.

Sprite Life

On a microtik:

  1. Dampen velocity a smidgen (90% - 95%).
  2. Sample the background pixel upon which the sprite sits, obtaining raw accelerations in x and y.
  3. attenuate the acceleration by a constant factor
  4. Add acceleration components to velocity, a delta-V.
  5. Orient the sprite along the velocity vector
  6. step the sprite

On a tik:

  • Step the background to the next torroidal slice - it’s almost, but not quite, the same as the slice before. This skews all the acceleration samples slightly.
  • On hitting ESC: Animation shuts down.

The outline for this appears in Post 54. Here is how the implementation turned out.

#@cli seekbetter : _width>64,_height>64,_depth>64,_sprite_count>0,0<=_acceleration_decay<=100,0<=_velocity_decay<=100,_microtik_rate>=0,_turbulence>=5,_backblend>=0
#@cli : Generate a `Seeking a Better Home` animation.
seekbetter :  -check "isnum(${1=512}) && ${1}>=64 && "\
	             "isnum(${2=512}) && ${2}>=64 && "\
	             "isnum(${3=128}) && ${3}>=64 && "\
		     "isint(${4=128}) && ${4}>0   && "\
		     "isnum(${5=50})  && ${5}>=1  && ${5}<=100 && "\
		     "isnum(${6=1})   && ${6}>=0  && ${6}<=100 && "\
		     "isnum(${7=50})  && ${7}>=0  && ${7}<=100 && "\
		     "isnum(${8=50})  && ${8}>=5  && ${8}<=100 && "\
		     "isnum(${9=0})   && ${9}>=0  && ${9}<=100 && "\
   # Set up parameters
   wid=$1                       # Field width: pixels 128 minimum
   hgh=$2                       # Field height: pixels 128 minimum
   dph=$3                       # field depth/tiktok slices: pixels: 64 minimum
   cnt=$4                       # Sprite count: count of swimming thingies — whatever they are. Positive integral count
   mul={exp(-$5/10)}            # Acceleration decay 0→100 (0 → 10 common) unitless multiplier
                                # 100 decays a lot, 0 not at all
   dcy={exp(-$6/100)}           # Velocity decay 0→100 (0→10 common): unitless real 100 decays a lot, 0 not at all 
                                # i. e., high decay: little velocity carry-over to the next microtik.
   tsz={round($dph*$7/100,1,0)} # Microticks per tiktok. lower microtick count evolves background at a faster pace.
   tub={$8/100}                 # Turbulence: 5 → 100. Higher: more turbulent landscape. Peaks and crannies galore!
   bkb={$9/100}                 # Background blend: 0 shows acceleration dynamics in background. 100: dark blue-gray
   rec=$10                      # If set (1), start in recording mode (Pre-presses 'r'). 's' stops recording. 
   # Otherwise a linear interpolation, with 50 representing a 50-50 blend.

   # Announcement
   -echo[^-1] "Starting a Seeking Better Home animation in a "$wid"×"$hgh"×"$dph" field "\
              "Sprite count (>0): "$cnt"; Relative Acceleration Attenuation (0→1): "$mul"; "\
              "Relative Velocity Decay (0→1): "$dcy"; Rel. Microtiks per Ticktok (frames) : "$tsz"; "\
              "Background Turbulence (>0.05): "$tub"; Background Fade (0→1): "$bkb
   # Generate data structures and viewport
   -input $cnt,1,1,4
   -name. sprites
   -mksprites[sprites] $wid,$hgh
   -mktorii  $wid,$hgh,$dph,10,$tub
   -name. torii
   -input $wid,$hgh,1,3
   -name. viewport

   # Outer tiktok loop. Page through the torus slices
       # Set the viewport background
       -fill[viewport] ">[i(#-2,x,y,"$tiktok",0),i(#-2,x,y,"$tiktok",1),0]"
       -normalize[viewport] 0,255
       -map[viewport] tarn
       -fill[viewport] "*lerp(I(#-1),[5,30,50],"$bkb")"
       +store[viewport] topography
       -window[viewport] $wid,$hgh,0,0,0,0,"Seeking a Better Land"
       -echo[] "Ticktok is: "$tiktok

       # Microtik loop. tsz → tick size → number of microticks before
       # advancing one frame to the next parameter space torus.
       -repeat $tsz

          # Events:
          #    Quit request?
          -if {*}" && "{*,ESC}
             -echo[] "Quitting..."

          #    Start recording frames?
          -elif {*}" && "{*,R}" && "$rec==0
	     -echo[] "Starting Recording in seek directory..."

          #    Cease recording frames?
	  -elif {*}" && "{*,S}" && "$rec==1
	     -echo[] "Stopping recording at "$oc" frames."

          # Paint the sprites
          -drawsprites. [-3],9,4,0.375

          # Step the dynamics
          -step[sprites] [-2],$tiktok,$mul,$dcy
          -toruswrap[sprites] 0,0,$wid,$hgh

          # Pause animation
          -window[viewport] $wid,$hgh,0,0,0,0,"Seeking a Better Land"
          -wait -10
	  -if $rec
	     -if !isdir('seek')
	        -exec "mkdir seek"
	        -if ${}
	           -error "Could not create output directory 'seek'; disabling recording."
             -output[viewport] "seek/seekbetter_"$oc".png"

          # Refresh background graphic
          -input $topography
          -name. topography
          -fill[viewport] I(#-1)
       -if $tiktok<$dph-1
   -while {*}" && "!{*,ESC}

mksprites : -check "isnum(${1=128}) && ${1}>=128 && isnum(${2=128}) && ${2}>=128 && isnum(${3=0}) && ${3}>=0" 
   -if s==4
      sw=$1  # Range Width
      sh=$2  # Range Height
      sm=$3  # Acceleration, pixels/sec²
      -fill. u([$sw,$sh,$sm,$sm])-[0,0,$sm/2,$sm/2]
      -round. 1
      -error "Channel count="{s}" is unexpected. 4 channels needed for sprites."

mktorii :  -check "isnum(${1=128}) && ${1}>=64 && "\
                  "isnum(${2=128}) && ${2}>=64 && "\
                  "isnum(${3=128}) && ${3}>=64 && "\
                  "isnum(${4=1})   && ${4}>0   && "\
                  "isnum(${5=0.5}) && ${5}>0   && ${5}<=1"

   # Parameter filtering
   wid=$1     # Field width in pixels (x)
   hgh=$2     # Field height in pixels (y)
   dph=$3     # Field depth in slices/pixels (z)
   acc=$4     # Peak to average relative distance. Higher → more active sprites
   tub={5*$5} # Turbulence (literally, spread of Gaussian noise in spectral space.
              # Higher → more spread → more high frequency components → more temporal turbulence 

   # Spectral noise
   -input $wid,$hgh,$dph,2,u([2,2,2])-[1,1,1]
   -name. snoise

   # Shape snoise into an approximate Gaussian distribution
   -input 100%,100%,100%,1
   -set. {whd},{(w/2)-1},{(h/2)-1},{(d/2)-1},0
   -blur. $tub,1,1
   -normalize. 0,1
   -append[-2,-1] c
   -name. smask
   -name. specspace
   -mul[specspace] {whd}

   # Locate noise kernel in the center of spectral space
   # Set frequency 0 ('DC') spectral point to zero
   -shift[specspace] {-(($wid/2)-1)},{-(($hgh/2)-1)},{-(($dph/2)-1)},0,2,0
   -set. 0,0,0,0,0
   -set. 0,0,0,0,1

   # zero-value dummy for imaginary component of each channel
   -fill. 0

   # Inverse Fourier Transform into temporal space

   # Heuristic: Choose the most nearly zero mean. (No basis in math)
   -if ia#-2>ia#-1
   -mul. {abs(im)>iM?$acc/im:$acc/iM}

step : -check ${"is_image_arg $1"}" && isint(${2=0}) && ${2}>=0 && isnum(${3=1}) && ${3}>=0 && isnum(${4=1}) && ${4}>=0"
   -pass$1 1
   -fill.. ">

toruswrap : -check "isnum(${1}) && isnum(${2}) && isnum(${3}) && isnum(${4})"
   lx=$1 # Lower bounds, x
   ly=$2 # Lower bounds, y
   dx=$3 # Width, x
   dy=$4 # Height, y
   fill. ">

drawsprites : -check ${"is_image_arg $1"}" && ${2=4} && ${2}>=4 && ${3=6} && ${3}>=4 && isnum(${4=0.5}) && ${4}>=0 && ${4}<=1"
   -pass$1 1   # 1D image, vector of sprites. Selected image is the canvas
   ra=$2       # a radius of ellipse
   rb=$3       # b radius of ellipse
   op=$4       # opacity of gray fill. Outline fully opaque
   -eval. ">

That’s it for now. Looks like a Cookbook, but a write-up won’t be 'til fallish. Thoughts, suggestions welcome. Probably drop this into garryosgood.gmic, gtutor_seekbetter, in the sweet fullness of time.


That is really impressive. Shows what is possible with G’MIC. Does remind me a bit of Processing works I have seen, but never bothered getting around doing animated things like that.

Me as well… Processing life

Hello Garry,
sorry I did a G’MIC summer break these last months.
I have read a bit of your last comments here and am very humbled :slight_smile:
I can dedicate a bit of time for making gmic-py releases go forward, but would be glad that this happen in some kind of remote sessions with other open source graphics related people, with some online appointment…