OrientationSensor.quaternion — Eigenschaft · JavaScript-Referenz

Signatur

get OrientationSensor.prototype.quaternion

Beschreibung

Die schreibgeschützte Eigenschaft quaternion ist Teil des Interfaces OrientationSensor. Sie liefert ein Array mit vier Elementen [x, y, z, w]. Diese Werte sind die Komponenten eines Einheits-Quaternions. Es beschreibt, wie das Koordinatensystem des Geräts gegenüber einem Referenzsystem gedreht ist. Die ersten drei Werte bilden den Vektoranteil, w ist der Skalaranteil. Da es ein Einheits-Quaternion ist, gilt x² + y² + z² + w² ≈ 1.

Die Eigenschaft wird über die konkreten Unterklassen genutzt: AbsoluteOrientationSensor (bezogen auf das Erdkoordinatensystem, mit Magnetometer) und RelativeOrientationSensor (ohne magnetischen Nordbezug, dafür unempfindlich gegen magnetische Störungen). Quaternionen haben gegenüber Eulerwinkeln einen Vorteil: Es gibt keinen Gimbal Lock, und man kann zwischen zwei Ausrichtungen gleichmäßig interpolieren. Deshalb eignen sie sich besonders für 3D-Szenen, AR/VR-Anwendungen und Spielsteuerungen per Gerätebewegung.

Solange der Sensor noch keinen Messwert geliefert hat oder gestoppt wurde, ist der Wert null. Man liest die Eigenschaft deshalb am besten im reading-Event. Soll das Quaternion direkt als Rotationsmatrix verwendet werden, etwa in WebGL, gibt es die Methode populateMatrix().

Rückgabewert

Typ

number[] | null

Beschreibung

Ein Array mit vier Zahlen [x, y, z, w], die das Einheits-Quaternion der Geräteausrichtung bilden. null, solange noch kein Messwert vorliegt.

Beispiele

Absolute Ausrichtung auslesen

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

sensor.addEventListener('reading', () => {
  const [x, y, z, w] = sensor.quaternion;
  console.log(`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();

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

Berechtigungen prüfen und Sensor mit Feature-Detection starten

const startOrientation = async () => {
  if (!('AbsoluteOrientationSensor' in window)) {
    console.warn('AbsoluteOrientationSensor wird nicht unterstützt.');
    return;
  }
  const results = await Promise.all([
    navigator.permissions.query({ name: 'accelerometer' }),
    navigator.permissions.query({ name: 'magnetometer' }),
    navigator.permissions.query({ name: 'gyroscope' })
  ]);
  if (results.some((r) => r.state === 'denied')) {
    console.warn('Keine Berechtigung für die Bewegungssensoren.');
    return;
  }
  const sensor = new AbsoluteOrientationSensor();
  console.log('Vor dem Start:', sensor.quaternion);
  sensor.onreading = () => console.log('Quaternion:', sensor.quaternion);
  sensor.start();
};

startOrientation();

Vor dem Start: null Quaternion: [0.01, -0.02, 0.71, 0.70]

Quaternion in einen Kompass-Kurs (Gierwinkel) umrechnen

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

const sensor = new AbsoluteOrientationSensor({ frequency: 10 });
sensor.onreading = () => {
  console.log(`Kurs: ${toYawDegrees(sensor.quaternion).toFixed(1)}°`);
};
sensor.start();

Kurs: 90.1°

Ausrichtung auf ein Three.js-Objekt übertragen

// Voraussetzung: Three.js ist geladen, `mesh` existiert in der Szene
const sensor = new RelativeOrientationSensor({ frequency: 60, referenceFrame: 'screen' });

sensor.addEventListener('reading', () => {
  mesh.quaternion.fromArray(sensor.quaternion).invert();
});

sensor.start();

// Wichtig · Fallstricke

Browser-Unterstützung: Nur in Chromium-basierten Browsern (Chrome, Edge, Opera, Samsung Internet). Firefox und Safari unterstützen die Generic Sensor API nicht. Als Alternative bietet sich dort das Event deviceorientation an. Vor der Nutzung immer mit Feature-Detection prüfen ('AbsoluteOrientationSensor' in window).
Sicherer Kontext: Funktioniert nur über HTTPS. Bei Iframes muss die Permissions Policy (accelerometer, gyroscope, magnetometer) die Nutzung erlauben.
Wert null: Vor dem ersten reading-Event und nach stop() ist der Wert null. Destrukturierung wie const [x, y, z, w] = sensor.quaternion wirft in diesem Fall einen TypeError.
Reihenfolge der Komponenten: Die Reihenfolge ist [x, y, z, w], der Skalaranteil steht also am Ende. Manche Bibliotheken erwarten w zuerst. Three.js (fromArray) und gl-matrix verwenden dieselbe Reihenfolge.
Referenzsystem: Mit der Konstruktor-Option referenceFrame: 'screen' werden die Werte auf die Bildschirmausrichtung bezogen, sodass ein Drehen des Bildschirms (Hoch-/Querformat) berücksichtigt wird. Der Standard ist 'device'.
Datenschutz und Leistung: Hohe Abtastraten verbrauchen viel Akku, und Bewegungssensoren können zum Fingerprinting missbraucht werden. Browser können deshalb die Frequenz begrenzen oder die Daten ungenauer machen. Den Sensor mit stop() beenden, sobald er nicht mehr gebraucht wird.

Siehe auch

AmbientLightSensor.illuminance AnimationEvent.animation MutationEvent.attrName MutationEvent.relatedNode NotificationEvent.action