Time for action – a sense of direction

In this example, we'll display an icon at the user's location, use values from the DeviceOrientation API to create a simple compass, and by rotating it, show which way is north. Perform the following steps to achieve what's been set out in this paragraph:

Open the previous example in your text editor, and change the icon we are using from a flag to an arrow. We'll use an arrow pointing up for north. Here's the code to accomplish this:
```
<div id="location" class="marker icon-arrow-up"></div>
```

Now, add the following code at the end of the script tag, right after our Geolocation code:

var deviceOrientation = new ol.DeviceOrientation({
  tracking: true
});
deviceOrientation.on('change:heading', onChangeHeading);
function onChangeHeading(event) {
  var heading = event.target.getHeading();
  var el = document.getElementById('location');
  el.style['-webkit-transform'] = 'rotate('+heading+'rad)';
  el.style['transform'] = 'rotate('+heading+'rad)';
});

Reload the page in your mobile device's web browser and try turning. The arrow should rotate as you do, showing the direction you are pointing relative to the map.

What just happened?

Let's walk through the code and see what it does. First, we create a new instance of OpenLayers' helper class ol.DeviceOrientation and indicate we would like to receive orientation updates, as follows.

var deviceOrientation = new ol.DeviceOrientation({
  tracking: true
});

Next, we register a function to receive updates to the heading property, and it will be passed an event object that has the information we need, as follows.

deviceOrientation.on('change:heading', onChangeHeading);

The function that receives the orientation update event does several things. First, we get the value of the heading property (in radians) from the event target.

var heading = event.target.getHeading();

Note

We mentioned before that the value of alpha is used to figure out the compass heading. Not all devices support reporting of the device orientation in the same way. In particular, WebKit on iOS reports an alpha value that is computed from where the device is pointing when tracking is turned on instead of from north. OpenLayers provides a special property, heading, which reports the true angle from north and standardizes this across different devices behind the scenes.

Next, we obtain a reference to the HTML element that contains our arrow. We gave it an ID to make this easier, as follows.

var el = document.getElementById('location');

Finally, we use CSS to rotate the arrow relative to north so that it's pointing in the direction our phone is pointing. The CSS3 transform property can apply a number of transformation functions to an element (see https://developer.mozilla.org/en-US/docs/Web/CSS/transform); in this case, we've selected the rotate function. We set the angle we want to rotate and specify that the value is in radians, since that is the unit that OpenLayers reports angles in. The following is the code to accomplish this:

el.style['-webkit-transform'] = 'rotate('+heading+'rad)';
el.style['transform'] = 'rotate('+heading+'rad)';

We set this property twice to accommodate Safari and Chrome, which still only support the vendor-specific prefixed version of the property name.

Here is the complete API for the DeviceOrientation class.

DeviceOrientation constructor options

When creating an instance of ol.DeviceOrientation, there is only one option currently available, which is as follows:

Option	Type	Description
`tracking`	`Boolean`	When tracking is turned on (`true`), the `DeviceOrientation` API reports changes in orientation automatically. The default value is `false`.

DeviceOrientation KVO property methods

The DeviceOrientation class inherits from ol.Object and has the following KVO properties.

Name	Type	Description
`alpha`	`number`	This is a read-only property. It is the value of `alpha` in radians. This might not be relative to north depending on the device.
`beta`	`number`	This is a read-only property. It is the value of `beta` in radians.
`gamma`	`number`	This is a read-only property. It is the value of `gamma` in radians.
`heading`	`number`	This is a read-only property. It is the heading of the device in radians clockwise from north, normalized for browser differences.
`tracking`	`Boolean`	This is a Boolean value indicating whether tracking is enabled or not.

Previous Chapter

The DeviceOrientation class

Next Chapter

Debugging mobile web applications

Table of Contents for OpenLayers 3 : Beginner's Guide

Time for action – a sense of direction

What just happened?

Note

DeviceOrientation constructor options

DeviceOrientation KVO property methods

Table of Contents for
OpenLayers 3 : Beginner's Guide