GMICExpr node¶
This documentation is for version 2.1 of GMICExpr.
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, open-source library distributed under the CeCILL-C (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 time-varying waves.0.5*(j(1)-j(-1))
will estimate the X-derivative of an image with a classical finite difference scheme.if(x%10==0,1,i)
will draw blank vertical lines on every 10th column of an image.
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),++
,--
,+=
,-=
,*=
,/=
,%=
,&=
,|=
,^=
,>>=
,<<=
(in-place operators). - Usual functions:
abs()
,acos()
,arg()
,argmax()
,argmin()
,asin()
,atan()
,atan2()
,cbrt()
,cos()
,cosh()
,cut()
,exp()
,fact()
,fibo()
,gauss()
,hypoth()
,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()
,sum()
,tan()
,tanh()
,variance()
.atan2(x,y)
is the version ofatan()
with two argumentsy
andx
(as in C/C++).hypoth(x,y)
computes the square root of the sum of the squares of x and y.permut(k,n,with_order)
computes the number of permutations of k objects from a set of k objects.gauss(x,_sigma)
returnsexp(-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 argumenta_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 valid path to a file (resp. to a directory) or not.isin(v,a_1,...,a_n)
returns 0 (false) or 1 (true) whether the first valuev
appears in the set of other valuesa_i
.argmin()
,argmax()
,kth()
,max()
,mean()
,med()
,min()
,std()
,sum()
andvariance()
can be called with an arbitrary number of scalar/vector arguments.round(value,rounding_value,direction)
returns a rounded value.direction
can be { -1=to-lowest | 0=to-nearest | 1=to-highest }.
- Variable names below are pre-defined. They can be overrided.
l
: length of the associated list of images, if any (0 otherwise).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. total number of pixel values).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,7].R
,G
,B
andA
are equivalent toi0
,i1
,i2
andi3
respectively.im
,iM
,ia
,iv
,is
,ip
,ic
: Respectively the minimum, maximum, average values, 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).- 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 instanceia#0
denotes the average value of the first image). 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 meansmaster thread
).T
: current time [OpenFX-only].K
: render scale (1 means full scale, 0.5 means half scale) [OpenFX-only].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 vector-valued elements.
[ a0,a1,..,aN ]
defines a (N+1)-dimensional vector with specified scalar coefficients ak.vectorN(a0,a1,,..,)
does the same, with the ak being repeated periodically.- In both 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 sub-vector [ ap..aq ] of a vector X is retrieved by
X[p,q]
. - Equality/inequality comparisons between two vectors is possible with the operators
==
and!=
. - Some vector-specific 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) andsame(A,B,_nb_vals,_is_case_sensitive)
(vector equality test). - Function
resize(A,size,_interpolation)
returns a resized version of vectorA
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 }. - Function
find(A,B,_is_forward,_starting_indice)
returns the index where sub-vector 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 2-dimensional vector may be seen as a complex number and used in those particular functions/operators:
**
(complex multiplication),//
(complex division),^^
(complex exponentiation),**=
(complex self-multiplication),//=
(complex self-division),^^=
(complex self-exponentiation),cabs()
(complex modulus),carg()
(complex argument),cconj()
(complex conjugate),cexp()
(complex exponential) andclog()
(complex logarithm). - A MN-dimensional vector may be seen as a M x N matrix and used in those particular functions/operators:
**
(matrix-vector multiplication),det(A)
(determinant),diag(V)
(diagonal matrix from vector),eig(A)
(eigenvalues/eigenvectors),eye(n)
(n x n identity matrix),inv(A)
(matrix inverse),mul(A,B,_nb_colsB)
(matrix-matrix multiplication),rot(x,y,z,angle)
(3d rotation matrix),rot(angle)
(2d rotation matrix),solve(A,B,_nb_colsB)
(least-square solver of linear system A.X = B),trace(A)
(matrix trace) andtransp(A,nb_colsA)
(matrix transpose). Argumentnb_colsB
may be omitted if equal to 1. - Specifying a vector-valued math expression as an expression modifies the whole spectrum range of the processed image(s), for each spatial coordinates (x,y,z). The command does not loop over the C-axis 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()
anduppercase()
return string with all string characters lowercased or uppercased.
- Special operators can be used:
;
: expression separator. The returned value is always the last encountered expression. For instance expression1;2;pi
is evaluated aspi
.=
: variable assignment. Variables in mathematical parser can only refer to numerical values. Variable names are case-sensitive. Use this operator in conjunction with;
to define more complex evaluable expressions, such ast=cos(x);3*t^2+2*t+1
. These variables remain local to the mathematical parser and cannot be accessed outside the evaluated expression.
- The following specific functions are also defined:
normP(u1,...,un)
computes the LP-norm of the specified vector (P being an unsigned integer orinf
).u(max)
oru(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 }. Omitted coordinates are replaced by their default values which are respectively x, y, z, c, interpolation and boundary. For instance expression0.5*(i(x+1)-i(x-1))
will estimate the X-derivative 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 specifiedoffset
in the associated image buffer (or 0 if offset is out-of-bounds).j[offset,_boundary_conditions]
does the same for an offset relative to the current pixel (x,y,z,c).i(#ind,_x,_y,_z,_c,_interpolation,_boundary)
,j(#ind,_dx,_dy,_dz,_dc,_interpolation,_boundary)
,i[#ind,offset,_boundary]
andi[offset,_boundary]
are similar expressions used to access pixel values for any numbered image[ind]
of the list.I/J[offset,_boundary_conditions]
andI/J(#ind,_x,_y,_z,_interpolation,_boundary)
do the same asi/j[offset,_boundary_conditions]
andi/j(#ind,_x,_y,_z,_c,_interpolation,_boundary)
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).crop(_#ind,_x,_y,_z,_c,_dx,_dy,_dz,_dc,_boundary)
returns a vector whose values come from the cropped region of image[ind]
(or from default image selected ifind
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 invokation 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 ifind
is not specified) at specified 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.if(condition,expr_then,_expr_else)
: return value ofexpr_then
orexpr_else
, depending on the value ofcondition
(0=false, other=true).expr_else
can be omitted in which case 0 is returned if the condition does not hold. Using the ternary operatorcondition?expr_then[:expr_else]
gives an equivalent expression. For instance, G’MIC expressionsif(x%10==0,255,i)
andx%10?i:255
both draw blank vertical lines on every 10th column of an image.dowhile(expression,_condition)
repeats the evaluation ofexpression
untilcondition
vanishes (or untilexpression
vanishes if nocondition
is specified). For instance, the expression:if(N<2,N,n=N-1;F0=0;F1=1;dowhile(F2=F0+F1;F0=F1;F1=F2,n=n-1))
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 nullity condition. When done, it returns the last value ofexpression
.for(init,condition,_procedure,body)
first evaluates the expressioninit
, then iteratively evaluatesbody
(followed byprocedure
if specified) whilecondition
is verified (i.e. not zero). It may happen that no iteration is done, in which case the function returns 0. Otherwise, it returns the last value ofbody
. For instance, the expression:if(N<2,N,for(n=N;F0=0;F1=1,n=n-1,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 asfor(init,condition,expression)
without the specification of an initializing expression.date(attr,path)
returns the date attribute for the givenpath
(file or directory), withattr
being { 0=year | 1=month | 2=day | 3=day of week | 4=hour | 5=minute | 6=second }.date(_attr)
returns the specified attribute for the current (locale) date.print(expression)
prints the value of the specified expression on the console (and returns its value).debug(expression)
prints detailed debug information about the sequence of operations done by the math parser to evaluate the expression (and returns its value).init(expression)
evaluates the specified expression only once, even when multiple evaluations are required (e.g. ininit(foo=0);++foo
).copy(dest,src,_nb_elts,_inc_d,_inc_s)
copies an entire memory block ofnb_elts
elements starting from a source valuesrc
to a specified destinationdest
, with increments defined byinc_d
andinc_s
respectively for the destination and source pointers.
- User-defined functions:
- 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)
. - Overriding a built-in function has no effect.
- Overriding an already defined macro function replaces its old 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 self-operations. For instance,
foo(x) = x + x; z = 0; result = foo(++x)
will setresult = 4
rather than expected value2
.
- Custom macro functions can be defined in a math expression, using the assignment operator
- Multi-threaded and in-place evaluation:
- If your image data are large enough and you have several CPUs available, it is likely that the math expression 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!). 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 operatorsi()
,i[]
,j()
andj[]
return values of the image being currently modified, in forward (>
) or backward (<
) order. The multi-threading evaluation of the expression is also disabled in this case. - Function
(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
andj[_#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 (withi(...)
andi[...]
), or relatively to the current position (x,y,z,c) (withj(...)
andj[...]
). These expressions always returnvalue
.
- Usual operators:
Inputs¶
Input | Description | Optional |
---|---|---|
Source | Yes | |
Mask | Yes |
Controls¶
Parameter / script name | Type | Default | Function |
---|---|---|---|
Expression / expression |
String | i | G’MIC/CImg expression, see the plugin description/help, or http://gmic.eu/reference.shtml#section9 |
Help... / help |
Button | Display help for writing GMIC expressions. | |
(Un)premult / premult |
Boolean | Off | Divide the image by the alpha channel before processing, and re-multiply it afterwards. Use if the input images are premultiplied. |
Invert Mask / maskInvert |
Boolean | Off | When checked, the effect is fully applied where the mask is 0. |
Mix / mix |
Double | 1 | Mix factor between the original and the transformed image. |