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,
  which must be a complete filespec (examples: D:TEST.DLA,
  D2:THING.DLA). The file will be the raw pixels, 8 per byte, 256
  pixels (32 bytes) per line, 170 lines. Size will be 5440 bytes,
  or 44 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. 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.

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.

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

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.

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.

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). The script has built-in
help, which can be viewed by running it with no arguments.

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]

dla2img.sh has been tested with various shells, including bash, zsh, ksh93,
mksh, and dash.