Signatur
Beschreibung
Die schreibgeschützte Eigenschaft probeSpace eines XRLightProbe-Objekts gibt einen XRSpace zurück. Relativ zu diesem Raum sind die Werte der Lichtschätzung angegeben, also die Richtung des Hauptlichts (primaryLightDirection) und die sphärischen Harmonischen (sphericalHarmonicsCoefficients) in einem XRLightEstimate.
Du brauchst probeSpace, wenn die Lichtdaten in dein Render-Koordinatensystem gehören, meist in einen XRReferenceSpace wie "local" oder "local-floor". Mit XRFrame.getPose(lightProbe.probeSpace, referenceSpace) bekommst du Position und Orientierung der Sonde und kannst damit z. B. die Lichtrichtung umrechnen oder eine Umgebungs-Cubemap (über XRWebGLBinding.getReflectionCubeMap()) richtig ausrichten.
Welche Pose der Raum hat, legt das Gerät fest. Oft stimmt sie mit dem Ursprung der Sitzung überein. Ohne Transformation kannst du dich darauf aber nicht verlassen. Die Pose kann sich während der Sitzung ändern, deshalb fragst du sie am besten in jedem Frame neu ab.
Rückgabewert
XRSpace, der Position und Orientierung der Lichtsonde verfolgt. Er hat keine eigenen Koordinaten. Die Pose bekommst du nur über XRFrame.getPose() relativ zu einem anderen Raum.Beispiele
Lichtsonde anfordern und probeSpace auslesen
const session = await navigator.xr.requestSession('immersive-ar', {
requiredFeatures: ['light-estimation']
});
const lightProbe = await session.requestLightProbe();
console.log(lightProbe.probeSpace instanceof XRSpace);Pose der Lichtsonde in jedem Frame bestimmen
const refSpace = await session.requestReferenceSpace('local');
const onFrame = (time, frame) => {
session.requestAnimationFrame(onFrame);
const probePose = frame.getPose(lightProbe.probeSpace, refSpace);
if (probePose) {
const { position, orientation } = probePose.transform;
console.log('Sonde bei', position.x, position.y, position.z);
console.log('Orientierung', orientation);
}
};
session.requestAnimationFrame(onFrame);Hauptlichtrichtung in den Referenzraum umrechnen
// Einen Vektor mit einem Quaternion drehen (v' = q * v * q⁻¹)
const rotate = (v, q) => {
const ix = q.w * v.x + q.y * v.z - q.z * v.y;
const iy = q.w * v.y + q.z * v.x - q.x * v.z;
const iz = q.w * v.z + q.x * v.y - q.y * v.x;
const iw = -q.x * v.x - q.y * v.y - q.z * v.z;
return {
x: ix * q.w + iw * -q.x + iy * -q.z - iz * -q.y,
y: iy * q.w + iw * -q.y + iz * -q.x - ix * -q.z,
z: iz * q.w + iw * -q.z + ix * -q.y - iy * -q.x
};
};
const onFrame = (time, frame) => {
session.requestAnimationFrame(onFrame);
const estimate = frame.getLightEstimate(lightProbe);
const pose = frame.getPose(lightProbe.probeSpace, refSpace);
if (!estimate || !pose) return;
const dir = rotate(estimate.primaryLightDirection, pose.transform.orientation);
// z. B. an eine Directional Light in three.js übergeben
console.log('Lichtrichtung (Welt):', dir);
};
session.requestAnimationFrame(onFrame);// Wichtig · Fallstricke
- Experimentell: Das WebXR Lighting Estimation Module unterstützen bisher im Wesentlichen Chromium-basierte Browser auf ARCore-fähigen Android-Geräten. Firefox und Safari unterstützen es nicht. Prüfe vorher, ob
session.requestLightProbeexistiert. - Die Sitzung muss mit dem Feature
'light-estimation'angefordert werden (inrequiredFeaturesoderoptionalFeatures). Sonst schlägtrequestLightProbe()fehl. - WebXR funktioniert nur in sicheren Kontexten (HTTPS). Eine Permissions-Policy (
xr-spatial-tracking) kann den Zugriff einschränken. frame.getPose()kannnullzurückgeben, z. B. wenn das Tracking verloren geht. Prüfe den Rückgabewert immer.- Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird still ignoriert, im Strict Mode wirft sie einen
TypeError. - Lichtdaten sind datenschutzrelevant, weil sie Rückschlüsse auf die Umgebung erlauben. Browser können sie deshalb in geringerer Genauigkeit oder zeitverzögert liefern.