Orientation API
chevron down

Orientation API

Variable: OrientationSensor

Type: [IOrientationSensor | undefined]

Interface: IOrientationSensor

The OrientationSensor API provides access to the orientation data measured by the hardware sensor.

An Orientation sensor measures the orientation of a device relative to an orthogonal coordinate frame.

The coordinate frame's axes, x, y and z are such that:

  • The x and y axes are perpendicular to each other, but do not point in a particular direction relative to the earth. The orientation of x and y relative to the earth can drift over time.
  • The z axis is perpendicular to the ground and points towards the sky.

Read the Orientation Sensor Guide for further information.

import { OrientationSensor } from "orientation";

if (OrientationSensor) {
   console.log("This device has an OrientationSensor!");
   const orientation = new OrientationSensor({ frequency: 1 });
   orientation.addEventListener("reading", () => {
      `Orientation Reading: \
        timestamp=${orientation.timestamp}, \
        [${orientation.quaternion[0]}, \
        ${orientation.quaternion[1]}, \
        ${orientation.quaternion[2]}, \
} else {
   console.log("This device does NOT have an OrientationSensor!");


readonly activated


Flag that indicates if the sensor is activated or not. When a sensor is created, the sensor is not activated, thus the initial value of this property equals false.


((this: Sensor, event: Event) => any) or undefined

Event handler that is called when the sensor is activated.


((this: Sensor, event: SensorErrorEvent) => any) or undefined

Event handler that is called when an error occurs. When an error occurs, the sensor is automatically stopped, and the activated property equals false.


((this: Sensor, event: Event) => any) or undefined

Event handler that is called whenever a new reading is available.

readonly readings

BatchedOrientationSensorReading or undefined

New in SDK 2.0

Interface: BatchedOrientationSensorReading

New in SDK 2.0


readonly i


readonly j


readonly k


readonly scalar


readonly timestamp


Interface: OrientationSensorReading

Device orientation measured by the Orientation sensor.


readonly quaternion

number[] or null

A four-element array containing the components of the unit quaternion (a.k.a versor) representing the device's orientation.

The first element of the array is the scalar part of the quaternion, and the last 3 elements form the i, j and k factors of the vector part. So if q is a quaternion reading, the quaternion can be written mathematically as:

q[0] + q[1]i + q[2]j + q[3]k
readonly timestamp

number or null

Timestamp of the reading in milliseconds.

NOTE: this is relative to an unspecified arbitrary 0 time, or null if no reading is available (when the sensor is not yet activated and there are no valid cached values that can be used).