Signatur
Beschreibung
Die schreibgeschützte Eigenschaft direction der Schnittstelle XRRay gibt an, in welche Richtung ein Strahl im 3D-Raum zeigt. Zusammen mit XRRay.origin (dem Startpunkt) beschreibt sie den Strahl vollständig. Der Wert ist ein DOMPointReadOnly, dessen Komponenten x, y und z einen Einheitsvektor bilden. Die Komponente w ist immer 0, weil es sich um eine Richtung und nicht um einen Punkt handelt.
Übergibt man dem Konstruktor new XRRay(origin, direction) einen nicht normalisierten Vektor, normalisiert der Browser ihn automatisch. Aus {x: 3, y: 0, z: 4} wird also {x: 0.6, y: 0, z: 0.8}. Ohne Angabe zeigt der Strahl standardmäßig entlang der negativen Z-Achse: {x: 0, y: 0, z: -1, w: 0}. Das ist in WebXR die Blickrichtung „nach vorn“.
In der Praxis braucht man direction vor allem beim Hit-Testing in AR-Sitzungen. Ein XRRay wird dort als offsetRay an XRSession.requestHitTestSource() übergeben, um relativ zu einem Raum (etwa dem Viewer-Raum) gezielt schräg oder nach unten zu testen. Außerdem kann man mit origin + t · direction beliebige Punkte entlang des Strahls berechnen, zum Beispiel für eigene Schnittberechnungen oder um einen Laserpointer zu zeichnen.
Rückgabewert
x, y und z einen normalisierten Richtungsvektor (Länge 1,0) bilden. w ist immer 0.Beispiele
Standardrichtung eines Strahls auslesen
// Ohne Argumente: Ursprung (0,0,0), Richtung entlang -Z
const ray = new XRRay();
const { x, y, z, w } = ray.direction;
console.log(x, y, z, w);Automatische Normalisierung der Richtung
const ray = new XRRay(
{ x: 0, y: 1.6, z: 0, w: 1 }, // Ursprung auf Augenhöhe
{ x: 3, y: 0, z: 4, w: 0 } // nicht normalisierte Richtung
);
const d = ray.direction;
const length = Math.hypot(d.x, d.y, d.z);
console.log(d.x.toFixed(2), d.y.toFixed(2), d.z.toFixed(2));
console.log('Länge:', length.toFixed(2));Punkt in bestimmter Entfernung entlang des Strahls berechnen
// Punkt = origin + t * direction
const pointAlongRay = (ray, t) => ({
x: ray.origin.x + ray.direction.x * t,
y: ray.origin.y + ray.direction.y * t,
z: ray.origin.z + ray.direction.z * t
});
const ray = new XRRay({ x: 0, y: 1, z: 0 }, { x: 0, y: -1, z: -1 });
console.log(pointAlongRay(ray, 2));Hit-Test mit schräg nach unten geneigtem offsetRay
const startAR = async () => {
const session = await navigator.xr.requestSession('immersive-ar', {
requiredFeatures: ['hit-test']
});
const viewerSpace = await session.requestReferenceSpace('viewer');
// Etwas unterhalb der Blickrichtung testen
const offsetRay = new XRRay({}, { x: 0, y: -0.5, z: -1 });
console.log('Testrichtung:', offsetRay.direction.y.toFixed(3), offsetRay.direction.z.toFixed(3));
const hitTestSource = await session.requestHitTestSource({
space: viewerSpace,
offsetRay
});
return { session, hitTestSource };
};
startAR().catch(console.error);// Wichtig · Fallstricke
- Schreibgeschützt: Weder
directionnoch die Komponenten desDOMPointReadOnlylassen sich ändern. Für eine neue Richtung erzeugt man einen neuenXRRay. - Ungültige Richtungen: Der Konstruktor wirft einen
TypeError, wennx,yundzalle0sind oder wenndirection.wnicht0ist. Umgekehrt mussorigin.wden Wert1haben. - Koordinatensystem: Die Richtung bezieht sich immer auf den Referenzraum, in dem der Strahl verwendet wird, etwa den
spacebeirequestHitTestSource(). Sie ist keine Angabe in Weltkoordinaten. - Gleitkomma: Nach der Normalisierung können kleine Rundungsfehler auftreten. Werte sollte man deshalb mit einer Toleranz vergleichen, nicht mit
===. - Kompatibilität:
XRRaygehört zum experimentellen WebXR Hit Test Module. Unterstützt wird es im Wesentlichen von Chromium-basierten Browsern (Chrome für Android, Samsung Internet, Meta Quest Browser), nicht von Firefox und Safari. Die API funktioniert nur in sicheren Kontexten (HTTPS). Vor der Nutzung sollte man per'XRRay' in windowprüfen, ob sie verfügbar ist.