Yes, and this makes me think that this should be actually the default behavior (without having to put v 1 in the command argument).
So:
and a
$ gmic update
should be enough to get this working 
(will be uploaded in a few moments).
(sometimes, I really love to see that GāMIC allows this).
Updated : works as intended 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:
$ 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:
help command
$ gmic help blur
blur (+):
std_deviation>=0[%],_boundary_conditions,_kernel |
axes,std_deviation>=0[%],_boundary_conditions,_kernel
Blur selected images by a deriche or gaussian filter (recursive
implementation).
(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'.
Example:
[#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.
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"
:o)
Fixed for the .pdf, thanks!
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" && "\
${8=$4}>0
sz,warpmag,cshift,ecent,ang=${1-5}
pw={2*$sz+1}
-local
nm={0,n}
-name. anim
aw,ah,ad:=[w#$anim,h#$anim,d#$anim]
missing=0
-onfail
nm="AutoAnimation"
aw,ah,ad=${6-8}
missing=1
-done
# Make spectral noiseball around specspace origin
$pw,$pw,$pw,2,u(-1,1)
-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
-mul[noiseball,gaussball]
# Take spectral noise to spatial space
-split[noiseball] c
-ifft[-2,-1]
-append[-2,-1] c
-orientation[noiseball] # Unscaled warping image...
# Missing anim? Provide default imagery
if $missing
-local[noiseball]
+structuretensors. 1
-eigen.
-abs..
-add.. 1.0e-06
-log..
-abs..
-split. c,2
-remove.
-fill.. rot(I(#-1,x,y,z),atan2(i(#$noiseball,x,y,z,1),i(#$noiseball,x,y,z,0)))*I
-remove.
-normalize. 0,255
-name. anim
-done
fi
#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.
ccnt={s#$anim-1}
-split[anim] c
foreach[^noiseball,microwarper] {
nm2={0,n}
-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
-remove[-1]
-shared[noiseball] {$>},{$>},1
-warp[-1] [microwarper],1,2,3
-remove[-1]
-done
-fi
-keep[anim]
-name[anim] $nm2
}
-remove[microwarper,noiseball]
-append c
-crop[anim] 0,0,1,{w-1},{h-1},{d-2}
-name. $nm
_mkclip:
nm={n}
-name. blurball
span:=_round($1,1,0)
ecent,ang=${2-3}
minax:=sqrt(1-$ecent^2)
-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]
-remove.
-done
-remove[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.
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 .
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!
Tutorial upgrades for February 9, 2024: 79d4ffa
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.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.
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.