*documentation by ***Petri Alanko**

Basically, the* Convolution Matrix* allows one to create simple custom filters. It sums together the color values at the 5x5 box around each pixel, multiplying each pixel in the box by the corresponding value from the matrix. The identity matrix does nothing.

It works like this:

0 |
0 |
0 |
0 |
0 |
---|---|---|---|---|

0 |
0 |
0 |
0 |
0 |

0 |
0 |
1 |
0 |
0 |

0 |
0 |
0 |
0 |
0 |

0 |
0 |
0 |
0 |
0 |

Divisor: 1 Offset: 0

The middle value represents the pixel to be modified. Here, the destination value is 1 (the source value, and the surrounding pixels are multiplied by 0 so they don't count). The matrix can be used for offsetting. For example:

0 |
0 |
0 |
0 |
0 |
---|---|---|---|---|

0 |
0 |
1 |
0 |
0 |

0 |
0 |
0 |
0 |
0 |

0 |
0 |
0 |
0 |
0 |

0 |
0 |
0 |
0 |
0 |

Divisor: 1 Offset: 1

Now the destination value for a pixel is the source value of the pixel above it, so this offsets the image one pixel downwards. A simple blur is like this:

0 |
0 |
0 |
0 |
0 |
---|---|---|---|---|

0 |
1 |
1 |
1 |
0 |

0 |
1 |
1 |
1 |
0 |

0 |
1 |
1 |
1 |
0 |

0 |
0 |
0 |
0 |
0 |

Divisor: 9 Offset: 0

Now, for each pixel, the value of that pixel and the eight surrounding pixels is taken, added together, and divided by nine. Thus, the resulting pixel is the average of the 3x3 region around it. Similarly, a very strong (and unsophisticated) sharpen filter is like this:

0 |
0 |
0 |
0 |
0 |
---|---|---|---|---|

0 |
0 |
-1 |
0 |
0 |

0 |
-1 |
5 |
-1 |
0 |

0 |
0 |
-1 |
0 |
0 |

0 |
0 |
0 |
0 |
0 |

Divisor: 1 Offset: 0

This takes the center pixel, multiplies its value by five, then subtracts the values of the four immediately adjacent pixels from that.This sort of operation enhances differences between colors.

The divisor argument is just a number by which the result is divided, and the offset is added to that. The offset is useful in some cases, such as this:

0 |
0 |
0 |
0 |
0 |
---|---|---|---|---|

0 |
1 |
1 |
0 |
0 |

0 |
1 |
0 |
-1 |
0 |

0 |
0 |
-1 |
-1 |
0 |

0 |
0 |
0 |
0 |
0 |

Divisor: 1 Offset: 128

In this case, the values on lower right are subtracted from the values at upper left. This is a basic embossing effect. Since these values could easily be negative, and a picture can't have negative colors, we add 128 everywhere, making this in all likelihood something like a gray bumpmap.The "Automatic" toggle just sets the divisor so that it is the sum of the matrix values. And if this sum is positive, then offset is 0, if it's negative, the offset is set to 255 (for inverting), and if the divisor is 0, the offset is 128 (for embossing).

The channel switches control which channels the plug-in operates on.The "Alpha-weighting" adds an additional factor in the calculations, namely the alpha channel. If this is used, the values of all pixels are weighted both by the matrix values, also by its alpha value. Try this out by making an image with nearly transparent (low alpha) green, and fully opaque red next to it. Now, if you don't have alpha-weighting, and you blur this, then you suddenly see a brownish line appearing between the transparent and red regions, because the transparency ("weakness", one might say) of the green wasn't taken into consideration. With alpha-weighting on, the blurring shouldn't bring any unexpected artifacts.

*Documentation by ***Mark Probst
**

MathMap is a plug-in which allows *distortion* of images specified by mathematical formulas. For each pixel in the generated image, an expression is evaluated which should return a pixel value. The expression can either refer to a pixel in the source image or can generate pixels completely independent of the source.

In order for the expression to refer to a pixel in the original image, a few variables are set:

- x The first cartesian coordinate of the pixel.
- y The second cartesian coordinate of the pixel.
- r The first polar coordinate of the pixel (0 <= r < 360).
- a The second polar coordinate of the pixel (the distance from the center).

To make it easier to write expressions which depend on the image size, a few additional variables are set:

- w The width of the image.
- h The height of the image.
- R The biggest possible value for r for the image.
- X The biggest possible value for x for the image.
- Y The biggest possible value for y for the image.

For the purpose of animations an additional variable is set:

- t The time which is 0 <= t < 1. If animation is disabled, the value of t is 0. If you want to make animations loop, make sure that the images at t == 0 and t == 1 are the same.

Simple Examples: Using the functions origValXY and origValRA it is possible to retrieve values of the origin image. To distort the image into itself, the following expressions can be used:

- origValXY(x,y)
- origValRA(r,a)

This would, of course, not make a lot of sense, but it should give you a feeling for how it works. The plug-in contains a few examples, (ed note: this makes this plug-in very usable even for non mathematical engineers, it's like the Filter Factory in Adobe Photoshop) so you can get an idea of what is possible with MathMap.

Operators

+ Addition

- Subtraction

* Multiplication

/ Division

% Modulo. This also works with real numbers.

Conditions and Loops

- if condition then consequence end
- Returns the value of consequence if the value of condition is not 0, 0 otherwise.
- if condition then consequence else alternative end
- Returns the value of consequence if the value of condition is not 0, otherwise the value of alternative.
- while invariant do body end
- While invariant is not 0, executes body, then returns 0.
- do body while invariant end
- Executes body until invariant is not equal 0, then returns 0

- sin(x)
- Returns the sine of x.
- cos(x)
- Returns the cosine of x.
- tan(x)
- Returns the tangent of x.
- asin(x)
- Returns the arc-sine of x.
- acos(x)
- Returns the arc-cosine of x.
- atan(x)
- Returns the arc-tangent of x.
- pow(x,y)
- Returns x to the power of y.
- sign(x)
- Returns -1 if x < 0, 0 if x = 0 and 1 if x > 0.
- min(x,y)
- Returns x if x < y, y otherwise.
- max(x,y)
- Returns x if x > y, y otherwise.
- inintv(a,x,y)
- Returns 1 if x <= a <= y, 0 otherwise.
- rand(x,y)
- Returns a random number a with x <= a <= y. Successive random numbers are evenly distributed within the interval.
- red(p)
- Returns the red component of p, which is 0 <= red(p) <= 1.
- green(p)
- Returns the green component of p, which is 0 <= green(p) <= 1.
- blue(p)
- Returns the blue component of p, which is 0 <= blue(p) <= 1.
- alpha(p)
- Returns the alpha component of p, which is 0 <= alpha(p) <= 1.
- gray(p)
- Returns the luminance of p, which is 0 <= gray(p) <= 1.
- origValXY(x,y)
- Returns the pixel value of the pixel at the cartesian position (x,y).
- origValRA(r,a)
- Returns the pixel value of the pixel at the polar position (r,a).
- rgbColor(r,g,b)
- Returns the pixel value of a pixel with red component r, green component g, blue component b and alpha component 1.
- rgbaColor(r,g,b,a)
- Returns the pixel value of a pixel with red component r, green component g, blue component b and alpha component a.
- grayColor(g)
- Returns the pixel value of a pixel with luminance g and alpha component 1.
- grayaColor(g,a)
- Returns the pixel value of a pixel with luminance g and alpha component a.

*Documentation by ***Ole Steinfatt**

There are two different types of signal (image) processing; *linear* and* non linear*. An example of a non linear filter is a median algorithm. The *Universal filter* is a linear filter. That means that you can describe a transfer function h which describes the output in relation to the input. In principle, a linear operation is reversible, but in practice a few non linear operations, like clipping and quantization, are involved which limit the reversibility. As for any linear system a frequency response can be calculated. In this description I will skip all mathematics and theory and just describe the basic working algorithm.

At the moment, the Universal filter uses a 3x3 matrix and two further parameters (divider and bias). The extra parameters can be calculated from the matrix in most cases, but you can set them if you want to. The filter works like this: For every pixel of the new image, the original pixel and the surrounding pixels are taken, multiplied with the values in the matrix, added to the bias value and divided by the divider. By changing the matrix values, different kinds of filters can be generated. If you put the value 1 in every matrix field (and leave the divider and bias value as calculated) you'll get a lowpass or blur effect, because you add all nine pixels to calculate the new one. If you want a smaller effect, you can increase the center value so the surrounding pixels will have less effect.To get a highpass filter or sharpening effect, you can use a matrix with -1 in all cells and a 9 in the centre.You can choose to run the filter in just one direction, by only using coefficients in the middle row, or the middle column of the matrix.To invert the picture, just put a -1 in the centre field.

The values for bias and the divider are calculated in such a way, that the resulting image will be in the normal range of 0 to 255 for color or gray values. So the divider is the absolute value of the sum of the matrix. If the sum is 0, then the divider is set to one. The bias value is derived of the sign of the matrix sum. If the sign is positive, the bias is 0, if negative it will be set to 255. In case the sum is 0, the bias value will be 128.

All calculated values are rounded to integers and clipped to the range 0 to 255 after the computation.

This is a clone of *Photoshop's Filter Factory*. You can load a Photoshop Filter Factory *AFS* file to it or you can create your own filters and save them in AFS format. In order to understand Filter Factory, read the manual that comes with *Adobe Photoshop* (we plan to make some documentation about this later on). The nice thing about this plug-in is that an enormous amount of free filters are now available for Gimp. Many of these filters are precompiled for *Mac* or *Windows* versions of Photoshop, which means that they not are in AFS format and therefore not compatible with Gimp. However, there is a nice little program called *Johann's photoshop Plug-in manager* that decompiles such files to AFS, so you can use them in Gimp. The big drawback is that in order to decompile, you must have Photoshop, so you may have to ask a friend who has Windowz and Photoshop to do it for you. You can take a look in Appendix X to get some info on where to get the program, filters and general info about Photoshop Filter Factory.