Orientation

This API provides the user with updates describing the attitude (angular orientation) of a mobile device.

The reported orientation provides a quaternion representation of the device orientation, a representation using Tait-Bryan (Euler) angles in degrees, as well as some information about the compass heading when available. See the Coordinate Frame page to learn how the Orientation is related to the various coordinate frames for reporting sensor data.

When motion events are not available on the device, Orientation events are polyfilled with pan touch events.

Example

var orientation = new MotionStack.Orientation();

orientation.start(function (e) {
  console.log(e.yaw, e.pitch, e.roll);
});

Constructor

new MotionStack.Orientation([options])

Create a new Orientation instance object.

Argument Type Description
options Object Options to pass in for the new Orientation instance (optional)

  • absolute {Boolean}
  • Whether the angular orientation of the device should respect magnetic north. Refer to the Coordinate Frames page for more detailed information about orientation and coordinate frames. Note that absolute device orientation is estimated using the magnetometer, which often becomes uncalibrated and may detract from the overall quality of the reported value.


    Default: false

  • fireOnAnimationFrame {Boolean}
  • Only emit the latest event within requestAnimationFrame intervals.


    Default: false

  • touchDamping {Number}
  • A multiplication coefficient used to scale the pan velocity. Used only for the touch polyfill when source = "touch".


    Default: 0.03

  • source {String}
  • The source used to calculate the reported data in order of approximation. If the specified source is not available, then the next available source is used.

    • "detectCompass" determines which is the best source estimate to use.
    • "rawOrientation" browser estimate.
    • "sensorFusion" sensor fusion via a Kalman filter.
    • "filteredOrientation" dynamic low-pass filter on the browser estimate.
    • "gravityPolyfill" accelerometer gravity estimate.
    • "touch" touch sensor.


    Default: "detectCompass"

var orientation = new MotionStack.Orientation({absolute: false});

Static Methods

isSupported()

Returns a Boolean value describing whether the device can report orientation estimates.

MotionStack.Orientation.isSupported(); // true or false

Instance Methods

start(callback, [context])

Start receiving orientation updates. Orientation data is reported as a quaternion and as Tait-Bryan angles.

Argument Type Description
callback Function Callback function that receives an object as an argument

  • function(e)
  • e.quaternion {Object}
    Orientation of the device reported as a unit quaternion
  • e.quaternion.{w, x, y, z} {Number}
    Axial components of the orientation quaternion
  • e.yaw {Number}
    Tait-Bryan yaw angle of orientation (degrees). This value depends on the absolute option passed to the constructor.
    See the orientation gesture page for a more detailed description of the yaw angle.
  • e.pitch {Number}
    Tait-Bryan pitch angle of orientation (degrees).
    See the orientation gesture page for a more detailed description of the pitch angle.
  • e.roll {Number}
    Tait-Bryan roll angle of orientation (degrees).
    See the orientation gesture page for a more detailed description of the roll angle.
  • e.absolute {Boolean}
    Describes whether quaternion and yaw respect magnetic north
  • e.compassIsCalibrated {Boolean}
    Describes whether the compass is estimated to be calibrated
  • e.compassHeading {Number}
    Measured heading offset from north (degrees). This is only computed when {absolute: true} is passed to the constructor.
  • e.timeStamp {Number}
    The time in milliseconds when the data is collected
  • e.source {String}
    The source used to calculate the reported data.

    • "rawOrientation" browser estimate.
    • "sensorFusion" sensor fusion via a Kalman filter.
    • "filteredOrientation" dynamic low-pass filter on the browser estimate.
    • "gravityPolyfill" accelerometer gravity estimate.
    • "touch" touch sensor.
    • "lowPass" low-pass filter on the accelerometer sensor.

context Object Context in which to invoke the callback (optional).
orientation.start(function(e) {
  console.log(e.yaw);
});

stop()

Stop orientation updates.

orientation.stop();

Source

src/interfaces/Orientation.js