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. The file will contain 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[*]. 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 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. 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). 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] If you get "stat: command not found", 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 (seriouly). 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.