Skip to content

Latest commit

 

History

History
67 lines (38 loc) · 6.49 KB

COORDINATES.md

File metadata and controls

67 lines (38 loc) · 6.49 KB
Raw

One-Page Coordinates Reference

This page is a comprehensive documentation of the coordinate systems used by Sensor Logger. Should you notice any error, please report by making an Issue or making a pull request directly. Additional information about sensors and measurements is available in-app by tapping the "eye" icon next to each sensor.

For information about units, refer to https://github.com/tszheichoi/awesome-sensor-logger/blob/main/UNITS.md

Acceleration on Phones

Acceleration is reported in the following coordinate system, with x and y being the horizontal and vertical axes of the screen and z pointing into/out of the screen. These axes "stick" to the device, so they never change even when the phone rotates.

Differences Between iOS and Android

This is what the coordinate frames look like by operating systems.

Screenshot 2024-02-24 at 00 57 04

IMPORTANT: These diagrams show the direction of the applied force. This is different to the diagrams on Apple's official documentation, which shows the inertial force (exact opposite). https://developer.apple.com/documentation/coremotion/cmheadphonemotionmanager.

While the directions of the axes are the same across platforms, there is a negative sign difference for all three axes between iOS and Android. For example, if you move your phone to the right, along the x axis, you will register positive values on Android, but negative values on iOS. This is simply a difference in definition -- likely because iOS' convention is in the context of inertial force, whereas Android's convention is in the context of accelerating force.

Accordingly, the Gravity sensor is also different by a negative sign between iOS and Android. When you place your phone flat on a table, the gravity vector points in -z on iOS and +z on Android.

💡: New in Version 1.29: Toggling Standardise Units & Frames under Settings > Sensor Configuration will eliminate this difference by automatically converting values logged on iOS to the Android convention. See this for more information.

Acceleration on Apple Watch & AirPods

Acceleration data from the Apple Watch follows the same convention as the iPhone. The acceleration values from the Headphone motion sensor follow the following convention.

Source: https://developer.apple.com/documentation/coremotion/cmheadphonemotionmanager

This photo below roughly aligns the coordinates for all three Apple devices. The coordinate system across the three pictured devices is always the same and consistent. As such, it is safe to compare and perform data fusion amongst measurements from these devices. However, they collectively are inconsistent with Android's coordinate system, as noted in the previous section. Toggling "Standardise Units & Frames" under Settings > Sensor Configuration will convert all measurements from Apple Watch and AirPods to Android's convention. Also note that the units of acceleration vary across iPhone, Apple Watch and AirPods if "Standardise Units & Frames" is not toggled on.

Screenshot 2024-03-07 at 00 39 40

This plot compares the units and coordinate system of acceleration data from all three Apple devices with "Standardise Units & Frames" toggled on (Note: "Standardise Units & Frames" is off by default).

Screenshot 2024-03-07 at 00 34 38

Gyroscope

The rotation rates and orientation are measured around the same axes as acceleration. When you read off the Gyroscope sensor in Sensor Logger, refer to the diagram below.

Source: https://developer.apple.com/documentation/coremotion/getting_raw_gyroscope_events

For the rotation rate readings from the Gyroscope sensor, iOS and Android have consistent definitions.

Orientation

The orientation is derived from the rotation rate and references the same axes. To be specific:

  • roll refers to the rotation around y;
  • pitch refers to the rotation around x;
  • yaw refers to the rotation around z. Sometimes also called the azimuth.

Additionally, orientation has an arbitrary offset, as it is an integrated value from the rotation rate (i.e. an integration constant). For this, Sensor Logger uses the x-north-z-vertical reference frame, meaning the yaw value is 0 when the x axis is aligned with the north (i.e. the angle between the device's y axis and the north).

Differences Between iOS and Android

Due to legacy reasons and backwards compatibility reasons, there are some key differences in interpreting the yaw value:

  1. On iOS, north means the true north, whereas on Android, it refers to the magnetic north. You may have to account for this difference if you are comparing absolute values measured across platforms, though factors such as the accuracy of the magnetometer may outweigh such differences.
  2. On iOS, yaw increases when you turn counterclockwise around the z axis (as pictured above). On Android, yaw increases when you turn clockwise around the z axis (opposite to pictured above, i.e. east is +π/2 and west is -π/2).
  3. On iOS, pitch decreases as you rotate around the x axis clockwise. On Android, pitch decreases as you rotate around the x axis counterclockwise (i.e. tiling the phone's top edge towards you and the phone's bottom edge away from you when you hold your phone normally)

Further, on Android, there are additional Orientations you can log with various trade-offs. See https://github.com/tszheichoi/awesome-sensor-logger/blob/main/ORIENTATION.md.

💡: New in Version 1.29: Toggling Standardise Units & Frames under Settings > Sensor Configuration will eliminate 1 and 2 by automatically converting values logged on iOS to the Android convention. See this for more information.