The most typical use case for the heading and bearing is showing an angle the user is walking to. There are two sources for the angle:
1. Bearing from the location estimate.
2. Heading from the Orientation listener.
| The main difference: bearing compensates switching from portrait to landscape when the user is on the move, while heading doesn't. |
Bearing
Bearing indicates direction of walking and hence doesn't react much to turns of the device while the user keeps walking straight. Bearing is accurate when walking.
On Android, bearing is accessible from IALocation.getBearing().
On iOS API is CoreLocation compatible and the bearing calculated by IndoorAtlas is called course. It's available as standard CLLocation class.
Heading
Heading reacts quickly to any movement of the device. Thus, when the user stands still and rotates the phone, heading follows the device's rotations on xy-plane in real time.
In more technical terms, heading indicates the direction the phone's y-axis* points towards. The phone's y-axis points forward when holding the phone in portrait mode, screen towards the ceiling.
The heading angle definition is : 0 for north, 90 is east, and so on.
To access heading, use the Orientation API. Here's a complete example for Android.
*Note that when in landscape mode, the y-axis points to the right or left.
The screenshot below shows heading in red and bearing in blue, just after stopping walking and turning the device 90 deg counterclockwise. Heading follows in real time.
3D Orientation API
The full orientation of the device in ENU coordinates is given by the orientation quaternion. The given quaternion can be used to project from phone sensor coordinates to local ENU (east, north, up) coordinates.
The heading and orientation provided by IndoorAtlas takes into account the local variations in the magnetic field and can be more precise and stable than what is provided by Android and iOS platforms currently.
The 3D orientation API can be utilized e.g. in Virtual Reality (VR) applications. See example in Android SDK Examples or iOS SDK Examples repository.
Note that IndoorAtlas has a separate Augmented Reality (AR) API.