UserFilter Plug-in for The Gimp

This page is still under construction.

Please go to the project page on SourceForge for the time being.

Nevertheless, you can find a short guide on how to use this plug-in below...

1 Introduction

The User Filter plug-in is a generic plug-in that enables the user to apply arbitrary functions to the R, G, B, and A channels of an image. These functions can be used to manipulate an image in almost any aspect that is possible also by writing a native Gimp plug-in. The advantage of this is, that a user does not need to have a very deep knowledge of programming in general or the Gimp's API in order to create a new filter, as "programming" is limited to writing the manipulator functions ? while the user interface stays more or less the same.

1.1 The User Filter Plug-in Interface

When opening the User Filter plug-in for the first time, you will notice a tabbed dialog that groups the functions of the plug-in into control filter effects, creating and editing filters, managing existing filters, and setting up search paths to define the locations where the plug-in should look for filter files.

1.1.1 User Filter Setup

The User Filter plug-in will, by default, look for new or existing filters in the directories $GIMP_DIR/userfilter and $GIMP_DATA_DIR/userfilter. This can be changed with the "Filter Directories" dialog, where you can add or remove search paths for the plug-in to look for filter files.

Note, that the User Filter plug-in will recursively scan these directories for new and existing filters when The Gimp is started. This means that you can organize your filters within these directories in subdirectories without having to manually add these in the directory settings panel.

1.1.2 Managing Your Filters

"Filter Management" is done using the dialog of the same name. "Management" here means, that you can load a filter from the list of filters that is shown in this panel or mark (or unmark) a filter for automatic registration in the Gimp's menu. Since you can easily collect several hundreds (even thousands) or filters (there are that many freely available on the internet that can be used with the User Filter plug-in), you will probably like the idea of not having all of them registered in The Gimp's menu, but still being able to select them from within the management panel.

Filters that are selected for registration in The Gimp's menu have a special marking in the "Plug-in" column of the filter list. You can toggle this by left-clicking with your mouse. These changes will, however, require The Gimp to be restarted in order to take effect.

Any filter can be loaded from the list by selecting it and the clicking the "Open" button in the panel ? or by simply double-clicking on a list entry.

1.1.3 Creating and Editing Filters

This is done in the "Filter Editor" panel. By default, the User Filter plug-in will start with a "do-nothing" filter preset that has already been tuned by the plug-in to match your environment settings, i.e. the authors name and the copyright information are set according to the login information retrieved from your system. The editor panel is divided into three main parts: filter information, user interface settings, and ? most important - the formula editor.

You can reset the plug-in to use this default "do-nothing" filter by clicking the "New" button in the panel. Any previously loaded filter will be cleared and the default "do-nothing" filter will be applied.

You can load existing filters from this panel, too, regardless whether they are located in your User Filter data directories or not. The User Filter plug-in recognizes four different types of files that can be loaded:

*.guf ? the native file format of the User Filter plug-in
*.8bf ? a (Windows) binary filter for Photoshop
*.afs ? a source file for Filter Factory or Filter Foundry
*.txt ? a source file for the Plugin Commander

Please note, that not all of the *.8bf (Photoshop binary filters) that you might find somewhere will work with the User Filter plug-in. Only those, that have been created using the Filter Factory plug-in for Photoshop or the Plugin Commander will.

The User Filter plug-in is designed to be backwards compatible with the above non-native file formats. It has, however, certain extensions that will require you to first tune the filter settings before you can fully use it, e.g. the *.afs format won't carry most of the information that is shown in the user interface of the User Filter plug-in. Therefore, when saving filters, you should always save them to the native file format of the User Filter plug-in in order not to lose this information (except, maybe, if you want to share your filter with a user of Filter Foundry or Plugin Commander who may not be able to read the native file format of User Filter). Please note also, that the old non-native file formats have certain limits with regards to the length of the functional expressions. You will not be able to export filters with functional expressions that are longer than 1024 characters to any of the non-native file-formats; also, you will not be able to export the filter to the proprietary binary executable *.8bf file format. Please note also, that you will not be able to export a filter to one of the non-native file formats if the filter utilizes any extension that is not backward compatible with Filter Factory / Filter Foundry for Photoshop. See also the chapter on portability for further information.

Most of the editor entries will be quite self-explaining ? except for the function editor. For this to understand, you should refer to the chapters on User Filter functions.

Note: Certain features that exist in the native User Filter file format (namely localization support for your filters) cannot yet be edited in this panel ? work is underway though...

1.2 User Filter Functional Language

Any filter consists of a set of functional expressions that are applied for each pixel in an image (or a selection in the image respectively). The plug-in will apply these expressions in sequence R,G,B,A ? this means, that you can store the results of certain subexpressions and re-use them in the next channel's functional expression.

The User Filter plug-in has been designed to be backward compatible with Filter Factory / Filter Foundry. It will understand the same functional language that is understood by these Photoshop plug-ins. This means that you can not only import filters that have been created with or for those plug-ins, but you can also use any tutorial or manual from these plug-ins for your work with User Filter as well. However, since there exist two versions of FF that differ from each other with regards to the values returned by certain functions and some maximum values, you should consult the section about portability in order to get the intended results with filters that have been written for FF.

Functional expressions follow a notation that closely resembles the syntax found in the "C" programming language.

1.2.1 Constants

The User Filter functional language has two kinds of constants: "true" constants, i.e. those that have a predefined value, image environment dependent constants, i.e. constants that have different values for every image, and pixel environment dependent constants, i.e. constants that have different values for every pixel within the image. Any of the named constants are often called "variables" in manuals and tutorials for Filter Factory / Filter Foundry, but since they cannot be modified by any of the functional expressions, we rather call them constants here.

Name	Description
Integer literals	Numeric values can be written in octal, decimal, and hexadecimal in the same notation as in the "C" programming language, i.e. any number starting with a 0 will be treated as an octal value, unless it also contains the digits 8 or 9; any number starting with 0x will be treated as a hexadecimal number.
rmin, gmin, bmin, amin, cmin	Minimum value that can be applied to the "red", "green", "blue", "alpha", and "current" color channel (0).
rmax, gmax, bmax, amax, cmax	Maximum value that can be applied to the "red", "green", "blue", "alpha", and "current" color channel (255). Note, that this value will change from a true constant into an image dependent constant when wider color channels will get supported¹.
R, G, B, A, C	Range of channel values such that R = \|rmin...rmax\|, G = \|gmin...gmax\|, B = \|bmin...bmax\|, A = \|amin...amax\|, and C = \|cmin...cmax\|.
r, g, b, a, c	Value of the current pixel in the "red", "green", "blue", alpha", and the "current" color channel, where rmin <= r <= rmax , gmin <= g <= gmax , bmin <= b <= bmax, amin <= a <= amax, and cmin <= c <= cmax respectively.
imin, umin, vmin	Minimum color values in YUV color space, where imin = 0, umin = -56, and vmin = -78.
imax, umax, vmax	Maximum color values in YUV color space, where imax = 255, umax = 56, and vmax = 78.
i, u, v	Current pixel value in YUV color space, where imin <= i <= imax, umin <= u <= umax, and vmin <= v <= vmax.
xmin, ymin	Minimum horizontal and vertical coordinates (0).
xmax, ymax	Maximum horizontal and vertical coordinates. This depends on the dimensions of the image.
X, Y	Range of horizontal and vertical image coordinates (width and height of the image), such that X = \|xmin...xmax\|, and Y = \|ymin...ymax\|.
x, y	Current horizontal and vertical coordinate of the pixel that is processed, where xmin <= x <= xmax and ymin <= y <=ymax.
dmin	Minimum angle within the image (0).
dmax	Maximum angle within the image (1023)².
D	Range of angles within the image, so that D = \|dmin...dmax\| = 1024.
d	Angle of the current pixel from the center of the image, where dmin <= d <= dmax.
mmin	Minimum distance ("magnitude") of the current pixel from the center of the image (0).
mmax	Maximum distance ("magnitude") of the current pixel from the center of the image, where mmax = (M = (?(X² + Y²)) / 2) - 1.
M	Range of magnitudes of the current pixel from the center of the image, where M = \|mmin...mmax\| = (?(X² + Y²)) / 2.
m	Distance ("magnitude") of the current pixel from the center of the image where mmin <= m <= mmax.
zmin	Minimum channel index (0).
zmax	Maximum channel index, depending on the color mode of the image, where 0 = Gray < GrayA < RGB < RGBA = 3.
Z	Range of channel indexes within one pixel, so that Z = \|zmin...zmax\|.
z	Channel index for the current expression, where 0 = R < G < B < A = 3.

Any of the "true" constants are treated like integer literals by the byte-code generator of User Filter and the plug-in translator uf2c. There is no difference between writing the constant name or its integer representation except where it comes to portability. The byte-code optimizer of User Filter will also reduce the code tree for any constant subexpression, except where pixel dependent constants are used.

Unlike as it is documented in Filter Factory, using i, u or v in your functions is not slower than using r, g, or b.

1.2.2 Variables

There are no true variables in the User Filter functional language (since you cannot "assign" values). It is possible, however, to store up to 256 different values in an indexed temporary store (and retrieve these values later). See the "put (y, i)" and "get (i)" functions for more information.

1.2.3 Operators

The operators are used in the functional language of User Filter as are used in the "C" language and with the same semantical effects (except for the assignment operators, which are not available here).

All arithmetic operations are done using 32-bit integer values. There are neither floating point nor fixed point operations.

All logical operations consider the value 0 being false, all other values being true. If a function or operation returns the value of true, it will effectively return the numeric value 1.

Operator	Syntax	Description
,	expression , expression	Sequence. The comma operator is used to chain multiple expressions into a single expression. Execution of code is from left to right ? both subexpressions are evaluated and the result value of the right expression is returned.
?:	expression ? expression : expression	Conditional. The conditional operator evaluates the expression before ? and if the result is not 0 returns the result of the first subexpression, else it returns the result of the second subexpression. Only one of the two conditional subexpressions is evaluated.
&&	expression && expression	Logical and. Returns 0 (false) if one of the two subexpressions is 0 (false), else 1 (true).
\|\|	expression \|\| expression	Logical or. Returns 1 (true) if one of the two subexpressions is 1 (true), else 0 (false). The logical operators are shortcut operators, i.e. if the result of the first subexpression would also be the result of both subexpressions, only the first subexpression gets evaluated (e.g. 1 \|\| 0 or 0 && 1).
&	expression & expression	Bitwise and. For any bit that is set in both expressions the bit is also set in the result.
^	expression ^ expression	Bitwise exclusive or. Returns a set bit for any bit that is set in the first or the second subexpression, but not in both.
\|	expression \| expression	Bitwise inclusive or. Returns a set bit for any bit that is set in one of the two subexpressions. The bitwise operators are full-evaluation operators, i.e. both subexpressions are evaluated.
==	expression == expression	Equal to. Returns 1 (true) if the results of the left and right subexpression are equal, else 0 (false).
!=	expression != expression	Not equal to. Returns 1 (true) if the results of the left and right subexpression differ, else 0 (false).
<	expression < expression	Lesser than. Returns 1 (true) if the results of the left subexpression is lesser than the result of the right subexpression, else 0 (false).
<=	expression <= expression	Lesser than or equal to. Returns 1 (true) if the results of the left subexpression is lesser than or equal to the result of the right subexpression, else 0 (false).
>	expression > expression	Greater than. Returns 1 (true) if the results of the left subexpression is greater than the result of the right subexpression, else 0 (false).
>=	expression >= expression	Greater than or equal to. Returns 1 (true) if the results of the left subexpression is greater than or equal to the result of the right subexpression, else 0 (false).
<<	expression << expression	Bitwise shift left. Shifts the bits of the result of the left subexpression result of the right subexpression times left. This operation is equivalent to an n-times multiplication of the left subexpression with 2.
>>	expression >> expression	Bitwise shift right. Shifts the bits of the result of the left subexpression result of the right subexpression times right. This operation is equivalent to an n-times division of the left subexpression by 2.
*	expression expression*	Multiplication. Returns the result of multiplication the left subexpression by the right subexpression.
/	expression / expression	Division. Returns the result of the left subexpression divided by the right subexpression. If the right subexpression returns 0, the operation will return 1.
%	expression % expression	Modulo division. Returns the remainder of the left subexpression divided by the right subexpression. If the right subexpression returns 0, the operation will also return 0.
+	expression + expression	Addition. Returns the value of the left subexpression plus the value of the right subexpression.
-	expression - expression	Subtraction. Returns the value of the left subexpression minus the value of the right subexpression.
!	! expression	Logical not. Returns 1 (true) if the result of the right expression is 0 (false), else 0.
~	~ expression	Bitwise not. Inverts all bits in the result of the right expression.
-	- expression	Negation. Returns the negative value of the result of the right expression.

1.2.4 Functions

Function	Description
ctl (i)	Value of slider i, where 0 <= i <= 7 and 0 <= ctl (i) <= 255.
val (i, a, b)	Value of slider i, where 0 <= i <= 7 and 0 <= ctl (i) <= 255 mapped onto the range [a...b] so that a <= val (i, a, b) <= b.
map (i, n)	Return entry n from mapping table i, where 0 <= n <= 255 and 0 <= i <= 3. Each mapping table uses a pair of sliders, ctl (2 i)* and ctl(2 i + 1)* for the high and the low values of the mapping table formula. The entries of the mapping table are computed so that if n <= ctl (2 i + 1) then 0 else if n >= ctl (2 * i) then 255 else if ctl (2 * i + 1) < n < ctl (2 * i) then (n - ctl (2 * i + 1)) * 255 / (ctl(2 * i) ? ctl(2 * i + 1)) else 0*.
src (x, y, z)	Return the channel value of the pixel at the cartesian coordinates x, y in color channel z, where xmin <= x <= xmax, ymin <= y <= ymax, and zmin <= z <= zmax. For off-image coordinates the channel value depends upon the setting of the edge-mode control³. Using this function to read the channel value at the current pixel coordinates is very inefficient; instead use r, g, b, a, or c.
rad (d, m, z)	Return the channel value of the pixel at the polar coordinates d, m in color channel z, where dmin <= d <= dmax, mmin <= m <= mmax, and zmin <= z <= zmax. For off-image coordinates the channel value depends upon the setting of the edge-mode control⁴.
cnv (m11, m12, m13, m21, m22, m23, m31, m32, m33, d)	The convolver function works similar to the Convolution Matrix filter of The Gimp with the difference that the matrix is a little smaller. Every pixel of the current color channel and its neighboring pixels are evaluated to get the result. Please refer to the documentation of the Convolution Matrix filter for the description of this function.
min (a, b)	Return the lesser of a and b, so that if a < b then a else b.
max (a, b)	Return the greater of a and b, so that if a > b then a else b.
abs (a)	Return the absolute value of a, so that if a < 0 then -a else a.
add (a, b, c)	Return the sum of a and b, or c, whichever is lesser, so that add (a, b, c) = min (a+b, c).
dif (a, b)	Return the absolute value of the difference of a and b, so that dif (a, b) = abs (a-b).
sub (a, b, c)	Return the difference of a and b, or c, whichever is greater, so that sub (a, b, c) = max (dif(a, b), c).
rnd (a, b)	Return a random number in range of [a...b], so that a <= rnd (a, b) <= b. The random number generator is seeded with a value computed from the image that is currently processed, thus guaranteeing that the applying the same filter on two identical images will produce the same result. The control panel of the plug-in will show a special control to set the random number seed to a different value when the filter is using the random number function.
mix (a, b, n, d)	Return the mixture of a and b by fraction n / d, so that if d = 0 then 0 else a n / d + b * (d - n) / d*.
scl (a, il, ih, ol, oh)	Scale a from input range [il...ih] to output range [ol...oh].
sqr (x)	Return the square root of x.
sin (d)	Sine function of d where dmin <= d <= dmax and the result is -D <= sin (d) <= D⁵.
cos (d)	Cosine function of d where dmin <= d <= dmax and the result is -D <= cos (d) <= D⁶.
tan (d)	Bounded tangent function of d where -dmax/4 <= d <= dmax/4 and the result is -D <= tan (d) <= D⁷.
r2x (d, m)	Return the horizontal displacement for the cartesian coordinate of the pixel that is m units away from the center of the image at an angle of d. The result is so that: x = r2x (d, m) + X / 2.
r2y (d, m)	Return the vertical displacement for the cartesian coordinate of the pixel that is m units away from the center of the image at an angle of d. The result is so that: y = r2y (d, m) + Y / 2.
c2d (x, y)	Return the angle of the pixel at cartesian coordinate x, y from the center of the image.
c2m (x, y)	Return the distance of the pixel at cartesian coordinate x, y from the center of the image.
put (v, i)	Store a value v in the temporary store at index i, where 0 <= i <= 255. The return value is so that if 0 <= i <= 255 then v else 0.
get (i)	Fetches a value from the temporary store at index i, so that if 0 <= i <= 255 then value else 0.

1.2.5 Portability

The User Filter plug-in has been written with backwards compatibility with Filter Factory for Photoshop in mind. That means that, as a rule of thumb, any filter that has been written with Filter Factory (or Filter Foundry) will also work with User Filter and (with some limitations) vice versa. There are, however, certain issues that needs to be taken care of when it comes to using an filter written for FF with User Filter or writing a filter with User Filter that should be used with FF.

Many filters written for FF use integer representation of certain values instead of the constants provided. This is not only bad style, but leads to problems. User Filter uses the constant values also used by the Macintosh version of Filter Factory, which in this aspect differs from the Windows variant. When importing a filter, it should be made certain, that the right constants are used in the filter code.
Filter Factory only supported 8-bit wide color channels, as does the current version of User Filter. The latter will change, however, when The Gimp will support wider color channels. This means, that the constants for the maximum channel values will differ depending on the image being processed. Many filters that have been written for FF do not use the constants for maximum channel width, but use integer literals instead. This needs to be corrected in order to make these filters work properly with future versions of User Filter and images that have wider color channels.
Filters written with User Filter can also be exported to FF filters and used with FF with the same results, except for the following cases:
- The filter depends upon the pixel-fetcher edge-mode option being different from FF's default behavior ("smear"). In this case, the filter can be used in FF, but will produce different results for processing off-image pixels than when used in User Filter.
- The filter source code exceeds 1024 characters in length per channel. In this case, it is not possible to export this filter to a file format that can be read by FF, since this is a limitation of FF that is not present in User Filter.
- The filter source code utilizes language extensions of User Filter. In this case, it is not possible to export the filter to a file format understood by FF, since FF does not know anything about these language extensions⁸.

Please note, that many authors of Filter Factory filters did not understand the difference between constants like X (which is the number of values in a range) and xmax (which is the maximum value of a given range). There are many cases where the maximum value if off by 1 due to this misunderstanding. Most of the cases, you will not recognize this, because FF's mode for handling off-image values defaults to "smear", but in other cases you may see a 1-pixel wide artifact at the edge of the image after processing it with a filter.

1.3 User Filter External Tools

A set of external tools is provided with the User Filter plug-in which are meant as helper tools for importing existing Filter Factory / Filter Foundry filters into the native filter file format of the User Filter plug-in and to translate filter files into native plug-ins for The Gimp.

1.3.1 The 8bf2guf, afs2guf, ffl2guf, and txt2guf Command Line Utilities

These programs can be used to quickly convert many Filter Factory filters into the native filter file format of the User Filter plug-in. They have been named, so that they match the filter filename extensions of the filter file types they have been written for, i.e. use 8bf2guf to convert *.8bf filters, afs2guf to convert *.afs filters and so on.

Since you can also load the FF filter file formats (except the *.ffl format, which is not a single filter, but instead a collection of filters) from within the editor panel of the User Filter plug-in, these external utility programs are meant for converting a larger number of filters at a time. For each filter processed by these tools, a single filter file will be created in *.guf file format. Where necessary, these tools will also fill the additional entries in the *.guf file with information (like tool-tips, filter description, version and date information). However, filter conversion is not perfect (the least it is for the proprietary *.8bf binary format) and User Filter can use a lot more information than Filter Factory or Filter Foundry are able to, so you will most likely need to hand-tune the filter information in the editor panel of the plug-in to make them look nice and integrate seamlessly in The Gimp (if you want to register them as stand-alone filters in The Gimp's menu). Please refer also to the section about portability of this document for further things that you might need to take care of in order to make the filters work as intended.

Please refer to the man-pages (8bf2guf(1), afs2guf(1), ffl2guf(1), txt2guf(1), 8bf(5), afs(5), ffl(5), guf(5)) for more details.

1.3.2 The uf2c Translator

This program will translate a filter into the "C" source code required to produce a native plug-in for The Gimp. These plug-ins will use the same user interface already known from the User Filter plug-in itself when running a filter in stand-alone mode. As a rule of thumb, translated filters will execute faster than those that are run from the User Filter plug-in itself, since the latter will be interpreted byte-code while translated filters are machine code. However, do not expect too much of it ? this will not turn a stock car into an F1 racer. Also, the User Filter plug-in is able to reduce the code tree significantly more than it is possible with a translated version of the same filter. This is due to the fact that all user interface derived values can be treated as constants prior to final application of the filter, while only compile-time optimization can be performed on the translated filter. The speed gained from translating a filter with uf2c will be quite noticeable for very complex filters though or for filters that use a lot of computation base on the current pixel coordinates.

Please refer to the man-pages (uf2c(1), guf(5)) for more details.

1Please note, that many of the existing filters (most of them written for Filter Factory) use integer representations of the maximum channel values. This will lead to problems when wider color channels are used. Whenever a filter that has been written for Filter Factory is to be used with User Filter, it should be checked that the correct constant is used.

2Please note, that Filter Factory for Adobe Photoshop unfortunately used two different values for the return results of the trigonometric functions (sin, cos, tan) in the Windows (512) and the Macintosh (1024) versions of the program. The User Filter plug-in for The Gimp uses the value also used by the Macintosh version of Filter Factory. This may lead to different results when using filters that have been written for the Windows variant of Filter Factory. When importing a filter, this should be checked and corrected whenever necessary.

3This is an Extension to the functionality of Filter Factory / Filter Foundry. Use the default edge-mode (?smear?) for fully backwards compatible filters.

4This is an Extension to the functionality of Filter Factory / Filter Foundry. Use the default edge-mode (?smear?) for fully backwards compatible filters.

5Please note, that Filter Factory for Adobe Photoshop unfortunately used two different values for the return results of the trigonometric functions (sin, cos, tan) in the Windows (512) and the Macintosh (1024) versions of the program. The User Filter plug-in for The Gimp uses the value also used by the Macintosh version of Filter Factory. This may lead to different results when using filters that have been written for the Windows variant of Filter Factory. When importing a filter, this should be checked and corrected wherever necessary.

6Please note, that Filter Factory for Adobe Photoshop unfortunately used two different values for the return results of the trigonometric functions (sin, cos, tan) in the Windows (512) and the Macintosh (1024) versions of the program. The User Filter plug-in for The Gimp uses the value also used by the Macintosh version of Filter Factory. This may lead to different results when using filters that have been written for the Windows variant of Filter Factory. When importing a filter, this should be checked and corrected wherever necessary.

7Please note, that Filter Factory for Adobe Photoshop unfortunately used two different values for the return results of the trigonometric functions (sin, cos, tan) in the Windows (512) and the Macintosh (1024) versions of the program. The User Filter plug-in for The Gimp uses the value also used by the Macintosh version of Filter Factory. This may lead to different results when using filters that have been written for the Windows variant of Filter Factory. When importing a filter, this should be checked and corrected wherever necessary.

8Currently, User Filter does not have any language extensions, but several extensions are planned, like access to the current foreground and background colors, access to another image or layer as alternative image sources, etc.