Gyroflow .gcsv reference
.gcsv gyro log format
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 sidecar files. This allows for automatic log detection.
.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:
GYROFLOW IMU LOG version,1.3 id,custom_logger_name orientation,YxZ note,development_test fwversion,FIRMWARE_0.1.0 timestamp,1644159993 vendor,potatocam videofilename,videofilename.mp4 lensprofile,potatocam/potatocam_mark1_prime_7_5mm_4k lens_info,wide frame_readout_time,15.23 frame_readout_direction,0 tscale,0.001 gscale,0.00122173047 ascale,0.00048828125 t,gx,gy,gz,ax,ay,az 0,39,86,183,-1137,-15689,-2986 1,56,100,202,-1179,-15694,-2887 2,63,108,218,-1247,-15702,-2794 3,71,108,243,-1308,-15675,-2727 4,83,101,268,-1420,-15662,-2661 5,101,93,294,-1575,-15661,-2629 6,121,95,319,-1677,-15654,-2639 7,143,97,348,-1709,-15673,-2654 8,163,98,362,-1704,-15691,-2685 9,173,93,371,-1678,-15698,-2736 10,181,98,375,-1623,-15697,-2810 11,173,105,365,-1578,-15693,-2929 12,159,111,363,-1555,-15711,-3057 13,157,113,348,-1540,-15747,-3159 14,157,118,327,-1542,-15780,-3246 15,153,123,310,-1595,-15812,-3319 ...
GYROFLOW IMU LOG version,1.3 id,custom_logger_name orientation,YxZ note,development_test fwversion,FIRMWARE_0.1.0 timestamp,1644159993 vendor,potatocam videofilename,videofilename.mp4 lensprofile,potatocam_mark1_prime_7_5mm_4k tscale,0.001 gscale,0.00122173047 ascale,0.00048828125 mscale,0.00059875488 t,gx,gy,gz,ax,ay,az,mx,my,mz 0,39,86,183,-1137,-15689,-2986,123,345,546 1,56,100,202,-1179,-15694,-2887,124,344,560 ...
- The very first line identifies the file as an IMU log. This line should either be
GYROFLOW IMU LOGor the more neutral
CAMERA IMU LOG.
- The second line
version,1.3describes the "version" of the .gcsv file format. This is equal to
1.3for 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
- The fourth line contains the orientation string. This corresponds to the
IMU Orientationfield 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
gscaledescribe constants used to scale the raw sensor values.
tscaleby the raw
tvalues 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.
gscaleby the raw
gx/gy/gzvalues should give the angular rate in rad/s
- (If accelerometer data present) Multiplying
ascaleby the raw
ax/ay/azvalues should give the acceleration in g
- (If magnetometer data present) Multiplying
mx/my/mzgives 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,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.
Noteis for other misc. information.
fwversionis the firmware of the logger/camera.
timestampis the unix timestamp when logging began.
vendorcan contain the vendor or developer
videofilenameis the name of the corresponding video file. Normally the
.gcsvfile name already matches, but this insures the information is kept if the filename changes.
lensprofileis the unique name of the lens preset and vendor folder. If it matches a lens profile in the database it is automatically selected during loading.
lens_infois additional information about the lens/field of view not available in the metadata. This could be
narrowfor different FOV settings,
linearfor lens distortion correction. Most relevant for action cameras with different crop settings.
frame_readout_timeis the time in milliseconds it takes to capture a full video frame using rolling shutter. This is used for rolling shutter correction.
frame_readout_directionis 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 samling frequency. Even more filtering is usually recommended, e.g. setting the builtin 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
- 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