Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify units and g-force for accelerometer #701

Merged
merged 2 commits into from
Aug 6, 2024
Merged

Clarify units and g-force for accelerometer #701

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
61c5474
Clarify units of g-force for accelerometer
rennis250 Aug 6, 2024
c40a22f
Don’t confuse a unit of g with total g-force
rennis250 Aug 6, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion neon/data-collection/data-format/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Recording Format
The page describes the data format when downloading Neon recordings from Pupil Cloud in the "Timeseries Data" and "Timeseries Data + Scene Video" formats. In this format the Data from the Neon Companion is augmented by adding gaze and eye state estimates whenever they had not been computed in realtime. Futhermore fixations and blink data as well as some IMU transformations are computed.

Check warning on line 2 in neon/data-collection/data-format/index.md

View workflow job for this annotation

GitHub Actions / ✍️ Check spelling 

Unknown word (Timeseries)

Check warning on line 2 in neon/data-collection/data-format/index.md

View workflow job for this annotation

GitHub Actions / ✍️ Check spelling 

Unknown word (Timeseries)

When downloading Native Recording Data from cloud or direclty [extracting it via usb from the companion device](/data-collection/transfer-recordings-via-usb/), use the [pl-neon-recording](https://github.com/pupil-labs/pl-neon-recording) python library to read and access the data. This data format will contain all video data as well as all data that had been computed in realtime on the companion device.

Check warning on line 4 in neon/data-collection/data-format/index.md

View workflow job for this annotation

GitHub Actions / ✍️ Check spelling 

Unknown word (direclty)


## Recording Folders
Expand All @@ -19,7 +19,7 @@
| **android_device_model** | Model name of the Companion device. |
| **android_device_name** | Device name of the Companion device. |
| **app_version** | Version of the Neon Companion app used to make the recording. |
| **calib_version** | Version of the offset correction used by the Neon Companion app. |

Check warning on line 22 in neon/data-collection/data-format/index.md

View workflow job for this annotation

GitHub Actions / ✍️ Check spelling 

Unknown word (calib)
| **data_format_version** | Version of the data format used by the Neon Companion app. |
| **duration** | Duration of the recording in nanoseconds|
| **firmware_version** | Version numbers of the firmware and FPGA. |
Expand Down Expand Up @@ -47,7 +47,7 @@
| Field | Description |
| -------- | -------- |
| **camera_matrix** | The camera matrix of the scene camera. |
| **dist_coefs** | The distortion coefficients of the scene camera. The order of the values is `(k1, k2, p1, p2, k3, k4, k5, k6)` following [OpenCV's distortion model](https://docs.opencv.org/4.x/d9/d0c/group__calib3d.html#ga3207604e4b1a1758aa66acb6ed5aa65d). |

Check warning on line 50 in neon/data-collection/data-format/index.md

View workflow job for this annotation

GitHub Actions / ✍️ Check spelling 

Unknown word (coefs)
| **serial_number** | Serial number of Neon module used for the recording. This number is encoded in the QR code on the back of the Neon module. |
| **version** | The version of the intrinsics data format. |

Expand Down Expand Up @@ -110,16 +110,16 @@
| **azimuth [deg]** | The [azimuth](https://en.wikipedia.org/wiki/Horizontal_coordinate_system) of the gaze ray corresponding to the fixation location in relation to the scene camera in degrees. |
| **elevation [deg]** | The [elevation](https://en.wikipedia.org/wiki/Horizontal_coordinate_system) of the gaze ray corresponding to the fixation location in relation to the scene camera in degrees. |

## saccades.csv

Check warning on line 113 in neon/data-collection/data-format/index.md

View workflow job for this annotation

GitHub Actions / ✍️ Check spelling 

Unknown word (saccades)
This file contains [saccades](/data-collection/data-streams/#fixations-saccades) detected by the fixation detector.

Check warning on line 114 in neon/data-collection/data-format/index.md

View workflow job for this annotation

GitHub Actions / ✍️ Check spelling 

Unknown word (saccades)


| Field | Description |
| -------- | -------- |
| **section id** | Unique identifier of the corresponding section. |
| **recording id** | Unique identifier of the recording this sample belongs to. |
| **saccade id** | Identifier of the saccade. The counter starts at the beginning of the recording. |

Check warning on line 121 in neon/data-collection/data-format/index.md

View workflow job for this annotation

GitHub Actions / ✍️ Check spelling 

Unknown word (saccade)

Check warning on line 121 in neon/data-collection/data-format/index.md

View workflow job for this annotation

GitHub Actions / ✍️ Check spelling 

Unknown word (saccade)
| **start timestamp [ns]** | UTC timestamp in nanoseconds of the start of the saccade. |

Check warning on line 122 in neon/data-collection/data-format/index.md

View workflow job for this annotation

GitHub Actions / ✍️ Check spelling 

Unknown word (saccade)
| **end timestamp [ns]** | UTC timestamp in nanoseconds of the end of the saccade. |
| **duration [ms]** | Duration of the saccade in milliseconds. |
| **amplitude [px]** | Float value representing the amplitude of the saccade in world camera pixel coordinates. |
Expand Down Expand Up @@ -165,7 +165,7 @@
| **recording id** | Unique identifier of the recording this sample belongs to. |
| **timestamp [ns]** | UTC timestamp in nanoseconds of the sample. |
| **gyro x [deg/s]**<br />**gyro y [deg/s]**<br />**gyro z [deg/s]** | Rotation speed around x, y or z-axis respectively in degrees/s. |
| **acceleration&nbsp;x&nbsp;[G]**<br />**acceleration&nbsp;y&nbsp;[G]**<br />**acceleration z [G]** | Translational acceleration along the x, y or z-axis respectively in G. Note `1 G = 9.80665 m/s^2`.|
| **acceleration&nbsp;x&nbsp;[g]**<br />**acceleration&nbsp;y&nbsp;[g]**<br />**acceleration z [g]** | Translational acceleration along the x, y or z-axis respectively in units of [g-force](https://en.m.wikipedia.org/wiki/G-force). Note `1 g-force = 9.80665 m/s^2`.|
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Technically, g-force is the name of the force and g is the name of the unit, isn't it? Using g-force as the unit in the text seems inaccurate.

If we want to mention g-force explicitly we could maybe say "Translational acceleration/g-force along..."? Or we just keep the link as is but change g-force to g.

Copy link
Contributor Author

@rennis250 rennis250 Aug 6, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

'g-force' is a confusing name, I find. It is force per unit mass, so it works out to a unit of acceleration. Some texts clarify that it should not be considered a force.

The unit of 'g-force' is written as 'g', but that is also easily confused with the 'g' of free-fall acceleration, which points downwards (provided you use a standard reference frame), whereas, when you stand on Earth, 'g-force' points upwards. 'G-force' is technically derived from 'g', so the absolute magnitude is the same, hence 'g' as the unit, but the direction is different.

True, you cannot really say "units of g-force", but rather, "total g-force that an object experiences". It is "the number of g units of acceleration," such as "that object experienced a g-force of 5.3g". I was trying to be compact and not add too much text. I will think of something better, as I feel it is useful for users that just read this part quickly and don't go through the link. For example, when you lay Neon down and upright on a table, you get +g for acceleration Z, and when turn Neon on its right side, you get -g for X acceleration. Both of which are confusing if you assume the 'g' of free-fall acceleration.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about:

Translational acceleration (in terms of g-force) along the x, y or z-axis respectively. Note 1 g = 9.80665 m/s^2.

Or maybe "acceleration (measured as g-force)"?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Either version seems fine to me! 👍

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@marc-tonsen Ok, done. Thanks for catching that!

| **roll [deg]** | Drift-free estimate of the roll (head tilt from side to side) in degrees. The output range is -180 to +180 degrees. Added in version 2 of this enrichment. |
| **pitch [deg]** | Drift-free estimate of the pitch (head tilt from front to back) in degrees. The output range is -90 to +90 degrees. Added in version 2 of this enrichment. |
| **yaw [deg]** | Drift-free estimate of the yaw (horizontal head rotation) in degrees. The output range is -180 to +180 degrees. Added in version 2 of this enrichment. |
Expand Down
Loading