Tree [r162] /
History



File Date Author Commit
src 2012-11-18 rodgersb [r162] FractalToy 0.2.1 bug-fix release.
COPYING 2010-08-24 rodgersb [r1] Initial import.
Changelog 2012-11-05 rodgersb [r161] Commiting documentation changes for 0.2.0.
README 2012-11-05 rodgersb [r161] Commiting documentation changes for 0.2.0.
TODO 2012-11-05 rodgersb [r161] Commiting documentation changes for 0.2.0.
VERSION 2012-11-18 rodgersb [r162] FractalToy 0.2.1 bug-fix release.
build.xml 2012-10-31 rodgersb [r146] Added target for SaveImageTaskTest.
fractaltoy-icon.png 2010-08-24 rodgersb [r1] Initial import.
fractaltoy-splash.png 2010-08-24 rodgersb [r1] Initial import.

Read Me

 _____                   _          _  _____             
|  ___|_ __  __ _   ___ | |_  __ _ | ||_   _|___   _   _ 
| |_  | '__|/ _` | / __|| __|/ _` || |  | | / _ \ | | | |
|  _| | |  | (_| || (__ | |_| (_| || |  | || (_) || |_| |
|_|   |_|   \__,_| \___| \__|\__,_||_|  |_| \___/  \__, |
                                                   |___/ 
------------------------------------------------------------------------
FractalToy v0.2.0 beta - an iterative fractal explorer
Copyright (C) 2010-2012 Bryan Rodgers <rodgersb@it.net.au>
Released to the public under GNU GPL
<http://fractaltoy.sourceforge.net/>

PROGRAM DOCUMENTATION (README file)
------------------------------------------------------------------------

*** TABLE OF CONTENTS ***

[1] Brief introduction
[2] Program requirements / launching
[3] Navigating your way around
[4] Known issues
[5] More information about fractals
[6] Future planned features 
[7] License / credits / contributions / contacting the author

------------------------------------------------------------------------

[1] Brief introduction

FractalToy is a graphical program for exploring iterated fractal
function systems, such as the Mandelbrot and Julia sets. It's written in
Java, and is platform-independent.

FractalToy is currently in early development stages, so implemented
functionality at the moment is only limited to zooming/moving around
fractals and taking still image snapshots. However future development
will include the ability to create motion sequences that can be rendered
to digital video files for playing back visual effects in realtime. An
API is also provided for writing your own fractal functions easily, if
you're a Java developer.

Why the humble name? There may not be anything world-saving about
FractalToy, but it sure might make a fairly good source of amusement and
fascination for some of you out there :)

------------------------------------------------------------------------

[2] Program requirements / launching

You'll need Sun/Oracle's Java Run-time Environment (JRE) version 1.6 or
later on your computer. You can always download the latest JRE from 
<http://www.java.com/en/download/manual.jsp>.

Once you've got the JRE installed and downloaded the
FractalToy-x.y.z.jar file (contains the program binary code - replace
x.y.z with program version), you can simply launch the program by typing
the following command at your operating system's command prompt:

java -jar FractalToy-x.y.z.jar
    (replacing x.y.z with program version as before)
    
Alternatively if the JRE for your operating system has some graphical
utility for launching programs from .jar archives, then you can also use
that.

To build the source code, make sure you have Apache Ant installed
(obtainable from <http://ant.apache.org/>). Use the supplied `build.xml'
in the source archive to build the program.

------------------------------------------------------------------------

[3] Navigating your way around

FractalToy's interface was designed to be as reasonably intuitive as
possible. All operations are currently controllable with the mouse.

Once you start the program up, you'll be looking at a full view of the
Mandelbrot set (the default fractal). From here you can do the
following:

Moving the view around:
    There are two navigation modes: magnifying and dragging. 
    
    The magnifying mode (toolbar icon: magnifying glass over a square)
    lets you pick either a point or rectangle in the image to zoom in
    on. In this mode, you can:
    
        Left-click on the image to select a point and zoom in 500%
        around it. 
    
        Left-click and drag the mouse cursor to select a rectangle to zoom
        in on (to cancel selection, move the mouse pointer back to where you
        first clicked, so that the mouse cursor becomes a cross).
    
    The second mode is dragging mode (toolbar icon: picture of a hand).
    The cursor will take on the appearance of a hand "grabbing" the
    picture. Simply left-click and drag the mouse cursor to scroll the
    image around, release the left mouse button when done.
    
    You can also click the right mouse button to change between the two
    modes, as well as pressing the "H" and "M" keys.

    In both cases you also have a "Revert" button (toolbar icon: picture
    of a magnifying glass and blue circular arrow); this takes you back
    to the previous location you were viewing.
    
    Alternatively you can also use the keyboard to navigate around. Use
    the grey [+] and [-] keys in the numeric keypad to zoom in/out
    respectively, and press [Backspace] to go back to the previous
    location you were viewing. When the viewing area is focused (make
    sure none of the toolbar icons or the maxIter field have a highlight
    over them), you can use the cursor keys to scroll the area as well.

    Lastly you can also hand-type in coordinates manually, or see
    exactly where you are (if you're interested). Click on the "Toggle
    Coordinates Window" button (toolbar icon: "z1 z2") to bring up a
    coordinates window, where you can type in the viewing bounds and get
    a visual reference indicator of the region of the fractal shape
    you're looking at. 
    
    Note that coordinates are given as complex numbers. They must have a
    real and imaginary part; see
    <http://en.wikipedia.org/wiki/Complex_numbers> for more info.
    
How to return to the top-level view (entire fractal shape):
    To reset the view to the top-level (the initial one where you can
    see the whole fractal shape), click either the "Reset View" button
    (toolbar icon: a box with "1x" in it, meaning 1x magnification), or
    press the [Esc] key.
    
Selecting a fractal:
    In "Fractal" menu, select one of the fractal names under "Built-in
    fractals" to view that fractal. Currently only five fractals are
    implemented (Burning Ship, Mandelbrot, Julia, Lyapunov and Newton),
    plus alternate renderings (Pickover Stalks, absolute value) of some
    of these), but more will be available in future releases.

Changing the palette:
    In "Palette" menu, select one of the palette names under "Built-in
    palette" to switch to that palette immediately.

Changing fractal parameters:
    This is where things start to get a little more interesting. 
    
    All fractals have a parameter called "Maximum iterations" (or
    "MaxIter" for short). This determines the maximum number of
    "iterations" for each point in the image. For most fractals the
    colours in the image are graded according to how many times the
    fractal function repeats before certain conditions are broken (also
    known as "escape-time" rendering). Areas where the fractal function
    iterates beyond the set maximum number of times will get shaded in
    black (these points are considered to be part of the fractal set).

    If you raise the MaxIter parameter for a fractal, this will allow
    some previously-black areas to be shaded in colour, as those points
    now "escape" the fractal set, and give way to revealing finer and
    deeper detail. However this comes at the expense of increased
    rendering time; you'll probably notice the image redraw struggling
    around the black regions of the image more.
    
    You can also reduce the MaxIter value to speed up fractal redrawing,
    however this has the side-effect of reducing the level of detail in
    the image.
    
    For the Pickover Stalks fractals, there are no black regions as this
    fractal is shaded by a "distance function" instead. Raising/lowering
    the MaxIter parameter will instead determine the number of
    "generations" of various shapes and curves that you can observe
    throughout the image.
    
Julia set special parameters:
    If you select the Julia set fractal, you'll see a floating toolbar
    pop up; this lets you input an extra parameter that the Julia set
    function needs (known as the reference point or "constant point").
    
    You could laboriously type in values into the text field, but it's
    probably more fun to instead click on the "Pick" button (toolbar
    icon: crosshairs) and just click on the image somewhere to change
    the constant point. As you do this, an outline of the Mandelbrot set
    will appear over the view. 
    
    Click near this outline to produce very interesting results;     
    You'll find the shape will morph depending on where you click.
    You'll usually get anything ranging from  black spiky blobs to
    intricate flower-like or seahorse-like formations.
    
    See <http://en.wikipedia.org/wiki/Julia_set#Quadratic_polynomials>
    for some examples.

Colour cycling:
    It's a fun gimmick, watching the colours pulsate through the
    different parts of the fractal shape. Just click the "Cycle Colours"
    button (toolbar icon: a colour palette with a play button) to toggle
    this.
    
------------------------------------------------------------------------

[4] Known issues

FractalToy is currently in early development stages. This current
version, despite being feature-incomplete, is still carefully tested to
ensure release-level quality, however there are some known issues and
bugs that will be fixed in future versions.

Here are the bugs/glitches/shortcomings that are currently known to me
as of this writing:

* Strange behaviour when mouse cursor goes beyond the confines of the
  window while drag-selecting a zoom rectangle. Usually the rectangle
  will keep extending in one direction while staying stationary in
  another.

  This needs a slight rewrite of the code that handles clipping of the
  rectangle. The operation has so many border cases that need to be
  taken into account. The current way of doing this is still viable from
  a muscle-memory perspective (move the mouse and box still grows at
  constant rate).

* Loss of precision once you zoom in far enough

  For speed reasons, FractalToy is coded using native floating-point
  arithmetic. You'll find that eventually once you zoom in far enough,
  the image will start looking blocky and chunky - that's because you're
  pushing the limits of IEEE 754 double-point precision, and that the
  numerical round-off (or "underflow") in calculations is causing
  separate points to get "aliased" together.
  
  There isn't an easy workaround to this problem. Future development
  plans will likely include either the ability to switch between
  floating-point and arbitrary-precision arithmetic (ideally
  automatically as needed on the fly), or some other system that
  preserves underflow error. I am interested in finding alternate
  algorithms, to set FractalToy apart from other non-realtime fractal
  renderers out there.
  
------------------------------------------------------------------------

[5] More information about fractals / further reading

To quote Wikipedia on Fractals:
    A fractal is "a rough or fragmented geometric shape  that can be
    split into parts, each of which is (at least approximately) a
    reduced-size copy of the whole," a property called
    self-similarity. 
    
    Roots of mathematically rigorous treatment of fractals can be traced
    back to functions studied by Karl Weierstrass, Georg Cantor and
    Felix Hausdorff in studying functions that were continuous but not
    differentiable; however, the term fractal was coined by Benot
    Mandelbrot in 1975 and was derived from the Latin fractus meaning
    "broken" or "fractured." 
    
    A mathematical fractal is based on an equation that undergoes
    iteration, a form of feedback based on recursion.
    
If you search deep around the various fractal shapes provided, you may
find some formations that often occur in nature. 

For instance in Mandelbrot, you can often find trees, tree roots,
rivers, waterfalls, and even complete replicas of the original
Mandelbrot "bulb". The fractals all have near-infinite detail; there is
always more to be revealed as you zoom in further.

In the Burning Ship fractal; zoom in to the lower-left region of the
image "behind" the main "ship"; you'll find many smaller ships hovering
away in the distance, exhibiting this fractal's self-similarity.

In the Pickover Stalk renderings of the various other fractals, you'll
find many different organic kinds of shapes, most of them resembling
either alienesque tendrils, ribcages, neural networks or tightly-woven
netting.

To learn more about the supplied fractals, you could always start on the
following Wikipedia links:

Mandelbrot set
    <http://en.wikipedia.org/wiki/Mandelbrot_set>
    
Julia set
    <http://en.wikipedia.org/wiki/Julia_set>
    
Burning ship fractal
    <http://en.wikipedia.org/wiki/Burning_ship_fractal>
    
Pickover Stalks
    <http://en.wikipedia.org/wiki/Pickover_stalks>

Lyapunov fractal
    <http://en.wikipedia.org/wiki/Lyapunov_fractal>

Newton fractal
    <http://en.wikipedia.org/wiki/Newton_fractal>

------------------------------------------------------------------------
    
[6] Future planned features 

A number of features have been slated for appearing in future releases
of FractalToy.

* Ability to create motion video sequences
    
  The user would define "waypoints" in the fractal image and set
  movement/transition parameters, allowing a continuous zoom/pan
  about the fractal image. Other parameters could be interpolated
  as well in order to create various morphing effects. 
  
  While Java is not powerful enough to be able to render frames in
  real-time, there's always the possibility of rendering each separate
  frame to an image file on disk (allowing the user to use their own
  video encoding program afterwards), or the individual frames could be
  fed via an interprocess pipe to an open-source video encoder such as
  MPlayer or FFmpeg to produce a movie file on the fly.
  
* Ability to create your own custom palettes

  Provisions have been made for creating user-made palettes (and
  applying them immediately), only an interface needs to be coded up in
  Swing.
  
* Ability to create your own fractal classes
  
  There is a simple API (albeit currently incomplete and may be subject
  to change in future beta releases) that minimises the amount of
  overhead code needed for implementing a fractal function. Look in the
  source package in the "fractaltoy/fractals" directory for some
  examples.
  
* Implementation of other types of fractal systems (IFS, flames etc)

  This may be a long way off as it requires a fair amount of refactoring
  in the current design, but it could be a good long-term idea.

------------------------------------------------------------------------

[7] License / credits / contributions / contacting the author

All work done by Bryan Rodgers (myself) unless otherwise indicated.

FractalToy is licensed under the GNU General Public License (GPL)
version 3 (or later). The full license text is available in the file
"COPYING", but in layman's terms: 

* You may freely distribute unmodified copies of FractalToy to anyone at
  any cost.
* You may distribute modified binary versions of FractalToy to anyone at
  any cost, on the condition you make copies of the corresponding
  modified source code available to the recipients of these modified
  binary copies.
* If you integrate source code from FractalToy into your own work of
  software, or write software that links directly with FractalToy object
  code, then the resulting aggregate work may only be distributed under
  the terms of the GPL.
  
If you'd like to help out with FractalToy development, feel free to let
me know or contribute patches. Have a read of the "TODO" file first to
make sure if what you're proposing is in line with the roadmap if you
want your feature to be integrated into the baseline, however fresh
ideas and constructive comments are always welcome.

I can be contacted via e-mail at <rodgersb@it.net.au>.

------------------------------------------------------------------------

*** END OF README ***