============================
		    = MANDELBROT EXPLORER v1.3 =
		    ============================

Introduction
============
Mxp (Mandelbrot explorer) is an X application for computing and exploring
Mandelbrot sets.  Features of mxp include:

	- zoom and un-zoom
	- dynamic resizing of drawing window
	- setup save/load
	- asynchronous image generation (buttons always work)
	- GIF output
	- animation
	- nine color schemes
	- color rotation
	- color change options
	- detailed statistics


Installation
============
If you have imake:
   1) Edit Imakefile.  Only the following options need to be set:
				- Compiler optimization options
				- If you have the XPM library and where it is
				- Install directory
				- Select Optional MPI support
   2) type "xmkmf"
   3) type "make"
   4) type "make  install"

If you don't have imake:
   1) Edit Makefile.noimake (same options as in Imakefile above)
   2) type "make -f Makefile.noimake"
   3) type "make -f Makefile.noimake install"


Documentation
=============
One of the marks of a good GUI interface is good usability without
having to read any documentation or refer to help files.  Most of the
functions in mxp are fairly intuitive and don't require help.  However
some of the options and features need some explanation.  The following
are tips for use and should suffice.  Since mxp does not have any options
other than the standard X11 options a man page has not been included.

Zooming:
Hold down the left mouse button and drag to zoom.  A box will highlight
the zoom area.  The zoomed image will be created when the button is
released.

Defaults:
The defaults for mxp may be altered by using the "File" menu "Save as
Default" option.  This option will save the current settings into
$HOME/.mxprc".  When mxp is started the defaults settings will be read
from this file.

Xplot Data:
The "Dump Xplot Data" option under the file menu will create a data file
(mxp.data) that may be used as input to the xplot utility to create some
really spiffy 3D Mandelbrot renderings.  Be warned, the xplot data file
is big!

Reset:
The reset option in the "File" menu will restore all of the default settings
except for the window size.

Resizing:
The drawing window may be resized by either selecting one of the standard
sizes from the "Size" menu or by using the mouse to stretch the window.
By default an aspect ratio of 1.333 will be maintained when the window
is stretched.  If a different aspect ratio is desired select "Var Aspect"
under the size menu.  If you end up covering the controls with the
drawing window pressing the left mouse button will raise the controls.
This is handy when doing full screen images.

Color Options:
The "Color Scheme" menu offers 9 color options and 2 options for gray scale.

The number of color changes per iteration can be changed in the "Color Inc"
menu.  This is useful when images get too busy from frequent color changes
at high magnification levels.  The "Single Seq" option normalizes the
iterations such that each color in the color map will only be used once.

The "Colors" +/- buttons set number of colors used in the private color map.
This option only affects the number of color steps and does not affect
which colors are used.  Larger number of colors will result in smoother
color transitions, but not necessarily more interesting pictures.  The
maximum number of colors is 512 (224 with 8 bit color depth displays).

The "Color Rotate" +/- buttons rotate the colors in the private color
map. Try it!

Animation:
The animation option under the "File" menu is used to create a sequence
of GIF files that can be made into an animation using xanim, an
mpeg-encoder or other available animation tools.  To create an animation
sequence create two setup files (starting and ending) via the "Save Setup"
option in the "File" menu.  Only the initial co-ordinates and the initial
number of iterations are used from the starting setup file.  The color
scheme, size, etc. are set from the ending setup file.

Selecting the "Animate" option will bring up a new window with entry panels
for configuring the animation.  There are panels for entering the starting
and ending setup filenames, the output directory for the GIF files and
a filename prefix for the GIF files.

The "Scaling Factor" sets the zoom in distance between each frame.  The
"Scaling Factor" is a multiplier that determines the dimensions of next
frame in the animation. For example with the default setting of 0.80 each
successive frame will have a dimension that is 80% of its predecessor.

The creation of GIF files and displaying of progress in an X11 window can be
be individually controlled via the "Display" and "Create GIFs" buttons.  The
"Estimate" button does a quick computation of the number of frames that
will be created based of the current settings.


Bugs
=====
Could be some, but then if I knew where they were I would fix them, right?

However, there is a kludge that you may want to know about.  Mxp has code
to place it's windows next to each other.  To do proper placement the
dimensions of the decorations added by the window manager are needed.
If there is a way to find out the width and/or height of these decorations
I could not figure it out.  Therefore, I added 2 defines (BORDER_WIDTH,
TITLE_HEIGHT) to mxp.h and set them to values that work for my window
manager setup.  If the window placement is less than ideal you can tweek
the values to get things in the right places.

Mxp currently supports 8, 16 and 24 bit color depths.  32 color depths may
work but it has not been tested.


Acknowledgments
================
The routines to generate GIF output (in the lug directory) are unmodified
modules from the "lug" library, written by Raul Rivero.

Many of the original concepts and a small amount of code came from an
example in the Cray Research "UNICOS Xwindow System Reference Manual
SR-2101".

--
Chris Brady
E-mail cbrady@cray.com