====== CSV format ======

Sim Racing Telemetry can export recorded telemetry data in a [[https://en.wikipedia.org/wiki/Comma-separated_values|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 [[https://en.wikipedia.org/wiki/Tab_key#Tab_characters|tab character]], formally a [[https://en.wikipedia.org/wiki/Tab-separated_values|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:

{{ :manual:srt-csv-import.png |}}

===== 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 [[https://en.wikipedia.org/wiki/International_System_of_Units|International System of Units]]. For historical reasons, the only exception is for //temperature// that is measured in [[https://en.wikipedia.org/wiki/Celsius|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 [[https://www.google.com/search?q=Unit+converter|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 [[https://en.wikipedia.org/wiki/Euclidean_distance|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 //(V<sub>X</sub>, V<sub>Y</sub>, V<sub>Z</sub>)//, but the real "telemetry data" acquired and exported are only the 3 components (i.e. the values of //V<sub>X</sub>//, //V<sub>Y</sub>// and //V<sub>Z</sub>// - 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 [[https://wikimedia.org/api/rest_v1/media/math/render/svg/401c719f8d6cbf845edb7c360deff6b7deb2b8da|this formula]] (with all the //P// components set to 0).