XRRay — Schnittstelle · JavaScript-Referenz

Signatur

interface XRRay

Beschreibung

Das Interface XRRay stammt aus dem WebXR Hit Test Module. Es beschreibt einen Strahl, der an einem Punkt im 3D-Raum beginnt und in eine Richtung unendlich weiterläuft. Solche Strahlen nutzt man in AR-Anwendungen vor allem, um herauszufinden, wo ein gedachter Strahl – etwa von der Kamera oder einem Controller aus – eine erkannte reale Fläche (Boden, Tisch, Wand) trifft.

Einen Strahl erzeugt man mit new XRRay(), entweder aus einem Ursprung und einer Richtung (beides DOMPointInit) oder aus einer XRRigidTransform. Ohne Argumente beginnt der Strahl im Koordinatenursprung {x: 0, y: 0, z: 0, w: 1} und zeigt entlang der negativen Z-Achse {x: 0, y: 0, z: -1, w: 0}, also „nach vorne“ aus Sicht des jeweiligen Referenzraums.

Eigenschaften (alle nur lesbar):

origin – ein DOMPointReadOnly mit dem Startpunkt (w ist immer 1).
direction – ein DOMPointReadOnly mit dem normierten Richtungsvektor (w ist immer 0).
matrix – ein Float32Array mit 16 Werten (4×4-Matrix, spaltenweise). Sie transformiert den Standardstrahl (Ursprung 0/0/0, Richtung −Z) in diesen Strahl.

Wichtigster Einsatzzweck ist der Parameter offsetRay von XRSession.requestHitTestSource() und requestHitTestSourceForTransientInput(). Damit wird der Strahl relativ zu einem XRSpace (z. B. dem viewer-Raum) definiert und in jedem Frame neu ausgewertet.

Parameter

Name	Typ	Default	Beschreibung
$origin	DOMPointInit	{x: 0, y: 0, z: 0, w: 1}	Startpunkt des Strahls. `w` muss `1` sein, sonst wird ein `TypeError` ausgelöst.
$direction	DOMPointInit	{x: 0, y: 0, z: -1, w: 0}	Richtungsvektor. Er wird automatisch normiert. `w` muss `0` sein, und `x`, `y` und `z` dürfen nicht alle `0` sein, sonst wird ein `TypeError` ausgelöst.
$transform	XRRigidTransform		Alternative Konstruktorform: Der Standardstrahl wird mit dieser starren Transformation (Position und Orientierung) verschoben und gedreht.

Rückgabewert

Typ

XRRay

Beschreibung

Ein neues, unveränderliches XRRay-Objekt mit den Eigenschaften origin, direction und matrix.

Beispiele

Strahl erzeugen und Eigenschaften auslesen

// Strahl 1,5 m über dem Boden, schräg nach vorne unten
const ray = new XRRay(
  { x: 0, y: 1.5, z: 0, w: 1 },
  { x: 0, y: -1, z: -1, w: 0 }
);

console.log(ray.origin.y);
console.log(ray.direction.y.toFixed(3), ray.direction.z.toFixed(3));
console.log(ray.matrix.length);

1.5 -0.707 -0.707 16

Hit-Test-Quelle mit offsetRay vom Blickpunkt aus

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, damit er eher den Boden trifft
  const offsetRay = new XRRay({ x: 0, y: 0, z: 0 }, { x: 0, y: -0.3, z: -1 });

  const hitTestSource = await session.requestHitTestSource({
    space: viewerSpace,
    offsetRay
  });

  const onFrame = (time, frame) => {
    const results = frame.getHitTestResults(hitTestSource);
    if (results.length > 0) {
      const pose = results[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: 0.02, y: -1.41, z: -2.3, w: 1}

Strahl aus einer XRRigidTransform erzeugen

// Um 90° um die Y-Achse gedreht, 1 m nach rechts versetzt
const angle = Math.PI / 2;
const transform = new XRRigidTransform(
  { x: 1, y: 0, z: 0 },
  { x: 0, y: Math.sin(angle / 2), z: 0, w: Math.cos(angle / 2) }
);

const ray = new XRRay(transform);
const { x, y, z } = ray.direction;
console.log(ray.origin.x, [x, y, z].map((v) => Math.round(v)));

1 [-1, 0, 0]

Ungültige Richtung abfangen

try {
  new XRRay({ x: 0, y: 0, z: 0 }, { x: 0, y: 0, z: 0 });
} catch (err) {
  console.log(err.name);
}

TypeError

// Wichtig · Fallstricke

Kompatibilität: Experimentell und nur in Chromium-Browsern (Chrome, Edge, Chrome für Android, Samsung Internet) verfügbar. Firefox und Safari unterstützen das WebXR Hit Test Module nicht. Vorher mit 'XRRay' in window prüfen.
Nur in sicheren Kontexten (HTTPS) verfügbar. Für Hit-Tests muss die Sitzung mit dem Feature 'hit-test' angefordert werden.
direction wird automatisch normiert. Wer die Länge des übergebenen Vektors als Distanz verwenden will, verliert diese Information.
Ein TypeError wird ausgelöst, wenn origin.w ≠ 1, direction.w ≠ 0 oder die Richtung ein Nullvektor ist.
Ein XRRay ist unveränderlich. Um den Strahl zu ändern, erzeugt man ein neues Objekt. Bei einer bestehenden Hit-Test-Quelle muss man dafür eine neue Quelle anfordern und die alte mit cancel() beenden.
Die Koordinaten beziehen sich immer auf den XRSpace, zu dem der Strahl übergeben wird, und nicht auf Weltkoordinaten.

Siehe auch

XRFrame XRHand XRLayer Serial URL