XRFrame.getDepthInformation() — Methode · JavaScript-Referenz

Signatur

XRFrame.prototype.getDepthInformation(view)

Beschreibung

getDepthInformation() ist Teil des WebXR Depth Sensing Module. Die Methode gibt für eine bestimmte Ansicht (XRView) die vom Gerät geschätzten Entfernungen zur realen Umgebung zurück. Damit lassen sich in AR-Anwendungen z. B. Verdeckungen (virtuelle Objekte verschwinden hinter echten Möbeln), physikalische Kollisionen oder einfache Entfernungsmessungen umsetzen.

Die Methode steht nur zur Verfügung, wenn die Sitzung mit dem Feature "depth-sensing" angefordert wurde und der Browser die Nutzung "cpu-optimized" gewählt hat (session.depthUsage). Bei "gpu-optimized" verwendet man stattdessen XRWebGLBinding.getDepthInformation(), das eine WebGL-Textur liefert.

Das zurückgegebene XRCPUDepthInformation-Objekt enthält den Rohpuffer (data), dessen Maße (width, height), den Umrechnungsfaktor rawValueToMeters, die Transformation normDepthBufferFromNormView sowie die bequeme Methode getDepthInMeters(x, y), die normalisierte Ansichtskoordinaten (0–1) direkt in Meter umrechnet.

Aufgerufen werden darf die Methode nur innerhalb des requestAnimationFrame()-Callbacks, solange der Frame aktiv und animiert ist. Die Daten gelten ausschließlich für diesen Frame.

Parameter

Name	Typ	Default	Beschreibung
$view Pflicht	XRView		Die Ansicht, für die Tiefendaten abgefragt werden – typischerweise ein Eintrag aus `frame.getViewerPose(refSpace).views`. Muss zum selben Frame gehören.

Rückgabewert

Typ

XRCPUDepthInformation | null

Beschreibung

Ein XRCPUDepthInformation-Objekt mit den Tiefendaten der Ansicht oder null, wenn für diesen Frame (noch) keine Tiefendaten vorliegen. Wirft NotSupportedError, wenn "depth-sensing" nicht aktiviert ist oder die Sitzung nicht "cpu-optimized" nutzt, sowie InvalidStateError, wenn der Frame nicht aktiv/animiert ist oder die View nicht zum Frame gehört.

Beispiele

AR-Sitzung mit CPU-Tiefendaten anfordern

const session = await navigator.xr.requestSession('immersive-ar', {
  requiredFeatures: ['depth-sensing'],
  depthSensing: {
    usagePreference: ['cpu-optimized', 'gpu-optimized'],
    dataFormatPreference: ['luminance-alpha', 'float32']
  }
});

console.log('Nutzung:', session.depthUsage);
console.log('Format:', session.depthDataFormat);

Nutzung: cpu-optimized Format: luminance-alpha

Entfernung in der Bildmitte pro Frame messen

const refSpace = await session.requestReferenceSpace('local');

const onFrame = (time, frame) => {
  session.requestAnimationFrame(onFrame);
  const pose = frame.getViewerPose(refSpace);
  if (!pose) return;

  for (const view of pose.views) {
    const depth = frame.getDepthInformation(view);
    if (!depth) continue; // noch keine Daten

    // Normalisierte Koordinaten: 0.5/0.5 = Bildmitte
    const meters = depth.getDepthInMeters(0.5, 0.5);
    console.log(`Abstand zur Mitte: ${meters.toFixed(2)} m`);
  }
};

session.requestAnimationFrame(onFrame);

Abstand zur Mitte: 1.37 m

Rohpuffer auswerten (nächster Punkt im Bild)

const findNearest = (depth, format) => {
  const values = format === 'float32'
    ? new Float32Array(depth.data)
    : new Uint16Array(depth.data); // luminance-alpha: 16 Bit pro Pixel

  let min = Infinity;
  for (const raw of values) {
    if (raw > 0 && raw < min) min = raw; // 0 = ungültig
  }
  return min * depth.rawValueToMeters;
};

const onFrame = (time, frame) => {
  session.requestAnimationFrame(onFrame);
  const view = frame.getViewerPose(refSpace)?.views[0];
  const depth = view && frame.getDepthInformation(view);
  if (depth) {
    console.log(`${depth.width}x${depth.height}, nächstes Objekt: ${findNearest(depth, session.depthDataFormat).toFixed(2)} m`);
  }
};
session.requestAnimationFrame(onFrame);

160x90, nächstes Objekt: 0.42 m

// Wichtig · Fallstricke

Experimentell: Derzeit praktisch nur in Chromium-Browsern auf Android mit ARCore-fähigen Geräten verfügbar; Firefox und Safari unterstützen die Methode nicht. Vorher per navigator.xr.isSessionSupported('immersive-ar') und Feature-Anfrage prüfen – am besten "depth-sensing" als optionalFeatures anfordern und Fallback vorsehen.
Nur bei session.depthUsage === "cpu-optimized" nutzbar, sonst NotSupportedError. Für GPU-Tiefendaten XRWebGLBinding.getDepthInformation() verwenden.
Nur innerhalb des requestAnimationFrame-Callbacks aufrufen; das Objekt außerhalb des Frames zu speichern und später zu nutzen führt zu InvalidStateError bzw. veralteten Daten.
Rückgabewert kann null sein (z. B. in den ersten Frames) – immer prüfen.
getDepthInMeters() erwartet normalisierte Ansichtskoordinaten (0–1), keine Pixel. Beim direkten Lesen von data muss normDepthBufferFromNormView berücksichtigt werden, da Puffer und Ansicht gedreht/gespiegelt sein können.
Performance: Das Durchlaufen des gesamten Puffers pro Frame ist teuer; nur benötigte Punkte abfragen oder Arbeit in einen Worker auslagern.
Datenschutz: Tiefendaten verraten Details der Umgebung des Nutzers; die Sitzung erfordert eine Nutzerzustimmung und einen sicheren Kontext (HTTPS).

Siehe auch

XRFrame XRCPUDepthInformation XRCPUDepthInformation.getDepthInMeters() XRDepthInformation XRWebGLBinding.getDepthInformation() XRFrame.getViewerPose() XRSession.depthUsage XRSystem.requestSession()