Program Name : Kisomandel
Version      : 0.66 (03 Jun 2001)
License      : Open Source (GNU Public License, Q Public License); freely distributable
Author       : Helmut Steger <hel.steger@rolmail.net>
Homepage     : http://members.tripod.de/HelmutSteger


Last change to this file: 06 Jun 2001


Note: At the moment this documentation is NOT complete and gives only a small introduction.
      (documentation in html is planed for the future)

New features of version 0.66:
-----------------------------
- Fixed some problems in calling the Open/Save File Dialogs of Qt.
- New About dialog :-)
- Cleaned up toolbar pixmaps
- Other minor changes

Read the file ChangeLog for more information.


Introduction
============
Kisomandel is a fractal program for Linux with 3d-display (isometric) in realtime. The 3d rendering is
done with the standard Qt drawing methods and does NOT use any OpenGL functions at the moment.
In this version you can choose between four different 3d modes:
1) wireframe single color
2) wireframe multi color
3) areas (multi color)
4) 3d-bars (multi color)
Kisomandel supports mandelbrot and julia fractals. More fractal types are planed for the future.
You can zoom in and out of the fractal and to save the parameters (there are some examples in the prefs
directory).



Installation
============
1. Uncompress the source archive:
   a) tar xvfz kisomandel.tar.gz (for the gzip-compressed archive)
   b) tar xvfI kisomandel.tar.bz2 (for the bzip2-compressed archive)

2. If you have installed KDevelop the easiest way is (after uncompressing the source archive) to run
   KDevelop and open the project file (kisomandel/kisomandel.kdevprj).
   If not, continue with the following steps:
   Go the the main directory (kisomandel) and call the configure-script:
   cd kisomandel
   ./configure
3. Make the executable:
   make

If compilation fails it could be necessary to change the CXXFLAGS or CPPFLAGS in the file
./kisomandel/kisomandel/Makefile.am. The default is:

   # Compiler flags (change if necessary)
   CXXFLAGS = -O2 -Wall -ffast-math -fomit-frame-pointer
   CPPFLAGS = -fexceptions

There is also included a small script to compile the dialogs created with Qt-Designer. The script is
located in kisomandel/kisomandel/compile_ui and generates the following files:

Input files:
	- isosettings.ui (dialog for iso settings)
	- fractsettings.ui (dialog for fractal settings)
	- generalsettings.ui (dialog for general settings)
	- aboutdialog.ui (about dialog)
Output files:
	- isosettings_form.h
	- isosettings_form.cpp
	- fractsettings_form.h
	- fractsettings_form.cpp
	- generalsettings_form.h
	- generalsettings_form.cpp
	- aboutdialog_form.h
	- aboutdialog_form.cpp
	
If you call this script please check that the compiler of the Qt-Designer (uic) is in the path, otherwise
change the script.


For more detailed information please read the file INSTALL.



How to use the program
======================
When you start the program you will see two different windows.
The main window contains the menus, toolbars and the 3d display (default is wireframe with single color).
The second window contains the fractal (mandelbrot or julia).


a) Mouse usage in the fractal window:
   ----------------------------------
   
   * Moving mouse while pressing left button :
   	Selects fractal area for 3d display (rectangle range)

   * Right mouse button :
   	By pressing once the right mouse button you can draw a zoom rectangle; pressing left mouse button
        after selecting the zoom range starts zooming in; if instead you press the right mouse button again,
	zoom range selection will be aborted;
	Note: if in the fractal settings dialog the option <Set Julia constants on/off> is activated, the
	right mouse button lets you change then julia constants interactively (see below).
	
   * Middle mouse button (or CTRL+left mouse button) :
        scroll fractal contents (changes fractal coordinates rmin and imin)


b) Mouse usage in the main window (3d display):
   --------------------------------------------

   * Moving mouse while pressing left button :
        Rotate display horizontaly

   * Moving mouse while pressing left button + shift key :
        Rotate display verticaly

   * Right mouse button :
        Opens pop up menu

   * Right mouse button + shift button:
        Zoom in/out

   * Middle mouse button (or CTRL+left mouse button) :
        Scroll 3d Display


c) Keyboard functions:
   -------------------
   
   In this section you will find only the key-functions that have no equivalent menu function.
   
     Arrow keys :
        scroll fractal contents (left, right, up, down)

     Key 'm' :
        sets fractal type to mandelbrot
	
     Key 'j' :
        sets fractal type to julia

     Key 'f' :
        sets calculation precision to float (only mandelbrot!)
	
     Key 'd' :
        sets calculation precision to double (only mandelbrot!)
	
     Key 'l' :
        sets calculation precision to long double (only mandelbrot!)
	
     Key 'r' :
        rotate demo (rotates the 3d-display once around)
     
     Key '+' :
        increase 3d-display resolution (default: 24 x 24)
	
     Key '-' :
        decrease 3d-display resolution

     Keys '4', '6', '2', '8' :
        rotate 3d-display (single step)
     
     PageUp :
        Zoom in (iso view)
	
     PageDown :
        Zoom out (iso view)
	

d) Menu functions:
   ---------------
   
   I. File Menu
      =========
      - Open:    You can choose a fractal parameter file to load (some examples are placed in
                 kisomandel/prefs)

      - Save:    At the moment same function like Save As (see below)

      - Save as: Shows a file dialog where you can save the fractal parameters. The parameters
                 are saved in human readable format (ascii), so you can change them also from any
		 text editor. 

      - Load palette:
                 Choose a palette file. The format of palette files is very easy: it just contains
		 the the RGB values in ascii format. Example:

                   0   0   0
                   224 236 248
                   224 236 248
                   228 240 248
                   232 240 248
                   232 240 248
		 
		 The maximum number of colors is limited to 10,000 (same as maximum iterations).
		 Some example palettes are placed in kisomandel/palettes. More palette files can
		 be downloaded from my homepage.

      - Print:   Prints the actual iso window contents. Uses the Qt-Print-Dialog where you can also
                 redirect the print output to a file.
      
      - Save Iso Picture: Saves the actual iso window to a file. All the picture formats that your
                          Qt-Library supports can be selected from the submenu. Commonly used formats are
			  JPEG, PNG, BMP, XPM.
			  
      - General settings: Here you can change the default settings of Kisomandel and save them. The settings
                          are saved in the file ~/.kisomandelrc and are loaded at every start of
			  Kisomandel.
			  At the moment there are two categories of settings:
			  1) Iso settings (resolution, height, zoom, ...)
			     If you click the button <Get current Iso settings> the actual iso settings
			     are used.
			  2) Other settings (default directory paths, start-palette, ...)
			  
      - Exit:    I don't think you want to call this function :-)
      
		 
  II. Iso
      ===
      - Display mode:  In this menu you can select the 3d display mode from a submenu:
                       1) Lines (single color): this is the fastest mode (wireframe); the color can
                          be changed in the settings dialog;
                       2) Lines (multi color): also wireframe mode, but the colors for every line are
		          taken from the fractal;
                       3) Areas: this mode is also colored and draws solid filled triangles;
		       4) 3D Bars: draws colored 3d-bars; this is the slowest mode but looks very nice!
		          Just go to try it out!

      - Smoothing:     This function is very useful. It interpolates every 3d coordinate with its neighbour
                       coordinates by calculating their average:
		       
		         P_new = ( P(x-1,y) + P(x+1,y) + P(x,y-1) + P(x,y+1) ) / 4
		       
		       This function is called for every point. The smoothing factor can be from 0 (no
		       smoothing) to 10 (maximum smoothing). The default value is 2, which means, that
		       the smoothing procedure is called twice for the whole 3d matrix.
		       
      - Area Outline:  Has only effect for area and 3d bar mode. The areas are drawn with an outline
                       color (can be changed in the settings dialog).
		       
      - Auto Height:   Takes the minimum and maximum height value from the 3d matrix and ensures that
                       the 3d display has always the same total height (see settings dialog).
		       
      - Horizontal Lines: Turn drawing of horizontal lines on or off; has only effect for single and multi
                          color line mode.

      - Vertical Lines:   Turn drawing of vertical lines on or off; has only effect for single and multi
      
      - Full Screen:      This main window (3d display) is displayed in full screen mode.
      
      - Settings:         Opens the settings dialog. This dialog should be self explaining!
                          Note that you can keep this dialog opened as it does not block the program.
		       
			
      
 III. Fractal
      =======
      - Fractal type:             Let's you choose between Mandelbrot and Julia.

      - Reset to default coords:  Sets the default fractal coordinates:
                                  Rmin=-2.0
				  Rmax=2.0
				  Imin=-1.5
				  Imax=1.5
				  Julia_rconst=-0.8
				  Julia_iconst=-0.2  

      - Adjust window size:       Adjusts the fractal window size in the relation 512:384 (W:H).
 
      - Adjust real (width):      Adjusts the value of real_size (rmax-rmin) in relation to imag_size
                                  (imax-imin). Real:Imag = 4:3

      - Adjust imag. (height):    Adjusts the value of imag_size (imax-imin) in relation to real_size
                                  (rmax-rmin). Imag:Real = 3:4
				  
      - Settings:                 Opens the settings dialog. Detailed information about this has still
                                  to be written!
				  Hint: in the register <Julia settings> you can switch on the button
				  <Set Julia constants on/off> to change the julia constans interactively
				  with the right mouse button in the fractal window.				  
				  
   
  IV. View
      ====
      - Toolbar:     Shows or hides the toolbar.
      
      - Statusbar:   Shows or hides the statusbar; at the moment the statusbar is only used to display
                     the fractal coordinates (when mouse moves around in the fractal window) and the maximum
		     iterations of the actual position.


   V. Help
      ====
      - About:       Displays information about the program and the author.
      - About Qt:    Displays information about the Qt Toolkit from Trolltech.


e) Toolbar:
   --------
   This one is still to write: for now see the tooltips
   


HAVE A LOT OF FUN!

