GMICExpr node
This documentation is for version 2.1 of GMICExpr (net.sf.cimg.CImgExpression).
Description
Quickly generate or process image from mathematical formula evaluated for each pixel. Full documentation for G’MIC/CImg expressions is reproduced below and available online from the G’MIC help. The only additions of this plugin are the predefined variables T
(current time) and K
(render scale).
Uses the ‘fill’ function from the CImg library. CImg is a free, opensource library distributed under the CeCILLC (close to the GNU LGPL) or CeCILL (compatible with the GNU GPL) licenses. It can be used in commercial applications (see http://cimg.eu).
Sample expressions
‘
j(sin(y/100/K+T/10)*20*K,sin(x/100/K+T/10)*20*K)
’ distorts the image with timevarying waves.‘
0.5*(j(1)j(1))
’ estimates the Xderivative of an image with a classical finite difference scheme.‘
if(x%10==0,1,i)
’ draws blank vertical lines on every 10th column of an image.‘
sqrt(zr=1.2+2.4*x/w;zi=1.2+2.4*y/h;for(i=0,zr*zr+zi*zi<=4&&i<256,t=zr*zrzi*zi+0.4;zi=2*zr*zi+0.2;zr=t; i=i+1))/255
’ draws the Mandelbrot fractal (give it a 1024x1024 image as input).
Expression language
The expression is evaluated for each pixel of the selected images.
The mathematical parser understands the following set of functions, operators and variables:
Usual operators:

(logical or),&&
(logical and),
(bitwise or),&
(bitwise and),!=
,==
,<=
,>=
,<
,>
,<<
(left bitwise shift),>>
(right bitwise shift),
,+
,*
,/
,%
(modulo),^
(power),!
(logical not),~
(bitwise not),++
,
,+=
,=
,*=
,/=
,%=
,&=
,=
,^=
,>>=
,<<=
(inplace operators).Usual math functions:
abs()
,acos()
,arg()
,argkth()
,argmax()
,argmin()
,asin()
,atan()
,atan2()
,avg()
,bool()
,cbrt()
,ceil()
,cos()
,cosh()
,cut()
,exp()
,fact()
,fibo()
,floor()
,gauss()
,int()
,isval()
,isnan()
,isinf()
,isint()
,isbool()
,isfile()
,isdir()
,isin()
,kth()
,log()
,log2()
,log10()
,max()
,mean()
, med(),
min(),
narg(),
prod(),
rol()(left bit rotation),
ror()(right bit rotation),
round(),
sign(),
sin(),
sinc(),
sinh(),
sqrt(),
std(),
srand(_seed),
sum(),
tan(),
tanh(),
variance(),
xor(). * '
atan2(y,x)' is the version of '
atan()' with two arguments __'y'__ and __'x'__ (as in C/C\+\+). * '
permut(k,n,with_order)' computes the number of permutations of __k__ objects from a set of __n__ objects. * '
gauss(x,_sigma)' returns __'exp(x\^2/(2\*s\^2))/sqrt(2\*pi\*sigma\^2)'__. * '
cut(value,min,max)' returns value if it is in range __\[min,max\]__, or __min__ or __max__ otherwise. * '
narg(a_1,…,a_N)' returns the number of specified arguments (here, __N__). * '
arg(i,a_1,..,a_N)' returns the __ith__ argument __a_i__. * '
isval()', '
isnan()', '
isinf()', '
isint()', '
isbool()' test the type of the given number or expression, and return __0 (false)__ or __1 (true)__. * '
isfile()' (resp. '
isdir()') returns __0 (false)__ or __1 (true)__ whether its argument is a path to an existing file (resp. to a directory) or not. * '
isin(v,a_1,…,a_n)' returns __0 (false)__ or __1 (true)__ whether the first value __'v'__ appears in the set of other values 'a_i'. * '
argmin()', '
argmax()', '
kth()', '
max()', '
mean()', '
med()', '
min()', '
std()', '
sum()' and '
variance()' can be called with an arbitrary number of scalar/vector arguments. * '
round(value,rounding_value,direction)`’ returns a rounded value. ‘direction’ can be { 1=tolowest  0=tonearest  1=tohighest }.Variable names below are predefined. They can be overridden.
‘
l
’: length of the associated list of images.‘
w
’: width of the associated image, if any (0 otherwise).‘
h
’: height of the associated image, if any (0 otherwise).‘
d
’: depth of the associated image, if any (0 otherwise).‘
s
’: spectrum of the associated image, if any (0 otherwise).‘
r
’: shared state of the associated image, if any (0 otherwise).‘
wh
’: shortcut for width x height.‘
whd
’: shortcut for width x height x depth.‘
whds
’: shortcut for width x height x depth x spectrum (i.e. number of image values).‘
im
’,‘iM
’,‘ia
’,‘iv
’,‘is
’,‘ip
’,‘ic
’: Respectively the minimum, maximum, average, variance, sum, product and median value of the associated image, if any (0 otherwise).‘
xm
’,‘ym
’,‘zm
’,‘cm
’: The pixel coordinates of the minimum value in the associated image, if any (0 otherwise).‘
xM
’,‘yM
’,‘zM
’,‘cM
’: The pixel coordinates of the maximum value in the associated image, if any (0 otherwise).All these variables are considered as constant values by the math parser (for optimization purposes) which is indeed the case most of the time. Anyway, this might not be the case, if function ‘
resize(#ind,..)
’ is used in the math expression. If so, it is safer to invoke functions ‘l()
’, ‘w(_#ind)
’, ‘h(_#ind)
’, … ‘s(_#ind)
’ and ‘ic(_#ind)
’ instead of the corresponding named variables.‘
i
’: current processed pixel value (i.e. value located at (x,y,z,c)) in the associated image, if any (0 otherwise).‘
iN
’: Nth channel value of current processed pixel (i.e. value located at (x,y,z,N)) in the associated image, if any (0 otherwise). ‘N’ must be an integer in range [0,9].‘
R
’,‘G
’,‘B
’ and ‘A
’ are equivalent to ‘i0
’, ‘i1
’, ‘i2
’ and ‘i3
’ respectively.‘
I
’: current vectorvalued processed pixel in the associated image, if any (0 otherwise). The number of vector components is equal to the number of image channels (e.g. I = [ R,G,B ] for a RGB image).You may add ‘
#ind
’ to any of the variable name above to retrieve the information for any numbered image [ind] of the list (when this makes sense). For instance ‘ia#0
’ denotes the average value of the first image of the list).‘
x
’: current processed column of the associated image, if any (0 otherwise).‘
y
’: current processed row of the associated image, if any (0 otherwise).‘
z
’: current processed slice of the associated image, if any (0 otherwise).‘
c
’: current processed channel of the associated image, if any (0 otherwise).‘
t
’: thread id when an expression is evaluated with multiple threads (0 means ‘master thread’).‘
T
’: current time [OpenFXonly].‘
K
’: render scale (1 means full scale, 0.5 means half scale) [OpenFXonly].‘
e
’: value of e, i.e. 2.71828…‘
pi
’: value of pi, i.e. 3.1415926…‘
u
’: a random value between [0,1], following a uniform distribution.‘
g
’: a random value, following a gaussian distribution of variance 1 (roughly in [6,6]).‘
interpolation
’: value of the default interpolation mode used when reading pixel values with the pixel access operators (i.e. when the interpolation argument is not explicitly specified, see below for more details on pixel access operators). Its initial default value is 0.‘
boundary
’: value of the default boundary conditions used when reading pixel values with the pixel access operators (i.e. when the boundary condition argument is not explicitly specified, see below for more details on pixel access operators). Its initial default value is 0.
Vector calculus: Most operators are also able to work with vectorvalued elements.
‘
[ a0,a1,...,aN ]
’ defines a (N+1)dimensional vector with scalar coefficients ak.‘
vectorN(a0,a1,,...,)
’ does the same, with the ak being repeated periodically if only a few are specified.In both previous expressions, the ak can be vectors themselves, to be concatenated into a single vector.
The scalar element ak of a vector X is retrieved by ‘
X[k]
’.The subvector [ X[p]…X[p+q1] ] (of size q) of a vector X is retrieved by ‘
X[p,q]
’.Equality/inequality comparisons between two vectors is done with operators ‘
==
’ and ‘!=
’.Some vectorspecific functions can be used on vector values: ‘
cross(X,Y)
’ (cross product), ‘dot(X,Y)
’ (dot product), ‘size(X)
’ (vector dimension), ‘sort(X,_is_increasing,_chunk_size)
’ (sorting values), ‘reverse(A)
’ (reverse order of components), ‘shift(A,_length,_boundary_conditions)
’ and ‘same(A,B,_nb_vals,_is_case_sensitive)
’ (vector equality test).Function ‘
normP(u1,...,un)
’ computes the LPnorm of the specified vector (P
being an unsigned integer constant or ’inf’). IfP
is omitted, the L2 norm is used.Function ‘
resize(A,size,_interpolation,_boundary_conditions)
’ returns a resized version of a vector ‘A’ with specified interpolation mode. ‘interpolation’ can be { 1=none (memory content)  0=none  1=nearest  2=average  3=linear  4=grid  5=bicubic  6=lanczos }, and ‘boundary_conditions’ can be { 0=dirichlet  1=neumann  2=periodic  3=mirror }.Function ‘
find(A,B,_is_forward,_starting_indice)
’ returns the index where subvector B appears in vector A, (or 1 if B is not found in A). Argument A can be also replaced by an image indice #ind.A 2dimensional vector may be seen as a complex number and used in those particular functions/operators: ‘
**
’ (complex multiplication), ‘//
’ (complex division), ‘^^
’ (complex exponentiation), ‘**=
’ (complex selfmultiplication), ‘//=
’ (complex selfdivision), ‘^^=
’ (complex selfexponentiation), ‘cabs()
’ (complex modulus), ‘carg()
’ (complex argument), ‘cconj()
’ (complex conjugate), ‘cexp()
’ (complex exponential) and ‘clog()
’ (complex logarithm).A MNdimensional vector may be seen as a M x N matrix and used in those particular functions/operators: ‘
*
’ (matrixvector multiplication), ‘det(A)
’ (determinant), ‘diag(V)
’ (diagonal matrix from a vector), ‘eig(A)
’ (eigenvalues/eigenvectors), ‘eye(n)
’ (n x n identity matrix), ‘inv(A)
’ (matrix inverse), ‘mul(A,B,_nb_colsB)
’ (matrixmatrix multiplication), ‘pseudoinv(A,_nb_colsA)
’, ‘rot(u,v,w,angle)
’ (3d rotation matrix), ‘rot(angle)
’ (2d rotation matrix), ‘solve(A,B,_nb_colsB)
’ (leastsquare solver of linear system A.X = B), ‘svd(A,_nb_colsA)
’ (singular value decomposition), ‘trace(A)
’ (matrix trace) and ‘transp(A,nb_colsA)
’ (matrix transpose). Argument ‘nb_colsB
’ may be omitted if it is equal to 1.Specifying a vectorvalued math expression as an argument of a command that operates on image values (e.g. ‘
fill
’) modifies the whole spectrum range of the processed image(s), for each spatial coordinates (x,y,z). The command does not loop over the Caxis in this case.
String manipulation: Character strings are defined and managed as vectors objects. Dedicated functions and initializers to manage strings are
[ 'string' ]
and'string'
define a vector whose values are the ascii codes of the specified character string (e.g.'foo'
is equal to [ 102,111,111 ])._'character'
returns the (scalar) ascii code of the specified character (e.g._'A'
is equal to 65).A special case happens for empty strings: Values of both expressions
[ '' ]
and''
are 0.Functions ‘
lowercase()
’ and ‘uppercase()
’ return string with all string characters lowercased or uppercased.Function ‘
stov(str,_starting_indice,_is_strict)
’ parses specified string ‘str
’ and returns the value contained in it.Function ‘
vtos(expr,_nb_digits,_siz)
’ returns a vector of size ‘siz
’ which contains the ascii representation of values described by expression ‘expr
’. ‘nb_digits
’ can be { 1=autoreduced  0=all  >0=max number of digits }.Function ‘
echo(str1,str2,...,strN)
’ prints the concatenation of given string arguments on the console.Function ‘
cats(str1,str2,...,strN,siz)
’ returns the concatenation of given string arguments as a new vector of size ‘siz
’.
Special operators can be used:
‘
;
’: expression separator. The returned value is always the last encountered expression. For instance expression ‘1;2;pi
’ is evaluated as ‘pi
’.‘
=
’: variable assignment. Variables in mathematical parser can only refer to numerical values (vectors or scalars). Variable names are casesensitive. Use this operator in conjunction with ‘;
’ to define more complex evaluable expressions, such as ‘t=cos(x);3*t^2+2*t+1
’. These variables remain local to the mathematical parser and cannot be accessed outside the evaluated expression.Variables defined in math parser may have a constant property, by specifying keyword
const
before the variable name (e.g.const foo = pi/4;
). The value set to such a variable must be indeed aconstant scalar
. Constant variables allows certain types of optimizations in the math JIT compiler.
The following specific functions are also defined:
‘
u(max)
’ or ‘u(min,max)
’: return a random value between [0,max] or [min,max], following a uniform distribution.‘
i(_a,_b,_c,_d,_interpolation_type,_boundary_conditions)
’: return the value of the pixel located at position (a,b,c,d) in the associated image, if any (0 otherwise). ‘interpolation_type’ can be { 0=nearest neighbor  other=linear }. ‘boundary_conditions’ can be { 0=dirichlet  1=neumann  2=periodic  3=mirror }. Omitted coordinates are replaced by their default values which are respectivelyx, y, z, c, interpolation
andboundary
. For instance command ‘fill 0.5*(i(x+1)i(x1))
’ will estimate the Xderivative of an image with a classical finite difference scheme.‘
j(_dx,_dy,_dz,_dc,_interpolation_type,_boundary_conditions)
’ does the same for the pixel located at position (x+dx,y+dy,z+dz,c+dc) (pixel access relative to the current coordinates).‘
i[offset,_boundary_conditions]
’ returns the value of the pixel located at specified ‘offset’ in the associated image buffer (or 0 if offset is outofbounds).‘
j[offset,_boundary_conditions]
’ does the same for an offset relative to the current pixel coordinates (x,y,z,c).‘
i(#ind,_x,_y,_z,_c,_interpolation,_boundary_conditions)
’, ‘j(#ind,_dx,_dy,_dz,_dc,_interpolation,_boundary_conditions)
’, ‘i[#ind,offset,_boundary_conditions]
’ and ‘i[offset,_boundary_conditions]
’ are similar expressions used to access pixel values for any numbered image [ind] of the list.‘
I/J[offset,_boundary_conditions]
’ and ‘I/J(#ind,_x,_y,_z,_interpolation,_boundary_conditions)
’ do the same as ‘i/j[offset,_boundary_conditions]
’ and ‘i/j(#ind,_x,_y,_z,_c,_interpolation,_boundary_conditions)
’ but return a vector instead of a scalar (e.g. a vector [ R,G,B ] for a pixel at (a,b,c) in a color image).‘
sort(#ind,_is_increasing,_axis)
’ sorts the values in the specified image [ind].‘
crop(_#ind,_x,_y,_z,_c,_dx,_dy,_dz,_dc,_boundary_conditions)
’ returns a vector whose values come from the cropped region of image [ind] (or from default image selected if ‘ind
’ is not specified). Cropped region starts from point (x,y,z,c) and has a size of dx x dy x dz x dc. Arguments for coordinates and sizes can be omitted if they are not ambiguous (e.g. ‘crop(#ind,x,y,dx,dy)
’ is a valid invocation of this function).‘
draw(_#ind,S,x,y,z,c,dx,_dy,_dz,_dc,_opacity,_M,_max_M)
’ draws a sprite S in image [ind] (or in default image selected if ‘ind
’ is not specified) at coordinates (x,y,z,c). The size of the sprite dx x dy x dz x dc must be specified. You can also specify a corresponding opacity mask M if its size matches S.‘
resize(#ind,w,_h,_d,_s,_interp,_boundary_conditions,cx,_cy,_cz,_cc)
’ resizes an image of the associated list with specified dimension and interpolation method. When using this, function, you should consider retrieving the (nonconstant) image dimensions using the dynamic functions ‘w(_#ind)
’, ‘h(_#ind)
’, ‘d(_#ind)
’, ‘s(_#ind)
’, ‘wh(_#ind)
’, ‘whd(_#ind)
’ and ‘whds(_#ind)
’ instead of the corresponding constant variables.‘
if(condition,expr_then,_expr_else)
’: return value of ‘expr_then
’ or ‘expr_else
’, depending on the value of ‘condition
’ (0=false, other=true). ‘expr_else
’ can be omitted in which case 0 is returned if the condition does not hold. Using the ternary operator ‘condition?expr_then[:expr_else]
’ gives an equivalent expression. For instance, expressions ‘if(x%10==0,255,i)
’ and ‘x%10?i:255
’ both draw blank vertical lines on every 10th column of an image.‘
dowhile(expression,_condition)
’ repeats the evaluation of ‘expression
’ until ‘condition
’ vanishes (or until ‘expression
’ vanishes if no ‘condition
’ is specified). For instance, the expression: ‘if(N<2,N,n=N1;F0=0;F1=1;dowhile(F2=F0+F1;F0=F1;F1=F2,n=n1))
’ returns the Nth value of the Fibonacci sequence, for N>=0 (e.g., 46368 for N=24). ‘dowhile(expression,condition)
’ always evaluates the specified expression at least once, then check for the loop condition. When done, it returns the last value of ‘expression
’.‘
for(init,condition,_procedure,body)
’ first evaluates the expression ‘init
’, then iteratively evaluates ‘body
’ (followed by ‘procedure
’ if specified) while ‘condition
’ is verified (i.e. not zero). It may happen that no iteration is done, in which case the function returns nan. Otherwise, it returns the last value of ‘body
’. For instance, the expression: ‘if(N<2,N,for(n=N;F0=0;F1=1,n=n1,F2=F0+F1;F0=F1;F1=F2))
’ returns the Nth value of the Fibonacci sequence, for N>=0 (e.g., 46368 for N=24).‘
whiledo(condition,expression)
’ is exactly the same as ‘for(init,condition,expression)
’ without the specification of an initializing expression.‘
break()
’ and ‘continue()
’ respectively breaks and continues the current running bloc (loop, init or main environment).‘
date(attr,path)
’ returns the date attribute for the given ‘path’ (file or directory), with ‘attr’ being { 0=year  1=month  2=day  3=day of week  4=hour  5=minute  6=second }, or a vector of those values.’
date(_attr)
returns the specified attribute for the current (locale) date.‘
print(expr1,expr2,...)
or’print(#ind)
prints the value of the specified expressions (or image information) on the console, and returns the value of the last expression (or nan in case of an image). Function ‘prints(expr)
’ also prints the string composed of the ascii characters defined by the vectorvalued expression (e.g. ‘prints('Hello')
’).’
debug(expression)
prints detailed debug information about the sequence of operations done by the math parser to evaluate the expression (and returns its value).‘
display(_X,_w,_h,_d,_s)
or’display(#ind)
display the contents of the vector ‘X
’ (or specified image) and wait for user events. if no arguments are provided, a memory snapshot of the math parser environment is displayed instead.‘
init(expression)
and’end(expression)
evaluates the specified expressions only once, respectively at the beginning and end of the evaluation procedure, and this, even when multiple evaluations are required (e.g. in ‘fill init(foo=0);++foo
’).‘
copy(dest,src,_nb_elts,_inc_d,_inc_s,_opacity)
copies an entire memory block of’nb_elts
’ elements starting from a source value ‘src
’ to a specified destination ‘dest
’, with increments defined by ‘inc_d
’ and ‘inc_s
’ respectively for the destination and source pointers.’
unref(a,b,...)
destroys references to the named variable given as arguments.’
stats(_#ind)
returns the statistics vector of the running image [ind], i.e the vector [ im,iM,ia,iv,xm,ym,zm,cm,xM,yM,zM,cM,is,ip ] (14 values).’
_(expr)
just ignores its arguments (mainly useful for debugging).
Userdefined macros:
Custom macro functions can be defined in a math expression, using the assignment operator ‘
=
’, e.g. ‘foo(x,y) = cos(x + y); result = foo(1,2) + foo(2,3)
’.Trying to override a builtin function (e.g. ‘
abs()
’) has no effect.Overloading macros with different number of arguments is possible. Redefining a previously defined macro with the same number of arguments discards its previous definition.
Macro functions are indeed processed as macros by the mathematical evaluator. You should avoid invoking them with arguments that are themselves results of assignments or selfoperations. For instance, ‘
foo(x) = x + x; z = 0; foo(++z)
’ returns ‘4’ rather than expected value ‘2’.When substituted, macro arguments are placed inside parentheses, except if a number sign ‘
#
’ is located just before or after the argument name. For instance, expression ‘foo(x,y) = x*y; foo(1+2,3)
’ returns ‘9’ (being substituted as ‘(1+2)*(3)
’), while expression ‘foo(x,y) = x#*y#; foo(1+2,3)
’ returns ‘7’ (being substituted as ‘1+2*3
’).Number signs appearing between macro arguments function actually count for ‘
empty
’ separators. They may be used to force the substitution of macro arguments in unusual places, e.g. as in ‘str(N) = ['I like N#'];
’.
Multithreaded and inplace evaluation:
If your image data are large enough and you have several CPUs available, it is likely that the math expression passed to a ‘
fill
’ or ‘input
’ command is evaluated in parallel, using multiple computation threads.Starting an expression with ‘
:
’ or ‘*
’ forces the evaluations required for an image to be run in parallel, even if the amount of data to process is small (beware, it may be slower to evaluate in this case!). Specify ‘:
’ (instead of ‘*
’) to avoid possible image copy done before evaluating the expression (this saves memory, but do this only if you are sure this step is not required!)If the specified expression starts with ‘
>
’ or ‘<
’, the pixel access operators ‘i()
’, ‘i[]
’, ‘j()
’ and ‘j[]
’ return values of the image being currently modified, in forward (‘>
’) or backward (‘<
’) order. The multithreading evaluation of the expression is also disabled in this case.Function ‘
critical(operands)
’ forces the execution of the given operands in a single thread at a time.
Expressions ‘
i(_#ind,x,_y,_z,_c)=value
’, ‘j(_#ind,x,_y,_z,_c)=value
’, ‘i[_#ind,offset]=value
’ and ‘j[_#ind,offset]=value
’ set a pixel value at a different location than the running one in the image [ind] (or in the associated image if argument ‘#ind
’ is omitted), either with global coordinates/offsets (with ‘i(...)
’ and ‘i[...]
’), or relatively to the current position (x,y,z,c) (with ‘j(...)
’ and ‘j[...]
’). These expressions always return ‘value
’.
Inputs
Input 
Description 
Optional 

Source 
Yes 

Mask 
Yes 
Controls
Parameter / script name 
Type 
Default 
Function 

Expression / 
String 
i 
G’MIC/CImg expression, see the plugin description/help, or http://gmic.eu/reference.shtml#section9 
Help… / 
Button 
Display help for writing GMIC expressions. 

(Un)premult / 
Boolean 
Off 
Divide the image by the alpha channel before processing, and remultiply it afterwards. Use if the input images are premultiplied. 
Invert Mask / 
Boolean 
Off 
When checked, the effect is fully applied where the mask is 0. 
Mix / 
Double 
1 
Mix factor between the original and the transformed image. 