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
The following types of annotations are currently
available: Car, X, Circle,
Diamond, Dot, Arrow,
Text, 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.
CarCar
@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 curly braces styling options for the caption can be set. |
| 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. The alignment is defined
as if the car faced eastward, so E will draw the text ahead
of the car, N to its left, and so forth. |
| % | Text inversion | Inverts the direction of the caption text. Useful if a choice of positioning leads to upside down text. |
X
@10 10
*1 #orange
Circle
@5 5
*1 >0.05 #fuchsia
Diamond
@7 7
*1 #pink
Dot
@13 13
*0.125 #yellow
Arrow
@3 15
*1 ^45 #yellow %
X, Circle, Diamond, Dot
and Arrow can be used to add general purpose markers to the map.
The syntax and available settings are the same as those for
Car, with a few additional options for some of the markers: Arrow accepts an optional
% setting which inverts the direction of the arrow. Arrows by
default start at their location, as specified through @. With
%, the arrow will end at the @-location and start
at what would, without the %, have been its end point.
| Syntax | Option | Available for | Notes |
|---|---|---|---|
| % | Inversion | Arrow
| Exchanges the start and end points of the arrow, so that it ends, and
points at, the location specified by @, rather than
beginning at it. |
| > | Line width | Arrow, Circle and
X |
Line width of the marker, in tiles. Note that, for arrows, the length of the arrow head is five times its line width. |
TextText "Hello!"
@9 10
^45 *0.5 #blue $50
Text adds a standalone caption. The options are the same as
those described for car captions, except for there being no alignment
setting, and for there being a @ position setting which
specifies where the left edge of the caption will be.
SegSeg
@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. |
| > | Line width | Line width of the segment, in tiles. |
Other options work as described for Car above.
SplitSplit
1
@7 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. |
| > | Line width | Line width of the split line, in tiles. |
| # | 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.
|
| % | Caption text inversion | Inverts the direction of the caption text. |
TraceTrace
:"070ZGUT.dat"
#plum !
+ {Car @30 "GUT {{SPEED}}"}
~0 20 {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. |
| > | Line width | Line width of the split line, in tiles. |
| + { } | Individual car/marker decoration | An annotation overlaid on some point of the path. Must be followed by
the specification of a car or marker annotation within curly brackets.
The options for the overlaid annotation follow the syntax described above
for regular 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 annotation 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 annotation will be placed
according to the replay path orientation. |
| ~ { } | Periodic car/marker decoration | Annotations 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 or marker annotation within curly brackets, using
the syntax described above for individual decorations
(+). |
{{ }}.
Below is a list of available substitutions:
| Placeholder | Displayed data |
|---|---|
| {{FRAMENUMBER}} | Frame number, starting from 0 for the initial frame.
|
| {{GAMETIME}} | Elapsed game time, assuming 20 frames per second. |
| {{SPEED}} | Car speed, in miles per hour. Note that the reported speed at frame
number n corresponds to the speed in the interval between
frames n-1 and n. |
| {{GEAR}} | Current gear. |
| {{HEIGHT}} | Height of the car relative to low ground, in metres. |
Both individual and periodic trace decorations support captions through the syntax described in the section about car annotations. A couple of examples:
Trace :"070ZGUT.dat" #plum +{Car @20 "{{SPEED}}" {$50}}
An individual car anotation at the 0:20.00 frame with an associated caption, positioned next to the car.
Trace :"070ZGUT.dat" #plum ~0 5 {Car "{{SPEED}}" {$50}}
A periodic car annotation, added every five seconds starting from the 0:00.00 frame, with an associated caption, positioned next to each car.
Individual decorations support an alternative form of caption, introduced
using the full syntax for standalone Text annotations within
& { }:
Trace :"070ZGUT.dat" #plum +{Car @20 &{Text "{{SPEED}}" @2 29 $50}}
The specification above will result in a periodic car annotation in which
each annotation is accompanied by a caption. The caption, however, is not
placed next to the car, but rather at the position specified by
@ (in this case, at coordinates (2, 29)). Such an
arrangement, which will be referred from now on as frame-bound standalone
captions, makes it possible to display car and frame information at fixed
positions on the map.
Unlike in the case of regular captions, there can be multiple frame-bound standalone captions per decoration:
Trace :"070ZGUT.dat" #plum +{Car @20 {Text "{{SPEED}}mph" @2 29 $50}
{Text "Gear: {{GEAR}}" @2 27 $50}}
Frame-bound standalone captions for periodic decorations are only allowed in flipbook rendering, as described in the next section, with a slightly different syntax.
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 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.
Regular annotations, such as split markers, stationary cars and unchanging standalone captions, can be added to a flipbook through the annotations text area.
Periodic overlays in trace flipbooks can frame-bound standalone
captions, so that frame information can be displayed at fixed positions.
As described in the subsection about frame decoration captions, they are
introduced through & { }, with the difference
that the caption specification should be next outside of, but next to, the
braces of the periodic decoration. For instance, here is an example with a
timer:
Trace :"070ZGUT.dat" #plum ! ~0 0.05 {Car} & {Text "{{GAMETIME}}" @2 29 $50}
If this feature is used to add a timer to a flipbook with multiple traces, the timer should be added to the longest trace, as otherwise the timer will remain frozen for the final frames, after the trace ends.
While the time interval parameter of the periodic 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.
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. Using 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
(In the above, 1329 should be replaced by the actual number
of frames in the flipbook.)