Data class used to represent a device orientation and returned by FusedOrientationProviderClient
to registered DeviceOrientationListeners.
Nested Class Summary
| class | DeviceOrientation.Builder | A builder for DeviceOrientation. |
|
Inherited Constant Summary
Field Summary
| public static final Creator<DeviceOrientation> | CREATOR |
Public Method Summary
| boolean | |
| float[] |
getAttitude()
Returns a float array of length 4 containing the device's estimated attitude.
|
| float |
getConservativeHeadingErrorDegrees()
A conservative estimate of the heading error in degrees, between [0, 180].
|
| long |
getElapsedRealtimeNs()
Return the time (in nanoseconds) when this device orientation is estimated, in
elapsed real-time since system boot.
|
| float |
getHeadingDegrees()
The estimated heading of the device in degrees between [0, 360).
|
| float |
getHeadingErrorDegrees()
The estimated error in the reported heading of the device, in degrees between
[0, 180].
|
| boolean |
hasConservativeHeadingErrorDegrees()
Returns whether the estimated conservative heading error value (in degrees) is
known.
|
| int |
hashCode()
|
| String |
toString()
|
| void |
writeToParcel(Parcel parcel, int
flags)
|
Inherited Method Summary
Fields
public static final Creator<DeviceOrientation> CREATOR
Public Methods
public boolean equals (Object object)
public float[] getAttitude ()
Returns a float array of length 4 containing the device's estimated attitude.
The device's attitude is represented as a quaternion with the scalar last: [qx, qy, qz, qw]. The reported quaternion represents the 3D orientation of the device relative to the east-north-up coordinate frame (aka world frame). The east-north-up coordinate system is defined as a direct orthonormal basis where:
- X points east and is tangential to the ground.
- Y points north and is tangential to the ground. When magnetic declination is available Y points to true north, otherwise to magnetic north.
- Z points in the opposite direction as gravity and is perpendicular to the ground.
The reported quaternion follows Hamilton's conventions for multiplication and composition, but with the passive interpretation [1], that is:
- The quaternion changes the coordinates of a vector from the device frame to the east-north-up frame.
- The quaternion follows right-to-left composition: if q_1 transforms B1 to B2, and q_2 transforms B2 to B3, then the quaternion that transforms B1 to B3 is q_2 * q_1, where * is quaternion multiplication.
SensorManager.getRotationMatrixFromVector(float[], float[]) can be used to
convert the reported quaternion into a rotation matrix:
float[] rotationMatrix = new float[9];
SensorManager.getRotationMatrixFromVector(rotationMatrix, deviceOrientation.getAttitude());
[1] Zanetti, Renato. "Rotations, transformations, left quaternions, right quaternions?." The Journal of the Astronautical Sciences 66.3 (2019): 361-381.
public float getConservativeHeadingErrorDegrees ()
A conservative estimate of the heading error in degrees, between [0, 180].
The reported error represents half the error cone. For example a value of 10.0 corresponds to the true heading lying between -10.0 degrees and 10.0 degrees around the heading output. This method returns 180 in the case that the estimated heading error is invalid. The error cone corresponds to two sigma error for small angles, which is approximately the 95th percentile two-sided confidence interval.
The error model is similar to
getHeadingErrorDegrees() but this model waits for a sufficient amount of
rotation to occur in a uniform magnetic field before determining the heading error.
Until then it will report 180 degrees. This method is rarely overconfident with respect
to the true heading error at the expense of increased latency in reporting the heading
error.
Only available when
hasConservativeHeadingErrorDegrees() is true.
public long getElapsedRealtimeNs ()
Return the time (in nanoseconds) when this device orientation is estimated, in elapsed real-time since system boot.
public float getHeadingDegrees ()
The estimated heading of the device in degrees between [0, 360).
The heading of the device is defined as the direction where the top of the device is pointing, assuming that the user is looking at the phone's screen and the phone is in hand. The heading is estimated clockwise from the true north when magnetic declination is available, and clockwise from the magnetic north otherwise. Therefore, when the device is pointing towards the north, the reported heading is ideally 0 degrees, towards east is 90 degrees, south is 180 degrees and west is 270 degrees. Note that the heading may deviate from its ideal value because of local magnetic disturbances or an uncalibrated magnetometer sensor.
The top of the device points to the direction of a particular phone axes, based on
the rotation of the phone's screen. For example, if the rotation of the phone's screen
is Surface.ROTATION_0
because the user is holding their phone in portrait mode, the top of the device is its
Y axis. Similarly if the rotation of the phone's screen is Surface.ROTATION_90
because the phone is in landscape mode, the top of the device is its -X axis.
public float getHeadingErrorDegrees ()
The estimated error in the reported heading of the device, in degrees between [0, 180].
The reported error represents half the error cone. For example a value of 10.0 corresponds to a true heading between -10.0 degrees and 10.0 degrees around the heading output. This method returns 180 in the case that the estimated heading error is invalid. The error cone corresponds to two sigma error for small angles, which is approximately the 95th percentile two-sided confidence interval. For large angles, the concept of a 95th percentile confidence begins to break down, ultimately becoming meaningless when there is no knowledge of the heading. Thus, when 180 degrees is reported it is no longer the 95th percentile confidence interval but instead a declaration of complete ignorance of the true heading.
public boolean hasConservativeHeadingErrorDegrees ()
Returns whether the estimated conservative heading error value (in degrees) is known.