path: root/README.txt

Diffusion Limited Aggregation (DLA) for Atari 8-bit
===================================================

Diffusion-limited aggregation (DLA) is the process whereby particles
undergoing a random walk due to Brownian motion cluster together to
form aggregates of such particles.

For a good description of DLA, see:
https://en.wikipedia.org/wiki/Diffusion_limited_aggregation

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.

Latest source and documentation can be found here:
https://slackware.uk/~urchlay/repos/dla-asm/

Latest executables can be found here:
https://slackware.uk/~urchlay/repos/dla-asm/plain/dla.xex
https://slackware.uk/~urchlay/repos/dla-asm/plain/dla2csv.xex
https://slackware.uk/~urchlay/repos/dla-asm/plain/dla2img.sh

Also, dla.xex and dla2csv.xex can be found on the TNFS server at
zapp.opensourcerers.net (these may not be the latest version).

This file explains how to use the generator and tools. Other
documentation:

ALGORITHM.txt - English description of what the program does.

BUILD.txt - Instructions for building from source. Most users won't
want or need to do this, since Atari executables are provided.

NOTES.txt - Technical details about the implementation.

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,
e.g. in an emulator or with an SIO2PC cable on real hardware. It will
run on any Atari 8-bit with at least 48K of RAM.

At startup, you're asked "How many particles?". The more particles you
enter here, the longer it will take to generate the image. The default
(if you just press Return) is 1000, which generally takes about 3 to
3.5 minutes. For a quick test just to see what the result will look
like, try 300, which should take less than 20 seconds. The maximum is
65535, which takes around 6-7 minutes to run... but more than about
2000 is too much anyway: The result starts to have a "ring" around it,
which means it outgrew the limited size of the Atari screen.

After you enter the number of particles, you'll be asked for the "Seed
type". The default is the standard DLA seed: a single pixel in the
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. Be patient...

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.
  If you don't include a drive spec (e.g. D: or D2:), drive 1 (D:)
  is assumed. Emulator users can use the H: drive here.
  The file will contain the raw pixels, 8 per byte, 176 pixels (22
  bytes) per line, 170 lines. Size will be 3740 bytes, or 30 sectors
  on a single-density disk. If an error happens while saving, you'll
  get the chance to retry the save.

- Redo: Run the generation process again, with the current particle count
  and seed type settings.

- New: Start the program over, so you can enter different settings.

The only way to exit the program (for now) is to press Reset or power
cycle the Atari.

Using dla2csv.xex (or just dla2csv)
-----------------------------------

This program operates almost identically whether it's running on an
Atari or a modern machine.

First, you will be prompted for an input filename[*]. This must be
a file created by the Save option in dla.xex. The file is read into
memory immediately.

Next, choose the line-ending type. Choices are Atari, Unix (including
Linux and Mac), and MS (aka MS-DOS or Windows). Choose the system
under which you'll be actually using the CSV file.

Next, you're asked for the output filename[*]. 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).

Next, the conversion process starts. This takes about half a 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. On the Atari, you can press Ctrl-C during the conversion to
abort the process (and delete the partial CSV file).

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.

[*] On the Atari, if you don't include a drive specifier (e.g. D: or D2:)
    in the filename, drive 1 (D:) is assumed. Also, when you're asked
    for the input or output filename, you can enter a number (a single
    digit) to see a directory of that drive number. If you're using an
    emulator that supports the H: (host drive) device, you can enter 0
    to see the directory of H:.

Using dla2img.sh
----------------

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).

Run dla2img.sh from a terminal (a shell). If it's not executable, make
it so, with "chmod +x dla2img.sh". The script has built-in help, which
can be viewed by running it with no arguments (as "./dla2img.sh").

Examples:

# convert TEST.DLA to a 256x170 PNG image:
./dla2img.sh TEST.DLA test.png

# as above, but automatically crop the black borders:
./dla2img.sh TEST.DLA test.png -trim

# 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

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]

Note: dla2img.sh has been tested with various shells, including bash,
zsh, ksh93, pdksh, mksh, dash, and bosh (from Schily-tools)... and
the ancient V7 UNIX Bourne shell compiled for Linux from AT&T source
(seriously). If your system doesn't have a /bin/sh that's compatible,
edit the script and change the "#!/bin/sh" to something that works on
your system.