1README for [stream]
2===================
3
4This README file will talk about the internals of [stream], that is,
5how it knows which colour to pick.
6
7The difficulty resides with the number of different possible cases. If
8we were to allow the check for the 8 surrounding chunks, that would
9give a 2^8 (256) possibilities and thus 256 different colours which is
10too much since the image is indexed and thus already has a limit of
11256 colours. So we'll check for only the 4 cardinal directions (N, E,
12S, W), which gives 2^4 (16) possibilities.
13
14The goal is to find who around the chunk we want to transform is of
15same nature, that is, has the same colour as the chunk under
16consideration, this way we'll know if we should transform it into a
17straight line, a right corner angle, a dead-end or a 4-way crossing
18for instance.
19
20Let's give arbitrary values of:
21- 1 for "same chunk on north side" (binary: 0001)
22- 2 for "same chunk on east side"  (binary: 0010)
23- 4 for "same chunk on south side" (binary: 0100)
24- 8 for "same chunk on west side"  (binary: 1000)
25
26We can image 4 functions that will return either 1 or 0 if a chunk
27exists around the one being transformed on each side. Let's call those
28is_north, is_east, is_south and is_west.
29
30To know what identical chunk is around, we just make the sum of the 4
31tests multiplied by the arbitrary value of each:
321 x is_north() + 2 x is_east() + 4 x is_south() + 8 x is_west().
33This will return a value between 0 and 15 (16 different cases) which
34cover all possible cases. All we have to do is to retrieve a colour
35value for this newly calculated index.
36
37In a word, we have, is the chunk is for a 4-way crossing, we'd have:
381111
39WSEN
40
41A T-crossing, would be:
421110
43WSE-
44
45This is why we store in the config file the colour in the following order:
460 1-n 1-e 2-ne 1-s 2-ns 2-es 3-nes 1-w 2-nw 2-ew 3-new 2-sww 3-nsw 3-esw 4
47If you were to calculate the corresponding index in the same order
48you'd find it goes from 0 to 15 by step of 1, so we can store the
49appropriate colour at the right index.
50
51Written by Artaxerxes2 at iname dot com
52=======================================
53