# 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.

Syntax | Option | Notes
--- | --- | ---
@ | 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 `{ }`
Syntax | Option | Notes
--- | --- | ---
# | 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.

Syntax | Option | Notes
--- | --- | ---
@ | 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.

Syntax | Option | Notes
--- | --- | ---
An integer | Section 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.

Syntax | Option | Notes
--- | --- | ---
: | 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

- Regular annotations, such as split markers and stationary cars, can be added to a flipbook through the annotations text area.
- While the time interval parameter of the periodic car annotations can be used when generating a flipbook, one image will be generated for each point in the path; for intervals larger than 0.05, frames will be duplicated rather than skipped.
- Car overlays in a flipbook are scaled from the specified base size according to the height at each point taken from the replay data, so as to give some visual cues when jumps occur.
- The set of images can be converted into a video with the appropriate tools. For those familiar with ffmpeg, for instance, a sample command might be:
  `ffmpeg -loop 1 -i backdrop.png -r 20 -i '0%04d.png' -filter_complex overlay -shortest -vcodec libx264 -frames 1329 -r 20 foo.mp4`