Brickcentral Railways

Introduction
============
This is the documentation for 'Brickcentral Railways'. This is a set of POV-Ray macros for making a computer animation of a 12V lego train. 12 V lego trains that used gray rails, were sold from 1980 till 1990.
The code that makes the train running is written in the POV-Ray scene description language. The code is divided into several files and directories according to their purpose.
The basic distinction that can be made is between code and data. First, there are files that contain POV-Ray macros. The code in these files is documented as good as possible, but a basic description of them is given below. Secondly, there are data files that contain data for laying the lego tracks to create a lego train railroad layout and running the train. To accomplish this these data files are read by the POV-Ray code. The contents and structure of these files are described below.

POV-Ray code
============

list of code files
==================
A pov file that calls the other macro files (trein_animatie.pov).
A file with common variables (common_vars.inc).
A include file to place the railroad layout (treinbaan.inc).
A include file to run the train (trein.inc).

quick start
===========
Just run povray still.ini to view only the railroad layout. Or run povray animation.ini to render multiple frames for an animation.


Train movement
==============
The direction of the train movement is determined by the variable 'train_direction' which is in degrees. 
0 degrees means that the movement is in the direction positive z-axis,
90 degrees, positive x-axis,
180 degrees, negative z-axis.
270 degrees, negative x-axis.

Data Files
==========

The data files can be found in the subdirectory 'railroad_layouts'.

Railroad layout files
=====================

A railroad layout file describes the layout by using code for the different track parts. 
The format of this file is as follows. Each line contains 2 numbers with a comma after each. Except for the last number at last line! This is because POV-Ray expects to read more characters after a comma.

The first number on each line is one of the list below.
1 - corresponds with a straight track with a lenght of 4 povray-units. 
2 - stands for a right-curved track and 
3 - for a left-curved track.
4 - flat crossing
5 - switch diverging left 
6 - switch diverging right
7 - switch converging left - drive straight path
8 - switch converging left - drive diverging path
9 - switch converging right - drive straight path
10 - switch converging right - drive diverging path

    5.	\  |	6. |  /
	 \ |	   | /	
	  \|	   |/
           |       |

    7.     |	8.    /
	  /|	     /|
   	 / |	    / |
        /  |       /  |

    9.  |	10. \
	|\	    |\
	| \	    | \
	|  \	    |  \

	short explanetion for the switches: The switches are to be approached from the bottom (in the drawing) at the vertical line segment. The total of six possibilities can be explained by the fact that there are two different switches. Each switch has three possible connections. So 2 times 3 makes 6.

0 - branch deliminator; when a railroad layout includes one or more switches, different branch(es) must be defined. Each new branch starts with a 0.

The second number on each line is a means to avoid drawing the same track element multiple times. For track-elements other than flat-crossings and switches it is 0 (zero). For flat-crossings and switches this number is used to indicate the amount of these track-elements. Flat-crossings have negative values and switches positive.
e.g. the first flat-crossing is depicted with -1, the second with -2.
Switches are depicted with positive values, no discrimination is made between the different switches.

How to create a railroad layout file
A railroad layout file consists of two numbers on each line that represent track-elements and a control number. Imagine you are going along this track and each time another track element is encountered it is written down (nummerically), along with the control number. So you start at any point in the railroad layout to make a loop (main loop). Keep in mind that you must always move in the same direction. When approaching a switch at the narrow end always choose the straight path. After completing the main loop a zero should be placed in the list, indicating another loop or branch will be described. The starting point of it is the first diverging switch listed in the main loop. After completing this loop, a zero will be placed, if another loop or branch is present, followed by the second diverging switch.
Make sure that when returning to the main loop through a converging switch, this switch is also listed. Otherwise the train can drive this part of the railroad layout.

When a railroad layout file contains one or multiple switches, a 0 is placed after the first loop. Then the part of the layout after the first switch is listed. This starts with a diverging switch, which must have been listed before, and ends with (if present) the final switch. The reason for listing the converging switch twice is for determining the route of the train correctly.
The last line of a file is indicated with '0, 1000'.

Train route files
=================

The format of this file is similar to that of the railroad layout file, 2 numbers on each line, seperated by commas and no comma after the last number on the last line.
This file list all the switches the train passes and indicates whether the direction of the train is straight ahead or whether the train switches direction.A 1 (one) is for 'straight ahead' and a 0 (zero) for the direction switching.
