OpenLayers 3 API Documentation - Class: ol.DeviceOrientation

new DeviceOrientation

Stability: experimental

The ol.DeviceOrientation class provides access to DeviceOrientation information and events, see the HTML 5 DeviceOrientation Specification for more details.

Many new computers, and especially mobile phones and tablets, provide hardware support for device orientation. Web developers targetting mobile devices will be especially interested in this class.

Device orientation data are relative to a common starting point. For mobile devices, the starting point is to lay your phone face up on a table with the top of the phone pointing north. This represents the zero state. All angles are then relative to this state. For computers, it is the same except the screen is open at 90 degrees.

Device orientation is reported as three angles - alpha, beta, and gamma - relative to the starting position along the three planar axes X, Y and Z. The X axis runs from the left edge to the right edge through the middle of the device. Similarly, the Y axis runs from the bottom to the top of the device through the middle. The Z axis runs from the back to the front through the middle. In the starting position, the X axis points to the right, the Y axis points away from you and the Z axis points straight up from the device lying flat.

The three angles representing the device orientation are relative to the three axes. alpha indicates how much the device has been rotated around the Z axis, which is commonly interpreted as the compass heading (see note below). beta indicates how much the device has been rotated around the X axis, or how much it is tilted from front to back. gamma indicates how much the device has been rotated around the Y axis, or how much it is tilted from left to right.

For most browsers, the alpha value returns the compass heading so if the device points north, it will be 0. With Safari on iOS, the 0 value of alpha is calculated from when device orientation was first requested. ol.DeviceOrientation provides the heading property which normalizes this behavior across all browsers for you.

It is important to note that the HTML 5 DeviceOrientation specification indicates that alpha, beta and gamma are in degrees while the equivalent properties in ol.DeviceOrientation are in radians for consistency with all other uses of angles throughout OpenLayers.

Parameters:

Name	Type	Argument	Description
`options`	olx.DeviceOrientationOptions	<optional>	Options.

Source:

deviceorientation.js, line 84

See:

http://dev.w3.org/geo/api/spec-source-orientation

Extends

ol.Object

Observable Properties

Name	Type	Settable	Event	Description
`alpha`	number	no	`change:alpha`	the euler angle in radians of the device from the standard X axis
`beta`	number	no	`change:beta`	the euler angle in radians of the device from the planar Z axis
`gamma`	number	no	`change:gamma`	the euler angle in radians of the device from the planar X axis
`heading`	number	no	`change:heading`	the euler angle in radians of the device from the planar Y axis
`tracking`	boolean	yes	`change:tracking`	the status of tracking changes to alpha, beta and gamma. If true, changes are tracked and reported immediately.

Methods

bindTo Stability: experimental

The bindTo method allows you to set up a two-way binding between a source and target object. The method returns an ol.ObjectAccessor with a transform method that lets you transform values on the way from the source to the target and on the way back.

For example, if you had two map views (sourceView and targetView) and you wanted the target view to have double the resolution of the source view, you could transform the resolution on the way to and from the target with the following:

sourceView.bindTo('resolution', targetView)
  .transform(
    function(sourceResolution) {
      // from sourceView.resolution to targetView.resolution
      return 2 * sourceResolution;
    },
    function(targetResolution) {
      // from targetView.resolution to sourceView.resolution
      return targetResolution / 2;
    }
  );

Parameters:

Name	Type	Argument	Description
`key`	string		Key name.
`target`	ol.Object		Target.
`targetKey`	string	<optional>	Target key.

Inherited From:

ol.Object#bindTo

Source:

object.js, line 232

Returns:

Type: ol.ObjectAccessor

dispatchChangeEvent Stability: experimental

Inherited From:

ol.Observable#dispatchChangeEvent

Source:

observable.js, line 35

get Stability: experimental

Gets a value.

Parameters:

Name	Type	Description
`key`	string	Key name.

Inherited From:

ol.Object#get

Source:

object.js, line 289

Returns:

Value.

Type: *

getAlpha Stability: experimental

Source:

deviceorientation.js, line 151

Returns:

The alpha value of the DeviceOrientation, in radians.

Type: number | undefined

getBeta Stability: experimental

Source:

deviceorientation.js, line 166

Returns:

The beta value of the DeviceOrientation, in radians.

Type: number | undefined

getGamma Stability: experimental

Source:

deviceorientation.js, line 181

Returns:

The gamma value of the DeviceOrientation, in radians.

Type: number | undefined

getHeading Stability: experimental

Source:

deviceorientation.js, line 196

Returns:

The heading of the device relative to north, in radians, normalizing for different browser behavior.

Type: number | undefined

getProperties Stability: experimental

Get an object of all property names and values.

Inherited From:

ol.Object#getProperties

Source:

object.js, line 348

Returns:

Object.

Type: Object.<string, *>

getTracking Stability: experimental

Are we tracking the device's orientation?

Source:

deviceorientation.js, line 211

Returns:

The current tracking state, true if tracking is on.

Type: boolean

notify Stability: experimental

Notify all observers of a change on this property. This notifies both objects that are bound to the object's property as well as the object that it is bound to.

Parameters:

Name	Type	Description
`key`	string	Key name.

Inherited From:

ol.Object#notify

Source:

object.js, line 368

on Stability: experimental

Listen for a certain type of event.

Parameters:

Name	Type	Argument	Description
`type`	string \| Array.<string>		The event type or array of event types.
`listener`	function		The listener function.
`this`	Object	<optional>	The object to use as `this` in `listener`.

Inherited From:

ol.Observable#on

Source:

observable.js, line 58

Returns:

Unique key for the listener.

Type: goog.events.Key

once Stability: experimental

Listen once for a certain type of event.

Parameters:

Name	Type	Argument	Description
`type`	string \| Array.<string>		The event type or array of event types.
`listener`	function		The listener function.
`this`	Object	<optional>	The object to use as `this` in `listener`.

Inherited From:

ol.Observable#once

Source:

observable.js, line 71

Returns:

Unique key for the listener.

Type: goog.events.Key

set Stability: experimental

Sets a value.

Parameters:

Name	Type	Description
`key`	string	Key name.
`value`	*	Value.

Inherited From:

ol.Object#set

Source:

object.js, line 399

setTracking Stability: experimental

Enable or disable tracking of DeviceOrientation events.

Parameters:

Name	Type	Description
`tracking`	boolean	True to enable and false to disable tracking.

Source:

deviceorientation.js, line 243

setValues Stability: experimental

Sets a collection of key-value pairs.

Parameters:

Name	Type	Description
`values`	Object.<string, *>	Values.

Inherited From:

ol.Object#setValues

Source:

object.js, line 428

un Stability: experimental

Unlisten for a certain type of event.

Parameters:

Name	Type	Argument	Description
`type`	string \| Array.<string>		The event type or array of event types.
`listener`	function		The listener function.
`this`	Object	<optional>	The object to use as `this` in `listener`.