1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
|
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, 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.
|
