RelativeOrientationSensor — Schnittstelle · JavaScript-Referenz

Signatur

interface RelativeOrientationSensor extends OrientationSensor

Beschreibung

RelativeOrientationSensor gehört zur Generic Sensor API und liefert die physische Orientierung des Geräts. Anders als AbsoluteOrientationSensor bezieht er sich nicht auf das Bezugssystem der Erde (magnetischer Norden, Schwerkraft), sondern auf einen beliebigen, festen Ausgangszustand. Intern werden dafür nur Beschleunigungssensor und Gyroskop ausgewertet, kein Magnetometer.

Deshalb eignet sich der Sensor gut für Anwendungen, die nur Drehungen relativ zueinander brauchen: 360°-Viewer, einfache VR/AR-Szenen, Steuerung durch Neigen oder 3D-Modelle, die sich mit dem Gerät mitdrehen. Weil Magnetfelder nicht mitgemessen werden, stören Metall oder Elektronik in der Nähe hier nicht. Dafür kann die Ausrichtung mit der Zeit langsam wegdriften, denn es fehlt ein fester Bezugspunkt, mit dem sich Fehler korrigieren ließen.

Die Schnittstelle erbt alles von OrientationSensor und Sensor: Mit quaternion liest man die Orientierung als Array [x, y, z, w] aus, mit populateMatrix() schreibt man sie direkt in eine Rotationsmatrix (zum Beispiel für WebGL). Gestartet und beendet wird die Messung mit start() und stop(). Die Ereignisse reading, activate und error informieren über neue Messwerte, den Start und Fehler.

Der Konstruktor new RelativeOrientationSensor(options) nimmt ein optionales Objekt mit frequency (Messwerte pro Sekunde, in Hz) und referenceFrame ("device" oder "screen") an.

Parameter

Name	Typ	Default	Beschreibung
$options	Object	{}	Optionales Konfigurationsobjekt für den Konstruktor.
$options.frequency	number	abhängig vom Gerät	Gewünschte Zahl der Messwerte pro Sekunde (Hz). Der Browser kann weniger liefern, wenn die Hardware nicht mehr schafft.
$options.referenceFrame	"device" \| "screen"	"device"	Koordinatensystem: `"device"` ist fest am Gerät, `"screen"` dreht sich mit der aktuellen Bildschirmausrichtung mit.

Rückgabewert

Typ

RelativeOrientationSensor

Beschreibung

Eine neue Sensor-Instanz. Sie misst erst nach dem Aufruf von start(). Solange noch kein Messwert vorliegt, ist quaternion null.

Beispiele

Sensor erzeugen und Quaternion auslesen

if ('RelativeOrientationSensor' in window) {
  const sensor = new RelativeOrientationSensor({ frequency: 60, 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('Sensorfehler:', event.error.name, event.error.message);
  });

  sensor.start();
} else {
  console.warn('RelativeOrientationSensor wird nicht unterstützt.');
}

Quaternion: x=0.012 y=-0.034 z=0.001 w=0.999

Berechtigungen prüfen und 3D-Objekt per Rotationsmatrix drehen

const startOrientation = async (onMatrix) => {
  const results = await Promise.all([
    navigator.permissions.query({ name: 'accelerometer' }),
    navigator.permissions.query({ name: 'gyroscope' })
  ]);

  if (results.some((r) => r.state === 'denied')) {
    throw new Error('Zugriff auf Bewegungssensoren verweigert.');
  }

  const sensor = new RelativeOrientationSensor({ frequency: 60, referenceFrame: 'screen' });
  const matrix = new Float32Array(16); // 4x4-Matrix für WebGL/three.js

  sensor.onreading = () => {
    sensor.populateMatrix(matrix);
    onMatrix(matrix);
  };
  sensor.onerror = (e) => console.error(e.error);
  sensor.start();
  return sensor;
};

// Einsatz, z. B. mit three.js: mesh.quaternion.fromArray(sensor.quaternion).invert();
const sensor = await startOrientation((m) => console.log('Matrix[0..3]:', Array.from(m.slice(0, 4))));

Matrix[0..3]: [0.998, -0.021, 0.054, 0]

Sensor beim Wechsel des Tabs anhalten (Akku sparen)

const sensor = new RelativeOrientationSensor({ frequency: 30 });

const logReading = () => console.log('Neue Orientierung:', sensor.quaternion);
sensor.addEventListener('reading', logReading);
sensor.addEventListener('activate', () => console.log('Sensor aktiv'));
sensor.start();

document.addEventListener('visibilitychange', () => {
  if (document.hidden) {
    sensor.stop();
    console.log('Sensor gestoppt');
  } else {
    sensor.start();
  }
});

// Später vollständig aufräumen:
// sensor.removeEventListener('reading', logReading);
// sensor.stop();

Sensor aktiv Neue Orientierung: [0.01, 0.02, -0.003, 0.9997]

// Wichtig · Fallstricke

Browser-Unterstützung: Nur Chromium-Browser (Chrome, Edge, Opera, Samsung Internet) unterstützen die Schnittstelle. Firefox und Safari kennen sie nicht. Vorher mit 'RelativeOrientationSensor' in window prüfen und als Ersatz auf das Ereignis deviceorientation ausweichen.
Sicherer Kontext: Funktioniert nur über HTTPS oder localhost. Außerdem muss die Permissions Policy accelerometer und gyroscope erlauben, in iframes also z. B. allow="accelerometer; gyroscope" setzen.
Fehlerbehandlung: Der Konstruktor kann einen SecurityError werfen, wenn die Policy den Zugriff blockiert. Deshalb in try/catch einschließen. Fehler während der Messung (NotAllowedError, NotReadableError, NotSupportedError) kommen über das Ereignis error.
Drift: Ohne Magnetometer gibt es keinen festen Bezugspunkt, die Werte verschieben sich also mit der Zeit langsam. Für Kompass-Anwendungen oder eine Ausrichtung nach Himmelsrichtungen stattdessen AbsoluteOrientationSensor verwenden.
Datenschutz und Akku: Hohe Messraten verbrauchen viel Strom, und über Bewegungsdaten lassen sich Geräte wiedererkennen (Fingerprinting). Den Sensor deshalb stoppen, wenn er nicht gebraucht wird oder die Seite im Hintergrund ist.
quaternion ist null, bis das erste Ereignis reading eingetroffen ist.

Siehe auch

Sensor Gyroscope Accelerometer AbsoluteOrientationSensor OrientationSensor