G'MIC Tutorial Fragments

sadly neither works for me… on zsh.

Had to write it like this :
gmic sp , repeat 9 +rotate\[0\] "{$>*36},1,0,50%,50%" done add div 10

or like this :face_with_spiral_eyes: :
gmic sp , repeat 9 +rotate\[0\] \{$\>\*36\},1,0,50%,50% done add div 10

I guess a solution regarding syntax difference per shell is to write a Python script that would address those limitations when it comes, and have user select shell example choices. I could do a bit of that via Python and regex as now I know how to use Python to automate G’MIC coding. But, I think that’s just way too much regardless. Maybe later I could help on that, but between G’MIC things and other things I like doing, consider me out on that.

Wouldn’t it be easier to write a script that generates .gmic files like @David_Tschumperle’s example ? And add it as download?

One simple trick for Linux :
If your G’MIC command line does not use the single quote character ', then using command run is a good way to execute commands :

$ gmic run 'sp , repeat 9 +rotate[0] {$>*36},1,0,50%,50% done add div 10'
1 Like

Oh that’s nice indeed. Just add v 1inside the quotes to see what’ s happening:

gmic run 'v 1 sp , repeat 9 +rotate[0] {$>*36},1,0,50%,50% done add div 10'


Yes, and this makes me think that this should be actually the default behavior (without having to put v 1 in the command argument).

and a

$ gmic update

should be enough to get this working :slight_smile: (will be uploaded in a few moments).
(sometimes, I really love to see that G’MIC allows this).


Updated : works as intended :slight_smile: Thanks!

The idea behind presenting examples in the Technical Reference as custom commands — rather than as shell command lines — is to place to one side issues arising from the transformations that shell preprocessing performs on command line strings before G’MIC even sees the string. As you all know, the two processors collide over many special characters: $, {, }, and so forth, that they share compete over.

At the top of this discussion @samj observed that many of the of the Technical Reference examples as written fail to work. Well, yes, that when the example is tried, whatever shell is in the mix has first rights on processing command lines and gets to do its substitutions and transformations first, then the transformed string is given over to gmic. As is often the case, that transformed string is no longer the example as written and failures arise because the transformations that the outer shell has done do not accommodate G’MIC syntax.

It is certainly the case that that the G’MIC run command, given a single-quote verbatim string that happens to be a pipeline, lays to rest many shell-conflict issues, so long as the shell in question recognizes the single-quote verbatim notation as a string to be passed — untransformed — to the application. Windows PowerShell does, and on Linux, so does the bash shell. The nice aspect of the run command is that it rather creates a temporary custom command on-the-fly. (use gmic debug… to see the show), so it is not so much different from the scheme of writing a Technical Reference example as a small custom command. Using run may be the way to go if I could convince myself that the vast majority of shells support verbatim strings and that the convention of introducing them with single quotes is de rigueur. Alas, there may be shells out there… That uncertainty keeps me in the camp of illustrating examples with small custom commands.

Note that I used single quotes here to delimitate the single run argument, but double quotes work also most of the time (except when I have to use the devil ! character that is still substituted by something, at least with bash).

@David_Tschumperle :
Feature request. Would it be possible to modify the (undocumented) G’MIC reference command so that it renders the specially formatted comment string:

#@cli  : $ <example command>

more-or-less in the same manner across all the supported output modes: (help command ascii, HTML, PDF)? Currently, PDF renders in an outlier fashion:

in that the PDF renderer is inserting a $ gmic in front of <example command>, suggesting to readers of the PDF document that the given examples are to typed onto a shell command line, thereby subjecting themselves to all the command line issues that have been aired on this thread thus far.

Note that the HTML renderer:

or the render for the help command

$ gmic help blur

 blur (+):
      std_deviation>=0[%],_boundary_conditions,_kernel |

    Blur selected images by a deriche or gaussian filter (recursive 
    (equivalent to shortcut command 'b').

    'boundary_conditions' can be { 0=dirichlet | 1=neumann | 2=periodic | 
    3=mirror }.
    'kernel' can be { 0=deriche | 1=gaussian }.
    When specified, argument 'axes' is a sequence of { x | y | z | c }.
    Specifying one axis multiple times apply also the blur multiple times.

    Default values: 'boundary_conditions=1' and 'kernel=1'.

      [#1] image.jpg +blur 5,0 +blur[0] 5,1
      [#2] image.jpg +blur y,10%

    Tutorial: https://gmic.eu/oldtutorial/_blur

Do not insert $ gmic in front of <example command>, so those venues are agnostic about the larger context. In so far as HTML or ASCII rendering goes, the <example command> may very well be in a command definition module or embedded in the verbatim string of a run command. If PDF rendering can be bought into alignment with this, then we will not be unintentionally leading the PDF readers astray regarding the shell command line.

As for the formatting issue that @samj raised, that some examples are overly long and are clipped on the right hand side in the PDF document, I do not see any straightforward fixes. PDF is the least forgiving on right-hand-margin overruns; the issue is not that apparent in help ASCII or HTML rendering.

1 Like

For information: I tested the option with ‘run’.
This example with " works on the Windows terminal and the Linux Bash:

gmic run "sp , repeat 9 +rotate[0] {$>*36},1,0,50%,50% done add div 10"


Fixed for the .pdf, thanks!

1 Like

And thank you!



#@cli warpseq : _complexity(1-7),_warpmag(>0),\
# _colorshift(>0),0<=_eccentricity<1,-180<=_eangle<=180,\
# _autoanim_w(>0),_autoanim_h(>0)_autoanim_frames(>0)
#@cli : Distort selected (or create a demo) animation
#@cli : which reflects the warping of a time-varying
#@cli : displacement field.
#@cli : $ warpseq 1,200,1,0,0,600,600,1024 \
#  split z o warpswirl.mp4,30,h264
warpseq: -check ${1=3}>0"      && "\
                ${1}<=7"       && "\
                ${2=1}>0"      && "\
                ${3=2}>0"      && "\
                ${4=0}>=0"     && "\
                ${4}<1"        && "\
                ${5=0}>=-180"  && "\
                ${5}<=180"     && "\
                ${6=512}>0"    && "\
                ${7=$4}>0"     && "\
      -name. anim

   # Make spectral noiseball around specspace origin
   -name. noiseball
   -resize[noiseball] {$aw},{$ah},{$ad},{s},0

   # Make spectral noiseball multiplier ellipse
   -input {w#$noiseball},{h#$noiseball},{d#$noiseball},1
   -name. gaussball
   _mkclip[gaussball] $pw,$ecent,$ang 
   -shift[noiseball] {-$pw/2},{-$pw/2},{-$pw/2},0,2,0
   -shift[gaussball] {-w/2},{-h/2},{-d/2},0,2,0
   -set[gaussball] 0,0,0,0,0
   -normalize[gaussball] 0,1

   # Take spectral noise to spatial space
   -split[noiseball] c
   -append[-2,-1] c
   -orientation[noiseball] # Unscaled warping image...

   # Missing anim? Provide default imagery
   if $missing
         +structuretensors. 1
         -add.. 1.0e-06
         -split. c,2
         -fill.. rot(I(#-1,x,y,z),atan2(i(#$noiseball,x,y,z,1),i(#$noiseball,x,y,z,0)))*I
         -normalize. 0,255
         -name. anim
   #Make a separate, per-channel micro-warper
   -mul[noiseball] {$warpmag}
   -input[0] 3,3,1,2,u(-1,1)
   -name[0] microwarper
   -blur[microwarper] 1,1
   -resize[microwarper] {w#$anim},{h#$anim},1,2,5
   -normalize[microwarper] -$cshift,$cshift

   # Micro-warper is responsible for per-channel
   # shifting. Methinks this can be simplified,
   # perturbing noiseball instead and eliminating
   # this per-channel song-and-dance.
   -split[anim] c
   foreach[^noiseball,microwarper] {
      -name. anim
      -pass[noiseball] 1
      -pass[microwarper] 0
      -warp[anim] [noiseball],1,2,3
      -if $><$ccnt
         -repeat {d#$anim}
            -shared[noiseball] {$>},{$>},0
            -warp[-1] [microwarper],1,2,3
            -shared[noiseball] {$>},{$>},1
            -warp[-1] [microwarper],1,2,3
      -name[anim] $nm2
   -append c
   -crop[anim] 0,0,1,{w-1},{h-1},{d-2}
   -name. $nm

   -name. blurball
   -set[blurball] 1,{(w/2)-1},{(h/2)-1},{(d/2)-1},0
   -blur[blurball] $span,1
   -normalize[blurball] 0,1
   -input {w#0},{h#0},1,1
   -gaussian. {$span*[1,$minax]},-$ang
   -name. gaussian
   -repeat d#$blurball
      -shared[blurball] {$>},{$>},0         
      -mul. [gaussian]
   -name[blurball] $nm


Last spring, @SlavaCat118 observed in Documentation and examples for writing scripts that there seemed to be no cohesive tutorial (or set of tutorials) to bring one up the curve from writing simple to complex scripts — instead there are tutorial “lamp posts”, here and there, illuminating a landscape that is otherwise pitch black.

The gist of the discussion ran along the lines that newcomers do not have G’MIC vocabularies to connect visual goals with some pipeline of G’MIC commands. There needs to be an orderly presentation that starts with Chopsticks and ends with Ragtime, perhaps. Running with this musical analogy, I have been thinking in terms of finger exercises that, as a series, develops a script from a Chopsticks form to a Ragtime form.

tvfritz.gmic may be way too much even for a Ragtime end-state, but I found the resulting animations pretty. Perhaps a Ragtime-to-Chopsticks reduction will be in the mix of finger exercise for upcoming tutorials, these to address SlavaCat’s concerns — perhaps not. Likely not. Even the Ragtime end-state probably needs to be simpler than TV-On-The-Fritz. But it was a fun Sunday-Morning-Before_Breakfast exercise. Enjoy spelunking the code.


Joyous holidays, all. Before this year lapses, a final package of tutorials, some new, some reworked.

Tutorial Updates, December - Part Two

A new set of articles, Riffs (riffs.gmd) and Finger Exercises (fingerexercises.gmd) provides newcomers a regimen for developing their G’MIC vocabulary. This regimen embodies
two complementary approaches:

(1) Riffs, which embody unstructured play, while

(2) Finger Exercises harness G’MIC’s command module
framework as an organizing structure.

Riffs seem the natural approach that newcomers take when first exploring G’MIC. From simple pipelines written on command lines, newcomers snowball these into longer constructs as they gain familiarity with a collection of G’MIC commands, these typically supporting an effect or two
which a newcomer might find especially interesting. Riffs, however, reach comprehensibility limits when they grow to greater length.

To work past this barrier, the second article advances custom G’MIC commands as an environment in which to ‘exercise one’s fingers’. The analogy to practicing with musical instruments stems from a particular physical construction that musical instruments impose on their players. Musical instruments like guitars, harps, pianos and harmonicas, among others, all have specific sonic properties; one has to absorb those ‘into one’s fingers’ as a matter of becoming proficient.

With G’MIC, the art and craft of writing custom commands furnishes a similar setting. If a riff provides squeaks and squawks that roughly move toward an interesting visual, embodying the riff within the framework of a custom command introduces an organizing structure. For example, writing argument lists draws the newcomer’s attention to how the custom command might interact with its users. If an especially long argument list seems in order, then perhaps the custom command itself is failing the KISS principle and, conceivably, should be pruned so as to do one thing — just one thing! — well, and assign the balance of the effort to some other command.

As noted in Post #149, above, this effort addresses documentation shortcomings observed by @SlavaCat118 last April. This tutorial update stems from that, but while in preparation, I came to realize that unstructured play formed a greater part of my G’MIC education than I was inclined to remember. This became especially clear to me when opening up an archive of projects dating from eleven years ago and encompassing some of my earliest tutorial writing. A decade or so and on, it became clear to me that much came out of simple doodling: trying this, trying that, trying something else just for the sake of trying. With this came much re-writing of what I had written before, this to acknowledge that unstructured play has its worth. So from finger exercises came the addition of jazz.

I’ll be rather preoccupied for the balance of 2023. Then in 2024 a greater push to fill more holes in these introductory tutorials, particularly the Math Expression tutorials, which, at present, has more holes than filled spots. And there are still un-migrated 1.6 tutorials in the Old Tutorial tree which desperately need to be upgraded.

Be well all; I’ll check in again after the Solstice.


Welcome back, @grosgood .

1 Like

Hello Garry,
So nice!

I’ve update the new tutorial content on the G’MIC web page , e.g. : Riffs

Thank you for all these great contributions!

1 Like

Tutorial upgrades for February 9, 2024: 79d4ffa

  • What kept me preoccupied for most of January was salvage from the old tutorial space: Road Systems Maybe Or Cells. The text could be about ten years old and addressed an antediluvian version of G’MIC. To bring it forward to the present day, I wanted to inject some newer commands and features and settled on @garagecoder 's noise_poissondisk, and had some fun romping through it. Perhaps, over the run of 2024, I could retire the oldtutorial space in its entirety. Still much to salvage though.
  • Augmented Start Here with a very simple custom command example based on parse_cli print,<fragment>, so that I could, at a very elementary level, introduce the idea of having custom commands of one’s own and putting such in places such as user.gmic/.gmic. For those with an uncertain grasp of commands, having a look-up tool that takes a fragment and returns a list of commands containing the fragment is a useful jog of one’s memory.

That’s it for now; hopefully another lot around or before the March Ides.


Doesn’t “About G’MIC” filter has a link to “Start Here”? That would garner a bit more coders, maybe.

1 Like

The Filter Design section of the gmic-qt plug-in provides a gateway to the technical reference, scripting tutorials and the include/template.gmic:


The filter header for this introduction lives at about line 41620 in gmic_stdlib.gmic.

1 Like