Added dla2csv, dla2img. Split up docs.

1 files changed, 74 insertions, 67 deletions

diff --git a/README.txt b/README.txt
index 0c64a2c..ea245a6 100644
--- a/README.txt
+++ b/README.txt
@@ -8,23 +8,29 @@ form aggregates of such particles.
 For a good description of DLA, see:
 https://en.wikipedia.org/wiki/Diffusion_limited_aggregation
 
-This Atari 8-bit implementation is written in 6502 assembly, using the
-ca65 assembler from the cc65 suite: https://cc65.github.io/
+The original version of this was in Atari BASIC, by ChrisTOS. It can
+be found at https://github.com/ctzio/DLA/
+
+This assembly version is by B. Watson (urchlay@slackware.com, Urchlay
+on libera.chat IRC). The code is licensed under the WTFPL: do WTF you
+want with it. It's written in 6502 assembly, using the ca65 assembler
+from the cc65 suite: https://cc65.github.io/
+
+Also included are support tools to convert the results to CSV or
+image files.
+
+This file explains how to use the generator and tools. Other
+documentation:
 
-Building
---------
+ALGORITHM.txt - English description of what the program does.
 
-You need a Unix/GNU like system (which might even be modern
-Windows), with GNU (or possibly BSD) make, Perl 5, and the CC65 tools
-installed. Provided you have all that, simply type "make" to assemble
-the source.
+BUILD.txt - Instructions for building from source. Most users won't
+want or need to do this, since Atari executables are provided.
 
-If you have trouble building on Linux, ask me for help. If you have
-trouble on other OSes, ask someone who actually knows about your OS
-(not me, I don't do Windows or Mac).
+NOTES.txt - Technical details about the implementation.
 
-Running
--------
+Using dla.xex
+-------------
 
 The executable is called "dla.xex", and is a standard Atari binary
 load file. It can be run in the same way you run any other .xex files,
@@ -45,14 +51,10 @@ center of the screen. Other seeds generate different types of image,
 and run faster than the dot; try them all.
 
 After you enter the seed type, the screen will clear and go solid
-black, while the image is generated. The ANTIC chip's DMA is disabled,
-to speed things up. However, you can "peek" at the progress of the
-generator by holding down the Start key. This will show the work in
-progress, but it will slow things down noticeably.
+black, while the image is generated. Be patient...
 
-After the image is finished generating, the screen DMA will be turned
-back on, so you can see it. The bottom line shows a menu, from which
-you can choose to:
+After the image is finished generating, the image will be displayed.
+The bottom line shows a menu, from which you can choose to:
 
 - Save: Save the image to disk. You'll be prompted for a filename,
   which must be a complete filespec (examples: D:TEST.DLA,
@@ -69,64 +71,69 @@ you can choose to:
 The only way to exit the program (for now) is to press Reset or power
 cycle the Atari.
 
-Algorithm
----------
+Using dla2csv.xex (or just dla2csv)
+-----------------------------------
 
-The algorithm works like this:
+This program operates almost identically whether it's running on an
+Atari or a modern machine.
 
-1. The initial "seed" pixels are drawn.
+First, you will be prompted for an input filename. On the Atari, you
+must include the drive specifier (e.g. D:TEST.DLA or D2:FOO.DLA). This
+must be a file created by the Save option in dla.xex. The file is read
+into memory immediately.
 
-2. Each particle starts on the edge of a circle whose center is the
-center of the screen. The circle's radius depends on the number of
-particles that have been rendered so far: radius is 15 for particles 1
-to 100, 30 for particles 101 to 300, 45 for particles 301 to 600, and
-75 for particles 601 and up.
+Next, choose the line-ending type. Choices are Atari, Unix, and MS
+(aka MS-DOS or Windows). Choose the system under which you'll be
+actually using the CSV file.
 
-3. Walk the particle around randomly. For each step, pick a random one
-of the 4 cardinal directions (no diagonals).
+Next, you're asked for the output filename. On the Atari, this must
+include the drive specifier (e.g. D:OUTPUT.CSV). This file will be
+overwritten if it exists (unless of course it can't be overwritten due
+to permissions or the Atari locked-file bit).
 
-4. If the particle goes "out of bounds" (see below), respawn it and
-try again (without incrementing the particle counter).
+Next, the conversion process starts. This takes about one minute on
+the Atari, and is instantaneous on a modern machine. Progress is shown
+as a percentage. When it's finished, the output CSV file has been
+written.
 
-5. If the particle is ever adjacent to a set pixel, it gets stuck
-there, the particle counter is incremented, and we go back to step 2.
+Last, you're asked whether to convert another file. Answering N here
+will exit the program. On the Atari, you should be returned to the DOS
+menu or prompt, but your mileage may vary (it works on DOS 2.0S, at
+least). Answering Y (or just pressing Return) starts the whole process
+over at the input filename prompt.
 
-When the particle counter reaches the max (the number the user
-entered), the process is complete.
+Using dla2img.sh
+----------------
 
-Notes
------
+This is a shell script that calls ImageMagick's "magick" binary. For
+it to work, you'll have to install your OS's image-magick package(s)
+(or whatever it's actually called), or (I suppose) compile your own
+ImageMagick from source (not recommended).
 
-It should be possible to optimize this a bit further, maybe shave
-another 5% to 10% off the run time.
+Run dla2img.sh from a terminal (a shell). The script has built-in
+help, which can be viewed by running it with no arguments.
 
-There might be a quick way to limit the particles' movement outside
-the initial circle's radius. Right now, it's limited to a square area;
-width and height are the diameter of the circle plus 10 pixels. The
-corners of this square waste a lot of time; it'd be better to come up
-with a way to do an octagon (the square with the corners cut off),
-which shouldn't slow down the inner loop too much... I actually did
-implement this, but it was too slow (the time spent in calculations
-was longer than the time saved by doing them).
+Examples:
 
-Tech stuff: rather than calculate points on a circle in asm code,
-the tables of points for the 4 circle sizes are pre-calculated by a
-perl script and included in the executable verbatim. The tables bloat
-the code some (2KB), but the speed boost is well worth it. Also, the
-graphics mode used is "graphics 8", but in ANTIC narrow playfield
-mode, so the X resolution is 256... meaning I don't need two bytes
-for the X cursor position (which saves a good bit of time). The code
-that plots pixels doesn't use CIO to do so (it writes directly to the
-screen memory), which also saves time. There's no floating point math
-in the generation process: if there were, the asm version wouldn't be
-all that much faster than the BASIC one...
+# convert TEST.DLA to a 256x170 PNG image:
+./dla2img.sh TEST.DLA test.png
 
-Author
-------
+# as above, but automatically crop the black borders:
+./dla2img.sh TEST.DLA test.png -trim
 
-The original version of this was in Atari BASIC, by ChrisTOS. It can
-be found at https://github.com/ctzio/DLA/
+# other image types are supported ("magick -list format" to see them all):
+./dla2img.sh TEST.DLA test.bmp
+./dla2img.sh TEST.DLA test.jpg
+./dla2img.sh TEST.DLA test.tiff
 
-This assembly version is by B. Watson (urchlay@slackware.com, Urchlay
-on libera.chat IRC). The code is licensed under the WTFPL: do WTF you
-want with it.
+If the conversion succeeds, there is no output in the terminal (no
+news is good news). If you get a "magick: command not found" error,
+you don't have ImageMagick installed correctly.
+
+If your magick binary is in a non-standard location (not in the
+shell's $PATH), you can run it as e.g.:
+
+MAGICK=/path/to/magick ./dla2img.sh [arguments]
+
+dla2img.sh has been tested with various shells, including bash, zsh, ksh93,
+mksh, and dash.