The Twist - Documentation
Table of Contents
- How to compile the Twist.
- How to install the Twist.
- How to use the Twist.
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
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:
If everything worked, the make utility should have created
the twist executable for you.
- 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.
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.
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
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:
exp[-(x - r)²/(0.04*dr²)].
After my first encounter with the GIMP I was so enthusiastic about it, that
I decided to provide a small contribution to this project in the form of a plugin.
I hope that the Twist will be useful for many GIMP users. If you have any
comments or suggestions please e-mail me at: firstname.lastname@example.org.
Please read the README and LICENSE files that come with the Twist. These files
contain important legal and technical last-minute information, so do not miss them.
But most of all, have fun.