Cloud Anchors-Entwicklerleitfaden für Unity (AR Foundation)

Weitere Informationen zur Verwendung von Cloud-Ankern in Ihren eigenen Apps

Voraussetzungen

Machen Sie sich mit den grundlegenden AR-Konzepten und der Konfiguration einer ARCore-Sitzung vertraut, bevor Sie fortfahren.

Wenn Sie Cloud-Anker noch nicht kennen, sollten Sie sich mit der Funktionsweise von Ankern und Cloud-Ankern vertraut machen.

ARCore API aktivieren

Bevor Sie Cloud-Anker in Ihrer App verwenden können, müssen Sie zuerst die ARCore API in Ihrer App aktivieren.

Cloud Anchor-Funktionen in der Sitzungskonfiguration aktivieren

Nachdem Sie die Cloud Anchors-Funktion in Ihrer App aktiviert haben, müssen Sie die Cloud Anchors-Funktionen in der AR-Sitzungskonfiguration Ihrer App aktivieren, damit sie mit der ARCore API kommunizieren kann:

Cloud-Anchor hosten

Das Hosting beginnt mit einem Aufruf von ARAnchorManager.HostCloudAnchorAsync(). ARCore lädt visuelle Daten, Gerätepose und die Ankerpose in die ARCore API hoch. Die API verarbeitet diese Informationen dann, um eine 3D-Featurekarte zu erstellen, und gibt schließlich eine eindeutige Cloud Anchor-ID für den Anker zurück.

Sie können die Lebensdauer eines gehosteten Ankers auch mit der ARCore Cloud Anchor Management API verlängern.

Ihre Anwendung sollte folgendermaßen vorgehen, um das Hosting eines Cloud-Ankers abzuschließen:

  1. Rufen Sie ARAnchorManager.HostCloudAnchorAsync() auf.
  2. Starten Sie eine Koroutine, um zu warten, bis das Promise ein Ergebnis liefert. Weitere Informationen finden Sie unter Coroutinen in Unity.
  3. Prüfen Sie den Ergebnisstatus, um festzustellen, ob der Vorgang erfolgreich war, oder interpretieren Sie den Fehlercode, falls er fehlgeschlagen ist.
  4. Geben Sie die Cloud Anchor-ID des Ergebnisses für andere Clients frei und verwenden Sie sie, um den Cloud Anchor mit ARAnchorManagerExtensions.ResolveCloudAnchorAsync() aufzulösen.

Kartierungsqualität von Featurepunkten prüfen

ARCoreExtensions.FeatureMapQuality gibt die Qualität der Merkmals-/Markierungspunkte an, die ARCore in den letzten Sekunden aus einer bestimmten Kamerapose gesehen hat. Cloud-Anchors, die mit Funktionen höherer Qualität gehostet werden, werden im Allgemeinen genauer aufgelöst. Verwenden Sie ARAnchorManagerExtensions.EstimateFeatureMapQualityForHosting(), um eine Schätzung der Qualität der Feature-Map für eine bestimmte Kameraposition zu erhalten.

Wert Beschreibung
Insufficient Die Qualität der in den letzten Sekunden anhand der Pose erkannten Markierungen ist niedrig. Dieser Status weist darauf hin, dass ARCore wahrscheinlich mehr Schwierigkeiten hat, den Cloud-Anker zu finden. Bitten Sie den Nutzer, das Gerät so zu bewegen, dass die gewünschte Position des Cloud-Ankerpunkts, den er hosten möchte, aus verschiedenen Blickwinkeln betrachtet werden kann.
Sufficient Die Qualität der in den letzten Sekunden anhand der Pose ermittelten Merkmals- und Positionsdaten ist wahrscheinlich ausreichend, damit ARCore einen Cloud-Anker erfolgreich auflösen kann. Die Genauigkeit der aufgelösten Pose wird jedoch wahrscheinlich reduziert. Bitten Sie den Nutzer, das Gerät so zu bewegen, dass die gewünschte Position des Cloud-Ankerpunkts, den er hosten möchte, aus verschiedenen Blickwinkeln betrachtet werden kann.
Good Die Qualität der in den letzten Sekunden ermittelten Funktionspunkte reicht wahrscheinlich aus, damit ein Cloud-Anker mit hoher Genauigkeit mit ARCore aufgelöst werden kann.

Zuvor gehosteten Anker auflösen

Rufen Sie ARAnchorManagerExtensions.ResolveCloudAnchorAsync() an, um einen gehosteten Cloud-Anchor aufzulösen. Die ARCore API vergleicht die visuellen Elemente in der Umgebung regelmäßig mit der 3D-Funktionskarte des Ankers, um die Position und Ausrichtung des Nutzers relativ zum Anker zu bestimmen. Wenn eine Übereinstimmung gefunden wird, gibt die API die Pose des gehosteten Cloud-Anker zurück.

Sie können Auflösungen für mehrere Cloud-Anchors nacheinander initiieren. Es können bis zu 40 gleichzeitige Cloud Anchor-Vorgänge vorhanden sein.

Vorgang abbrechen oder Cloud-Anker entfernen

ARCloudAnchor.OnDestroy() wird automatisch aufgerufen, wenn die ARCloudAnchor-Komponente aus dem Game-Objekt entfernt wird, das sie enthält. Dadurch wird das zugrunde liegende native Cloud Anchor-Objekt getrennt und freigegeben.

Ergebnisstatus eines Cloud Anchor-Vorgangs prüfen

Mit CloudAnchorState können Sie den Ergebnisstatus des Hosting- oder Auflösungsvorgangs prüfen, einschließlich Fehlern.

Wert Beschreibung
ErrorResolvingCloudIdNotFound Die Auflösung ist fehlgeschlagen, da die ARCore API die angegebene Cloud Anchor-ID nicht finden konnte.
ErrorHostingDatasetProcessingFailed Das Hosting ist fehlgeschlagen, weil der Server den Datensatz für den angegebenen Anker nicht verarbeiten konnte. Versuchen Sie es noch einmal, wenn das Gerät mehr Daten aus der Umgebung erfasst hat.
ErrorHostingServiceUnavailable Die ARCore API war nicht erreichbar. Hierfür können verschiedene Ursachen vorliegen. Das Gerät befindet sich möglicherweise im Flugmodus oder es ist keine Internetverbindung vorhanden. Die an den Server gesendete Anfrage ist möglicherweise abgelaufen, ohne dass eine Antwort zurückgegeben wurde. Möglicherweise gibt es eine schlechte Netzwerkverbindung, DNS-Nichtverfügbarkeit, Firewallprobleme oder andere Probleme, die die Fähigkeit des Geräts beeinträchtigen, eine Verbindung zur ARCore API herzustellen.
ErrorInternal Eine Hosting- oder Auflösungsaufgabe für diesen Anker wurde mit einem internen Fehler abgeschlossen. Die App sollte nicht versuchen, diesen Fehler zu beheben.
ErrorNotAuthorized Die App kann aufgrund einer ungültigen Autorisierung nicht mit der ARCore API kommunizieren. Prüfen Sie unter Projekteinstellungen > XR > ARCore-Erweiterungen, ob eine gültige Autorisierungsstrategie vorhanden ist.
ErrorResolvingPackageTooNew Cloud Anchor konnte nicht aufgelöst werden, da das zur Auflösung von Cloud Anchor verwendete ARCore-Erweiterungspaket neuer als die Version, die zum Hosten verwendet wird, und nicht mit ihr kompatibel ist.
ErrorResolvingPackageTooOld Cloud Anchor konnte nicht aufgelöst werden, da das zur Auflösung von Cloud Anchor verwendete ARCore-Erweiterungspaket älter als die Version ist, die zum Hosten verwendet wird, und mit dieser nicht kompatibel ist.
ErrorResourceExhausted Die Anwendung hat das dem betreffenden Google Cloud-Projekt zugewiesene Anfragekontingent aufgebraucht. Sie sollten in der Google Developers Console ein zusätzliches Kontingent für die ARCore API für Ihr Projekt anfordern.
Success Eine Hosting- oder Aufklärungsaufgabe für diesen Anchor wurde erfolgreich abgeschlossen.

API-Kontingente für Host- und Auflösungsanfragen

Bei der ARCore API gelten die folgenden Kontingente für die Anfragebandbreite:

Kontingenttyp Maximum Dauer Gilt für
Anzahl der Anker Unbegrenzt – Projekt
Anfragen an Host anpinnen 30 Minute IP-Adresse und Projekt
Anfragen an Anchor bearbeiten 300 Minute IP-Adresse und Projekt

Best Practices für eine gute User Experience

Bitten Sie die Nutzer, Folgendes zu tun, um eine gute Nutzererfahrung mit Ihrer App zu gewährleisten:

  • Warten Sie nach Beginn der Sitzung einige Sekunden, bevor Sie versuchen, einen Anker zu hosten, indem Sie beispielsweise ein Objekt platzieren. So hat das Tracking Zeit, sich zu stabilisieren.
  • Wählen Sie einen Ort für den Anker aus, der visuelle Merkmale aufweist, die sich leicht voneinander unterscheiden lassen. Die besten Ergebnisse erzielen Sie, wenn Sie keine reflektierenden Oberflächen oder Oberflächen ohne visuelle Merkmale wie weiße Wände verwenden.

  • Richten Sie die Kamera auf den Mittelpunkt und bewegen Sie das Gerät um ihn herum, um die Umgebung aus verschiedenen Blickwinkeln zu erfassen. Halten Sie dabei ungefähr denselben Abstand. So können Sie mehr visuelle Daten erfassen und die Auflösung wird robuster.

  • Achten Sie darauf, dass die Umgebung beim Hosten und Auflösen von Cloud-Anchors ausreichend beleuchtet ist.

Einstellungsrichtlinie

  • Apps, die mit dem ARCore SDK 1.12.0 oder höher erstellt wurden, unterliegen der Richtlinie zur Einstellung der Cloud Anchor API.
  • Bei Apps, die mit dem ARCore SDK 1.11.0 oder niedriger erstellt wurden, können Cloud-Anker nicht gehostet oder aufgelöst werden, da das SDK eine ältere, nicht mehr unterstützte ARCore API verwendet.

Nächste Schritte