GCSV Format
.gcsv gyro log format
Last updated
.gcsv gyro log format
Last updated
What follows is a text-based gyro log format that can be implemented in custom hardware/firmware called .gcsv (short for gyro csv or Gyroflow csv). As a text-based format this is meant to be easily implementable and inspectable (compatible with standard CSV reading software) at the cost of space efficiency.
Firstly, for a video file called videofilename.mp4, the corresponding gyro log file is videofilename.gcsv, this is a case of the .gcsv acting as . This allows for automatic log detection.
The .gcsv file contains information about the gyro orientation, scaling, and a unique identifier. The following is an example of a .gcsv file from a logger supporting logging of gyro and accelerometer:
If a magnetometer is present, some additional fields are present, e.g.:
The very first line identifies the file as an IMU log. This line should either be GYROFLOW IMU LOG or the more neutral CAMERA IMU LOG.
The second line version,1.3 describes the "version" of the .gcsv file format. This is equal to 1.3 for now. The versions are backwards compatible, but changes with the addition of new metadata fields.
The third line contains a unique ID associated with the logger/camera. For instance a high-end camera with internal logging may use id,potatocam_deluxe_4k_grey_edition.
The fourth line contains the orientation string. This corresponds to the IMU Orientation field in Gyroflow (see the implementation notes below for further details).
The next few lines contain optional metadata. These are not strictly required, but may improve workflow and stabilization. Developers are thus encouraged to include all known fields.
The subsequent lines with tscale, ascale and gscale describe constants used to scale the raw sensor values.
Multiplying tscale by the raw t values should give the time in seconds. It can thus be deduced that the file above is logging at 1000 Hz since each line increments by 1*0.001=0.001 s, corresponding to a frequency of 1 KHz. The resolution of the timestamps should be 1 ms or better.
Multiplying gscale by the raw gx/gy/gz values should give the angular rate in rad/s
(If accelerometer data present) Multiplying ascale by the raw ax/ay/az values should give the acceleration in g
(If magnetometer data present) Multiplying mscale by mx/my/mz gives the measurements in gauss (Note that 1 tesla = 10000 gauss).
The rest of the file simply consists of a standard CSV header and the raw values. The header and data order should be one of the following: t,gx,gy,gz, t,gx,gy,gz,ax,ay,az, or t,gx,gy,gz,ax,ay,az,mx,my,mz. Gyroscope data is the minimum requirement. Acceleration data is required for horizon lock, while magnetometer data improves drift in orientation determination (Not currently of significant importance).
For the data itself, fixed-point integers are recommended with a scalar (point 6) in order to avoid excessively large text files. Using floating points here is still valid though.
The following are all optional fields for the metadata block, but developers should include as many known fields as possible.
note is for other misc. information.
fwversion is the firmware of the logger/camera.
timestamp is the UNIX timestamp when logging began.
vendor can contain the vendor or developer
videofilename is the name of the corresponding video file. Normally the .gcsv file name already matches, but this insures the information is kept if the filename changes.
lens_info is additional information about the lens/field of view not available in the metadata. This could be wide, normal, narrow for different FOV settings, linear for lens distortion correction. Most relevant for action cameras with different crop settings.
frame_readout_time is the time in milliseconds it takes to capture a full video frame using rolling shutter. This is used for rolling shutter correction.
frame_readout_direction is the direction of the readout. Most cameras with rolling shutter capture the top of the frame first. Note that Gyroflow currently only supports correcting 0 and 1.
0: Top to bottom
1: Bottom to top
2: Left to right
3: Right to left
The required parts of the header of the .gcsv file remains static for a given camera/setup, and can thus be written as a constant string to the file.
Raw sensor values are often represented as 16-bit signed integers, meaning a range between of +/- 2^15. If the acceleration range is known to be +/- 4 g as was the case in the example above. Then ascale = 4/2^15 = 0.00012207031. Refer to the datasheet for conversion information. Similarly, a gyroscope with a range of +/- 1000 deg/s gives gscale = (1000 * pi / 180)/2^15 = 0.00053263221. Note that even when configured to a setting such as +/- 1000 deg/s, the actual calibration of the sensor may lead to a maximum slightly above or below this value. As always, consult the datasheet.
For a logger/camera implementation, some other things to think about:
For a camera, the timestamps should be based on the same time source as the video capture. This prevents drift between the two.
Consider using microseconds for the timestamp if a faster sampling rate if the time source allows. This may improve the timing during the sync process.
Consider using the data ready interrupts of IMU's instead of polling for more consistent timings.
Ensure proper filtering of the data to meet the Nyquist criteria for the sampling frequency. Even more filtering is usually recommended, e.g. setting the built-in hardware low pass filter cutoff at 50 Hz to 100 Hz is a good starting point, even for higher sampling frequencies.
For the IMU Orientation string, the following figure corresponds to YxZ.
For the gyroscope, data for an axis correspond to the right-handed rotation rate of the camera body about that axis.
The accelerometer data correspond to linear acceleration applied in the given direction. Due to the nature of gravity, a stationary object will experience an upwards acceleration of 9.81 m/s2, while an object in freefall will experience zero acceleration.
The magnetometer data corresponds to the measured magnetic field vector.
In order for orientation determination to work correctly, the data must have the same/aligned coordinate axes. For combined IMU sensors, this is already the case for the raw data. If a rotation is applied to the gyro data before being written, the same rotation should be applied to the accelerometer (and magnetometer). This ensures that the axes stay aligned.
If the gyroscope and accelerometer data come from separate sensors, their axes must similarly be aligned, either physically or by applying a rotation in software.
1.0: Initial version
1.1: Add lens profile field
1.2: Add rolling shutter information
1.3: Add lens_info field
lensprofile is the unique name of the lens preset and vendor folder. If it matches a lens profile in the it is automatically selected during loading.
