RelativeHeading

This API enables the user to get updates describing the heading and roll angle of a mobile device.

The RelativeHeading always starts at a value of 0 and, as the device is rotated to the left or right, the relative heading angle is updated in degrees. Rotating the device to the left causes the relative heading value to decrease, whereas moving or rotating to the right causes the value to increase.

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

Example

var relativeHeading = new MotionStack.RelativeHeading();

relativeHeading.start(function (e) {
  console.log(e.angle);

  if (Math.abs(e.angle) > 360) {
    relativeHeading.stop();
  }
});

Constructor

new MotionStack.RelativeHeading([options])

Create a new RelativeHeading instance object.

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

  • continuous {Boolean}
  • Determines whether the heading angle can grow indefinitely. When this is false, the value of relative heading is bounded between 0 and 360 degrees.


    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

  • headingRange {Number}
  • The maximum allowed magnitude of the heading angle. That is, the heading angle is restricted between -headingRange <= heading <= headingRange.


    Default: Infinity

  • 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 relativeHeading = new MotionStack.RelativeHeading({continuous: true});

Instance Methods

start(callback, [context])

Start receiving relative heading updates.

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

  • function(e)
  • e.angle {Number}
    Current heading angle of the device as measured from the initial heading when the start() method was first invoked on the given instance
  • 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.

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

stop()

Stop relative heading updates.

relativeHeading.stop();

Source

src/interfaces/RelativeHeading.js