# The Twist 2.0 - Documentation

## Table of Contents

1. Introduction.
2. How to compile and install.
3. How to use the twist.
4. Contact.

## Introduction

The twist is a plugin for the gimp which provides a variety of geometric image distortion functions. The twist maps 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. All this applies to layers as well as to images. The effect of a selected parameter setting can be viewed interactively in the preview image. Each function provides eight predefined effects which help the unexperienced to get a feeling for the parameter settings. Currently nine distortion functions are available. More functions will follow when I find the time (and the ideas) to implement them.

## How to compile and install

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

1. Read the readme and license files which come along with the twist tarball carefully. The readme file contains basic information on the current distribution. The license files contains important legal information.
2. Edit the Makefile and review the header section. Change the paths as explained there. Since the newly 'acquired' Makefile version uses gimptool-2.0 most compiles should work without editing.
3. type 'make ; make install' at the command prompt to create the binary and to install it.

If everything worked, the make utility should have created and installed the twist executable into your local plug-ins directory.

## How to use the twist

Select <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. Some cool effects can be achieved by simply having an image with an alpha channel overlay another, so experiment.
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 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. 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 get a 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.
Finally, 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²)].

## Contact

Version 2.0 of the twist is suitable for gimp-2.0. If you have to use version 1.2, please download twist.0.99 which is still available at the plugin registry. If you wish to contact me, my current e-mail address is:
uray@grazer-bergland.com
If you speak german, have a look at the web site www.grazer-bergland.com. Its all about mountaineering, climbing, skiing and stuff. Many nice images - all edited with the Gimp of course ;-)
Please also note my new graphics project named moth. moth is a 3D modeller for creating OpenGL graphics. See
moth.titanothere.com
for details.
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.