
Graced v. 0.99
==============
Graphical trace editor for creating tracks for Grand Prix Legends


Requirements:
=============
This program will edit altitude data extracted from a .gtk file, created by GPLTrk.
To extract a suitable text file, use "txt2gtk.exe" by P.A.Flack. You can get it from:
http://home.online.no/~bi-knu/editing/apps/apps.htm
With this, you can also enter edited data into the .gtk again.

For getting started quickly, the directory "mytrack" contains such an exported file, and all other optional files for the "mytrack" example available as part of the GPLEA track creating tutorial at:
http://home.online.no/~bi-knu/editing/
Copy these files to the location of graced.exe in order to try the editor with them.


Configuration:
==============
Edit the configuration file "graced.cfg", which must be in the same directory as graced.exe.
An example file is included.
In there, you must specify the name of the file exported by txt2gtk in the INFILE line.
You can also specify a path to the file here.
You must in the same way specify a file to save the edited data in, in the OUTFILE line.

The program reads the lateral position of the traces from a .trk file exported from GPLTrk.
To indicate the .trk file to read, enter the name under TRKFILE in graced.cfg
Optionally, you can create a file telling the lateral positions of your traces. This file
will only be read, if the TRKFILE could not be found.
The file must contain precisely 16 numbers in a single line, even if you use fewer traces. Just fill in dummy zeroes.
Example format:
-18.0 -16 -14.0 -12.0 -5.3 -5.0 5.0 5.3 10.0 12.0 15.0 20.0 22.0 0 0 0
Graced will look for a file called tracepos.txt, but you can specify another name in graced.cfg in the TRACEPOSFILE line.

Another optional file can be used to overplot the trace graphs with reference data from your planned track.
The file name is specified in the ALTREFFILE entry in graced.cfg, with the default name being "altref.txt".
The format is a pair of numbers for each line, with the first being the distance from the start of the track and the second being the height at that point.
Example format:
0	23.25
198.70	20.50
685.09  22.40
If you need to offset the reference data by a constant height, this can be specified in craced.cfg in the ALTREFOFFSET line.

The reference data are only plotted when the trace designated as the centre-line is selected. This trace is automatically selected to be the most central one, but if you for some reason want another trace as centre-line, specify the trace number in the CENTRELINE entry in graced.cfg. Leave the line out, or give a negative id for automatic assignment.

The effective length of a trace depends on the amount of curvature of a section, with the inner trace being shorter than the outer. The length is an important parameter when calculating the gradient, so if you want the gradients of adjacent sections to match perfectly, the program
needs to know the turn radius of each section.
The turn radius is automatically extracted from the .trk file specified by the TRKFILE entry
in graced.cfg
Alternatively, you can painstakingly examinine the section data in GPLTrk, and write them to a text file.
Enter the radius in meters, and for a straight section enter a radius of 0 in stead.
The file looks like this:
       0       0
       1       0
       3       -50
       6       0
       7       151
etc. There must be one line for each section.
Specify the name of the file in the RADIUSFILE entry of graced.cfg. By default, "radius.txt" is looked for. This file is only read if the TRKFILE could not be found.
Note that the correction of the gradient is quite subtle in most cases, and if the track has no narrow climbing turns etc., you might get away with not taking turn radius into account.

The bank between traces and the climb angle at each section beginning is written on top of the graphs. If you do not need these numbers, set the SHOWANGLES entry to "0" in graced.cfg. This can also be toggled at run-time by pressing "a".

The desired resolution can be specified in graced.cfg like this:
GRAPHRES     1024 768
Try to enter numbers that you already know works on your hardware. Due to memory handling issues, you may find that not all known resolutions works with this program.

The option FONTFILE      CNEW10.PCX sets the font and hight for text output.
The option SFONTFILE     CNEW8.PCX sets the font and hight for small text output
The option MFONTFILE     CNEW9.PCX sets the font and hight for medium text output
The option BFONTFILE     CNEW10.PCX sets the font and hight for big text output but in version 0.99 it's not used. We can change that later maybe


Graced.cfg must end with a non-empty line after the last entry. An easy way to remember this is to put an "END"
in the last line.


Running Graced
==============

A two graphs will appear:

Lower graph:
This shows a number of track sections, initially all of them, divided by blue vertical dotted lines. One section is selected, and is identified by a bright cyan border at the beginning. Selection can be done by the left/right cursor keys, or by left-clicking the mouse on a blue line.
The traces are shown as red curves. Again, one is selected: This is drawn in bright white, or if it is the assigned centre-line, in bright yellow. Traces are selected by the up/down cursor keys. The centre-line trace can also be selected by pressing the Home key.
Optionally, reference data can be overplotted as white +'es, and are only shown when the centre-line is selected.
At the top, each section number is shown in gray and optionally the gradient of the selected trace at each section border is printed in white. Display of angles can be toggled by pressing "a". To the left, the height is shown in metres, and at the bottom the distance from the start of the track is displayed in meters.
You can zoom in and out in the following way:
The leftmost section id is selected by by the numeric pad "7" and "1" keys, and the rightmost section is controlled by the numpad "9" and "3" keys. This requires the mouse cursor to be in the lower graph.
Another way to zoom is to draw a rectangle over the area to zoom to, by holding the right mouse button in while
moving diagonally. Note that the section selection is still limited to entire sections.

Upper graph:
This displays a cross-section of the track at the beginning of the selected section. The selected trace is shown in the same colour as in the lower graph.
The angle between the traces, i.e. track bank, is written in white, and the track id's in grey.
With the mouse cursor in the upper graph, you can zoom in on certain traces using the numeric pad, similarly to the section zoom described above.

Trace editing:
All editing of height and gradient is done at the border between two sections. So first select the border, and also select the trace.
Note that when the centre-line trace is edited, the change is added to all the other traces in the section. In this way, you can define the general look by edition the centre-line, and edit the others when you are finished with the centre-line.
Set the new height of the trace by left-clicking on the selected border at the desired height. You can keep the
button pressed and drag the trace to the desired height. When the button is released, the gradient must be
selected. Move the mouse relative to the small circle marking the new height. The current angle will be displayed
to the upper right. When satisfied, left-click again to mark the new gradient.
If you start editing by mistake, cancel by right-clicking, or even exit without saving by pressing shift-q.

Fixing gaps and kinks:
Your traces may have discontinuities in both height and gradients if e.g., you have edited the section length or turn radius in GPLTrk after starting the editing of trace heights.
Also, editing the centre-line when using the radius correction feature may introduce gradient kinks, as it is not trivial to decide what effect the centre-line change should have on the other traces.
In this case, you are advised to always check for kinks by pressing "c" and fix them by pressing "f". You can also skip the checking and just select to fix anything.
Note that the fixing may not be done in a way that you like, so you should check if the corrected traces look ok.

When satisfied, save the result by pressing "w". The new file can now be read into txt2gtk.


Command overview:

w: Write traces to file
a: Toggle display of angles
c: Check altitude and gradient jumps
f: Fix altitude and gradient jumps
z: Zoom out to show entire track
q: Quit
Q: Quit without saving

Cursor up/down: Select trace
Home:           Select centre-line trace
KP 7/1:         Select leftmost section or trace (*)
KP 9/3:         Select rightmost section or trace (*)
Insert/Delete:  Zoom upper height limit
Page Up/Down:   Zoom lower height limit

Left mouse btn:  Select section or edit trace
Right mouse btn: Cancel edit

(*) Depends on in which graph the mouse cursor is.

H/h: calling a small help window which will list the available keyboard options.


Bugs:
=====
When compiled with MinGW32, garbage pixels are often left behind when moving the mouse.


Disclaimer:
===========
I do not accept responsibility for any effects, adverse or otherwise,
that this editor may have on your computer and data. Use it at your own risk.


Contact:
========
You may direct questions, problem reports etc. to "anton.norup at gmail.com" or to the Sim Racing Mirror Forum which you can access here: http://srmz.net



License:
========
Copyright Anton Norup Sørensen, 2002-5
This program is distributed under the GNU General Public License
for free software. Read the included "license.txt" file for further details.


Thanks to:
==========
Phil Flack - without his tools and documentation of file formats,
this tool would never be possible.
Bernd Nowak - added Windows 7 / 2008 / Vista compability and some small adds (fonts and help function)


Compiling the source code
=========================
The source code is included in the "src" directory, with a makefile for gcc-compatible compilers.
You will need the Allegro library. Get it at http://alleg.sourceforge.net/
The program has been compiled and run using:
Windows 98se, DJGPP 2.03, Allegro 4.0.2
Linux RedHat 7.3, gcc, Allegro 4.0.2
MinGW32 2.0.0, Allegro 4.0.3
Version 0.99 has been compiled using gcc version 4.4.1 (TDM-2 mingw32) and Allegro 4.4

Changes:
========
0.90 : First executeable release
0.91 : Bug fix: Only very large gradient mismatches would be detected and fixed
0.92 : Lateral zoom in cross-section window. Axis length and width markers.
0.93 : Update of trace being edited while moving mouse. Zoom by mouse. Single key unzoom.
0.94 : Distributed .exe is compiled with MinGW32 for Windows XP compatability
0.95 : Height of mouse pointer is always shown.
       Bug fix: You could not zoom completely out in the right side of cross-section window.
0.96 : Radius and trace position data can be read from .trk file.
       Max number of sections increased to 4096
0.99 : The Allegro library has been changed to version 4.4 and that the colors use desktop colors
       Also the backbuffer rendering has changed to run with Windows XP and Windows 7
       A small help text has been incorperated by pressing H/h
       The ability to use different fonts by using PCX font files. You can get TTF2PCX here: http://www.allegro.cc/resource/Tools/Fonts/ttf2pcx
       Added the functions to use different PCX files for small, medium and big fonts.
       If someone has an idea which text might be useful to use the big font please tell us :)
