Welcome to JFrac 1.0!
=====================

JFrac is a Java program designed to produce fractal images by zooming,
recentering, and manipulation of the mapping between fractal indexes
and colors.  It should run properly on any Java-supported platform,
and is known to work on Linux, Windows 98, Windows 2000, and Windows
XP.  If people have reports of successful use on other systems, we
would appreciate knowing; see the About box for contact information.

The major point of this introduction is to run through a brief
tutorial for manipulating fractals and saving the results.  This
should provide most users sufficient information to get started with
the program, although it may not necessarily cover all features.
Topics include:

  * Zooming, Recentering, Resizing, and Rendering
  * Colormap Control Points
  * Color Index Distributions
  * Saving and Loading
  * Plugins
  * Technical Plugin Notes


Zooming, Recentering, Resizing, and Rendering
=============================================

The most important button on the entire JFrac screen is the Render
button.  While it's not very complicated (you just click it to make it
happen), it's the button that makes all of the others interesting.
The Render button starts drawing the fractal into the image window.
The process can be stopped by clicking on the Stop button.  Note that
the drawing capability is not smart enough to start from where it left
off, though, so if you stop the render, it will start over from the
beginning the next time you click on the Render button.

JFrac would not be much fun at all if the only thing you could do was
to draw the image that you see the first time around.  There are two
features that make it more interesting however:  recentering and
zooming.  To recenter the image, simply click anywhere on the image.
When the Render button is clicked, the drawing will be shifted such
that the point you clicked will be in the middle of the image.  You
may click as many times as you like on the image; the last position
clicked will be the one in the middle for the next render.

There are three ways to change the zoom for JFrac.  The first two are
the easiest:  the Halve and Double buttons.  The Halve button cuts the
zoom factor in half, and the Double button doubles the zoom factor.
In addition, the zoom factor can be modified directly by typing in the
zoom factor box.  The zooming used in JFrac is constructed so that
zoom values bigger than 1 zoom IN to the image (i.e., expand the part
in the middle to cover the current image), and numbers less than 1
zoom OUT.  If you want to see more detail, you generally want to zoom
in (i.e., use the Double button, or enter a number greater than 1).

Note that you can use combinations of zooming and recentering without
needing to hit the render button inbetween.  If you want to have a
particular point in the image in the middle, and want to see it in
twice as much detail, you can click the point, click the Double
button, and then click Render to see the zoomed, recentered image.
Also note you can click the Double button multiple times before
clicking Render if you wish to zoom in quite a bit.

Finally, you can also change the size of the image.  Note that this is
different than zooming:  zooming changes the scale of what you see,
while resizing changes the dimensions of the image.  The image's width
and height are listed below the Render and Stop buttons.  You can type
in a new width and/or height and click the Resize button in order to
change the size of the image.  If the image is too big to fit
on-screen, scrollbars will appear to let you scroll to different parts
of the image.

Note that resizing doesn't always work properly with zooming and
recentering.  In other words, if you decide you wish to change the
size of the image, you should do so BEFORE recentering or zooming, and
click the Render button between resizing and any other operations.
This is not to imply that the program will crash if you try to do
zooming and recentering while resizing.  However, you probably will
not end up zoomed and recentered to the right place if you
simultaneously resize the image.


Colormap Control Points
=======================

Zooming in, zooming out, recentering, and resizing get pretty boring
after a while, especially with the rather hideous set of colors which
are used to draw the fractals by default.  JFrac allows you to change
the colors that are used to draw the different bands by manipulating
control points on the color map.  The colormap is displayed in the
lower left portion of the screen, and the set of control points is
displayed on the lower right.

Essentially, you add a series of control points which anchor portions
of the colormap in place, and then change the colors at the control
points.  JFrac automatically generates the intervening colors to make
smooth transitions between points.

To add a new control point, simply click in the location you desire on
the colormap display.  A new control point will be added, which will
appear both in the list and as a marker line between the indexes and
the color band on the colormap.  To remove an existing control point,
find it in the list, and click on the X for that line.  The control
point will disappear, as will its line on the colormap.

A control point can also be moved if it is slightly in the wrong spot.
To do so, locate the control point in the list, and click on either
the plus (+) or minus (-) buttons to increase or decrease the index
value (respectively).  The number in the list will be updated, as will
the marker on the color map.  Alternatively, you may directly enter a
new value for the control point in the numerical display.

Note that the color for the control point is always taken from the
colormap, so if a control point is moved, the color will change.  If
you desire to keep the color the same, you will need to reselect the
color after the point has moved.  Also, note that no two control
points may occupy the same index position on the colormap.  As a
result, you cannot move one control point past another using the plus
and minus buttons.

Finally, and most importantly, you can change the color for a control
point.  To do so, find the control point in the list, and click on the
small button which shows its current color.  Select a new color from
the color selector, and click Ok to make the change.  At that point,
JFrac will automatically generate a smooth color gradient between both
the preceding and following control points.  When selecting a new
color, note that the color selector has three different color
selection modes, any of which can be used to select colors.


Color Index Distributions
=========================

To assist you in picking which colors to modify, JFrac can also
display information about which indexes are present in the current
image, both as a percentage, and as an actual number of pixels.  This
allows you to decide which portions of the color map need to be
modified to generate the results that you desire.

To get a broad overview of the distribution of indexes in the current
image, click on the Reset button.  This will show the distribution for
all indexes, divided into 10 equally-sized groups.

If more specific information is desired, you can specify the starting,
ending, and grouping values and click on the Change button.  For
example, suppose you click on the Reset button, and discover that 100%
of the pixels are in the 100-199 range.  This is not really enough
information to determine how to modify the colors in an interesting
way.  Thus, you could enter 100 as the Start value, 199 as the End
value, 10 as the Step value, and then click Change.  The display would
then show the ranges 100-109, 110-119, etc.  If you wanted even more
fine-grained information, you could change the Step value to 5, which
would show 100-104, 105-109, 110-114, etc.

As a final note, the index distribution display does NOT automatically
refresh when a new image is generated.  You will need to click on
either the Reset or the Change buttons to update the index display
after clicking on Render.


Saving and Loading
==================

When you discover an interesting or pretty fractal design with JFrac,
you may wish to save your progress so that you can start from there in
the future.  In addition, you may wish to save an actual image usable
by other programs, as wallpaper, or on a web page.  JFrac allows you to
save and load several different formats of data to support these
goals.

The current state of the fractal (including its position, its size,
the active plugin, and the colormap) can be saved into a special
fractal data file (a .frac file).  To do so, click on the File menu
and click on Save.  A dialog box will appear in which you can enter a
file name or select a destination directory.  Note that only
directories and .frac files are shown in its display.  Also note that
JFrac automatically adds .frac to the end of the filename if
necessary.  Once you've selected the directory and the filename, click
Save to save the fractal information.

The fractal data can be loaded at a later time by clicking on the File
menu and selecting Load.  Note that only fractal files (with a .frac
extension) are displayed, along with directories.  To load the fractal
data, select the file in the display and click Open.

Since fractal data files are not widely understood by programs other
than JFrac, and since the images are really where the fun is, JFrac
also allows you to export your image to a file.  Two different file
formats are supported, bitmap and ppm.  Note that JFrac does not
support loading of images, however, since no actual fractal
information is stored in images.  To export your image to a file,
click on the File menu and click on Export Image.  In the file type
box at the bottom, select the type of image you wish to write (bmp or
ppm).  Then, select the destination directory, and enter a file name.

Finally, JFrac supports saving and loading of raw colormap data.  If
you generate a colormap that you wish to try on a different fractal
(perhaps one that has been previously saved), you can save your
colormap, load your new fractal, and then load the colormap again.

To save a colormap, click on the File menu and click on Save
ColorMap.  To load a colormap, click on the File menu and click on
Load Colormap.  Note that only colormap data files (.cmap files) are
allowed to be loaded or saved.

As a final note for both colormap files and fractal files, please be
aware that the control points are NOT saved in either of these files.
Thus, if you wish to use the same control points, you will need to
select them over again (sadly, this may be a fair bit of work).


Plugins
=======

The final thing covered in this tutorial is how to work with plugins.
Plugins provide the means by which different fractal generating
functions can be used to draw pictures.  Essentially, if you wish to
think of it this way, each fractal generating function generates its
own particular patterns.  As such, using a single function may not
produce enough variety to find the particular type of images you are
interested in.  JFrac is designed to handle this problem by using
plugins which define fractal generating functions.  You can change to
a different function by selecting a different plugin.

To see a description of the plugin that is currently in use, click on
the Plugin menu and click on 'Plugin info...'  A box will appear which
shows the descriptive information for the plugin.  Usually this will
include the name of the plugin, what version it is, who wrote it, and
some information about the function it actually draws.

To change to a different plugin, click on the Plugin menu and click on
'Select plugin...'  A box will appear listing all of the plugins that
JFrac was able to find.  Simply click on the name of the plugin you
wish to use and click Ok.  When you next click on the Render button,
the image will be generated with the new fractal plugin.

Please note that when you select a new plugin, the zoom, center point,
and size information for the image are left alone.  As such, you may
end up looking at a completely uninteresting part of the new fractal;
in that case, the best suggestion is to zoom out a bit (assuming you
had zoomed in on the previous image) to get a better understanding of
what portion of the fractal you are observing.


Technical Plugin Notes
======================

The following two topics are of a more technical nature, and do not
deal directly with using JFrac.  If you are not interested in
programming, or do not desire to understand the means in which plugins
are auto-detected or constructed, you may skip the remainder of the
tutorial.  First, the method for detecting plugins is discussed.
Following that, a discussion of the means by which new plugins can be
constructed is covered.

In version 1.0 of JFrac, plugins are found by searching for all
classes in the classpath which are in the jfrac.plugins package.  All
such items found in any portion of the classpath are considered to be
valid options for plugins, and will appear on the plugin list.
Clearly, this is not the desired behavior for fully dynamic plugin
support; some fairly careful construction is required to ensure that
no non-plugin classes appear in the jfrac.plugins package.
Additionally, this constrains the allowed names for plugins to be
globally unique, since multiple classes with the same full name in the
classpath can produce odd results.  This particular behavior is thus
expected to change in a future version of JFrac.

Creating new plugins, however, should not change from the version
provided here.  It is possible that new types of plugins will be
added, but the existing plugin architecture should always be
supported.  Writing new plugins is actually relatively easy:
plugin classes must simply implement the jfrac.FractalPlugin
interface.  This interface only defines two methods, one which
provides the plugin description, and one which computes the index for
a given coordinate value based on the maximum allowed index value.  No
mapping of actual colors is required, leaving the user free to
generate whatever sets of colors they desire, solely based on the
index to color mapping.

If you desire to write your own plugin, then, all you need to do is
create a class in the jfrac.plugins package which implements the
jfrac.FractalPlugin interface.  To use your plugin, you simply need to
ensure that it can be found appropriately in the classpath when
running JFrac.  Do note, however, that this particular construction
cannot be done using the java -jar jfrac.jar command; you will instead
need to invoke JFrac by including jfrac.jar and your classpath
together as the classpath for java, and invoke it on the jfrac.JFrac
class directly, i.e.:

java -cp your/classpath/entry:jfrac.jar jfrac.JFrac

As mentioned, this means of discovering plugins will hopefully be
changing in a future release to prevent this particular problem.

As a final note, if you do happen to write a plugin which is
particularly interesting, please consider making it open source, and
sending it to the JFrac development team for inclusion in later
versions of JFrac.