new XRRay() — Methode · JavaScript-Referenz

Signatur

new XRRay(origin, direction) | new XRRay(transform)

Beschreibung

Der Konstruktor XRRay() erzeugt einen Strahl im 3D-Raum. Er besteht aus einem Ursprung (origin) und einer Richtung (direction). Solche Strahlen kommen vor allem im WebXR Hit Test Module vor. Dort legen sie fest, in welche Richtung ein Hit-Test ausgehend von einem XRSpace „schießt“, z. B. um Punkte auf echten Oberflächen wie Boden oder Tisch zu finden.

Es gibt zwei Formen: Entweder übergibst du Ursprung und Richtung als DOMPointInit-Objekte, oder du übergibst ein XRRigidTransform. Im zweiten Fall entsteht der Strahl so: Der Standardstrahl (Ursprung (0, 0, 0), Richtung (0, 0, -1)) wird mit der Transformation verschoben und gedreht. Ohne Argumente zeigt der Strahl vom Koordinatenursprung entlang der negativen Z-Achse, also in WebXR „nach vorn“.

Die Richtung wird automatisch normalisiert, hat danach also die Länge 1. Das fertige Objekt hat die schreibgeschützten Eigenschaften origin und direction (beide DOMPointReadOnly) sowie matrix. matrix ist ein Float32Array mit 16 Werten: die Transformationsmatrix, die den Standardstrahl in diesen Strahl überführt.

Meistens verwendest du den Strahl als offsetRay in XRSession.requestHitTestSource() oder requestHitTestSourceForTransientInput().

Parameter

Name	Typ	Default	Beschreibung
$origin	DOMPointInit	{ x: 0, y: 0, z: 0, w: 1 }	Startpunkt des Strahls. `w` muss `1` sein, denn es handelt sich um einen Punkt.
$direction	DOMPointInit	{ x: 0, y: 0, z: -1, w: 0 }	Richtungsvektor. `w` muss `0` sein, denn es handelt sich um einen Vektor. `x`, `y` und `z` dürfen nicht alle `0` sein. Der Vektor wird normalisiert.
$transform	XRRigidTransform		Alternative zu `origin`/`direction`: Diese Transformation wird auf den Standardstrahl (Ursprung `(0,0,0)`, Richtung `(0,0,-1)`) angewendet.

Rückgabewert

Typ

XRRay

Beschreibung

Ein neues XRRay-Objekt mit origin, normalisierter direction und der zugehörigen matrix.

Beispiele

Strahl aus Ursprung und Richtung erzeugen

// Strahl 1,6 m über dem Ursprung, schräg nach vorn unten
const ray = new XRRay(
  { x: 0, y: 1.6, z: 0, w: 1 },
  { x: 0, y: -1, z: -1, w: 0 }
);

console.log(ray.origin.y);
console.log(ray.direction.y.toFixed(4), ray.direction.z.toFixed(4));

1.600000023841858 -0.7071 -0.7071

Standardstrahl und Strahl aus XRRigidTransform

const defaultRay = new XRRay();
console.log(defaultRay.direction.z); // -1

// Strahl 0,5 m nach rechts verschoben und 90° um die Y-Achse gedreht
const angle = Math.PI / 2;
const transform = new XRRigidTransform(
  { x: 0.5, y: 0, z: 0 },
  { x: 0, y: Math.sin(angle / 2), z: 0, w: Math.cos(angle / 2) }
);
const turnedRay = new XRRay(transform);

console.log(turnedRay.origin.x);
console.log(Math.round(turnedRay.direction.x)); // zeigt nun nach -X

-1 0.5 -1

Hit-Test mit Offset-Strahl in einer AR-Sitzung

const startAR = async () => {
  const session = await navigator.xr.requestSession('immersive-ar', {
    requiredFeatures: ['hit-test', 'local']
  });
  const viewerSpace = await session.requestReferenceSpace('viewer');
  const localSpace = await session.requestReferenceSpace('local');

  // Strahl leicht nach unten geneigt, um bevorzugt den Boden zu treffen
  const offsetRay = new XRRay({ x: 0, y: 0, z: 0, w: 1 }, { x: 0, y: -0.3, z: -1, w: 0 });
  const hitTestSource = await session.requestHitTestSource({ space: viewerSpace, offsetRay });

  const onFrame = (time, frame) => {
    const hits = frame.getHitTestResults(hitTestSource);
    if (hits.length > 0) {
      const pose = hits[0].getPose(localSpace);
      console.log('Treffer bei', pose.transform.position);
    }
    session.requestAnimationFrame(onFrame);
  };
  session.requestAnimationFrame(onFrame);
};

document.querySelector('#ar-button').addEventListener('click', startAR);

Treffer bei DOMPointReadOnly {x: …, y: …, z: …, w: 1}

// Wichtig · Fallstricke

Der Konstruktor wirft einen TypeError, wenn direction der Nullvektor ist, wenn direction.w nicht 0 ist oder wenn origin.w nicht 1 ist.
Die Richtung wird normalisiert. Lies deshalb keine ursprünglichen Längen aus direction zurück.
Die Werte werden intern als 32-Bit-Gleitkommazahlen gespeichert. Dadurch entstehen kleine Rundungsabweichungen, z. B. 1.600000023841858 statt 1.6.
Die Koordinaten beziehen sich immer auf den XRSpace, mit dem der Strahl verwendet wird, z. B. space in requestHitTestSource(). Sie sind keine Weltkoordinaten.
Kompatibilität: Die API ist experimentell und steht nur in sicheren Kontexten (HTTPS) zur Verfügung. Sie wird vor allem von Chromium-basierten Browsern auf Android und vom Meta Quest Browser unterstützt, nicht von Firefox und Safari. Prüfe vor der Nutzung mit 'XRRay' in window.

Siehe auch

XRRay XRRigidTransform XRSession.requestHitTestSource() XRFrame.getHitTestResults() XRHitTestSource DOMPointReadOnly new CSSSkew()