Signatur
Beschreibung
AbsoluteOrientationSensor ist ein Fusionssensor aus der Generic Sensor API. Er verrechnet die Messwerte von Beschleunigungssensor, Gyroskop und Magnetometer zu einer Ausrichtung des Geräts relativ zum Erdkoordinatensystem. Die X-Achse zeigt dabei nach Osten, die Y-Achse nach magnetisch Nord und die Z-Achse senkrecht zum Boden nach oben.
Die Schnittstelle erbt von OrientationSensor und damit von Sensor und EventTarget. Die Ausrichtung steht als Quaternion in der Eigenschaft quaternion (Array [x, y, z, w]) zur Verfügung. Alternativ schreibt populateMatrix() sie als 4×4-Rotationsmatrix in ein Float32Array, ein Float64Array oder ein DOMMatrix-Objekt. Das eignet sich direkt für WebGL oder Three.js.
Typische Einsatzfälle sind Kompass-Anwendungen, Augmented Reality, 360°-Panoramen und Himmelskarten, also alles, was eine absolute Himmelsrichtung braucht. Wenn nur relative Drehungen zählen, etwa bei Spielen, ist RelativeOrientationSensor die bessere Wahl. Er kommt ohne Magnetometer aus und wird deshalb nicht durch magnetische Störungen verfälscht.
Der Sensor arbeitet nur in einem sicheren Kontext (HTTPS). Außerdem braucht er die Berechtigungen accelerometer, gyroscope und magnetometer, die eine Permissions Policy auch sperren kann. Die Messung beginnt erst nach start(). Neue Werte werden über das Event reading gemeldet, Fehler über error.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $options | Object | {} | Optionales Konfigurationsobjekt für den Konstruktor new AbsoluteOrientationSensor(options). |
| $options.frequency | number | gerätespezifisch | Gewünschte Anzahl Messungen pro Sekunde (Hz). Der Browser kann den Wert nach unten begrenzen. |
| $options.referenceFrame | "device" | "screen" | "device" | Bezugssystem der Achsen. Bei "screen" werden die Achsen an die aktuelle Bildschirmausrichtung (Hoch- oder Querformat) angepasst. |
Rückgabewert
start(). Die wichtigsten Mitglieder sind quaternion, populateMatrix(), activated, hasReading, timestamp, start() und stop().Beispiele
Sensor erzeugen und Quaternion auslesen
// Funktioniert nur über HTTPS und in Chromium-Browsern
if ('AbsoluteOrientationSensor' in window) {
const sensor = new AbsoluteOrientationSensor({ frequency: 30, referenceFrame: 'device' });
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();
} else {
console.warn('AbsoluteOrientationSensor wird nicht unterstützt.');
}Berechtigungen prüfen und Fehler behandeln
const startOrientation = async () => {
const names = ['accelerometer', 'gyroscope', 'magnetometer'];
const results = await Promise.all(
names.map((name) => navigator.permissions.query({ name }))
);
if (results.some((r) => r.state === 'denied')) {
console.warn('Mindestens eine Sensor-Berechtigung wurde verweigert.');
return null;
}
try {
const sensor = new AbsoluteOrientationSensor({ frequency: 60 });
sensor.onerror = (e) => {
if (e.error.name === 'NotReadableError') {
console.error('Sensor ist nicht verfügbar.');
}
};
sensor.start();
return sensor;
} catch (err) {
// SecurityError (Permissions Policy) oder ReferenceError (nicht unterstützt)
console.error('Sensor konnte nicht erzeugt werden:', err.name);
return null;
}
};
startOrientation();Rotationsmatrix für ein 3D-Modell (z. B. WebGL/Three.js)
const sensor = new AbsoluteOrientationSensor({ frequency: 60, referenceFrame: 'screen' });
const rotationMatrix = new Float32Array(16);
sensor.onreading = () => {
sensor.populateMatrix(rotationMatrix);
// Bei Three.js zum Beispiel:
// model.quaternion.fromArray(sensor.quaternion).invert();
console.log('Matrix-Zeile 1:', Array.from(rotationMatrix.slice(0, 4)).map((v) => v.toFixed(2)));
};
sensor.start();
// Sensor anhalten, wenn der Tab im Hintergrund ist (spart Akku)
document.addEventListener('visibilitychange', () => {
document.hidden ? sensor.stop() : sensor.start();
});Einfacher Kompass: Himmelsrichtung aus dem Quaternion
const sensor = new AbsoluteOrientationSensor();
sensor.addEventListener('reading', () => {
const [x, y, z, w] = sensor.quaternion;
// Gierwinkel (Drehung um die Z-Achse) in Grad
const yaw = Math.atan2(2 * (w * z + x * y), 1 - 2 * (y * y + z * z));
const heading = (360 - (yaw * 180) / Math.PI) % 360;
console.log(`Richtung: ${Math.round(heading)}°`);
});
sensor.start();// Wichtig · Fallstricke
- Browser-Kompatibilität: Die Schnittstelle wird nur von Chromium-Browsern unterstützt (Chrome, Edge, Opera, Samsung Internet), und zwar vor allem auf Mobilgeräten mit passender Hardware. Firefox und Safari unterstützen sie nicht. Prüfen Sie die Unterstützung vorher mit
'AbsoluteOrientationSensor' in window. Als Rückfallebene bietet sich das Eventdeviceorientationabsolutean bzw.deviceorientationmitwebkitCompassHeadingin iOS-Safari. - Sicherer Kontext: Die API steht nur über HTTPS (oder
localhost) zur Verfügung. - Permissions Policy: In iframes müssen
accelerometer,gyroscopeundmagnetometerfreigegeben sein, sonst wirft der Konstruktor einenSecurityError. - Fehlende Hardware: Hat das Gerät keinen Magnetometer, wird kein Fehler im Konstruktor geworfen. Stattdessen löst
start()einerror-Event mitNotReadableErroraus. Registrieren Sie deshalb immer einenerror-Handler. - Magnetische Störungen: Metall, Magnete und Elektronik in der Nähe können die Nordrichtung deutlich verfälschen. Außerdem bezieht sich „Nord“ auf den magnetischen und nicht auf den geografischen Nordpol.
- Datenschutz und Akku: Hohe Frequenzen verbrauchen Energie und können theoretisch für Fingerprinting oder Seitenkanalangriffe missbraucht werden. Browser drosseln die Frequenz deshalb und liefern im Hintergrund-Tab keine Werte. Rufen Sie
stop()auf, wenn der Sensor nicht gebraucht wird. quaternionistnull, bis die erste Messung vorliegt. Das lässt sich überhasReadingprüfen.