home *** CD-ROM | disk | FTP | other *** search
/ Between Heaven & Hell 2 / BetweenHeavenHell.cdr / 100 / 64 / mandelex.doc < prev    next >
Text File  |  1987-07-23  |  21KB  |  595 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.                               MANDELEX Version 2.1
  11.  
  12.                                   DOCUMENTATION
  13.  
  14.                        Copyright (c) 1987, David W. Roscoe
  15.  
  16.                                       LODJI
  17.                                   P.O. BOX 397
  18.                              N. CHELMSFORD, MA 01863
  19.  
  20.  
  21.  
  22.         TABLE OF CONTENTS
  23.  
  24.  
  25.         1: INTRODUCTION
  26.  
  27.         2: REQUIREMENTS
  28.  
  29.         3: THIS SOFTWARE IS SHAREWARE
  30.  
  31.         4: DESCRIPTION OF FILES
  32.  
  33.         5: GETTING STARTED.
  34.  
  35.         6: USING MANDELEX.
  36.  
  37.         6.1: MAIN MENU
  38.  
  39.         6.2: DISPLAY-DONE MENU
  40.  
  41.         6.3: CONFIGURATION PARAMETERS
  42.  
  43.         7: RECORD OF UPDATES
  44.  
  45.         8: BUGS AND WORKAROUNDS
  46.  
  47.         9: ERROR MESSAGES
  48.  
  49.         10: FUTURE VERSIONS
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.         Page 2, 1: INTRODUCTION
  70.  
  71.  
  72.         1: INTRODUCTION
  73.  
  74.         MANDELEX is a program for exploring and displaying the infinitely 
  75.         complex boundary of the Mandelbrot Set.  
  76.  
  77.         The Mandelbrot set is a set of points in the (X,Y) plane, or the 
  78.         complex number plane, depending on your point of view.  Many 
  79.         people became interested in the set after an article about it 
  80.         written by A. K. Dewdney was published in Scientific American 
  81.         magazine (Aug. 1985, p16, Computer Recreations).  
  82.  
  83.         The set is interesting because, even though it can be defined 
  84.         using a very simple formula, it has an extremely complex shape.  
  85.         Although it can be completely enclosed in a 3x3 square and 
  86.         therefore has a finite area, the boundary of the set is a fractal 
  87.         curve and so has infinite length.  Looking closer and closer at 
  88.         it reveals more and more detail, without limit!  Many people 
  89.         think that a multicolored display of the set and the points 
  90.         around it is beautiful.  It almost must be seen to be believed!  
  91.  
  92.         MANDELEX was designed to make exploring the boundary of the 
  93.         Mandelbrot fast, interactive, visual, and fun.  Features which 
  94.         distinguish MANDELEX from other programs of its type are:
  95.  
  96.              It uses a algorithm which I call "Contour Following" to 
  97.              concentrate its calculations near the boundary lines between 
  98.              the areas of different color on the image.  It is much 
  99.              faster than conventional brute force algorithms which 
  100.              evaluate the Mandelbrot function at every pixel.  Although I 
  101.              am not sure I, suspect that it is now the fastest Mandelbrot 
  102.              image calculator which runs on similar hardware.  
  103.  
  104.              It plots iteratively in stages of increasing resolution.  
  105.              Instead of plotting pixels, it plots rectangles, big ones at 
  106.              first.  It halves the rectangle size at the end of each 
  107.              stage until the rectangles are 1 pixel on a side during the 
  108.              final stage.  This means that a user can see the general 
  109.              shape of images sooner, which makes display adjustments and 
  110.              exploration faster and easier.  
  111.  
  112.         Other less unusual features of MANDELEX are: 
  113.  
  114.              displays while it calculates;
  115.  
  116.              saves images in compressed format on disk for viewing later;
  117.  
  118.              incomplete image calculations can be interrupted and saved 
  119.              to disk for resumption later;
  120.  
  121.              adjusts for pixel aspect ratio;
  122.  
  123.              allows specification of a zoom view graphically as well as 
  124.              numerically;
  125.  
  126.              allows specification of the colors and number of colors to 
  127.              be used in image;
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.         Page 3, 1: INTRODUCTION
  136.  
  137.  
  138.  
  139.              allows specification of function contour values (also known 
  140.              as iteration breakpoints);
  141.  
  142.              gives automatic menu help;
  143.  
  144.              uses 8087 coprocessor if present.
  145.  
  146.  
  147.  
  148.         2: REQUIREMENTS
  149.  
  150.         MANDELEX requires PC/MS-DOS Version 2 or later.  I recommend that 
  151.         you have 128 Kbyte of RAM available for MANDELEX.  It also 
  152.         requires one of the following computer systems:
  153.  
  154.  
  155.         -    IBM PC with a CGA (Color Graphics Adapter), or a compatible 
  156.              system.  It need not be fully compatible.  It need only be 
  157.              BIOS and video memory map compatible.  For example, it even 
  158.              works on a Zenith Z-100 running ZPC, a CGA PC emulator 
  159.              program.  The program should also run on an EGA system since 
  160.              EGAs provide this much CGA compatibility.  
  161.  
  162.         -    Heath/Zenith H/Z-100 (not PC) with color capability.
  163.  
  164.  
  165.  
  166.         3: THIS SOFTWARE IS SHAREWARE
  167.  
  168.         This software is shareware.  You may copy it provided that you do 
  169.         not sell it, but I encourage you to make copies of it for others, 
  170.         place it in public domain software libraries and on computerized 
  171.         bulletin board systems, and do anything else you can think of to 
  172.         spread it around.  
  173.  
  174.         If you like and use MANDELEX then please send me a contribution.  
  175.         I could really use the money now.  Send contributions to:
  176.  
  177.              LODJI
  178.              P.O. BOX 397
  179.              N. CHELMSFORD, MA 01863
  180.  
  181.         If you send $20 or more then I will:
  182.  
  183.         -    send you an MS-DOS Version 2 disk containing the most recent 
  184.              version of MANDELEX.
  185.  
  186.         -    send you a printed copy of the complete user documentation.
  187.  
  188.         -    notify you of the next major update to MANDELEX when it is 
  189.              ready.
  190.  
  191.         I would be thankful if you could say where you got your first 
  192.         copy of MANDELEX, or how your heard about it.
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.         Page 4, 3: THIS SOFTWARE IS SHAREWARE
  202.  
  203.  
  204.         Please send bug reports, comments, or suggestions about MANDELEX 
  205.         to me at the above address.
  206.  
  207.  
  208.  
  209.         4: DESCRIPTION OF FILES
  210.  
  211.         The MANDELEX package consists of the following files:
  212.  
  213.         -    MANDELEX.DOC - The file you are reading.
  214.         -    MANDELEX.EXE - MANDELEX in executable form.
  215.         -    *.CFG - ConFiGuration files (for various machines).
  216.         -    *.PID - sample Plot Image Data files (for various machines).
  217.         -    IBMPC.* - files for IBM PC CGA and compatible systems.
  218.         -    Z100.* - files for Heath/Zenith Z-100 (not PC) computers 
  219.              with color.
  220.  
  221.  
  222.  
  223.         5: GETTING STARTED.
  224.  
  225.         1.   Backup all the files, if you don't want to lose them.  
  226.  
  227.         2.   If you have a hard disk or a RAM disk then you may want to 
  228.              copy all the files to a subdirectory on that disk to speed 
  229.              file operations, however MANDELEX will run from floppy.
  230.  
  231.         3.   Configure for your computer.  To do this, copy the 
  232.              appropriate configuration file, whose name ends in ".CFG", 
  233.              to "MANDELEX.CFG".  This file contains some initialization 
  234.              data for the program.  For example, type:
  235.  
  236.              COPY IBMPC.CFG MANDELEX.CFG<enter>
  237.  
  238.              at the PC/MS-DOS prompt for IBM PC CGA compatible systems.
  239.  
  240.              You may also need to type:
  241.  
  242.              SET COMPATIBILITY=IBM<enter>
  243.  
  244.              if your computer is an IBM compatible system but is not one 
  245.              of the ones that MANDELEX recognizes.  This will cause 
  246.              MANDELEX to assume IBM compatibility and act accordingly.
  247.  
  248.         4.   At the PC/MS-DOS prompt type:
  249.  
  250.              MANDELEX<enter>
  251.  
  252.         5.   MANDELEX will prompt you with various options.  There should 
  253.              be a sample image file for your computer on the distribution 
  254.              disk.  You can display it by using the "L" (for Load) 
  255.              command in the main menu.  For example, if you have an IBM 
  256.              PC CGA compatible you would type:
  257.  
  258.              IBMPC<enter>
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.         Page 5, 5: GETTING STARTED.
  268.  
  269.  
  270.              when the Load routine prompts you for a file name.  
  271.  
  272.  
  273.  
  274.         6: USING MANDELEX.
  275.  
  276.  
  277.         6.1 MAIN MENU
  278.  
  279.         The main menu options are:
  280.  
  281.         C    Create a new image.  This selection asks you for a name of a 
  282.              file to use to store the results, calls the configuration 
  283.              parameter editor so you can make any final parameter 
  284.              adjustments,  and  then begins calculating a new image based 
  285.              on  the parameters.   Calculations continue until  they  are 
  286.              done or you interrupt by hitting any key.   Then the program 
  287.              goes to the display-done menu for processing.
  288.  
  289.         L    Load/resume an old image.  This selection asks you for the 
  290.              name of a file which contains the results of a previous 
  291.              image, and loads it.  If you hit a key then MANDELEX 
  292.              terminates the load and goes to the display-done menu for 
  293.              processing.  If the load completes but the image is 
  294.              incomplete then MANDELEX will resume calculations on it.  If 
  295.              the image is complete then the program goes to the display-
  296.              done menu.  
  297.  
  298.         P    edit configuration Parameters.  This selection activates the 
  299.              Configuration Parameter Editor which is described elsewhere. 
  300.              When you are done editing, you are asked whether or not to 
  301.              save the parameters to disk.  If you answer "Y" then the new 
  302.              parameters are saved back into the MANDELEX.CFG file.  These 
  303.              become the new defaults.
  304.  
  305.         E    End program.  This selection returns control to the 
  306.              operating system.
  307.  
  308.  
  309.         6.2: DISPLAY-DONE MENU
  310.  
  311.         When a display is complete or interrupted by you, the program 
  312.         beeps and goes to this menu.  The options are:
  313.  
  314.         V    View.  This selection removes any menu from the screen so 
  315.              that the image of the Mandelbrot set, whether complete or 
  316.              not, can be viewed without obstruction.
  317.  
  318.         Z    Zoom.  This selection is for closer examination of a part of 
  319.              the image.  It displays a zoom box on the screen and 
  320.              activates the zoom menu.  The zoom menu is normally not 
  321.              displayed, but will be displayed if you type an illegal key.  
  322.              The zoom menu allows you to move the zoom box around on the 
  323.              screen and to change its size until it encloses exactly the 
  324.              part of the image at which you want a closer look.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.         Page 6, 6.2: DISPLAY-DONE MENU
  334.  
  335.  
  336.              The box mover algorithm was designed for expanding and 
  337.              contracting binary searches.  Depending on context, a single 
  338.              keystroke could move the box 1 pixel or hundreds.  But 
  339.              moving the box should become easy after a few seconds of 
  340.              use.  If the box is too low then type the Up key (U),  if 
  341.              the box is too far to the left then type the Right (R) key, 
  342.              etc. .  
  343.  
  344.              When your box is of proper size and position, type "E" to 
  345.              end the zoom menu.  The program sets the View parameters to 
  346.              match the dimensions of the zoom box, asks you for a new 
  347.              file name, and goes to the Configuration Parameter Editor 
  348.              for any adjustments you might want in the other parameters.  
  349.              When you end the editor a new image is begun.  
  350.  
  351.         E    End.  Returns to the main menu.
  352.  
  353.  
  354.         6.3 CONFIGURATION PARAMETERS
  355.  
  356.         The configuration parameters do 2 things:
  357.  
  358.         1.   They describe how the graphics hardware is configured.  
  359.  
  360.         2.   They describe how you want an image of the Mandelbrot set to 
  361.              look.
  362.  
  363.         The configuration parameters are loaded from the file 
  364.         MANDELEX.CFG when MANDELEX is started.  All *.CFG files supplied  
  365.         with MANDELEX describe a sample 3-color view of the entire 
  366.         Mandelbrot set.  
  367.  
  368.         Also, each time a image (*.PID) file is loaded, the parameters 
  369.         are loaded also.  Each file contains a copy of the parameters in 
  370.         use when the file was created.  
  371.  
  372.         A routine called the Configuration Parameter Editor is called at 
  373.         various times to allow you to change these parameters.  It is  
  374.         screen-oriented.  "Forward" and "Backward" motion commands move a 
  375.         cursor from one parameter to another.  A "Change" command changes 
  376.         the value of the selected parameter.  "Initialize-all" loads the 
  377.         default values from the MANDELEX.CFG file.  "End" exits the 
  378.         editor.
  379.  
  380.         In the editor's display, the parameters at the top describe 
  381.         hardware use.  These may not be changed in this version of 
  382.         MANDELEX.  They could be changed in an earlier version but 
  383.         changing them is now meaningless because they are all now 
  384.         determined by the hardware.  They will probably be eliminated in 
  385.         a later version.
  386.  
  387.         The parameters at the bottom determine how a Mandelbrot image 
  388.         will be calculated and you will probably change them often.  
  389.  
  390.         View parameters describe the X and Y limits of the area of the 
  391.         Mandelbrot set to be calculated.  Since the aspect ratio of your 
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.         Page 7, 6.3: CONFIGURATION PARAMETERS
  400.  
  401.  
  402.         screen is fixed, you may change only the first 3 parameters.  The 
  403.         4th is changed automaticly.  
  404.  
  405.         The number of Image Colors to use is programmable from 2 to 16.  
  406.         But note that more colors means more contours and therefore a 
  407.         longer execution time.  
  408.  
  409.         The color (Col:) values (also known as attributes), and the 
  410.         Mandelbrot function contour (Con:) values at boundaries between 
  411.         color areas, are listed together last.  The contour function 
  412.         values can range from 1 to 32767.  High contour values more 
  413.         closely approximate the Mandelbrot set boundary, and need to used 
  414.         at high magnifications to show small details, but here also 
  415.         higher values mean longer execution time.
  416.  
  417.         Your choice of contour values can greatly affect how your display 
  418.         will look.  For example, although the Mandelbrot set has been 
  419.         proven to be a connected set, some parts of it are connected by 
  420.         filaments less than 1 pixel wide.  The trick in showing these 
  421.         filaments is to pick contour values low enough to show the 
  422.         presence of a filament, but high enough so that the contour 
  423.         following algorithm will detect and follow its inner structure.  
  424.  
  425.         To show this, create a new image using the following parameters:
  426.  
  427.              -.3200314 <= x <= .1126761 
  428.               .8620286 <= y <= ...
  429.              # colors: 4,
  430.              col: 3, con: 20, col: 2, con: 30, col: 1, con: 90, col: 0
  431.  
  432.         Then create another image and note the difference with the 
  433.         following single contour parameter change:
  434.  
  435.              change the con: 20 to con: 10
  436.  
  437.  
  438.         7: RECORD OF UPDATES
  439.  
  440.         VERSION   DESCRIPTION
  441.  
  442.         1.0       Original release, written in interpretive BASIC.
  443.  
  444.         1.1       An error caused memory to be exhausted sometimes.  
  445.                   Changed dynamic array allocation to fix.
  446.  
  447.                   An error caused resumed images to sometimes loop 
  448.                   repeatedly around a single contour.  Changed function 
  449.                   cache invalidate routine to fix.
  450.  
  451.         1.2       Fixed an error which caused improper recycling of pair 
  452.                   elements, which caused a fatal error with pair elements 
  453.                   exhausted during complex images.
  454.  
  455.         2.0       Translated to C language.  Had seperate .EXE files for 
  456.                   each type of computer.  Now about 10 times faster, or 
  457.                   100 times faster with 8087 coprocessor.
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.         Page 8, 7: RECORD OF UPDATES
  466.  
  467.  
  468.  
  469.         2.01      Got a single .EXE file to handle multiple computer 
  470.                   types.
  471.  
  472.         2.02      Changed to data file format rev. 1 . This format 
  473.                   appears to use about 23% of the file space used by 
  474.                   original format.  MANDELEX will now read either format 
  475.                   but always writes rev. 1 .  Original format files will 
  476.                   be converted to new format by the Load command at main 
  477.                   menu.
  478.  
  479.                   Also, fixed bug in image cache (introduced during 
  480.                   translation to C) which ruined the hit ratio.  Speed 
  481.                   increased slightly.
  482.  
  483.         2.1       Made a few cosmetic changes.
  484.  
  485.  
  486.  
  487.         8: BUGS AND WORKAROUNDS
  488.  
  489.         There is one bug that I first saw in version 1.2.  I was planning 
  490.         to fix this bug after the translation to C language, hoping that 
  491.         the bug might be eliminated in the translation process.  
  492.         Unfortunately the bug survived.
  493.  
  494.  
  495.         The bug results in an error message, something like "inserting 
  496.         duplicate, fatal error".  The message is the result of an 
  497.         internal consistency check of some of the data structures used in 
  498.         MANDELEX.  
  499.  
  500.         The bug seems to associated with saving or resuming a partially 
  501.         completed image on disk, because it never appears if I let an 
  502.         image go from start to finish without interruption.  
  503.  
  504.         If this bug occurs just restart the image.  The bug is rare and 
  505.         usually does not appear the second time because you are unlikely 
  506.         to interrupt it again in the same spot.  
  507.  
  508.         If all else fails then allocate enough time on your computer and 
  509.         don't interrupt the calculation until the image is finished.
  510.  
  511.  
  512.  
  513.         9: ERROR MESSAGES
  514.  
  515.         ERROR: unrecognized computer : this means that MANDELEX couldn't 
  516.         figure out what type of computer it is running on.  It does this 
  517.         by looking for manufacturer copyright ASCII strings in ROM.  See 
  518.         Byte magazine special issue, Inside the IBM PCs, 1987, page 181, 
  519.         for the technique used.  If you are sure your computer is IBM 
  520.         compatible then you may tell MANDELEX this.  See GETTING STARTED 
  521.         for details.
  522.  
  523.         ERROR: IBM PC, can't set CGA mode 4 : After deciding that the 
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.         Page 9, 9: ERROR MESSAGES
  532.  
  533.  
  534.         computer is an IBM compatible it was unable to select the 
  535.         graphics mode needed for displaying images.  Your computer is 
  536.         probably not really IBM PC compatible.
  537.  
  538.         wrong hardware or file? FATAL ERROR - : the parameters from a 
  539.         *.CFG or *.PID file do not match the type of computer MANDELEX 
  540.         thinks it is running on.  You can't mix files from different 
  541.         machines.
  542.  
  543.         error openning file : probably means the file doesn't exist.  
  544.         Maybe you mistyped its name.
  545.  
  546.         inserting duplicate, FATAL ERROR - : this is caused by a rare 
  547.         bug.  See BUGS AND WORKAROUNDS.  
  548.  
  549.  
  550.         If you get an error message not listed above then please notify 
  551.         me, because either the documentation needs updating or MANDELEX 
  552.         needs fixing.
  553.  
  554.  
  555.  
  556.         10: FUTURE VERSIONS
  557.  
  558.         Besides fixing bugs, which has the highest priority, I plan to 
  559.         work on some enhancements.
  560.  
  561.         I plan to try 3 ideas on the imaging algorithm.  Each has the 
  562.         potential of increasing execution speed by a factor of 2.  And 
  563.         one of them is likely to make image files even more compact.
  564.  
  565.         I would also like to make color selection easier and more 
  566.         flexible.
  567.  
  568.         If I receive enough contributions then I may even get myself a 
  569.         computer with an E.G.A. display and make MANDELEX use its high 
  570.         resolution mode.
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.