Quat - A 3D-Fractal-Generator
Version 0.92

Copyright (C) 1997,98 Dirk Meyer
email: dirk.meyer@studbox.uni-stuttgart.de

----------------------------------------------------------------------------
Contents:
1. Introduction
    1.1 What's new?
    1.2 System requirements
    1.3 Bugs and adresses
2. General instructions
    2.1 Mathematical basis of fractal calculation
    2.2 Coordinate systems and definition of the view plane
    2.3 ZBuffers
3. Operations
    3.1 Using the user interface version (Windows, X Window System)
            Object Editor, View Editor, Color Editor and Intersection Editor

    3.2 Other features of Quat in Windows 95
    3.3 Using the text only version
4. Structure of the initialization file(s)
    4.1 Key words for definition of fractal object and view
    4.2 Key words for definition of colours
    4.3 Key words for definition of intersection objects
    4.4 Other key words
5. Appendix
    5.1 Exploring a 3D-fractal
    5.2 Examples for the effect of some parameters
    5.3 Cross eyed view (for true 3D perception of an object)
    5.4 The initialization file(s)

----------------------------------------------------------------------------
[Web page of Quat]    [Deutsche Version]
----------------------------------------------------------------------------

1. Introduction

                      [A screenshot - Quat in action]

Idea and purpose of this program is the calculation of three-dimensional
fractals. The calculated objects are twisted, freely in space floating (and
- of course - fractal) "lumps" which look like made of dough - in contrast
to what is normally called "three-dimensional" fractals (namely a simple
reinterpretation of the two-dimensional data).

The objects can be colored by linking space coordinates (or other parameters
in later versions) to colors using a mathematical formula. The palette of
colors can consist of up to 50 colors or color ranges.

Additional, it is possible to define intersection planes. With this feature
the internal construction of the fractals can be displayed. Of course,
especially interesting is an intersection with the complex plane: you get
the usual two-dimensional fractal as intersection object how it could also
be calculated by "Fractint" for example. Moreover it can be seen how
different regions of the two-dimensional fractal are connected together in
three-dimensional space.

Normally, the the picture is calculated and saved in 24bit true color, but
it can be displayed in 256 color during calculation (however in poorer
quality).

The fractals calculated with Quat correspond exactly to the usual, two-
dimensional "julia sets", which almost every fractal program can calculate.
(As iteration formulas available are xn+1 = xn2 - c and xn+1=cxn(1-xn) ; x0
represents the pixel being calculated.)
To achieve the third dimension, Quat uses the so-called "Hamiltonian
quaternions" instead of the complex numbers with two components (real and
imaginary part). The "quaternions" are a generalization of the complex
numbers and consist of 4 components (1 real part, 3 imaginary parts). If you
set the 2 additional components to zero, you get the usual complex numbers.
Using quaternions (by the way, the name "Quat" is derived from
"quaternions") it would be possible to calculate even four-dimensional
fractals, nevertheless, only three-dimensional ones are really calculated.
(If somebody invents a four-dimensional monitor, I will agree to change my
program accordingly... :-) )

Generation of a really three dimensional view is possible (3d stereo). The
fractal can be seen three dimensional without any utilities like 3d glasses.

The output format is the PNG format. It is the successor of GIF and offers -
like GIF - compression of image data without loss of quality (JPEG
compresses better, but the quality gets worse). More information on PNG:
http://www.cdrom.com/pub/png. Because of the fact that PNG allows the
storage of data specific to the application, Quat saves all data neccessary
for the generation of the image within the PNG picture.

Quat uses a library named "ZLIB" to write the PNG-files. This library is a
compression library and has nothing to do with fractal calculation. It was
written by Jean-loup Gailly and Mark Adler. More information on ZLIB:
http://www.cdrom.com/pub/infozip/zlib

Quat is free software; you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.

You should have received a copy of the GNU General Public License along with
this program; if not, write to the Free Software Foundation, Inc., 59 Temple
Place - Suite 330, Boston, MA 02111-1307, USA.

Special thanks to Max Schwoerer for the clarification of some of the
juridical questions, and to Oliver Siemoneit for his help on the English
translation.
Many thanks to Larry Berlin (lberlin@sonic.net) for his advice in stereo
view related topics, his many ideas for how to improve the program
(especially the user interface), his testing of pre-release versions of Quat
0.92 and last but not least for the title image of Quat that he created!
Larry Berlin maintains a great 3D-ezine
(http://3dzine.simplenet.com/3dzine.html). He plans to show a gallery of
images he derived from objects generated by Quat. I had the chance to see
some examples. Really worth visiting!
Thanks to Eva-Maria von Garrel for testing.

1.1 What's new?

Version 0.92:

   * Finally added a GUI in Windows and X Window versions: [Graphical] User
     Interface, though I never wanted to do this...
     full functionality of hitherto (and still) existing initialization
     files can be reached through dialog-boxes: There is an "Object Editor",
     a "View Editor", a "Color Editor", an "Intersection Editor" and a
     dialog for the remaining parameters.
     There now are also scroll bars when the image is larger than the
     window. The user interface is completely Windows style (Image|Open,
     Image|Save, Image|Save As,...), which also means that much more memory
     is needed than before...
   * Windows version: compiled for 32bit (thus requires Win 95 or NT), is
     much faster than before, supports long file names, Win95 look&feel.
   * Generation of 3D stereo pairs, which can be viewed in true 3D without
     any special equipment (through the so called "cross eyed view"). For
     this the key word "interocular" has been added.
   * A new formula added: xn+1 = cxn(1-xn)
   * Generation of so-called "ZBuffers". This makes it possible to change
     certain parameters, that don't have anything to do with the fractal
     calculation itself (colors for example), even after calculation. One
     can play with the object this way, try different colors for example, to
     see what looks best without having to wait a long time.
   * another, simpler algorithm for calculation of normal vector is used.
   * New functions for color formula: atan, asin and acos
   * the calculation time is stored along with the image (but not very
     exactly, in seconds only)
   * linked against the library zlib, version 1.1.3.

Version 0.91: (8/2/1998)

   * initialization file structure changed
     now all the information can be kept in one file, but the old scheme is
     also possible by using the keyword "include <file>". Keywords
     "colorfile", "objectfile" and "cutfile" are no longer recognized (use
     "include" instead.)
   * antialiasing keyword added
     This feature is used to reduce moire patterns which disturb the image.
     Results in much better image quality in most cases!
   * formula interpreter ("colorscheme") rewritten.
   * bugfix concerning the option "-p" (Segmentation fault)
   * bugfix: Machines which need "alignment" of "doubles" (DEC Alpha, not
     Intel) could not create images with intersection planes.
   * Windows version: Improved usage in Win95 (Drag & Drop on Icon, Context
     menu)
     For more information, read paragraph 3.2 in this file.

Version 0.90b: (14/9/97)

   * No changes in source code, only english language documentation added.

Version 0.90: (29/7/97)
Initial version.

1.2 System requirements

Theoretically none, if you are able to compile ANSI-C-Code with your
system... :-)

The requirements for the pre-compiled versions of Quat are:

   * Windows: 486 processor or better (this includes Pentium), approx. 16 MB
     RAM (depends on size of image that is calculated), operating system
     Windows 95 or Windows NT (very probably also Windows 98, but I didn't
     try it). Windows 3.11 (even with Win32S) doesn't work. High- or true
     color graphics mode recommended.
   * X Window System/Linux: hardware requirements the same as Windows
     version. The X-Window-version needs a library called "Qt" by Troll
     Tech. It is freely available (see http://www.troll.no), and should be
     included in all current Linux distributions. If you are using the KDE
     Window Manager, this library is installed for sure.
   * DOS: (text version without output on screen). 486 processor or better
     (this includes Pentium), 4 MB RAM (theoretical value, I wasn't able to
     test it, because I don't have a computer with that few memory). If you
     want to use a pure DOS (without Win 95 in background), you need a DPMI
     driver. You can download one from every WWW/FTP-Server which also
     offers DJGPP 2. The name is "CSDPMI4B.ZIP". This file has only 41
     KBytes size. (A link to it in the United States:
     ftp://ftp.cdrom.com/pub/simtelnet/gnu/djgpp/v2misc/)

The source code of Quat is available, so it is possible to create a text
only version (without graphical display, minimal memory usage) on any system
that can compile ANSI-C. This makes sense for UNIX systems for example,
which often have a GNU-C compiler installed along with the operating system.

1.3 Bugs and adresses

If you have some proposals for improving this program or if you want to
report a bug, please send me an email (dirk.meyer@studbox.uni-stuttgart.de).
I appreciate any feedback, especially because this version is a beta-
version. Almost for sure there are some bugs in it. If you like to (and are
able to) program, you can send me your C-code. I'll build it into future
versions. (Of course I'll mention you as the author!) I have the model of
"Fractint" in mind, maybe there are also some enthusiasts in this case!
My postal adress is:
Dirk Meyer
Marbacher Weg 29
D-71334 Waiblingen
Germany
New versions (and the source-code) of Quat are available at
http://wwwcip.rus.uni-stuttgart.de/~phy11733/index_e.html

2. General instructions

2.1 Mathematical basis of fractal calculation

Essential part of the calculation of fractals is a formula to iterate.
(There are other types of fractals, but this is the one most commonly used).
"Iterate" means, that the value, which resulted through the formula, is
feeded in it again the next step, and so forth. Such a step is called an
iteration. The point, which is to be calculated, is used as starting value.

A point in this context is a complex number (in case of a two-dimensional
fractal). A complex number consist of two components, which are independent
of each other. They are called real and imaginary part. If the imaginary
part is zero, the complex numbers are identical to the real numbers (e.g.
1.23324, -23, ...). To mark the imaginary part, the letter "i" is used.
There is one rule: i*i=-1. (This fact shows, that "i" can't be a real
number, because no real number multiplied with itself is -1.) In general a
complex number "c" is written like this: c = a + i*b, where "a" is the real
part and "b" is the imaginary part (both are real numbers). In
two-dimensional fractal programs the real part is identified with the X
coordinate on the screen, the imaginary part with the Y coordinate.

Quat needs numbers which have one component more to calculate its fractals.
This component is necessary for the Z coordinate. Such numbers don't exist,
but there are numbers with four components: the Hamiltonian quaternions
(sometimes also called "hypercomplex numbers"). They consist of one real
part and three imaginary parts. The signs for these parts are e, j, k and l.
"e" corresponds to the real part (e equals to 1), "j" to the imaginary part
of the complex numbers. In case k- and l-part are zero, we again have the
good old complex numbers. There are special multiplication rules for e, j, k
and l. (These rules reveal a difference between quaternions and hypercomplex
numbers, but it isn't of any importance for this section. Quat uses
quaternions, but for simplicity I'll use both names exchangeable.)

Four components would allow even four-dimensional fractals, but for
practical reasons (see above) and the limitations of human mind (_not_ the
programmer's incapacity...), Quat is "only" able to render three-dimensional
fractals. The additional fourth dimension (fourth component) is set to a
constant value, which is defined by the parameter "lvalue" in the OBJ-file
(User interface versions: in the Object Editor). This proceeding produces a
three-dimensional intersection of a four-dimensional fractal analogous to
the two-dimensional intersection of the three-dimensional fractals
calculated by Quat which is made by common fractal programs.

Back to our iteration formula. Quat uses one of the following formulas: xn+1
= xn2 - c; or xn+1 = c*xn*(1-xn)
x0 is the starting-value ( = point that has to be calculated)
"n" is a count index which numbers the "x" (n=0,1,2,3...).
The value "c" in the formula is a hypercomplex number, that remains constant
during the whole calculation. This is defined in the Object Editor/OBJ-file
as parameter "c". "c" determines the shape of the fractal.

One could see that the sequence of all xn defined by the iteration formula
can show three different schemes:

  1. the sequence converges toward a fixed value (e.g. zero)
  2. it oscillates periodically between some values
  3. it gets bigger and bigger and goes toward infinity this way.

The object drawn by Quat is the amount of all points ( = numbers) x0, for
which the sequence defined by the formula doesn't go toward infinity. (In
other words: which doesn't show scheme 1. or 2.).

This formulation isn't completely exact: there is the problem that a
computer can't do the calculation up to infinity to see whether the sequence
converges or not. (The reason is the limitation of human life, again not
incapacity of the programmer :-) ). Because of this the calculation is
stopped after a previously defined number of iterations. This number is set
in the Object Editor/OBJ-file through the parameter "maxiter". But how does
Quat know after maxiter iterations whether the sequence goes to infinity or
not? Thus there is the value "bailout" (naming freely after "Fractint"). If
this value was exceeded during the maxiter iterations, it is assumed that
the sequence goes towards infinity.

Now we are able to describe the calculated object exactly: It is the amount
of all points ( = numbers) x0, for which the sequence defined by the
iteration formula of the xn didn't exceed the value "bailout" after at most
"maxiter" iterations. (How complicated nice shapes are described
mathematically... On the other hand: How nice mathematics can be!)

But to calm you down a little bit: those who don't understand all this or
who simply are not interested in it can, nevertheless, calculate nice
pictures.

2.2 Coordinate systems and defintion of the view plane

What we have up to now is an object in Quaternion-Space (Q-Space). What we
don't have is someone, who looks at this object. That means: we have to
project the object onto the screen. Therefore we have to define a view
window on a view plane in Q-Space, which represents the screen. The way the
object is seen by the view plane is the way it is displayed on the screen.

As a result we have two different coordinate systems: First, the system that
has to be displayed (the Q-Space), second, the system on which is projected
(view plane, monitor).

The Q-Space is defined by three axes, called e, j and k, analogous to the
components of hypercomplex numbers (the l-part is set to a constant value,
see above). The e-axis is the real axis ("ray of numbers"), the plane
defined by e- and j-axis is the complex plane, in which 2D fractal programs
calculate their fractals.

On the view plane there are two axes of the view coordinate system, called X
and Y axis, which correspond to the horizontal and vertical direction of the
monitor. Additional there is a Z axis, which points perpendiculary away from
the view plane and into the direction of the fractal.

Regarding the fact that fractal objects are always around the origin of the
Q-Space, the following way to construct the view plane seems obvious. There
is a point in Q-Space defined in the initialization file, the "view point".
The view plane goes through the view point and is perpendicular on the
vector from the origin to "view point". ("view point" has a double meaning:
it defines position and orientation of the view plane). The view point
defines the Z axis of the view coordinate system. Henceforth we will move
only on the so defined view plane.

Now there has to be taken a rectangular window on the view plane (= the view
window), which is oriented in the way that two opposite lines of the
rectangle are parallel to the projection of the "up vector" (see later) on
the view plane. The direction of this projection is called Y direction and
corresponds to the vertical direction on the monitor. The horizontal
direction is called X direction and corresponds to the two other lines of
the rectangle. As we see, the "up vector" defines where is up. Accordingly
the directions of X and Y axis have been defined through this.

The diagonals of the view window/rectangle intersect in the "view point"
(This means that the view point lies in the "middle" of the screen/view
window). Now the view window is scaled around the view point as follows: the
side which is the X direction gets the length "lxr" (measured in Q-Space,
see parameter "lxr") and the relation between the lengths X and Y gets the
same value as the relation between the X and Y resolutions (see parameter
"resolution"). (to achieve display without distortment). The base vectors of
the view window (derived from X and Y directions) get the length 1. Now we
are ready. The view coordinate system is defined completely.

To get all possible positions of the view window (up to now every
describable plane is oriented around the origin), the view plane is shifted
in X and Y direction to the amount of the values given through the parameter
"move" (it's a movement in the view plane's own coordinate system).

2.3 ZBuffers

This new feature of Quat 0.92 makes it possible to split the calculation
into two parts: into the slow fractal calculation and the relatively fast
display of the image. To do this, Quat generates a so-called ZBuffer, in
which the shape of the object as seen from the viewpoint is stored.
Having created a ZBuffer, you can still change certain parameters (light
source, palette, color formula, Phong highlight and ambient light) and
generate an image from the ZBuffer, what works relatively fast.

                                  [Image]
                     Chart 1: Different way to an image

ZBuffers open a wide field of experimentation, you can find out the best
look of the object by trying some different looks.
ZBuffers have the suffix "ZPN". The full set of parameters is stored in it,
as well as in images (PNG). ZBuffers are quite usual PNG files, but they
don't contain an image. Some graphics programs even recognize them and
display them very easily when they are opened, some other need the suffix to
be changed to "PNG". I don't know if it makes sense to directly view
ZBuffers, because one can't do anything with the data stored therein.

3. Operations

3.1 Using the user interface version (Windows, X Window System)

Starting Quat:

   * Win95: Quat is started by double-clicking on the Quat symbol in
     explorer
   * X: Start Quat by typing "xquat" in a terminal or by clicking on the
     corresponding icon in a file manager.
     You can also pass the usual X arguments like "-geometry 200x160", or
     "-display foggy:0.0" or arguments provided by Qt like "-style=windows".
     You can also give the name of a file (png or zpn), which will be opened
     on startup.

Description of the menus:

"Image" menu:

Image | Open...
Opens an image (PNG file), shows it and reads the parameters stored in it.
Quat shows how much of the image is already calculated afterwards.
You may get the error message "PNG file has no QUAT chunk". This happens if
you try to open a PNG written by another program. In this case Quat can't
read the fractal parameters.
Note: In 256 color modes you should use a specialized program to view the
image, because it can do a better job with the limited amount of colors.
"Graphic Workshop for Windows 1.1u" or "Paintshop Pro 3.11" support PNG
images (Windows), also "XV 3.10a" with the PNG-patch (X).

Image | Close
Closes the image, but leaves the parameters in memory. If you want to change
some parameters of an image and want to recalculate it, you must first close
the image, then change the parameters and as last step start the
calculation.

Image | Save
Save the image (PNG) using the name shown in the title bar. Often this is a
name generated automatically with a number at the end.
All parameters needed for recalculation of the image are stored along with
the image.

Image | Save As...
Like "Image | Save", but uses a custom name for the image. You can enter the
name in the dialog which opens after selecting this command.

Image | Adjust Window
Sets the window size to the size of the image (as long as it fits on screen)

Image | About
Shows information on Quat.

Image | Exit
Exits from Quat.

"Calculation" menu:

Calculation | Start/Resume an image:
Starts a calculation of an image using the current parameters (see
"Parameters" menu) or resumes a stopped one. If you have a Z buffer open
(which must be calculated completely), you can turn it into an image using
this option. (See section 2.3)
An image is a fractal object which is lighted and colored, as opposed to a Z
buffer.

Calculation | Start/Resume a ZBuffer:
Starts a calculation of a Z buffer using the current parameters (see
"Parameters" menu) or resumes a stopped one.
A Z buffer has the shape of the fractal object, but has no colors and is not
lighted. Calculating a Z buffer does most of the calculation, turning a Z
buffer into an image is relatively fast. The advantage is, that you can
still change the parameters (colors, light) that don't affect the shape of
the fractal and render an image in a short time. If you don't like the
appearance of the object, simply close the image, which will return you to
the Z buffer. See section 2.3 for more information on Z buffers.

Calculation | Stop:
Stop the running calculation (of both an image and a Z buffer). You can
resume calculation, see the two menu points above.

"Parameters" menu:
Parameters | Reset:
Resets the parameters to their default values. If you calculate an image
with these values, you will get a sphere.

Parameters | Read from INI:
Reads in the parameters for creating an image. It doesn't reset the
parameters to default values first! (Use "Reset" to do this.)
The INI file may have been created by "Save As..." or with a text editor. An
INI file holds data necessary to generate an image.
You can also read in a COL file previously saved in the Color Editor.

Parameters | Read from PNG:
All data necessary for image generation is stored in the image itself
(according to PNG specification). This menu point reads the parameters from
the image for re-generation or editing.

Parameters | Save As:
Writes the parameters to an INI file, which is a simple text file that can
be edited with a text editor. You can use this option if you want to
calculate the image with the text version of Quat. (Text versions use INI
files to get the parameters they need.)

The editors (in which you can edit the parameters):

Parameters | Object Editor:
A dialog opens which looks as follows (shown here: X-Window-version with KDE
Window Manager):

                          [Image of Object Editor]

In this dialog you can specify the fractal data of the object. This data
determines the shape of the fractal. You can enter values for following
keywords: "maxiter", "lvalue", "bailout" and "c". (See their description in
Section 4.1).
Additional the editor has the ability to see the effect of a change of a
value immediately (... if you have a Pentium or above / in a few seconds for
a 486). You see a "Mandel Preview" which shows the Mandelbrot set (or, more
exactly, two dimensional intersections of the four dimensional
generalization of the Mandelbrot set). This set can be seen as a map for
"Julia sets" (the objects being calculated by Quat). The red cross marks the
selected point "c". Every point "c" generates another Julia set. Points that
lie in the Mandelbrot set (the black figure) lead to connected Julia sets,
the other case they are split up.
You can click or drag with the mouse into the Mandelbrot Preview to move the
red cross. The values for the first two parts of "c" are updated
accordingly.
If you click the right mouse button in the Mandelbrot Preview, it gets
updated. This is necessary if you changed "maxiter", "bailout" or the last
two parts of "c". In the X-Window-version a red frame around the preview
window shows that an update is necessary.
The six buttons below the Mandel Preview serve the navigation in the
Mandelbrot Preview. You can move and zoom the section that is shown.
The upmost button "up" moves the viewable section up, the downmost down. The
one on the left moves left, on the right right. The two buttons in the
middle zoom in "+" and out "-".
In the "Julia Preview" you can see two dimensional intersections of the
subsequent object. If you hit the "2D-Preview" button, the Julia set
according to the current values is calculated. With the scroll-bar "3rd-dim.
Intersec." you can choose which intersection with the three-dimensional
object you want to see. Change it and hit "2D-Preview". If you put these
different intersections on top of each other (in mind), you get a bit of an
imagination how the three-dimensional object will look like.
If you press the button "3D-Preview", you'll get a three dimensional image
as Quat would calculate it. This kind of preview is relatively slow, so it
is recommendable to first use 2D-Preview to see whether the fractal is
according to your imagination and play around with the parameters until it
is and then use 3D-Preview. The check box "use own view" decides whether a
standard view is used in 3d preview or whether those parameters will be
used, which are adjusted in the other editors (view, colors,...).

Parameters | View Editor:
This dialog looks as follows (shown: Windows version)

                           [Image of View Editor]

Here is the place to define how the object should be viewed. A view plane
(on which the fractal gets projected) is defined by the parameters
"viewpoint", "up", "move", "lxr" and "interocular". The "light"-source is
also defined. (See descriptions in Section 4.1).
Next to the edit control for "interocular" there is an angle shown. It is
the angle between the left eye viewpoint, the origin (before applying the
MOVE) and the right eye viewpoint. This angle should be between 3 and 6
degrees if you want to create a 3D stereo image pair. If interocular is zero
(and thus the angle is also zero), a 2D projection of the fractal object is
generated.
Because it would be boring if you could only enter values you could also
enter in a text editor (INI file), there are three views of the view point
in this dialog. (You look at it "from above", "from beside" and "from
front".) The black arrows are the axes in Quaternion space (or the
three-dimensional sub-space defined by "lvalue" [Object Editor].) "e" is the
usual real axis, "j" the imaginary axis (same as with complex numbers; These
two are used by every 2D fractal program) and "k" points into the third
dimension (there is no "l" axis as the value for l is constant ["lvalue"]).
The arrows point in the direction of positive values, the length of an
arrows corresponds to the length 2 in Q-space.
The blue rectangle marks the view point, the green rectangle shows the size
of the view plane. You can click into the blue rectangle and drag it to a
position of your choice to change the view point. Some positions are not
defined (if the view point is (0,0,0) or if the "up" vector is perpendicular
to the view plane)
The yellow circle is the origin of the view coordinate system (= the upper
left point on screen)

Parameters | Color Editor:

                          [Image of Color Editor]

If you want to specify colors (or better, color ranges), do it here. To the
left you see a vertical scroll bar which you can use to select the color
range you want to edit. Next to it there are two buttons, "Add" and "Del".
"Add" adds a color range before the current position in the palette, "Del"
deletes the active color. There has to be at least one color, and not more
than 30. For each color range you can enter values for the start color
("Color 1"), the end color ("Color 2") (or press the buttons "Sel" to get
the standard Windows/KDE dialog for choosing colors) and a weight for the
color range.
The weight defines how much of the palette is made of the selected color
range. This last value must not be zero. (See also section 4.2). If you
don't want to create a color range but only a color, set both colors (Color
1 and Color 2) of the color range to the same values.
For every one of the two colors there are two buttons "Copy" and "Paste".
"Copy" copies the corresponding color into the clipboard (not into the
global one of Windows/X, but into the rectangle in the upper right corner).
"Paste" replaces the corresponding color with the color in the clipboard.
Below these items there is a preview of the whole palette. The selected
color range is marked through a black rectangle. The color preview is
intended for high- and true-color modes, if you use a mode with fewer
colors, the preview is not excellent...
Below this preview you can enter the color scheme formula either directly or
by choosing one of the predefined formulas. (See key word "colorscheme")
If you hit the "Save As" button, you can save the color information in a
COL-file, which can be read in with "Read from INI".

Parameters | Intersection Editor:

                       [Image of Intersection Editor]

Is used to define intersection planes. The scroll bar on the left has the
same purpose as in the "Color Editor" described above: Select the object to
edit. The buttons "Add" and "Del" also work like above, one adds a new
plane, the other deletes the selected plane. There may be between 0 and 20
intersection planes. A plane is defined by its normal vector (pointing into
the half-space in that the object should disappear) which must not be zero,
and a point on that plane. (See also section 4.3)

Parameters | Other Parameters:

                    [Image of "Other Parameters" dialog]

Other Parameters are "resolution", "phong", "ambient" and "antialiasing".
See section 4.4 for the first one, and section 4.1 for the last three.
Windows only: You can adjust the number of pixels calculated before events
are checked. That means that user input and the display of the image is only
done every n pixels. If you set this to a high value, calculation will be
somewhat faster.
In the Dialog there are five buttons (Resolution shortcuts). If you hit one
of them the resolution is set accordingly to the button hit.
In this dialog the calculation time needed to calculate the image so far is
shown.

ZBuffer menu:

To learn more about Z Buffers, please read section 2.3. The commands in this
menu are for opening, saving, saving as and closing a Z Buffer.

3.2 Other features of Quat in Windows 95

If you want to use INI files to feed Quat with information, it can also be
used completely through the "Explorer". It can be used in similar manner if
you use the X Window System with the KDE Window Manager (highly
recommended!), but this description refers to Windows.
Files with suffix "ini" are associated to the notepad/editor by default. A
double click on an ini file opens it for editing, so it is no problem to
change a value, or something else.
In the context menu (right mouse button on a file) you can additionally
create an entry to start the calculation of the ini file. To create the
entry, do the following: (Note: I have a German version of Win 95, I do not
know the exact names of the English version, I can only try to translate
from German.)

   * In the Explorer, select "View" in Menu "Options..."
   * Select folder "File types"
   * Select the type "Configuration settings" in the list "registered file
     types" and select the button "Edit". A new window appears.
   * Click the "New" button in this new window.
   * In the first line ("Process") enter "Calculate" e.g.
   * give name and path of Quat in the line "Application for this process".
     (e.g. "C:\Quat\Quat.exe"). The field "use DDE" should be deactivated.
   * Click the OK-Button of every window that appeared up to now, until you
     are in the Explorers main window again.

If you click with the right mouse button onto an ini file, you are now able
to select "Calculate" in the appearing context menu. Quat will start the
calculation of the fractal described in the ini file immediately. In the
same manner you can create a process "Continue calculation" for the file
type "png". This will allow you to continue calculation of images (which are
not yet finished) by only two mouse clicks. In some circumstances the file
type "png" is not registered. If this happens, you have to create this file
type.
There is another possibility for use: You can create a link to Quat on your
desktop. If you have done this, you can simply drag an ini or png file out
of the Explorer and drop it onto the Quat-icon on your desktop. Quat will
immediately start or continue the calculation.
To create the link, you only have to go to the directory you installed Quat
to (using the Explorer), drag "Quat.exe" (or "Quat") and drop it onto the
desktop. Windows creates an icon at the place you dropped it.

3.3 Using the text only version

(Not applicable to versions with user interface.)
Quat understands following parameters, which are given in the command-line:

                    calculates an image from an ini file. (Ini files are
-i <ini file>       used for feeding Quat with the values it needs to start
                    a calculation)
-z <ini file>       calculates a Z buffer (suffix ZPN) from an ini file.
                    generates an image by using a precalculated Z buffer.
-i <zpn file>       (This of course is much faster than calculate from an
                    ini file.)

-i <zpn file> <ini  generates an image from a Z buffer, but replaces
file>               certain parameters (coloring e.g.) with the values
                    given in the ini file.
-p <png or zpn      reads the parameters that have been used to calculate
file>               the image/zbuffer and writes them to an ini file.

-c <png or zpn      continues calculation of an unfinished image. The ini
file>               file that has been used to generate the image is not
                    needed.
-h                  shows short information.

A call looks like this:

quat -i test.ini

A calculation is stopped by

   * DOS version: pressing a key
   * other text versions: (turning off the computer). It isn't possible to
     terminate the text version since I don't know how to access the
     keyboard in a way that works on all system platforms (ANSI C)... :-(

4. Structure of the initialization file(s)

If you use a version with a user interface (called "UI" in the following)
you can skip this section 4 (but you should read the sub-sections 4.1-4.4,
where you'll find the descriptions of the parameters in the Editors).
In text files the parameters necessary to start a calculation are defined.
(As mentioned above: once the calculation had been started, they are
superfluous.) Their structure is quite simple:
The double cross (#) introduces a comment. Everything written after it in
the same line is ignored. Normally a line begins with a key word, which is
followed by one ore more parameters. The parameters and the key word have to
be in the same line and have to be seperated by blanks. Following types of
parameters are possible:
int: integer values (like 1, -1, 0, 2, 3, 1001, ...)
float: floating point values (like -0.2353, 21.21324, 0.001, ...)
strings: strings of characters
If a key word is not mentioned, a default value will be used instead. Some
example files are included in the program's distribution kit. You should
look at them, for many things will become clear in an instant simply by
looking at them, whereas it is more difficult to understand it only
theoretically.

4.1 Key words for definition of fractal object and view

   * "c"
     followed by four float parameters. UI: located in Object Editor.
     They define the real and three imaginary parts of the constant "c" in
     the formula "xn+1 = xn2 - c" or the other one supported. The four float
     numbers are e, j, k and l parts of the hypercomplex number.
     These parameters determine the shape and the structure of the fractal.
     To get good results, they should be near the origin (in 4d space!),
     that means they should range from -2 to 2.
     Note: It is interesting to experiment with this (that's where the fun
     comes in)!
   * "bailout"
     one float parameter follows. UI: located in Object Editor.
     defines the value (as float number) from which the iteration sequence
     is assumed to go towards infinity. Then the calculation of the point is
     finished. Corresponds to the parameter with the same name in the
     program "Fractint".
   * "maxiter"
     One int parameter follows. UI: located in Object Editor.
     is the maximum number of iterations being calculated.
     If the value "bailout" (see above) isn't exceeded after maxiter
     iterations, the iteration sequence is assumed to converge towards zero
     or as to be periodic and therefore belonging to the julia set (the
     object).
     This value can be found in every fractal program with a comparable
     name. In contrast to 2d fractal programs this value shouldn't be too
     high in Quat (less than 100): The value increases detail, which is
     wanted in 2d, but not nice in 3d, since the surface of the object gets
     in the worst theoretical case infinitely rugged.
   * "lvalue"
     One float parameter follows. UI: located in Object Editor.
     a constant float value (for the fourth component of a point in space),
     which represents the fourth dimension. As start value x0 for an
     iteration the point in space is taken which has to be calculated. Doing
     this we have only three components. The fourth component is set to
     "lvalue".
   * "formula"
     One int parameter follows. UI: located in Object Editor.
     Defines which iteration formula is to be iterated. The values "0" and
     "1" are allowed, which correspond to the following formulas
     0        xn+1 = xn2 - c
     1        xn+1 = cxn(1-xn)
   * "viewpoint"
     Three float parameters follow. UI: located in View Editor.
     It's a vector in Q-Space that defines the point in space which is
     center of the view plane (from which the object is seen.) See also
     Section 2.2.
   * "up"
     Three float parameters follow. UI: located in View Editor.
     It is a vector in Q-Space, which defines the up direction. This vector
     must not be perpendicular to the view plane! See also Section 2.2.
   * "light"
     Three float parameters follow. UI: located in View Editor.
     It's a vector in the view coordinate system, which describe the
     position of the light source relatively to the position of the viewer
     ("viewpoint") measured in view coordinate system units.
   * "lxr"
     one float parameter follows. UI: located in View Editor.
     Defines the length of the "screen" on the view plane in Q-Space.
     Determines the size of the view window/object. See also Section 2.2.
   * "move"
     Two float parameters follow. UI: located in View Editor.
     Defines the way how the view window is shifted (in it's own coordinate
     directions X and Y) See also Section 2.2.
   * "interocular"
     One float parameter follows. UI: located in View Editor.
     If this value is zero, a 2d projection of the 3d object is generated.
     If you set it to a nonzero value, two 2d projections of the object are
     generated, one for the left eye (=the right image) and one for the
     right eye (=the left image). If you know how to fuse them, you can see
     the object in true 3D! Great experience! See "Cross eyed view" for
     explanation of how to fuse the images.
     The value is the distance that the two different view points for the
     different eyes have in Q-Space. It should be lower than LXR.
   * "phong"
     two float parameters follow. UI: located in "Other Parameters".
     The first number defines the maximum intensity of the phong highlight
     (ranges from 0 to 1), and the latter how sharp the phong highlight will
     be (how fast the brightness gets near the usual brightness without
     highlight.). Ranges from 1 to infinity.
     A "phong highlight" is a glaring light reflexion as it can be seen on a
     billard-ball e.g.
   * "ambient"
     one float parameter follows. UI: located in "Other Parameters".
     Defines the brightness of ambient light. Range from 0 to 1.
   * "antialiasing"
     one int parameter follows. UI: located in "Other Parameters".
     To reduce moire patterns (regular patterns on the objects consisting of
     black pixels) some intermediate points are calculated instead of one
     pixel. The average of these intermediate points' brightness is taken as
     the brightness of the pixel. The parameter behind this keyword defines
     how many intermediate points are calculated. For example, the effect of
     "antialiasing 2" is that a pixel is replaced by a 2x2 rectangle. So 4
     points are calculated and the average of their brightnesses is the
     brightness of the pixel. Of course, this decreases the calculation
     speed to one fourth!
     The value has to be between 1 and 5 inclusive.

4.2 Key words for definition of colours

A color in Quat is represented by a red-green-blue triple, where red, green
and blue are numbers from 0.0 to 1.0.
When using a color together with other colors (as it is in a palette) every
color needs some kind of factor, that defines the amount of the palette to
be occupied by the color. Same is true for color ranges. The factors or
weightings of all colors and/or color ranges are summed up by Quat to find
out what 100% are.
It is possible to define many colors and color ranges, which taken together
are building the palette. The color described first in the file corresponds
to the value "0.0", the last one "1.0". This will become important when
we'll see how to get the color we want through a mathematical formula. The
key words are:

   * "color"
     four float parameters follow. UI: indirectly located in Color Editor.
     (Create a color range with both colors the same.)
     The first number is the weight of the color (meaningless, if the whole
     palette is built by one single color) MUST NOT BE ZERO. The remaining
     three parameters are intensity of red, green and blue (in this order).
     They are values between 0.0 (no intensity) and 1.0 (maximum intensity)
   * "colorrange"
     seven float parameters follow. UI: located in Color Editor.
     The 1st number is the weight (see "color"), the next three the color at
     which the color range starts and the last three the color, where the
     color range ends at. Inbetween those two colors the colors are
     interpolated.

4.3 Key words for definition of intersection objects

Objects can be defined (only planes yet), which intersect with the fractal
object.
Key words:

   * "plane"
     six float parameters follow. UI: Located in Intersection Editor.
     Defines a plane which divides the space into two half-spaces. The first
     three parameters describe a vector that is perpendicular to the plane
     (normal vector), the last three the point at which the plane is fixed.
     The normal vector points into the half-space which will be cut away
     from the fractal.

4.4 Other key words

   * "include"
     inserts another text file. The result is the same as if the statements
     put in the included file would be given directly at the location of
     "include".
     "include" is followed by a string parameter, that gives the name of the
     file (with suffix!) to include. You should avoid using pathnames here.
   * "resolution"
     three int parameters follow. UI: located in "Other Parameters".
     The first two numbers define the size of the image in pixels to
     calculate (the 1st the X, the 2nd the Y direction). The last determines
     the image's resolution in Z direction (perpendicular on screen).
     The bigger the value, the smaller the steps that are taken to look for
     the fractal in Z direction will get. This value should be approximately
     as big as the Y resolution. Is it too small, the calculation becomes
     faster, but it could happen that the edges of the fractal get frayed
     out, because at special places (preferably at the edges) the fractal is
     not hit. (See Appendix 5.2 for examples.)
   * "colorscheme"
     string follows. UI: located in Color Editor.
     This is the place to define the formula, which determines the color of
     the fractal in correlation to the point in space. The formula should
     give values between 0 and 1 in the chosen region of space. If it leaves
     this range of values, Quat will do some kind of "floating point
     modulo", which will reduce the result to the range between 0 and 1.
     Does the palette consist only of one single color, the formula could
     simply be written as "0".
     Following variables are predefined: x, y and z. They are the X, Y and Z
     coordinate of the point in space (to be more exactly: the e, j and k
     values of the point in Q-Space), whose color should be calculated. You
     can use brackets to give some order to the operations. Along with the
     usual mathematical operations (+,-,*,/) power (^) you can use following
     functions:
     sin, cos, tan, sqr, sqrt, exp, ln, atan, asin, acos, round, trunc, abs,
     random
     sin(x): the sine of x (x in radians)
     cos(x): the cosine of x (x in radians)
     tan(x): tangens of x (x in radians)
     sqr(x): x to square (x*x)
     sqrt(x): the square root of x
     exp(x): e^x. (e to the power of x). "e" is the Eulerian number
     (2.718....)
     ln(x): inverse function to exp(x). Natural logarithm.
     atan(x): arcus tangens of x. Inverse function to tangens.
     asin(x): arcus sine of x. Inverse function to sine.
     acos(x): arcus cosine of x. Inverse function to cosine.
     round(x): rounds x as usual: e.g. round(2.5) = 3.0; round(2.4999) =
     2.0;
     trunc(x): the largest integer that is less than or equal to x. E.g.
     trunc(2.0) = 2.0; trunc(2.5) = 2.0; trunc(2.99) = 2.0;
     abs(x): absolute value: abs(x) = x if x>0 and -x if x<0
     random(x): a random value in range from 0 to x.

5. Appendix

5.1 Exploring a 3D-fractal

[ looking for somebody to translate this section... ]
The German version of this section describes how you could do with
"Fractint" what you can do with Quat now (>=0.92) in the "Object Editor" if
you use the user interface version.

5.2 Examples for the effect of some parameters

Here is described how a z-resolution that is too low can cause strange
images and how antialiasing can reduce the Moire-effect. All images are
low-quality-JPEGs.

 [Image]                 [Image]                  [Image]
 Image 1: This is an     Image 2: This image has  Image 3: Here is the
 example for a depth     an increased             image for reference.
 resolution that is too  z-resolution (2048):     It has a z-resolution
 low (240): "resolution  "resolution 320 240      that is high enough
 320 240 240". You see   2048". The edges are no  (2048): "resolution 320
 the frayed edges of the longer frayed out.       240 2048" like the image
 blue parts of the       Nevertheless you can see on the left.
 object. There the       disturbing patterns of   Additional it has an
 object is so thin that  pixels caused by the     antialiasing value of 4:
 it is not hit by a      so-called Moire-effect   "antialiasing 4", which
 calculation with        (on the orange parts of  means that every pixel is
 z-resolution of 240.    the image e.g.). They    the average of 4x4
 No antialiasing is      could be reduced by      sub-pixels.
 done: "antialiasing 1"  antialiasing, which is
                         not done in this
                         example: "antialiasing
                         1"

5.3 Cross eyed view (for true 3D perception of an object)

Perhaps you know from the "Magic Eye" books that special ways to look at
something (without any additional equipment like 3d glasses) can produce
very amazing three dimensional perceptions. The principle used by Quat is
different from that of the "Magic Eye" books (Autostereograms), but in my
opinion it is easier to learn and achieves great results!
The principle is as follows: Two images seen from two slightly different
points are calculated and displayed next to each other. The image to the
right is for the left eye, the image to the left for the right eye. (Thus
the name "cross eyed"). If you hold your thumb in ca. 10 cm distance in
front of your eyes and look at it as usual, you'll remark that you see the
background twice. This is what the principle builds on.

                        [Example image for 3d stereo]

Look at the example image above. Sit in front of the screen at the distance
you usually work at, and then hold your thumb between screen and your eyes
(nearer to the eyes than to the screen). You should sit straight in front of
the screen, not incline your head and not look from beside at the screen.
Now look at the thumb as usual. Pay attention to the images on the screen
(without looking at them directly, always look at the thumb!)
If you see four images now, then the thumb is too near to the eyes. Move it
a bit further away from the eyes and look at it again as usual, while paying
attention to the background. Change the distance thumb-eyes until you only
see three images. Now the one in the middle is seen three dimensional, but
perhaps not sharp. To get a sharp image is a matter of concentration, with
increasing experience it gets easier. Watch the non-sharp image for a while
(but don't look at it directly). There'll be a point at which mind begins to
recognize, that the data that it gets, make really sense and it tries to
make it sharp. For some people this process is a bit difficult (as it was
for me), others have no problem with it.
By the way, this way to view is not an exotic feature of Quat, in the
Internet such stereo images are widely used. This way it is possible to
display a photograph of a landscape three dimensionally, for example

5.4 The initialization file(s)

Initialization files are used to feed Quat with the parameters it needs for
image generation.
Users of a version with user interface (Windows, X Window System): Though
this paragraph also applies to these versions, most users probably do not
need to read it. You can use the dialogs to enter parameters conveniently -
but if you want, you can also use initialization files.

To start a calculation in the text only versions, a so-called
"initialization file" is needed, in which the object, the view, the colors
and intersection planes are defined. This file (and all that are "included",
see below) are simple text files, which can be written in any common
text-editor, (for example, "edit" with DOS, "notepad" with Windows, "vi"
with Unix). The syntax used is very simple, in every line there is a keyword
with a list of parameters following. (e.g., "viewpoint 0 0 1" defines the
viewpoint)
In this initialization file you can include other files automatically (by
using the keyword "include"). This makes it possible to define color ranges
seperate from fractal data or intersection planes (in files with a different
suffix, e.g.). If such a file is included at a special location in the
initialization file, it is the same as if its contents would be typed in at
this location. The initialization file is only required to start the
calculation. Once a PNG file has been created, they aren't needed any more.
The fractal data is stored in the PNG file itself an can be reconstructed
from it.

Suggestion of how to separate the data in different files:
INI    this file suffix type is given by Quat. Is is the initialization
file. All the information needed to generate an image can be saved in it. It
is also possible to "include" other files (as suggested here).
OBJ    Fractal parameters determining shape and viewpoint, from which the
object is shown and some raytracing parameters, which specify the
illumination, are defined in files with this suffix.
COL    stores color or color-range of the object
CUT    These files serve for the declaration of a intersection plane
configuration. (in most cases probably only a single intersection plane).

This concept may appear a little bit complicated on the first view, but it
offers high flexibility. For example, it allows to give the fractal other
colors very quickly, or to add some intersection planes without changing
something on the object-definition itself: Only one line in the INI-file has
to be changed. But for those who still think this to be too complicated: You
can use all keywords in the initialization file, too.
