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.uk, 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, with an SIO2PC cable on real hardware, boot from the TNFS server with FujiNet, etc. It will run on any Atari 8-bit with at least 48K of RAM. XL/XE users should boot without BASIC (hold down Option at boot, or "BASIC OFF" if you use SpartaDOS). SpartaDOS X users, you'll have to run it with the X command, e.g. "X DLA.XEX". If you try to run it normally, it will complain that there's not enough memory (and there's not; the SDX cart "eats" 8K 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. - Quit: Exit the program. You'll be asked "Exit program[y/N]?". Answering Y here returns you to DOS. N starts the program over. You can also exit the program by entering Q at the "How many particles?" prompt, or pressing the Reset key at any time. 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. Some sanity checking is done: if the file is the wrong size (not 3740 bytes), and/or if it has any pixels set in the left 3 columns (where dla.xex never puts particles), you'll be given the chance to back out (most likely, you typed the wrong filename). 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 (for a file with 1000 particles), 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). In case of error (bad filename, disk full, bad sector, etc), you'll be given the chance to retry the conversion. At the end of conversion, you'll be shown the number of particles. This includes the seed particles, so e.g. if you used the single-dot seed and entered 1000 particles, you'll see "1001 particles" here. Last, you're asked whether to convert another file. Answering N here will exit the program. On the Atari, you'll be returned to the DOS menu or prompt. Answering Y (or just pressing Return) starts the whole process over at the input filename prompt. [*] If you just press Enter (Return on the Atari) when asked for a filename, you'll be asked whether you want to exit the program. 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"). If you're going to be using dla2img.sh a lot, copy it to some place like /usr/local/bin (somewhere in your $PATH). 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.