Quat: Online documentation
Author: Dirk Meyer

# 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 1, i, j and k 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 (much 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" to "4" are allowed, which correspond to the following formulas

  0 | Classical Julia | xn+1 = xn2 - c
  1 | Lambda Julia | xn+1 = cxn(1-xn)
  2 |  | xn+1 = xn*ln(xn) - c
  3 | Cubic Julia | xn+1 = xn3 - c
  4 |  | xn+1 = xnp1 - c

- p1, p2, p3 and p4
  four float parameters follow each. UI: located in Object Editor (visible only if it makes sense).
  They are extra parameters for the iteration formula. Up to now only p1 is needed. p1 is, for example, the exponent in the 5th iteration formula (x^p1-c). The 4 values are the 4 parts of a quaternion.
- 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 Editor".
  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 for example.
- ambient
  one float parameter follows. UI: located in "Other Editor".
  Defines the brightness of ambient light. Range from 0 to 1.
- antialiasing
  one int parameter follows. UI: located in "Other Editor".
  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 colors

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 Editor".
  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 1, i and j 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.

  Special functions for fractal calculation are:
  `orbite(n)`: The 1-part of the Quaternion after n iterations.
  `orbitj(n)`: The i-part of the Quaternion after n iterations.
  `orbitk(n)`: The j-part of the Quaternion after n iterations.
  `orbitl(n)`: The k-part of the Quaternion after n iterations.

  You can get an object oriented coloring by using the `orbit?` functions.