Gyroflow .gcsv reference
.gcsv
gyro log format
What follows is a text-based gyro log format that can easily be implemented in custom hardware/firmware called .gcsv
(short for gyro csv or Gyroflow csv).
Firstly, for a video file called videofilename.mp4
, the corresponding gyro log file is videofilename.gcsv
. This allows for automatic log detection.
The .gcsv
file contains information about the gyro orientation, scaling, and a unique identifier. For a logger supporting logging of gyro and accelerometer:
GYROFLOW IMU LOG
version,1.1
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
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
Breaking this down:
- The first line identifies the file as an IMU log. This line should either be
GYROFLOW IMU LOG
or the more neutralCAMERA IMU LOG
. - The second line
version,1.1
describes the "version" of the .gcsv file format. This is equal to1.1
for now. - 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. - The next few lines with
note
,fwversion
,timestamp
,vendor
,videofilename
,lenspreset
are all optional.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,lensprofile
is the unique name of the lens preset and brand folder. - The subsequent lines with
tscale
,ascale
andgscale
describe constants used to scale the raw sensor values.- Multiplying
tscale
by the rawt
values should give the time in seconds. It can thus be deduced that the file above is logging at 1000 Hz. - Multiplying
ascale
by the rawax/ay/az
values should give the acceleration in g - Multiplying
gscale
by the rawgx/gy/gz
values should give the angular rate in rad/s
- Multiplying
- The rest of the file simply consists of a standard CSV header and the raw values. Note that fixed-point integers are used with a scalar in order to avoid excessively large text files. Using floating points here is still valid though.
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 maximum slightly above or below this value. As always, consult the datasheet.
If a magnetometer is present, it's simply:
GYROFLOW IMU LOG
version,1.1
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
mscale
leading to values in gauss (Note that 1 tesla = 10000 gauss
). Similarly, if only gyroscope data is used, the ax,ay,az
columns can be left out.
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.
For the IMU Orientation string, the following figure corresponds to YxZ
.