INTRODUCTION
============
Evolvotron is interactive "generative art" software to evolve
images/textures/patterns through an iterative process of random
mutation and user-selection driven evolution.  If you like lava-lamps,
and still think the Mandelbrot set is cool, this could be the software
for you.

It uses C++, STL & Qt, and is multithreaded (using Qt's threading API).

Home page: http://www.bottlenose.demon.co.uk/share/evolvotron

Author: timday at timday dot com

If you manage to make practical use of evolvotron, especially
if evolvotron derived imagery makes it into print or other
mass media, I'd love to hear about it: please email!

Have fun
Tim

LICENSE
=======
This program 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.

[The license should be in the LICENSE file in the same directory as this
README]

BUILDING
========
There's no reason it shouldn't work on any platform with a correctly
set up qmake.
 
You do NOT need to be root until the (optional) install stage.

In the top level directory, you can either do the "traditional"

  ./configure
  make

or just have both done for you by doing

  ./BUILD

Make will recurse into and build the libevolvotron directory
(which is 99% of the work) and some additional subdirectories with executables.

Among other things, this will give you an "evolvotron" executable which you
can run immediately with
  ./evolvotron/evolvotron
and/or copy where you like (see INSTALL section).

BUILD OPTIONS
=============
qmake's default optimisation settings are pretty conservative
(-O2, i386 instructions i686 timings). There are some overrides
modifying QMAKE_CXXFLAGS_RELEASE near the start of common.pro. 
If you change them, do "make distclean" and ./BUILD to ensure 
Makefiles are rebuilt.

Here's the times for a 2.4GHz P4 to run a 2048x2048 evolvotron_render
(gcc 3.2 compiled) on a benchmark image:
  Qt defaults (-O2):                                        30.6s
   -O2 -> -O3:                                              28.6s
   add -fomit-frame-pointer                                 28.2s
   add -funroll-loops                                       26.8s
   add -ffast-math                                          26.5s
   add arch/cpu -> -march=pentium4 -mfpmath=sse -msse2      23.6s
   add -finline-limit=4000                                  19.4s
(but that last one involves a 32m build time, cf ~2m for the others)
]

BUILD PROBLEMS
==============
The author develops on 
  RedHat 8 (gcc 3.2, qt 3.0.5),
  RedHat 9 (gcc 3.2.2, qt 3.1.1)
and sometimes also tests on on RedHat 7.3 (gcc 2.96, qt 3.0.5).
(So the closer your system is to these, the less likely you are to have problems).

If you have QT problems:

Check you have your QTDIR environment defined, and possibly also your
QMAKESPEC too.  The former should point to your Qt installation.  The latter
will be something like "linux-g++" if needed; check the Qt docs for other
architectures or perhaps look in your QT installation's mkspecs directory.
(RedHat defines QTDIR for the normal user environment, and seems to work fine
without explicitly setting QMAKESPEC.  A Mandrake user reports having to set both.)

A Debian (3.0r1) user reports Debian's Qt package not including qmake.
They eventually got hold of a version from somewhere (Trolltech?).
Attempting a regular build they apparently encountered a header/library
version incompatibility (old headers, new library) which was solved by hand
editing the qmake-generated Makefile and adding "-I- -I. " in front of
the other -I paths.

If you have gcc/c++ problems:

If you have to change anything, the chances are it should be changed in
common.pro.  Remember that any Makefiles are generated by qmake from
.pro files and therefore hacking on Makefiles is a fruitless excercise.

Some source releases have had problems with other versions of gcc than
the ones I test on.  A COMPLETE record of a failed build would be
appreciated (including the initial display of the gcc version).
If you can fix it, the patches would be even better!

[Other (non-x86) platforms: 
Linc Davis reports:
  "I built it on a Mac with Qt installed via Fink (if you know what that is.)
  All I had to do is add '$(QTDIR)/include/qt' to the include path and then
  run make."
]

INSTALL
=======
Doing
  make install
will attempt to install the executable in the INSTALLPATH directory defined in
common.pro.  This is set to ~/bin by default (which will give you a "personal
install" of evolvotron assuming you have such a directory and it's in your path).
If you change INSTALLPATH to /usr/local/bin then you'll need to "su" before
the make install.

NB If you change a ".pro" file, you'll need to ./configure again to make changes
take effect.

INSTALL PROBLEMS
================
Users of some distros (Mandrake?) report problems with the install code
generated by qmake.

If you'd rather just do it by hand, all you need to do is copy the executables
./evolvotron/evolvotron
./evolvotron_render/evolvotron_render
to wherever you like (e.g ~/bin, /usr/local/bin).
There are no extra supporting files which need to be in special places.

USAGE & INTERFACE
=================

BASICS
------
You will need a fast machine, or patience
(if you still find it slow on a P3 or P4 machine make sure you have compiled it with
the SSE options enabled... see BUILD OPTIONS section above).

On starting the application, a grid of images is displayed.
(For some reason the default size is quite small: you'll 
probably want to resize/fullscreen the window to be larger).

Repeat the following until bored:
 - Click (singleclick) on an image you like to 
   spawn the next generation of its mutant offspring.
 - Wait until variations on it are regenerated in sufficient 
   detail that you can decide which one you like best again.

IMPORTANT: Initially you should select images with some sort of variation.
It can take quite a few generations before you get something more interesting
than a simple gradient.  If you select a uniform image, you may get stuck
in a degenerate zone with little to mutate and therefore little chance of
escape to a more interesting area.  You can always reset/restart from the
"File" menu (the difference is that "reset" also resets the mutation
parameters to their default values).  Note that spirals, grids and tiles,
although complex looking, are actually implemented by a single function node
and may leave you stuck too.

COMMAND LINE OPTIONS
--------------------
  -geometry <width>x<height> : usual Qt/X option to set on-screen size in pixels
  -g <rows> <cols> : sets number of image display cells (defaults 7 by 5)
  -t <threads> : sets number of compute threads (defaults to 2)
  -v : verbose mode (mainly to assist debugging)
  -f <frames> : Number of frames in animations (defaults to 1 i.e no animation)
  -r <framerate> : Rate at which frames are displayed (integer).  (Defaults to 8).
 
RIGHT-CLICK CONTEXT MENU
------------------------
Right clicking on an image gets you a few more options:
 - "Respawn" regenerates just the current image from whatever it was
   spawned from (and using recolour or warp, if that's what was used
   to produce it).
   The main use of this is to make your grid of images look nice
   by regenerating any which aren't up to scratch.
 - "Spawn" is the same as clicking an image.  It generates mutated
   images to all unlocked images in the grid.
 - "Recolour" to produce different coloured variants of the selected image
 - "Warp"'s sub-options produce variants of the image which have been
   zoomed/rotated/panned.
 - "Lock" to prevent an image from being overwritten by spawns from other
   images (select again to toggle).
 - "Big" to produce a blow-up of the image in a single window.
   (submenu selects either a scrollable view of a fixed size image,
   or a freely resizable window)
 - "Save image" to save the image in a file (.ppm or .png format).
   Note that this is most useful on a "Big" blown-up image: if you
   save a small grid image, the size you see on the screen is the size
   you get in the file.  Note that the save won't be allowed until the
   full resolution image has been generated.
 - "Save function" to store the function to an XML file.
 - "Load function" to load a stored function from an XML file.
   NB if the file was saved from a different version numbered
   evolvotron, a warning message will be generated.
   Save/load of functions is an experimental feature and you should
   not count on future versions of evolvotron being able to load
   files saved from old versions, or producing the same image
   from a loaded function.  Attempting to load functions from later
   versions into earlier versions is even less likely to succeed.

MIDDLE MOUSE BUTTON
-------------------
[NB This feature will probably only be usable by those with multi-GHz machines].

You can use the middle mouse button to drag-adjust individual images.
This is useful for "final composition" type tweaks, e.g centering an
image's most interesting feature, or just for satisfying your curiosity 
about what's off the edge of the image.

It also works on "Big" images, although it's virtually unusable without
a bit of practice on smaller, faster ones (just boldly make the adjustment
you want, release the button... and wait).

Changes made can be rolled-back on the main Edit->Undo menu item,
one drag-action at a time.

An unmodified middle-mouse drag pans the image around following
the mouse motion.

A SHIFT-middle drag zooms the image in and out with scaling
proportional to the distance from the centre of the image.  Beware of
generating huge zooms by clicking too near the centre of the image.

An ALT-SHIFT-middle drag is similar but anisotropic: the scaling
may be different in X and Y.  Warning: this technique is very
sensitive and can be quite tricky to use!  In particular,
if you initially click near the centre axes of the image the zoom factor
can be HUGE, so the best way to start using this is to click about halfway
on a diagonal between the image centre and a corner and gently move in and
out radially.  Dragging from one side of the image to the other flips it over
(the degenerate case of infinite zoom at the centre is handled cleanly I think).
If it all goes horribly wrong, undo and try again.

A CTRL-middle drag rotates the image about its centre.

A CTRL-ALT-middle drag shears the image (the best way to see what this does
is to click in the corner of an image and move the mouse horizontally or
vertically).

MAIN MENU BAR
-------------
On the application's main menu-bar, the Edit menu lets you undo
previous full-grid spawns and middle-button adjustments.
There is a large but limited number of levels of undo; note that
locking is overriden, and that locking/unlocking a display is
not currently recorded in the undo history), and bring
up a dialog to modify the mutation parameters (see "useful tips"
and "advanced usage" below).

STATUS BAR
----------
An area on the status bar shows how many "tasks" are outstanding.  
Each "task" is the recomputation of an image at some resolution.
Tasks are prioritised by their number of pixels  (small image =>higher
priority).  This is why, if the main grid is still recomputing,
recalculationa of a "big" image will appear to freeze after it
has reached a certain resolution, at least until other lower
resolution tasks have completed. 

TIPS
====
- Don't start a session with any preconceived ideas about the kind
  of image you want to get out of it.  You'll be disappointed.
- I get the best results when I click the image which most
  immediately catches my eye as they start appearing.  If you stop
  to think about it too much then things seem to go downhill.
- If you seem to be just getting the same old spirals and grids
  all the time, stop clicking on spirals and grids! 
  (The same goes for random mush).
- Don't get too hung up on using the warp and middle-mouse drag
  adjustments every iteration... use those tools for final
  polishing of your masterpiece.
- You can quickly cycle through a lot of initial images (until
  you find one with real potential) by bashing on the menu
  accelerator keys Alt+F,Alt+R to repeatedly restart.

ANIMATION
=========
As of version 0.2.0 evolvotron contains some experimental support
for animation (although so far the results have been pretty
disappointing IMHO).

NB THIS IS EVEN MORE COMPUTATIONALLY AND MEMORY INTENSIVE THAN
THE CONVENTIONAL STATIC IMAGE MODE.

Simply supply a -f <frames> command line option and evolvotron will
generate animated sequences with the specified number of frames.
These will be displayed at the frame rate specified by the optional
-r <framerate> option (default 8).  So "evolvotron -f 24" will generate
3 second long animations.  Animations reverse direction at each end
to avoid a sudden jump.

If you save an animation, multiple files will be saved with
.fnnnnnn (where nnnnnn is the zero-filled frame number) 
inserted in each filename before the filetype qualifier.
This is a bit awkward, but is a consequence of Qt lacking
support for saving movie format files, so I suggest
you use the ImageMagick tools to convert to a more usable
format for now.

For example, if you enter foo.ppm as the filename to save,
files foo.f000000.ppm, foo.f000001.ppm... will be saved.
You can convert these to a MNG (a multi-frame PNG) playing at
approx. 8 frames per second with: 
  convert -delay 12 foo.f??????.ppm foo.mng

ADVANCED USAGE
==============
Evolvotron's idea of an image is a function which converts
XYZ co-ordinates to an RGB colour (however we can only display
a 2D plane for now so the input Z is fixed to zero, or varied 
with time when animating).

The image functions are constructed from trees of function nodes.
(In the mathematical expression 1+(2*x) the "+" and the "*" would
be function nodes.)  Evolvotron's nodes tend to correspond to
geometric or colour-space operations or anything else which can be
applied to a 3D vector.

By mutating the structure of the function tree (adding random
branches, for example) and the values of the constant embedded
within it, the image can be changed.

The mutation parameters are under control from the dialog accessible via the
Edit->Mutation Parameters... menu, and also from buttons on the status bar).

There are two kinds of mutation: perturbations to the magnitude of constants, 
and structural mutations which rearrage the function tree of an image.  
Four types of structural mutations are currently implemented:
replacement of a function branch by a new random stub (a "Glitch" mutation),
a random shuffle of a node's arguments, the insertion of random nodes
between a node and it's children and the substitution of a node with one
of a different type (but with child nodes unaffected where possible).
The probability (per function node) of these mutations is controlled
from spinboxes on the dialog (expressed as chances-in-a-million), 
as is the size of perturbations to constants.

It is useful to think of the constant perturbations as being a thermal effect
(hence the "heat" and "cool" buttons), while structural alterations are
more drastic and are caused by high energy gamma rays or something
(hence "irradiate" and "shield" buttons to adjust the probability of
structual mutations). 

So why would you want to change the mutation parameters from the initial
defaults ?  Basically, if you're getting too much variation in spawned images 
(this tends to happen after many generations of images, by which time the
function trees have grown quite large and therefore are experiencing a lot
of mutations) then cool and/or shield.
If all the images look too similar, heat and/or irradiate.

2 types of function node are considered fundamental: constant nodes
(which return a constant) and position nodes (which should really be
called identity nodes) which return their position argument.  There
are two slider controls to affect things realted to these:
 - "proportion constant" controls the proportion of fundamental nodes
   which are constants.  Changing this from its default value of 0.5 doesn't
   actually seem to have much effect.
 - "identity supression" causes all identity nodes to actually include a
   random transform; the main effect of this is that images are less commonly
   obviously centred on the origin or aligned with the axes.  I think this
   is a good thing, so identity supression is at 1.0 by default.

OTHER OPTIONS
=============
On the mutation parameters dialog there are tick boxes to enable two classes of
function which are disabled by default.  These are "iterative" functions and
"fractal" functions (Mandelbrot and Julia set type things).  The main reason
for their being optional is that, in the former case they're expensive, and
in the latter case they're expensive and ugly.  Note that if fractal functions
are enabled, then iterative functions are enabled too.

OTHER EXECUTABLES
=================
This release also installs two other executables:

 - evolvotron_render
   Usage: evolvotron_render [-s <width> <height>] [<file.ppm>|<file.png>] < <file.xml>
   Reads a XML function description from it's standard input and renders it to the
   file specified (suffix determines type, defaults to ppm if not recognised) at the
   specified resolution (defaults to 512x512).
   [NB This app does not use multiplt compute threads].

 - evolvotron_mutate
   Usage: evolvotron_mutate [-g | < <file.xml>] > <file.xml>
   With the -g (generate, genesis?) option, creates a new random
   evolvotron function and writes its XML description to standard out.
   Without the -g option, reads an XML function description from
   standard input, mutates it (using the same algorithm and parameters
   as evolvotron in its default state) and writes the new function's XML
   representation to the standard output.

For example:
  evolvotron_mutate -g | evolvotron_render /tmp/xxx.ppm ; display /tmp/xxx.ppm
  evolvotron_mutate -g | evolvotron_mutate | evolvotron_render /tmp/xxx.ppm ; display /tmp/xxx.ppm

These were added to enable the possibility of:
 - setting up an evolvotron web server, or other alternative
   frameworks to the main evolvotron app.
 - producing animations by repeatedly manipulating some
   aspect of a function and re-rendering it.

FUTURE DEVELOPMENTS
===================
Please check the TODO file before you send me email!

BUILDING CODE DOCUMENTATION
===========================
If you have doxygen (and graphviz too) and want to build
the source code documentation, execute 
  ./mkdoc
at the top level.  The code documentation then appears in ./doc/html/

THANKS
======
...to
  Dmitry Kirsanov
  Jonathan Melhuish
  Karl Robillard
for feedback, suggestions and patches.

...to the participants in a SIGGRAPH conference panel many
years ago who first got me interested in this kind of thing.

...to www.di.fm, www.somafm.com and Trance4Ever for music to code to.

