Signatur
Beschreibung
OrientationSensor ist eine abstrakte Basisschnittstelle der Generic Sensor API. Sie erbt von Sensor (und damit von EventTarget) und beschreibt die räumliche Ausrichtung eines Geräts. Du kannst sie nicht direkt instanziieren. In der Praxis verwendest du eine der beiden konkreten Unterklassen:
AbsoluteOrientationSensor: Ausrichtung relativ zum Koordinatensystem der Erde (Norden, Osten, Schwerkraft). Grundlage sind Beschleunigungssensor, Gyroskop und Magnetometer.RelativeOrientationSensor: Ausrichtung relativ zu einem festen, aber beliebigen Bezugssystem. Das Magnetometer wird dabei nicht verwendet, deshalb stören magnetische Einflüsse nicht, die Werte können aber mit der Zeit abdriften.
Die Schnittstelle bietet zwei Mitglieder: die schreibgeschützte Eigenschaft quaternion und die Methode populateMatrix(targetMatrix). quaternion liefert ein Array aus vier Zahlen [x, y, z, w], das die Drehung des Geräts beschreibt. populateMatrix() schreibt dieselbe Drehung als 4×4-Rotationsmatrix in ein Float32Array, ein Float64Array oder eine DOMMatrix. Diese Matrix kannst du direkt an WebGL oder Three.js übergeben oder für CSS-Transformationen verwenden.
Typische Einsatzgebiete sind 360°-Ansichten, AR- und VR-Anwendungen, Kompasse, Spiele mit Neigungssteuerung und 3D-Modelle, die sich mit dem Gerät mitdrehen. Die Messung folgt dem üblichen Ablauf der Sensor-API: Objekt erzeugen, reading- und error-Handler registrieren, start() aufrufen und zum Schluss stop() aufrufen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $options.frequency | number | vom Gerät abhängig | Konstruktor-Option der Unterklassen: gewünschte Abtastrate in Hz, also Messungen pro Sekunde. Der Browser kann sie nach unten begrenzen. |
| $options.referenceFrame | 'device' | 'screen' | 'device' | Konstruktor-Option der Unterklassen: Bezugssystem der Koordinaten. Mit 'screen' wird die aktuelle Bildschirmausrichtung (Hoch- oder Querformat) berücksichtigt. |
| $targetMatrix Pflicht | Float32Array | Float64Array | DOMMatrix | Parameter von populateMatrix(): das Ziel, in das die 4×4-Rotationsmatrix geschrieben wird. Ein typisiertes Array muss mindestens 16 Elemente haben. |
Beispiele
AbsoluteOrientationSensor starten und Quaternion auslesen
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) => {
if (event.error.name === 'NotAllowedError') {
console.warn('Zugriff auf den Sensor wurde verweigert.');
} else if (event.error.name === 'NotReadableError') {
console.warn('Sensor ist nicht verfügbar.');
}
});
sensor.start();Berechtigungen prüfen und Unterstützung erkennen
const startOrientation = async () => {
if (!('AbsoluteOrientationSensor' in window)) {
console.log('Orientierungssensoren werden nicht unterstützt.');
return null;
}
const results = await Promise.all(
['accelerometer', 'gyroscope', 'magnetometer'].map((name) =>
navigator.permissions.query({ name })
)
);
if (results.every((r) => r.state === 'granted')) {
const sensor = new AbsoluteOrientationSensor({ frequency: 60 });
sensor.start();
console.log('Sensor läuft.');
return sensor;
}
console.log('Keine Berechtigung für die Sensoren.');
return null;
};
startOrientation();Rotationsmatrix auf ein 3D-Element (CSS) anwenden
const cube = document.querySelector('#cube');
const matrix = new DOMMatrix();
const sensor = new RelativeOrientationSensor({ frequency: 60, referenceFrame: 'screen' });
sensor.onreading = () => {
// schreibt die 4x4-Rotationsmatrix direkt in die DOMMatrix
sensor.populateMatrix(matrix);
cube.style.transform = matrix.toString();
};
sensor.onerror = (event) => console.error(event.error.name, event.error.message);
sensor.start();
// Sensor abschalten, wenn der Tab im Hintergrund ist
document.addEventListener('visibilitychange', () => {
document.hidden ? sensor.stop() : sensor.start();
});Matrix für WebGL in ein Float32Array schreiben
const rotation = new Float32Array(16);
const sensor = new AbsoluteOrientationSensor({ frequency: 60 });
sensor.addEventListener('reading', () => {
sensor.populateMatrix(rotation);
// z. B. gl.uniformMatrix4fv(uModelMatrix, false, rotation);
console.log(rotation.slice(0, 4));
});
sensor.start();