quat_mand_gtk

A quaternian based julia set generator with a gtk interface.

The name is based on the fact that it used to generate a mandelbrot
set but now generates julia sets (much more exploration value) but 
the name has stuck.


quat_mand_gtk builds fairly simply on a linux system with gtk 2.0 
(both headers and libraries, the dev package in ubuntu or other 
distros) and g++ installed.  For saving images you need 
imagemagick's "convert" program installed and in your path.

just type "make" and it should work.


To run, just type "./quat_mand_gtk".
You should then be confronted with a graphic drawing on the left 
(in the form of parallel viewing stereo card) and a bunch of buttons 
and entry boxes on the right.

The entry boxes represent all of the parameters for this image.  To
adjust a parameter either select it in the entry box and type a new 
entry (hitting enter when finished, still need to work out all of 
the quirks) or use the four buttons beneath it.  The four buttons 
will be labeled something like: "+ 1e-2", "- 1e-2", "+" and "-". 
The button marked "+ 1e-2" will increment the parameter by 0.01.  
The "- 1e-2" button will decrement the parameter by 0.01.  The
"+" button will increase the exponent that the first two buttons will
increment or decrement by.  So hitting the "+" butt will change the
"+ 1e-2" and the "- 1e-2" buttons to "+ 1e-1" and "- 1e-1" so they 
increment and decrement by 0.1.  The "-" button similarly decreases 
the exponent on the first two buttons by one.

The parameters themselves:
The first four parameters are the quaternian components of "c", the 
"location" (on the Mandelbrot set) of the Julia set we're going
to draw.

iteration threshold is the number of iterations of a = a^2 + c that
must remain bounded for the location a to be considered within this 
Julia set.  c is the parameter above, a is the quaternian initialized 
with the location on the display being queried (the fourth dimention
is silently set to 0 and not explored).

cube partion size:  The implicit surface polygonizer partitions space 
into a bunch of cubes and builds triangles out of the intersection of 
the solution surface and lines within these cubes.  The cube partition
size is roughly speaking the resolution of the polygonizer.  This is 
what determines the number of polygons a surface will be broken into.

The above parameters define the polygon that is created.  The rest of
the parameters describe how it is displayed.

viewer coordinates (x,y,z):  The point in space of the observer

subject coordinates (x,y,z):  The point in space that is the focus

up vector (x,y,z): the direction perpendicular to the line between 
the viewer and the subject that defines up.

stereo eye separation:  The distance to the right or left of the 
coordinates that the stereo views are generated from.  

focal length:  Relative focal length of the "lens" used by the viewer.


Below the display there are three buttons: 

Quit: quits the application

Save Triangles: toggle switch.  When depressed, the triangles used to
create the image so that if just display parameters are changed there
are fewer calculations required to redraw the image.  The problem with
this is that each triangle takes 72 bytes of RAM and a good hi res 
image can require 100s of millions of triangles (or more).

Save Hires:  toggle switch to generate a high resolution (7200 x 4800) 
version of the image in memory and save it to disk when the render
completes.  If you leave this on, it will litter your current 
directory with hi res pngs and corresponding text files with the 
parameters used to generate the image.  Uses a call to imagemagick's
convert utility to generate the png from an uncompressed rgb file.


Also below the display are a list of statistics that can be used for 
general info, debugging and rough memory usage.

The statistics are:
tc:  triangle count, how many triangles were used to make (each side of)
     this image.  If the "Save Triangles" toggle is set, each triangle
     consumes 72 bytes of ram + ~2 bytes overhead
cp:  cubes processed, how many partition cubes were looked at by the 
     polygonizer.  Each cube consumes 8 bytes ram + ~3 bytes overhead
     and wastage

cq:  cubes queued, how many cubes are queued up to be processed.  These
     also consume 8 bytes ram + overhead but it pales in significance
     to cubes processed.

the remaining stats relate to internal caches of sizes set at compile 
time.

cch: corner cache hits
ccm: corner cache misses
ccs: corner cache size (in entries)
the corner cache is cache of the function value at a give cube corner.
Each corner cache entry consumes 8 bytes.

vch: vertex cache hits
vcm: vertex cache misses
vcs: vertex cache size (in entries)
the vertex cache is the point at which the solution to the function
passes between two nearby corners.  Each vertex cache entry consumes
40 bytes.