new RelativeOrientationSensor() — Methode · JavaScript-Referenz

Signatur

new RelativeOrientationSensor(options)

Beschreibung

Der Konstruktor RelativeOrientationSensor() erzeugt einen Sensor der Generic Sensor API. Er verknüpft die Daten von Beschleunigungssensor und Gyroskop und berechnet daraus die Drehlage des Geräts. Anders als beim AbsoluteOrientationSensor wird kein Magnetometer verwendet. Die Werte beziehen sich deshalb nicht auf den geografischen Norden, sondern auf einen frei gewählten, festen Bezugsrahmen.

Nützlich ist der Sensor überall dort, wo es nur auf relative Drehungen ankommt: 360°-Ansichten, einfache VR-Szenen, Spielsteuerung durch Neigen des Geräts oder Panoramabilder. Weil das Magnetometer fehlt, stören Metall oder Magnetfelder in der Nähe nicht. Dafür kann die Richtung mit der Zeit langsam abweichen (Drift).

Nach dem Erzeugen misst der Sensor noch nichts. Erst start() startet die Messung. Die Messwerte kommen über das Ereignis reading und stehen in der Eigenschaft quaternion als Array [x, y, z, w]. Mit populateMatrix() lassen sich die Werte direkt in eine Rotationsmatrix schreiben, etwa für WebGL. Fehler werden über das Ereignis error gemeldet.

Parameter

Name	Typ	Default	Beschreibung
$options	object	{}	Optionales Konfigurationsobjekt mit den unten aufgeführten Eigenschaften.
$options.frequency	number	vom Gerät abhängig	Gewünschte Anzahl an Messungen pro Sekunde (Hz). Der Browser kann eine niedrigere Rate verwenden, als angefordert wurde.
$options.referenceFrame	'device' \| 'screen'	'device'	Koordinatensystem: `'device'` bezieht sich auf das Gerät selbst, `'screen'` auf die aktuelle Bildschirmausrichtung (Hoch- oder Querformat wird berücksichtigt).

Rückgabewert

Typ

RelativeOrientationSensor

Beschreibung

Ein neues, noch nicht gestartetes Sensor-Objekt. Die Messung beginnt erst mit start().

Beispiele

Sensor erzeugen und Quaternion auslesen

const sensor = new RelativeOrientationSensor({ frequency: 30, referenceFrame: 'device' });

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

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

sensor.start();

Quaternion: 0.012, -0.034, 0.001, 0.999

Berechtigungen prüfen und Funktion erkennen

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

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

  if (results.some((r) => r.state === 'denied')) {
    console.warn('Keine Berechtigung für Bewegungssensoren');
    return null;
  }

  try {
    const sensor = new RelativeOrientationSensor({ frequency: 60 });
    sensor.start();
    return sensor;
  } catch (err) {
    // SecurityError bei Sperre durch die Permissions Policy
    console.error('Sensor konnte nicht erstellt werden:', err.name);
    return null;
  }
};

startOrientation();

Rotationsmatrix für WebGL oder CSS befüllen

const sensor = new RelativeOrientationSensor({ frequency: 60, referenceFrame: 'screen' });
const matrix = new Float32Array(16);
const box = document.querySelector('#box');

sensor.addEventListener('reading', () => {
  sensor.populateMatrix(matrix);
  // Die Spaltenreihenfolge passt direkt zu CSS matrix3d()
  box.style.transform = `matrix3d(${Array.from(matrix).join(',')})`;
});

sensor.start();

// Messung beenden, wenn die Seite ausgeblendet wird (spart Akku)
document.addEventListener('visibilitychange', () => {
  document.hidden ? sensor.stop() : sensor.start();
});

// Wichtig · Fallstricke

Browser-Unterstützung: Nur in Chromium-Browsern (Chrome, Edge, Opera, Samsung Internet) verfügbar. Firefox und Safari unterstützen die API nicht. Prüfe die Unterstützung vorher mit 'RelativeOrientationSensor' in window. Als Ersatz kommt das Ereignis deviceorientation infrage.
Sicherer Kontext: Funktioniert nur über HTTPS (oder localhost).
Permissions Policy: Die Funktionen accelerometer und gyroscope müssen erlaubt sein. Sonst wirft der Konstruktor einen SecurityError. In iframes muss man das mit allow="accelerometer; gyroscope" freigeben.
Fehler erst zur Laufzeit: Fehlt die Hardware oder verweigert der Nutzer die Berechtigung, wirft der Konstruktor meist keinen Fehler. Stattdessen löst der Sensor nach start() ein error-Ereignis aus, z. B. mit NotReadableError oder NotAllowedError.
Drift: Ohne Magnetometer gibt es keinen festen Bezug zum Norden. Die Richtung um die Hochachse kann deshalb mit der Zeit abweichen. Für Kompass-Anwendungen AbsoluteOrientationSensor verwenden.
Akku und Datenschutz: Hohe Messraten verbrauchen viel Energie. Mit stop() abschalten, wenn der Sensor nicht gebraucht wird. Bewegungsdaten eignen sich für Fingerprinting, darum drosseln Browser die Rate teilweise oder pausieren den Sensor in Hintergrund-Tabs.

Siehe auch

Sensor.start() Gyroscope Accelerometer new AbsoluteOrientationSensor() new DeviceOrientationEvent()