new AbsoluteOrientationSensor() — Methode · JavaScript-Referenz

Signatur

new AbsoluteOrientationSensor(options)

Beschreibung

Der Konstruktor AbsoluteOrientationSensor() gehört zur Generic Sensor API und erzeugt einen Fusionssensor, der aus Beschleunigungsmesser, Gyroskop und Magnetometer die absolute räumliche Ausrichtung des Geräts berechnet. „Absolut“ bedeutet: Die Ausrichtung bezieht sich auf das Erdkoordinatensystem (X nach Osten, Y nach magnetisch Norden, Z nach oben). Damit ist der Sensor gut geeignet für Kompass-Anwendungen, Augmented Reality, 360°-Panoramen oder Kartenansichten, die sich nach der Himmelsrichtung ausrichten.

Durch das Erzeugen des Objekts wird der Sensor noch nicht aktiviert. Erst sensor.start() startet die Messung; neue Werte werden dann über das reading-Ereignis gemeldet und stehen in sensor.quaternion als Array [x, y, z, w] bereit. Mit populateMatrix() lässt sich die Ausrichtung direkt in eine Rotationsmatrix für WebGL oder three.js schreiben.

Über das Optionsobjekt legen Sie die gewünschte Abtastrate (frequency) und das Bezugssystem (referenceFrame) fest. Mit "screen" wird die Ausrichtung an die aktuelle Bildschirmorientierung (Hoch-/Querformat) angepasst – das ist für die meisten Darstellungsaufgaben die richtige Wahl.

Brauchen Sie keinen Bezug zur Nordrichtung, sondern nur relative Drehungen, ist RelativeOrientationSensor die bessere Wahl, da er ohne Magnetometer auskommt und weniger von magnetischen Störungen beeinflusst wird.

Parameter

Name	Typ	Default	Beschreibung
$options	object	{}	Optionales Konfigurationsobjekt mit den folgenden Eigenschaften.
$options.frequency	number	plattformabhängig	Gewünschte Anzahl Messwerte pro Sekunde (Hz). Der Browser kann eine niedrigere Rate verwenden, wenn die Hardware sie nicht unterstützt.
$options.referenceFrame	"device" \| "screen"	"device"	Bezugssystem: `"device"` bezieht sich auf das Gerät selbst, `"screen"` berücksichtigt die aktuelle Bildschirmausrichtung.

Rückgabewert

Typ

AbsoluteOrientationSensor

Beschreibung

Ein neues, noch inaktives AbsoluteOrientationSensor-Objekt. Die Messung beginnt erst nach Aufruf von start().

Beispiele

Sensor erzeugen und Quaternion auslesen

const sensor = new AbsoluteOrientationSensor({ frequency: 30, referenceFrame: 'screen' });

sensor.addEventListener('reading', () => {
  const [x, y, z, w] = sensor.quaternion;
  console.log(`Quaternion: x=${x.toFixed(3)} y=${y.toFixed(3)} z=${z.toFixed(3)} w=${w.toFixed(3)}`);
});

sensor.addEventListener('error', (event) => {
  console.error(`${event.error.name}: ${event.error.message}`);
});

sensor.start();

Quaternion: x=0.012 y=-0.034 z=0.707 w=0.706

Berechtigungen prüfen und Fehler sauber behandeln

const startOrientation = async () => {
  if (!('AbsoluteOrientationSensor' in window)) {
    console.warn('AbsoluteOrientationSensor wird nicht unterstützt.');
    return null;
  }

  const results = await Promise.all(
    ['accelerometer', 'gyroscope', 'magnetometer'].map((name) =>
      navigator.permissions.query({ name })
    )
  );

  if (results.some((r) => r.state === 'denied')) {
    console.warn('Zugriff auf Bewegungssensoren verweigert.');
    return null;
  }

  try {
    const sensor = new AbsoluteOrientationSensor({ frequency: 60 });
    sensor.onerror = (e) => {
      if (e.error.name === 'NotReadableError') {
        console.warn('Sensor ist nicht verfügbar.');
      }
    };
    sensor.start();
    return sensor;
  } catch (err) {
    // SecurityError bei Blockade durch Permissions-Policy
    console.error('Sensor konnte nicht erstellt werden:', err.name);
    return null;
  }
};

startOrientation();

Kompass: Himmelsrichtung aus Quaternion berechnen

const sensor = new AbsoluteOrientationSensor({ referenceFrame: 'screen' });

const toHeading = ([x, y, z, w]) => {
  // Gierwinkel (Drehung um die Z-Achse) in Grad
  const yaw = Math.atan2(2 * (w * z + x * y), 1 - 2 * (y * y + z * z));
  return (360 - (yaw * 180) / Math.PI) % 360;
};

sensor.onreading = () => {
  console.log(`Richtung: ${Math.round(toHeading(sensor.quaternion))}°`);
};

sensor.start();

// Nach 10 Sekunden stoppen, um Akku zu sparen
setTimeout(() => sensor.stop(), 10_000);

Richtung: 87°

Rotationsmatrix für WebGL/three.js befüllen

const sensor = new AbsoluteOrientationSensor({ frequency: 60, referenceFrame: 'screen' });
const rotationMatrix = new Float32Array(16);

sensor.onreading = () => {
  sensor.populateMatrix(rotationMatrix);
  // z. B. in three.js: mesh.quaternion.fromArray(sensor.quaternion).invert();
  console.log(rotationMatrix.slice(0, 4));
};

sensor.start();

Float32Array(4) [0.99, -0.02, 0.01, 0]

// Wichtig · Fallstricke

Browser-Kompatibilität: Nur in Chromium-basierten Browsern (Chrome, Edge, Opera, Samsung Internet) verfügbar. Firefox und Safari unterstützen die Generic Sensor API nicht – immer per 'AbsoluteOrientationSensor' in window prüfen und ggf. auf das deviceorientationabsolute-Ereignis ausweichen.
Sicherer Kontext: Nur über HTTPS (oder localhost) nutzbar.
Berechtigungen: Benötigt die Berechtigungen accelerometer, gyroscope und magnetometer. In iframes müssen diese per Permissions-Policy (allow="accelerometer; gyroscope; magnetometer") freigegeben sein, sonst wirft der Konstruktor einen SecurityError.
Fehlt die Hardware, wirft der Konstruktor meist keinen Fehler – stattdessen wird nach start() ein error-Ereignis mit NotReadableError ausgelöst. Beide Fehlerwege behandeln.
sensor.quaternion ist null, bis der erste Messwert eingetroffen ist.
Magnetometer-Werte werden durch Metall, Lautsprecher oder Elektronik in der Nähe verfälscht. Sensoren mit stop() anhalten, wenn sie nicht gebraucht werden, um Akku zu sparen. Messungen werden automatisch pausiert, wenn die Seite nicht sichtbar ist.
Datenschutz: Bewegungssensoren können für Fingerprinting missbraucht werden; Browser begrenzen deshalb teils Frequenz und Genauigkeit.

Siehe auch

AbsoluteOrientationSensor RelativeOrientationSensor OrientationSensor.quaternion OrientationSensor.populateMatrix() Sensor.start() Sensor.stop()