Annotations

Annotations to a track map are specified by text commands inserted into the annotations text area of the viewer. A particular set of commands might look like this:

 Car @15.5 10 ^105 #aliceblue "Alan Rotoi" {'S *1} Split 1
@11 14 ^S *3 'N

There are currently three types of annotations available: Car, Seg, Split and Trace. These keywords inform the program the following values should be taken as styling options of an annotation of the corresponding kind. Most of the options are identified by leading symbols (@, ^ etc.), which have roughly equivalent meanings for the different annotations. In most cases, the options can be omitted (thus being replaced by sensible defaults) and reordered freely. The syntax is quite liberal about whitespace and linebreaks.

The syntax and meaning of the fields for each sort of annotation is described below. Mandatory fields are highlighted; fields whose position can not be changed are underlined.

Car

Car @15.5 10 ^45 *0.5 #orange "Mark Nailwood" { #yellow $50 ^0 *0.5 'N }

Car adds a car annotation, similar to the one used for the 0x02/0x03 ghost car track elements.

SyntaxOptionNotes
@Position Position of the car, in tile units with @0 0 being the southwestern (i.e. lower left) corner of the map. To center the car in, say, the tile (15, 23) as displayed by the grid indices of the map, use @15.5 23.5
^Angle Angle in degrees of the direction the car points to, starting from east and growing counterclockwise (as per the usual convention in maths).
*Size Length of the car relative to tile size. The default value, 0.5, is the same used for the ghost car track elements.
#Colour Colour of the body of the car. Must be either one of the 147 colour names listed here and typed as shown there (lower case, no spaces) or a hex RGB triplet (thus #yellow and #ff00ff are equivalent).
"..." { }Caption Text to be used as a caption, drawn beside the car. Within the (optional) curly braces styling options for the caption can be set.
Caption options within the { }
SyntaxOptionNotes
#Colour Colour of the caption text. All observations done just above apply here.
$Background opacity Opacity of the caption background, from 0 to 100 (percent). The default is zero, thus making the background invisible. Set a higher value in case the map colours make the caption hard to read.
^Angle Angle in degrees of the direction the text goes.
*Size Font size, relative to the tile size.
'Caption and car alignment Alignment of the caption in relation to the car. The value must be one of E, N, W and S (which stand for the four cardinal directions).

Seg

Seg @17.5 10.25 ^90 *3.5 #orange "Start of braking zone" { #ffa500 $25 ^30 *0.5 'N }

Seg adds a line segment over the map.

SyntaxOptionNotes
@Position Position of one of the ends of the segment.
^Angle Angle in degrees of the direction of the segment, starting from the coordinates defined by @.
*Length Length of the segment, in tiles.

Other options work as described for Car above.

Split

Split 1 @22 14 ^E *5 #yellow $40 'W

Split adds a split / section marker, drawn as a segment with specialised properties.

SyntaxOptionNotes
An integerSection number Number of the track section. Drawn as an identifying caption beside the split line. Must be an integer.
@Position Coordinates of the tile where the split line begins. The values must be integer. The actual starting point of the line is southwestern corner of the tile.
^Split direction Direction of the split line. One of E, N, W and S.
*Length Length of the split line, in tiles. The value must be integer.
#Colour Colour of the both the split line and its caption.
$Caption background opacity Opacity of the caption background, from 0 to 100 (percent).
'Caption and split alignment Alignment of the caption in relation to the split line. Must be one of E, N, W and S.

Trace

Trace :"146zctg.dat" #red ! + {Car @0 "CTG"} ~1 1 {Car}

Trace adds the path of a replay, optionally decorated with car annotations. The path is meant to be rendered from data extracted from a replay (e.g. through dstien's repldump DOS tool) and formatted for reading with the companion tool repldump-to-carto.

SyntaxOptionNotes
:Replay data path File containing the replay data. The path is relative to the base path set with the Cartography interface.
#Colour Colour of the trace; used as a default for cars and other decorations. The decorations may override the default colour with a # option of their own.
!Visibility Add an exclamation mark to make the trace line, but not cars or other decorations. invisible.
+ { }Individual car decoration A car overlaid on some point of the path. Must be followed by the specification of a car annotation within curly brackets. The options for the overlaid car follow the syntax described above for regular car annotations, except for the position and angle annotations. The @ position symbol should be followed by a single number, which sets at which moment of the lap should the car be positioned (for instance, @7.5 will place the annotation on the position at 7.5s or, equivalently, the 150th frame). The angle annotation should be omitted, as the car will be placed according to the replay path orientation. Additionally, adding a caption to the car with the text {{FRAMENUMBER}} or {{GAMETIME}} will result in the frame number and the time in seconds of the frame, respectively, to be displayed automatically.
~ { }Periodic car decoration Cars overlaid on the path at regular intervals. The symbol should be followed by two numbers, which set the initial moment and the spacing in seconds, and by a car annotation within curly brackets, using the syntax described above for individual car decorations (+).

Creating flipbooks

A flipbook is a set of images, which, taken together, form an animation of laps by one or several cars performing replays. To create a flipbook, specify one or several trace annotations with periodic car overlays in the Flipbook text area of the Cartography interface and render the map as usual. After a while (rendering all frames will likely take a few minutes), the link to save a flipbook will become active. The flipbook consists of a zip file containing one PNG per replay frame, plus a background image with the track map as well as any static annotations.

Caveats and tips