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.
.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_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 LOGor the more neutral
CAMERA IMU LOG.
- The second line
version,1.1describes the "version" of the .gcsv file format. This is equal to
- 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.
- The next few lines with
lenspresetare all optional.
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,
lensprofileis the unique name of the lens preset.
- 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.
ascaleby the raw
ax/ay/azvalues should give the acceleration in g
gscaleby the raw
gx/gy/gzvalues should give the angular rate in rad/s
- 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
mscaleleading to values in gauss (Note that
1 tesla = 10000 gauss). Similarly, if only gyroscope data is used, the
ax,ay,azcolumns 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