The Twist - Documentation

Introduction.
How to compile the Twist.
How to install the Twist.
How to use the Twist.
Conclusion.

Introduction

The Twist is a plugin for the GIMP which provides a variety of geometric image distortion functions. The principle of all distortion types provided by the Twist to map the input image onto the output image by translating the original pixels according to a 2D vector field which is determined by the selected distortion function. In order to support the user's creativity some parameters (up to eight, depending on the function type selected) can be adjusted, resulting in different effects. The output of the Twist plugin is a geometrically distorted image. The effect of a selected parameter setting can be viewed interactively in a preview image. Each selectable function provides eight predefined effects which can help the unexperienced to get a feeling for the parameter settings. Currently eight different distortion functions are available. More functions will follow when I find the time (and the ideas) to implement them.

How to compile the Twist

The Twist plugin source code comes with a makefile. In order to create and install the executable plugin proceed as follows:

Read the README and LICENSE files which come along with the twist-0.92beta.tar.gz file carefully. The README file contains basic information on the current distribution. The LICENSE files contains important legal information.
Edit the Makefile and review the header section. Change the paths as explained there.
Type 'make' at the command prompt.

If everything worked, the make utility should have created the twist executable for you.

How to install the Twist

You can install the Twist by copying the plugin executable file to the same directory where all the other GIMP plugins are. On my system this directory is: /usr/local/lib/gimp/0.99/plug-ins/. On your system this might be different depending on the version of GIMP you are using and depending on where you installed the GIMP.

Another possibility to install the twist is to type 'make install' at the command prompt. Be sure that you have reviewed the header section of the Makefile and that all parameters there are correct before doing this.

It might be necessary to be logged in as root for installation. This depends on your system configuration.

How to use the Twist

In order to distort an image, which is assumed to be already displayed in a GIMP window, proceed as follows. First you must start the Twist. This is done by selecting <Filters/Distorts/Twist> from the GIMP's floating menu. Note that you cannot distort indexed images. If you have such an image it must be converted into an RGB or grayvalue image.

Figure 1 below shows the user interface of the Twist.

The Twist - user interface

Figure 1. The user interface of the Twist plugin.

There are four frames, the 'Preview image' frame, the 'Parameter settings' frame, the 'Functions/Effects' frame and the 'Cutoff function' frame.

The first frame you will probably want to use is the 'Functions/Effects' frame. This frame contains two parts, the 'Functions' menu and the 'Effects' buttons. You can choose one of several distortion functions by activating the 'Funcions' menu. Having chosen a distortion function you must choose a parameter set that, in combination with the chosen distortion function, defines the effect you will obtain.

There are two ways how you can define a parameter set. The first, and easier, way is to select one of eight effects from the 'Effects' buttons in the 'Functions/Effects' frame. The parameters defining the effect will be displayed in the 'Parameter settings' frame. The effect on the image can be seen almost immediately in the preview image at the top left corner of the dialog window. The 'R' button resets the parameters.

The second way for choosing a parameter set is to use the sliders in the 'Parameter settings' frame. Note that some of the sliders may be labeled 'unused', indicating that modifying this parameter will not affect the image distortion effect. The labels of the sliders depend on the distortion function.

In order to acquire a certain feeling for the parameters of each distortion function I recommend that you experiment with the sliders after having chosen an effect. If you feel that the preview image is too small to see what actually will happen to the image, do not hesitate to execute the Twist by pressing the [OK] button at the bottom of the dialog. The Twist will remember all parameters you have selected when it is started again providing you with the possibility of fine-tuning an effect. Another application of successive application of the Twist with slightly varying parameters would be animation.

The last frame, which has not been discussed yet, is the 'Cutoff function' frame. The cutoff function is a mechanism for damping the image distortion function depending on the distance r from the image's center. This means that, when the cutoff function is activated, the image distortion is a product of the selected distortion function and of the cutoff function. The toggle button labeled 'Use cutoff' is used for switching this modifier on and off. The meanings of the two parameters, r and dr, which can be modified by the sliders are visualized by figure 2 below. Note that some of the predefined effects use the cutoff function. So have an eye on this frame when you want to figure out which parameters yield an effect that you like.

Figure 2. The shape and the parameters of the Twist cutoff function. Here e is the Euler number (2.71...) The cutoff function is equal to 1 in the interval [0, r]. Outside this interval it is equal to:
d(x) = exp[-(x - r)²/(0.04*dr²)].

Conclusion