_____ _ _ _____ | ___|_ __ __ _ ___ | |_ __ _ | ||_ _|___ _ _ | |_ | '__|/ _` | / __|| __|/ _` || | | | / _ \ | | | | | _| | | | (_| || (__ | |_| (_| || | | || (_) || |_| | |_| |_| \__,_| \___| \__|\__,_||_| |_| \___/ \__, | |___/ ------------------------------------------------------------------------ FractalToy v0.2.1 beta - an iterative fractal explorer Copyright (C) 2010-2012 Bryan Rodgers Released to the public under GNU GPL 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 . 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 ). 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 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 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 Julia set Burning ship fractal Pickover Stalks Lyapunov fractal 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 . ------------------------------------------------------------------------ *** END OF README ***