home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Between Heaven & Hell 2
/
BetweenHeavenHell.cdr
/
100
/
64
/
mandelex.doc
< prev
next >
Wrap
Text File
|
1987-07-23
|
21KB
|
595 lines
MANDELEX Version 2.1
DOCUMENTATION
Copyright (c) 1987, David W. Roscoe
LODJI
P.O. BOX 397
N. CHELMSFORD, MA 01863
TABLE OF CONTENTS
1: INTRODUCTION
2: REQUIREMENTS
3: THIS SOFTWARE IS SHAREWARE
4: DESCRIPTION OF FILES
5: GETTING STARTED.
6: USING MANDELEX.
6.1: MAIN MENU
6.2: DISPLAY-DONE MENU
6.3: CONFIGURATION PARAMETERS
7: RECORD OF UPDATES
8: BUGS AND WORKAROUNDS
9: ERROR MESSAGES
10: FUTURE VERSIONS
Page 2, 1: INTRODUCTION
1: INTRODUCTION
MANDELEX is a program for exploring and displaying the infinitely
complex boundary of the Mandelbrot Set.
The Mandelbrot set is a set of points in the (X,Y) plane, or the
complex number plane, depending on your point of view. Many
people became interested in the set after an article about it
written by A. K. Dewdney was published in Scientific American
magazine (Aug. 1985, p16, Computer Recreations).
The set is interesting because, even though it can be defined
using a very simple formula, it has an extremely complex shape.
Although it can be completely enclosed in a 3x3 square and
therefore has a finite area, the boundary of the set is a fractal
curve and so has infinite length. Looking closer and closer at
it reveals more and more detail, without limit! Many people
think that a multicolored display of the set and the points
around it is beautiful. It almost must be seen to be believed!
MANDELEX was designed to make exploring the boundary of the
Mandelbrot fast, interactive, visual, and fun. Features which
distinguish MANDELEX from other programs of its type are:
It uses a algorithm which I call "Contour Following" to
concentrate its calculations near the boundary lines between
the areas of different color on the image. It is much
faster than conventional brute force algorithms which
evaluate the Mandelbrot function at every pixel. Although I
am not sure I, suspect that it is now the fastest Mandelbrot
image calculator which runs on similar hardware.
It plots iteratively in stages of increasing resolution.
Instead of plotting pixels, it plots rectangles, big ones at
first. It halves the rectangle size at the end of each
stage until the rectangles are 1 pixel on a side during the
final stage. This means that a user can see the general
shape of images sooner, which makes display adjustments and
exploration faster and easier.
Other less unusual features of MANDELEX are:
displays while it calculates;
saves images in compressed format on disk for viewing later;
incomplete image calculations can be interrupted and saved
to disk for resumption later;
adjusts for pixel aspect ratio;
allows specification of a zoom view graphically as well as
numerically;
allows specification of the colors and number of colors to
be used in image;
Page 3, 1: INTRODUCTION
allows specification of function contour values (also known
as iteration breakpoints);
gives automatic menu help;
uses 8087 coprocessor if present.
2: REQUIREMENTS
MANDELEX requires PC/MS-DOS Version 2 or later. I recommend that
you have 128 Kbyte of RAM available for MANDELEX. It also
requires one of the following computer systems:
- IBM PC with a CGA (Color Graphics Adapter), or a compatible
system. It need not be fully compatible. It need only be
BIOS and video memory map compatible. For example, it even
works on a Zenith Z-100 running ZPC, a CGA PC emulator
program. The program should also run on an EGA system since
EGAs provide this much CGA compatibility.
- Heath/Zenith H/Z-100 (not PC) with color capability.
3: THIS SOFTWARE IS SHAREWARE
This software is shareware. You may copy it provided that you do
not sell it, but I encourage you to make copies of it for others,
place it in public domain software libraries and on computerized
bulletin board systems, and do anything else you can think of to
spread it around.
If you like and use MANDELEX then please send me a contribution.
I could really use the money now. Send contributions to:
LODJI
P.O. BOX 397
N. CHELMSFORD, MA 01863
If you send $20 or more then I will:
- send you an MS-DOS Version 2 disk containing the most recent
version of MANDELEX.
- send you a printed copy of the complete user documentation.
- notify you of the next major update to MANDELEX when it is
ready.
I would be thankful if you could say where you got your first
copy of MANDELEX, or how your heard about it.
Page 4, 3: THIS SOFTWARE IS SHAREWARE
Please send bug reports, comments, or suggestions about MANDELEX
to me at the above address.
4: DESCRIPTION OF FILES
The MANDELEX package consists of the following files:
- MANDELEX.DOC - The file you are reading.
- MANDELEX.EXE - MANDELEX in executable form.
- *.CFG - ConFiGuration files (for various machines).
- *.PID - sample Plot Image Data files (for various machines).
- IBMPC.* - files for IBM PC CGA and compatible systems.
- Z100.* - files for Heath/Zenith Z-100 (not PC) computers
with color.
5: GETTING STARTED.
1. Backup all the files, if you don't want to lose them.
2. If you have a hard disk or a RAM disk then you may want to
copy all the files to a subdirectory on that disk to speed
file operations, however MANDELEX will run from floppy.
3. Configure for your computer. To do this, copy the
appropriate configuration file, whose name ends in ".CFG",
to "MANDELEX.CFG". This file contains some initialization
data for the program. For example, type:
COPY IBMPC.CFG MANDELEX.CFG<enter>
at the PC/MS-DOS prompt for IBM PC CGA compatible systems.
You may also need to type:
SET COMPATIBILITY=IBM<enter>
if your computer is an IBM compatible system but is not one
of the ones that MANDELEX recognizes. This will cause
MANDELEX to assume IBM compatibility and act accordingly.
4. At the PC/MS-DOS prompt type:
MANDELEX<enter>
5. MANDELEX will prompt you with various options. There should
be a sample image file for your computer on the distribution
disk. You can display it by using the "L" (for Load)
command in the main menu. For example, if you have an IBM
PC CGA compatible you would type:
IBMPC<enter>
Page 5, 5: GETTING STARTED.
when the Load routine prompts you for a file name.
6: USING MANDELEX.
6.1 MAIN MENU
The main menu options are:
C Create a new image. This selection asks you for a name of a
file to use to store the results, calls the configuration
parameter editor so you can make any final parameter
adjustments, and then begins calculating a new image based
on the parameters. Calculations continue until they are
done or you interrupt by hitting any key. Then the program
goes to the display-done menu for processing.
L Load/resume an old image. This selection asks you for the
name of a file which contains the results of a previous
image, and loads it. If you hit a key then MANDELEX
terminates the load and goes to the display-done menu for
processing. If the load completes but the image is
incomplete then MANDELEX will resume calculations on it. If
the image is complete then the program goes to the display-
done menu.
P edit configuration Parameters. This selection activates the
Configuration Parameter Editor which is described elsewhere.
When you are done editing, you are asked whether or not to
save the parameters to disk. If you answer "Y" then the new
parameters are saved back into the MANDELEX.CFG file. These
become the new defaults.
E End program. This selection returns control to the
operating system.
6.2: DISPLAY-DONE MENU
When a display is complete or interrupted by you, the program
beeps and goes to this menu. The options are:
V View. This selection removes any menu from the screen so
that the image of the Mandelbrot set, whether complete or
not, can be viewed without obstruction.
Z Zoom. This selection is for closer examination of a part of
the image. It displays a zoom box on the screen and
activates the zoom menu. The zoom menu is normally not
displayed, but will be displayed if you type an illegal key.
The zoom menu allows you to move the zoom box around on the
screen and to change its size until it encloses exactly the
part of the image at which you want a closer look.
Page 6, 6.2: DISPLAY-DONE MENU
The box mover algorithm was designed for expanding and
contracting binary searches. Depending on context, a single
keystroke could move the box 1 pixel or hundreds. But
moving the box should become easy after a few seconds of
use. If the box is too low then type the Up key (U), if
the box is too far to the left then type the Right (R) key,
etc. .
When your box is of proper size and position, type "E" to
end the zoom menu. The program sets the View parameters to
match the dimensions of the zoom box, asks you for a new
file name, and goes to the Configuration Parameter Editor
for any adjustments you might want in the other parameters.
When you end the editor a new image is begun.
E End. Returns to the main menu.
6.3 CONFIGURATION PARAMETERS
The configuration parameters do 2 things:
1. They describe how the graphics hardware is configured.
2. They describe how you want an image of the Mandelbrot set to
look.
The configuration parameters are loaded from the file
MANDELEX.CFG when MANDELEX is started. All *.CFG files supplied
with MANDELEX describe a sample 3-color view of the entire
Mandelbrot set.
Also, each time a image (*.PID) file is loaded, the parameters
are loaded also. Each file contains a copy of the parameters in
use when the file was created.
A routine called the Configuration Parameter Editor is called at
various times to allow you to change these parameters. It is
screen-oriented. "Forward" and "Backward" motion commands move a
cursor from one parameter to another. A "Change" command changes
the value of the selected parameter. "Initialize-all" loads the
default values from the MANDELEX.CFG file. "End" exits the
editor.
In the editor's display, the parameters at the top describe
hardware use. These may not be changed in this version of
MANDELEX. They could be changed in an earlier version but
changing them is now meaningless because they are all now
determined by the hardware. They will probably be eliminated in
a later version.
The parameters at the bottom determine how a Mandelbrot image
will be calculated and you will probably change them often.
View parameters describe the X and Y limits of the area of the
Mandelbrot set to be calculated. Since the aspect ratio of your
Page 7, 6.3: CONFIGURATION PARAMETERS
screen is fixed, you may change only the first 3 parameters. The
4th is changed automaticly.
The number of Image Colors to use is programmable from 2 to 16.
But note that more colors means more contours and therefore a
longer execution time.
The color (Col:) values (also known as attributes), and the
Mandelbrot function contour (Con:) values at boundaries between
color areas, are listed together last. The contour function
values can range from 1 to 32767. High contour values more
closely approximate the Mandelbrot set boundary, and need to used
at high magnifications to show small details, but here also
higher values mean longer execution time.
Your choice of contour values can greatly affect how your display
will look. For example, although the Mandelbrot set has been
proven to be a connected set, some parts of it are connected by
filaments less than 1 pixel wide. The trick in showing these
filaments is to pick contour values low enough to show the
presence of a filament, but high enough so that the contour
following algorithm will detect and follow its inner structure.
To show this, create a new image using the following parameters:
-.3200314 <= x <= .1126761
.8620286 <= y <= ...
# colors: 4,
col: 3, con: 20, col: 2, con: 30, col: 1, con: 90, col: 0
Then create another image and note the difference with the
following single contour parameter change:
change the con: 20 to con: 10
7: RECORD OF UPDATES
VERSION DESCRIPTION
1.0 Original release, written in interpretive BASIC.
1.1 An error caused memory to be exhausted sometimes.
Changed dynamic array allocation to fix.
An error caused resumed images to sometimes loop
repeatedly around a single contour. Changed function
cache invalidate routine to fix.
1.2 Fixed an error which caused improper recycling of pair
elements, which caused a fatal error with pair elements
exhausted during complex images.
2.0 Translated to C language. Had seperate .EXE files for
each type of computer. Now about 10 times faster, or
100 times faster with 8087 coprocessor.
Page 8, 7: RECORD OF UPDATES
2.01 Got a single .EXE file to handle multiple computer
types.
2.02 Changed to data file format rev. 1 . This format
appears to use about 23% of the file space used by
original format. MANDELEX will now read either format
but always writes rev. 1 . Original format files will
be converted to new format by the Load command at main
menu.
Also, fixed bug in image cache (introduced during
translation to C) which ruined the hit ratio. Speed
increased slightly.
2.1 Made a few cosmetic changes.
8: BUGS AND WORKAROUNDS
There is one bug that I first saw in version 1.2. I was planning
to fix this bug after the translation to C language, hoping that
the bug might be eliminated in the translation process.
Unfortunately the bug survived.
The bug results in an error message, something like "inserting
duplicate, fatal error". The message is the result of an
internal consistency check of some of the data structures used in
MANDELEX.
The bug seems to associated with saving or resuming a partially
completed image on disk, because it never appears if I let an
image go from start to finish without interruption.
If this bug occurs just restart the image. The bug is rare and
usually does not appear the second time because you are unlikely
to interrupt it again in the same spot.
If all else fails then allocate enough time on your computer and
don't interrupt the calculation until the image is finished.
9: ERROR MESSAGES
ERROR: unrecognized computer : this means that MANDELEX couldn't
figure out what type of computer it is running on. It does this
by looking for manufacturer copyright ASCII strings in ROM. See
Byte magazine special issue, Inside the IBM PCs, 1987, page 181,
for the technique used. If you are sure your computer is IBM
compatible then you may tell MANDELEX this. See GETTING STARTED
for details.
ERROR: IBM PC, can't set CGA mode 4 : After deciding that the
Page 9, 9: ERROR MESSAGES
computer is an IBM compatible it was unable to select the
graphics mode needed for displaying images. Your computer is
probably not really IBM PC compatible.
wrong hardware or file? FATAL ERROR - : the parameters from a
*.CFG or *.PID file do not match the type of computer MANDELEX
thinks it is running on. You can't mix files from different
machines.
error openning file : probably means the file doesn't exist.
Maybe you mistyped its name.
inserting duplicate, FATAL ERROR - : this is caused by a rare
bug. See BUGS AND WORKAROUNDS.
If you get an error message not listed above then please notify
me, because either the documentation needs updating or MANDELEX
needs fixing.
10: FUTURE VERSIONS
Besides fixing bugs, which has the highest priority, I plan to
work on some enhancements.
I plan to try 3 ideas on the imaging algorithm. Each has the
potential of increasing execution speed by a factor of 2. And
one of them is likely to make image files even more compact.
I would also like to make color selection easier and more
flexible.
If I receive enough contributions then I may even get myself a
computer with an E.G.A. display and make MANDELEX use its high
resolution mode.