XRFrame.getLightEstimate() — Methode · JavaScript-Referenz

Signatur

XRFrame.prototype.getLightEstimate(lightProbe)

Beschreibung

Mit getLightEstimate() fragt man in einer AR-Sitzung ab, wie die reale Umgebung gerade beleuchtet ist. Das zurückgegebene XRLightEstimate enthält sphärische Harmonische für das Umgebungslicht (sphericalHarmonicsCoefficients), die Richtung des stärksten Lichts (primaryLightDirection) und dessen Intensität (primaryLightIntensity). Diese Werte kann man an die Materialien und Lichtquellen der eigenen 3D-Szene übergeben, damit virtuelle Objekte zur realen Umgebung passen.

Voraussetzung ist eine immersive-ar-Sitzung, bei der das Feature "light-estimation" angefordert wurde. Anschließend erzeugt man über XRSession.requestLightProbe() einmalig eine XRLightProbe und ruft in jedem Frame-Callback von requestAnimationFrame() die Methode frame.getLightEstimate(probe) auf.

Die Methode kann null zurückgeben, zum Beispiel direkt nach Sitzungsstart, solange das Gerät noch keine Schätzung berechnet hat. Solche Frames sollte man überspringen oder die letzte gültige Schätzung weiterverwenden.

Parameter

Name	Typ	Default	Beschreibung
$lightProbe Pflicht	XRLightProbe		Die Lichtsonde, die zuvor über `XRSession.requestLightProbe()` für dieselbe Sitzung erzeugt wurde.

Rückgabewert

Typ

XRLightEstimate | null

Beschreibung

Ein XRLightEstimate mit den Beleuchtungswerten für den aktuellen Frame, oder null, wenn noch keine Schätzung verfügbar ist.

Beispiele

AR-Sitzung mit Lichtschätzung starten

const startAR = async () => {
  if (!(await navigator.xr?.isSessionSupported('immersive-ar'))) {
    console.warn('AR wird nicht unterstützt');
    return;
  }
  const session = await navigator.xr.requestSession('immersive-ar', {
    requiredFeatures: ['light-estimation']
  });
  const probe = await session.requestLightProbe();
  const refSpace = await session.requestReferenceSpace('local');

  const onFrame = (time, frame) => {
    session.requestAnimationFrame(onFrame);
    const estimate = frame.getLightEstimate(probe);
    if (!estimate) return; // noch keine Schätzung
    const { x, y, z } = estimate.primaryLightDirection;
    console.log('Hauptlicht aus Richtung:', x.toFixed(2), y.toFixed(2), z.toFixed(2));
  };
  session.requestAnimationFrame(onFrame);
};

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

Hauptlicht aus Richtung: 0.31 0.89 -0.33

Gerichtetes Licht in three.js anpassen

// light: THREE.DirectionalLight, probe: XRLightProbe
const applyEstimate = (frame, probe, light) => {
  const estimate = frame.getLightEstimate(probe);
  if (!estimate) return;

  const dir = estimate.primaryLightDirection;
  const int = estimate.primaryLightIntensity;

  // Licht kommt aus dir -> Position entlang dieser Richtung
  light.position.set(dir.x, dir.y, dir.z).multiplyScalar(10);

  // Intensität (RGB) als Farbe + Helligkeit übernehmen
  const max = Math.max(int.x, int.y, int.z, 1e-4);
  light.color.setRGB(int.x / max, int.y / max, int.z / max);
  light.intensity = max;
};

Umgebungslicht aus sphärischen Harmonischen

const updateAmbient = (frame, probe, lightProbe3D) => {
  const estimate = frame.getLightEstimate(probe);
  if (!estimate) return;

  // 9 Koeffizienten × RGB = Float32Array(27)
  const sh = estimate.sphericalHarmonicsCoefficients;
  console.log('SH-Werte:', sh.length);
  lightProbe3D.sh.fromArray(sh); // z. B. THREE.LightProbe
};

SH-Werte: 27

// Wichtig · Fallstricke

Experimentell: Die Methode wird derzeit nur von Chromium-basierten Browsern auf Android (ARCore) unterstützt. Firefox und Safari bieten sie nicht an. Vor der Nutzung sollte man per Feature-Erkennung prüfen, z. B. mit 'getLightEstimate' in XRFrame.prototype.
Ohne das Feature "light-estimation" in requiredFeatures oder optionalFeatures schlägt requestLightProbe() fehl.
Die Methode wirft einen InvalidStateError, wenn der Frame nicht aktiv ist (Aufruf außerhalb des requestAnimationFrame-Callbacks) oder wenn die Sonde zu einer anderen Sitzung gehört.
Der Rückgabewert kann null sein. Prüfe ihn deshalb immer, bevor du auf Eigenschaften zugreifst.
Nur in sicheren Kontexten (HTTPS) verfügbar. Die Berechtigung kann über die Permissions-Policy xr-spatial-tracking eingeschränkt werden.
Datenschutz: Die Beleuchtungswerte werden vom Browser absichtlich gerundet oder zeitlich geglättet, damit sich daraus keine Rückschlüsse auf die Umgebung des Nutzers ziehen lassen.

Siehe auch

XRFrame XRLightEstimate XRLightProbe XRSession.requestLightProbe() XRSession.requestAnimationFrame() XRWebGLBinding.getReflectionCubeMap()