XRFrame.trackedAnchors — Eigenschaft · JavaScript-Referenz

Signatur

XRFrame.trackedAnchors

Beschreibung

Die Eigenschaft trackedAnchors des XRFrame-Interfaces gibt ein XRAnchorSet zurück. Das ist ein Set-ähnliches Objekt mit allen XRAnchor-Objekten, die das Gerät im aktuellen Animations-Frame noch verfolgt. Anker sind feste Punkte in der realen Welt, zum Beispiel ein virtuelles Objekt auf einem Tisch. Das XR-System gleicht ihre Position laufend an, wenn es die Umgebung besser erkennt.

Man nutzt trackedAnchors typischerweise in der Render-Schleife, die mit XRSession.requestAnimationFrame() läuft. Für jeden verfolgten Anker holt man mit frame.getPose(anchor.anchorSpace, referenceSpace) die aktuelle Pose und setzt damit das zugehörige 3D-Objekt neu. Anker, die nicht mehr im Set stehen, hat das System verloren. Die dazugehörigen Inhalte sollte man ausblenden oder entfernen.

Damit die Eigenschaft funktioniert, muss die Sitzung mit dem Feature "anchors" angefordert werden, zum Beispiel über requiredFeatures oder optionalFeatures in navigator.xr.requestSession(). Anker selbst legt man mit XRFrame.createAnchor() oder XRHitTestResult.createAnchor() an.

Rückgabewert

Typ

XRAnchorSet

Beschreibung

Ein schreibgeschütztes, Set-ähnliches Objekt (forEach(), has(), size, Iteration mit for...of) mit allen XRAnchor-Objekten, die in diesem Frame verfolgt werden.

Beispiele

AR-Sitzung mit Anker-Unterstützung starten

const startAR = async () => {
  if (!navigator.xr || !(await navigator.xr.isSessionSupported('immersive-ar'))) {
    console.log('Immersive AR wird nicht unterstützt');
    return;
  }
  // Das Feature "anchors" ist Voraussetzung für trackedAnchors
  const session = await navigator.xr.requestSession('immersive-ar', {
    requiredFeatures: ['anchors', 'local']
  });
  const refSpace = await session.requestReferenceSpace('local');
  console.log('Sitzung gestartet', session, refSpace);
};

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

Sitzung gestartet XRSession {...} XRReferenceSpace {...}

Verfolgte Anker in der Render-Schleife aktualisieren

// anchorObjects: Map<XRAnchor, { visible: boolean, matrix: Float32Array | null }>
const anchorObjects = new Map();

const onXRFrame = (time, frame) => {
  const session = frame.session;
  session.requestAnimationFrame(onXRFrame);

  const tracked = frame.trackedAnchors;

  // Verlorene Anker ausblenden
  for (const [anchor, obj] of anchorObjects) {
    if (!tracked.has(anchor)) {
      obj.visible = false;
    }
  }

  // Posen der verfolgten Anker übernehmen
  for (const anchor of tracked) {
    const pose = frame.getPose(anchor.anchorSpace, refSpace);
    const obj = anchorObjects.get(anchor);
    if (pose && obj) {
      obj.visible = true;
      obj.matrix = pose.transform.matrix;
    }
  }
};

session.requestAnimationFrame(onXRFrame);

Anker anlegen und Anzahl der verfolgten Anker ausgeben

const placeAnchor = async (frame, refSpace) => {
  // Anker 1 m vor dem Ursprung des Referenzraums
  const pose = new XRRigidTransform({ x: 0, y: 0, z: -1 });
  const anchor = await frame.createAnchor(pose, refSpace);
  anchorObjects.set(anchor, { visible: true, matrix: null });
};

const logAnchors = (time, frame) => {
  frame.session.requestAnimationFrame(logAnchors);
  console.log(`Verfolgte Anker: ${frame.trackedAnchors.size}`);
};

Verfolgte Anker: 1

// Wichtig · Fallstricke

Experimentell: Das WebXR Anchors Module ist bisher nur ein Entwurf. Unterstützt wird es vor allem von Chrome für Android mit ARCore. Firefox und Safari unterstützen es nicht. Vor der Nutzung sollte man per Feature-Erkennung prüfen, ob es verfügbar ist, zum Beispiel mit 'trackedAnchors' in XRFrame.prototype.
Ohne das Feature "anchors" beim Start der Sitzung ist die Eigenschaft leer oder nicht nutzbar.
Ein XRFrame ist nur während des Callbacks von requestAnimationFrame() aktiv. Wer trackedAnchors außerhalb davon abfragt, zum Beispiel nach einem await, bekommt eine InvalidStateError-Ausnahme.
Ein Anker kann zeitweise aus dem Set verschwinden, wenn das Tracking verloren geht, und später wieder auftauchen. Die zugehörigen Inhalte sollte man deshalb nicht sofort löschen, sondern nur ausblenden.
Einen Anker, der nicht mehr gebraucht wird, gibt man mit XRAnchor.delete() frei. Das spart Rechenleistung beim Tracking.
Die API gibt es nur in sicheren Kontexten (HTTPS). Außerdem kann eine Permissions Policy (xr-spatial-tracking) sie einschränken.

Siehe auch

XRFrame XRAnchorSet XRAnchor XRFrame.createAnchor() XRFrame.getPose() XRHitTestResult.createAnchor() XRSession.requestAnimationFrame()