XRRigidTransform.position — Eigenschaft · JavaScript-Referenz

Signatur

XRRigidTransform.position

Beschreibung

Die Eigenschaft position einer XRRigidTransform gibt einen DOMPointReadOnly zurück, der die Verschiebung (Translation) der Transformation beschreibt. Die Komponenten x, y und z sind in Metern angegeben und beziehen sich auf den Ursprung des jeweiligen Referenzraums (XRReferenceSpace). Die Komponente w ist immer 1.

Eine starre Transformation besteht aus einer Drehung (orientation) und einer Verschiebung (position). Dabei wird zuerst gedreht und danach verschoben. In der Praxis liest man position zum Beispiel aus XRViewerPose.transform aus, um die Kopfposition des Nutzers zu ermitteln, oder aus der Pose eines Controllers, um Objekte in der Szene zu platzieren oder Abstände zu berechnen.

Der Wert lässt sich nicht nachträglich ändern. Soll eine andere Position gelten, erzeugt man mit new XRRigidTransform(position, orientation) ein neues Objekt – zum Beispiel, um mit XRReferenceSpace.getOffsetReferenceSpace() den Nutzer im virtuellen Raum zu versetzen („Teleportation“).

Rückgabewert

Typ

DOMPointReadOnly

Beschreibung

Punkt mit x, y, z in Metern und w = 1. Er beschreibt die Translation der Transformation relativ zum Ursprung des Referenzraums.

Beispiele

Transformation erzeugen und Position auslesen

// Punkt 1 m rechts, 1,6 m hoch, 2 m vor dem Ursprung (−z zeigt nach vorn)
const transform = new XRRigidTransform({ x: 1, y: 1.6, z: -2 });

const { x, y, z, w } = transform.position;
console.log(x, y, z, w);

1 1.6 -2 1

Kopfposition des Nutzers in jedem Frame ermitteln

const session = await navigator.xr.requestSession('immersive-vr');
const refSpace = await session.requestReferenceSpace('local-floor');

const onFrame = (time, frame) => {
  const pose = frame.getViewerPose(refSpace);
  if (pose) {
    const p = pose.transform.position;
    console.log(`Kopf: x=${p.x.toFixed(2)} y=${p.y.toFixed(2)} z=${p.z.toFixed(2)} m`);
  }
  session.requestAnimationFrame(onFrame);
};

session.requestAnimationFrame(onFrame);

Kopf: x=0.03 y=1.62 z=-0.05 m

Abstand zwischen Controller und Kopf berechnen

const distance = (a, b) => Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z);

const checkReach = (frame, refSpace, inputSource) => {
  const viewer = frame.getViewerPose(refSpace);
  const grip = inputSource.gripSpace && frame.getPose(inputSource.gripSpace, refSpace);
  if (!viewer || !grip) return null;

  const d = distance(viewer.transform.position, grip.transform.position);
  console.log(`Armabstand: ${d.toFixed(2)} m`);
  return d;
};

Armabstand: 0.48 m

Teleportation: neuen Referenzraum mit versetzter Position erzeugen

// Zielpunkt, an den der Nutzer versetzt werden soll
const target = { x: 3, y: 0, z: -4 };

// Der Offset wird invertiert angegeben: die Welt verschiebt sich entgegengesetzt
const offset = new XRRigidTransform({ x: -target.x, y: -target.y, z: -target.z });
refSpace = refSpace.getOffsetReferenceSpace(offset);

console.log(offset.position.x, offset.position.z);

-3 4

// Wichtig · Fallstricke

Schreibgeschützt: Zuweisungen wie transform.position.x = 2 werden ignoriert (im Strict Mode TypeError). Für eine neue Position legt man ein neues XRRigidTransform an.
Einheit Meter, rechtshändiges Koordinatensystem: +y zeigt nach oben, -z nach vorn. Die Werte beziehen sich immer auf den Referenzraum, der an getPose() bzw. getViewerPose() übergeben wurde. Bei 'local' liegt y etwa auf Augenhöhe bei 0, bei 'local-floor' liegt der Boden bei 0.
Übergibt man dem Konstruktor einen Punkt mit w ungleich 1, wird ein TypeError ausgelöst.
Posen gelten nur für den aktuellen XRFrame. Wer Werte über mehrere Frames speichern will, sollte x, y und z kopieren, statt das Objekt selbst aufzubewahren.
Für Grafikbibliotheken ist oft transform.matrix (ein Float32Array mit 16 Werten, spaltenweise) bequemer. Dort steckt die Position in den Einträgen 12–14.
Kompatibilität: WebXR steht nur in sicheren Kontexten (HTTPS) zur Verfügung. Unterstützt wird es vor allem von Chromium-Browsern (Chrome, Edge, Meta Quest Browser) und Samsung Internet. Firefox und Safari auf dem Desktop unterstützen WebXR nicht; auf der Apple Vision Pro ist es nur eingeschränkt verfügbar. Prüfe die Unterstützung vorher mit navigator.xr?.isSessionSupported().

Siehe auch

XRRigidTransform XRRigidTransform.orientation XRRigidTransform.matrix XRRigidTransform.inverse DOMPointReadOnly XRPose.transform XRReferenceSpace.getOffsetReferenceSpace()