User Tools

Site Tools


manual:csv-format

CSV format

Sim Racing Telemetry can export recorded telemetry data in a comma-separated values (CSV) file. This is a simple textual file format that can be easily imported in other tools (like Microsoft Excel, LibreOffice, Matlab, etc) or easily read by custom computer programs.

Since the delimiter used for separate values in each row is the tab character, formally a tab-separated values (TSV) file is exported.

Here you can find the documentation of the exported data, including documentation of the system fields. System fields allow you to properly manage the exported data and re-create a correct telemetry stream. Game-dependent fields are not covered by this guide.

Importing into Excel, LibreOffice and other software

To correctly import the CSV files in a third-party software (like Microsoft Excel, LibreOffice, Matlab, etc), you must correctly configure the import options to match the file format. Opening the CSV file with a text editor will show you exactly how data are formatted. The following are the settings used by the exported CSV files:

  • Format: DELIMITED (not “Fixed width”)
  • Field separator: TAB (not comma or others);
  • Decimal separator: . (the DOT character, not the comma or others)
  • Charset/Encoding: UTF-8

An example of valid import options in LibreOffice:

Telemetry bins

Each row in the CSV file contains data of a specific “telemetry bin”. A “telemetry bin” contains telemetry data at a fixed distance on track (usually measured from the point where lap times begin to be measured, usually the finish-line), where near telemetry samples are “consolidated” in a single sample (this requires a relatively complex algorithm). The result is that you can pick a specific bin and you're able to get the corresponding telemetry data from all the available laps.

System fields

Some of the exported fields are important if you want to properly analyze or re-construct the telemetry stream.

Field name Description
validBin If the row contains valid data (1) or not (0). Not valid rows can be ignored. Some laps - like the start race lap and the end race lap - contains only few valid rows. To simplify management in some software (e.g. math/statistics software usually import such CSV files as multi-dimensional matrixes), we always export all the telemetry bins of the laps, including invalid bins. When a row is not valid, all game-related fields are set to -1.
carId Car identifier string (as reported by the game).
trackId Track identifier string (as reported by the game).
trackLength Track length in metres (as reported by the game). The field lap_distance represents the telemetry bin distance over the trackLength.
lapIndex 0-based index of the lap in the CSV file. Each distinct lap in the file has a different index.
lapNum 0-based lap number, as reported during a race. It's semantic is bound to lapFlag field (see explanation later).
lapFlag 0 for normal laps, 1 for “race-start” laps. It changes the semantic of several other fields (like the lapNum field, see explanation later).
binIndex 0-based index of the “telemetry bin” in the lap. Data, from different laps, with the same binIndex can be compared.
lap_number The 0-based lap number as reported by the game. We suggest to use the lapNum field.
lap_distance Position of this sample in the track, This is reported as the distance of this bin on track, usually measured from the point where lap times begin to be measured.
lap_time Lap time for the lap with index lapNum. Note that it can span different lapIndex values accordingly to lapFlag (see explanation later).

Other fields are game-dependent and are not covered here (but see section Data Fields for some helpful generic information). In general, values set to -1 are invalid.

The "lapFlag" field

For normal laps, lapFlag is 0 and the lapNum is the 0-based lap number. But there's a special case that must be managed if you want to properly re-create the events during a race: in some races, the race begins before the normal finish-line (i.e. the start-line is before the normal finish-line - if the start-line is after the finish-line, this is not a problem as all the data are already consistent). Such hundred of extra-metres are reported using:

  • lapFlag set to 1;
  • lapNum set to 0 (as it's definitely part of the first lap);
  • lap_time starts counting (as such extra metres are part of the first lap time);
  • lap_distance reporting the right and normal position on track (i.e. the distance from the normal finish-line);
  • lapIndex is set to 0.

After crossing the normal finish-line, the “normal” data are then reported:

  • lapFlag is set to 0;
  • lapNum remains 0 (as we're still in the first racing lap);
  • lap_time is not reset (as it's still counting the first racing lap time);
  • lap_distance resets to always report the right position on track;
  • lapIndex increases and is set to 1.

While the samples with lapFlag set to 1 are not interesting from a telemetry point of view, they can contain important events of the race (like overtakes and changes in positions). Depending on your needs, for simplicity you could ignore laps with lapFlag set to 1 and you'll end working with simple, consistent and valid data.

Lap and sector times

Lap time

To have mathematically consistent bins, each bin is associated to a unique “representative” position on track (specifically the one reported by lap_distance). This usually doesn't match the exact last millimetre in the lap, so the lap_time field is always a little bit behind the real registered lap time. We could add this information in the future.

Sector time

As not all games and tracks have the same number of sectors, exporting each sector as a separated column would produce CVS files harder to parse (the number and names of the columns wouldn't have a fixed layout anymore). We could add this information in the future (likely “packing” the data using a special format).

Tyre/wheel data

Data for tyres/wheels are reported with a 0-based index, usually following the front-to-back/left-to-right order.

For a 4-wheels vehicle:

Suffix Description
_0 Front Left (FL)
_1 Front Right (FR)
_2 Rear Left (RL)
_3 Rear Right (RR)

For a 2-wheels vehicle:

Suffix Description
_0 Front (F)
_1 Rear (R)

Data fields

Most data fields are game-dependent and are not covered here. In general, values set to -1 are “invalid”. Nevertheless, we try to manage all the data in a consistent way.

Unit of Measures

All the exported data use the unit of measures as defined by the standard International System of Units. For historical reasons, the only exception is for temperature that is measured in degree Celsius.

So - for example - all the velocities are exported in “metres/second”, while in the application they are converted in more useful units (for example: for the vehicle speed, we convert m/s to kilometres/hour for the metric system and to miles/hour for the imperial system; while we continue using m/s for suspension velocities; etc).

Conversions are often trivial: e.g. to convert from m/s to km/h you must simply multiply by 3.6. There are many online resources about units conversions.

Vector data

For most vector data (like the Velocity for example), where possible we use a local coordinate reference frame (i.e. relative to the vehicle), with component X representing the “forward” (longitudinal) value, the component Y representing the “right” (lateral) value and the component Z representing the “up” (vertical) value.

For all parameters composed by multiple components (like the Velocity for example), we export only the single components. Inside the application, in addition to the single components, we show also the Euclidean norm (when this makes sense of course).

For example this is the case with the Velocity: the Velocity (V) value we show inside the application is the norm of the vector (VX, VY, VZ), but the real “telemetry data” acquired and exported are only the 3 components (i.e. the values of VX, VY and VZ - the “Velocity” scalar value is just computed by SRT and is not part of the source telemetry data). To compute the same value you can simply apply this formula (with all the P components set to 0).

manual/csv-format.txt · Last modified: 2024/01/13 16:01 by Staff