Cloud Anchors-Entwicklerleitfaden für Android (Kotlin/Java)

Cloud Anchors in Ihren eigenen Apps verwenden

Voraussetzungen

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

Wenn Sie Cloud Anchors noch nicht kennen:

  • Machen Sie sich mit der Funktionsweise von Ankern und Cloud-Anker vertraut.
  • In der quickstart finden Sie Informationen zu Systemanforderungen, zur Einrichtung und zur Installation.

ARCore API aktivieren

Bevor Sie Cloud Anchors 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 die Cloud Anchors-Funktionen in Ihrer App aktiviert wurden, aktivieren Sie sie in der AR-Sitzungskonfiguration Ihrer App, damit sie mit der ARCore API kommunizieren kann:

Java

Config config = new Config(session);
config.setCloudAnchorMode(Config.CloudAnchorMode.ENABLED);
session.configure(config);

Kotlin

val config = Config(session)
config.cloudAnchorMode = Config.CloudAnchorMode.ENABLED
session.configure(config)

Cloud Anchor hosten

Das Hosting beginnt mit einem Aufruf von hostCloudAnchorAsync(). ARCore lädt visuelle Daten, Gerätepositionen und die Ankerposition in die ARCore API hoch. Die API verarbeitet diese Informationen dann, um eine 3D-Featuremap zu erstellen und schließlich eine eindeutige Cloud Anchor-ID für den Anker an das Gerät zurückzugeben.

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

Ihre App sollte die folgenden Schritte ausführen, um das Hosting eines Cloud Anchor abzuschließen:

  1. Rufen Sie hostCloudAnchorAsync() auf.
  2. Warten Sie auf den Callback oder prüfen Sie regelmäßig den Status „Future“, bis der Vorgang abgeschlossen ist.
  3. Prüfen Sie den Ergebnisstatus, um festzustellen, ob der Vorgang erfolgreich war, oder interpretieren Sie den Fehlercode, wenn er fehlgeschlagen ist.
  4. Geben Sie die resultierende Cloud-Anker-ID für andere Clients frei und verwenden Sie sie, um den Cloud-Anker mit resolveCloudAnchorAsync() aufzulösen.

Kartenqualität von Elementpunkten prüfen

Session.FeatureMapQuality gibt die Qualität der Elementpunkte an, die ARCore in den vorangegangenen Sekunden aus einer bestimmten Kameraposition gesehen hat. Cloud-Anchors, die mit qualitativ höherwertigen Features gehostet werden, werden in der Regel genauer aufgelöst. Verwenden Sie Session.estimateFeatureMapQualityForHosting(), um eine Schätzung der Qualität der Elementkarte für eine bestimmte Kameraposition zu erhalten.

Wert Beschreibung
INSUFFICIENT Die Qualität der Elementpunkte, die in den letzten Sekunden ermittelt wurden, ist gering. Dieser Status deutet darauf hin, dass es in ARCore wahrscheinlich schwieriger ist, den Cloud Anchor aufzulösen. Empfehlen Sie den Nutzenden, das Gerät so zu bewegen, dass die gewünschte Position des Cloud-Ankers, den er hosten möchte, aus verschiedenen Blickwinkeln zu sehen ist.
SUFFICIENT Die Qualität der Merkmalspunkte, die in den vorherigen Sekunden ermittelt wurden, reicht wahrscheinlich aus, damit ARCore einen Cloud Anchor erfolgreich auflösen kann, die Genauigkeit der aufgelösten Pose wird aber wahrscheinlich beeinträchtigt. Empfehlen Sie den Nutzenden, das Gerät so zu bewegen, dass die gewünschte Position des Cloud-Ankers, den er hosten möchte, aus verschiedenen Blickwinkeln zu sehen ist.
GOOD Die Qualität der Featurepunkte, die in den vorangegangenen Sekunden ermittelt wurden, reicht wahrscheinlich aus, damit ARCore einen Cloud Anchor mit einem hohen Maß an Genauigkeit auflösen kann.

Zuvor gehosteten Anker auflösen

Rufen Sie resolveCloudAnchorAsync() auf, um einen gehosteten Cloud-Anker aufzulösen. Die ARCore API vergleicht in regelmäßigen Abständen visuelle Elemente aus der Szene mit der 3D-Kartenfunktion des Ankers, um die Position und Ausrichtung des Nutzers relativ zum Anker genau zu bestimmen. Wenn eine Übereinstimmung gefunden wird, gibt die API die Position des gehosteten Cloud-Ankers zurück.

Sie können Auflösungen für mehrere Cloud-Anker hintereinander initiieren. Es können bis zu 40 Cloud Anchor-Vorgänge gleichzeitig ausgeführt werden.

Vorgang abbrechen oder Cloud Anchor entfernen

Rufen Sie cancel() auf, um einen ausstehenden Cloud Anchor-Vorgang abzubrechen. Rufen Sie detach() auf, um einen bereits aufgelösten Cloud Anchor aus der App zu entfernen.

Ergebnisstatus eines Cloud Anchor-Vorgangs prüfen

Verwenden Sie Anchor.CloudAnchorState, um den Ergebnisstatus des Hosting- oder Auflösungsvorgangs, einschließlich Fehlern, zu prüfen.

Wert Beschreibung
ERROR_CLOUD_ID_NOT_FOUND Die Lösung konnte nicht aufgelöst werden, da die ARCore API die angegebene Cloud Anchor-ID nicht finden konnte.
ERROR_HOSTING_DATASET_PROCESSING_FAILED Das Hosting ist fehlgeschlagen, da der Server das Dataset für den angegebenen Anker nicht verarbeiten konnte. Versuche es noch einmal, wenn das Gerät mehr Daten in der Umgebung erfasst hat.
ERROR_HOSTING_SERVICE_UNAVAILABLE Die ARCore API war nicht erreichbar. Hierfür können verschiedene Ursachen vorliegen. Möglicherweise ist auf dem Gerät der Flugmodus aktiviert oder die Internetverbindung funktioniert nicht. Bei der an den Server gesendeten Anfrage ist möglicherweise eine Zeitüberschreitung aufgetreten, ohne dass eine Antwort erfolgt. Möglicherweise gibt es eine schlechte Netzwerkverbindung, Nichtverfügbarkeit von DNS, Firewallprobleme oder andere Faktoren, die die Verbindung des Geräts zur ARCore API beeinträchtigen können.
ERROR_INTERNAL Eine Hosting- oder Lösungsaufgabe für diesen Anker wurde mit einem internen Fehler beendet. Die App sollte nicht versuchen, diesen Fehler zu beheben.
ERROR_NOT_AUTHORIZED Die von der Anwendung erteilte Autorisierung ist ungültig. Weitere Informationen finden Sie unter Fehlerbehebung bei der ARCore API-Autorisierung.
ERROR_RESOLVING_SDK_VERSION_TOO_NEW Der Cloud-Anker konnte nicht aufgelöst werden, da die SDK-Version, mit der der Anker aufgelöst wurde, neuer und nicht mit der Version kompatibel ist, die zum Hosten des Ankers verwendet wurde.
ERROR_RESOLVING_SDK_VERSION_TOO_OLD Der Cloud-Anker konnte nicht aufgelöst werden, da die SDK-Version, die zum Auflösen des Ankers verwendet wurde, älter und nicht mit der Version kompatibel ist, die zum Hosten des Ankers verwendet wurde.
ERROR_RESOURCE_EXHAUSTED Die Anwendung hat das für das angegebene Google Cloud-Projekt zugewiesene Anfragekontingent aufgebraucht. In der Google Developers Console sollten Sie ein zusätzliches Kontingent für die ARCore API für Ihr Projekt anfordern.
SUCCESS Eine Hosting- oder Lösungsaufgabe für diesen Anker wurde erfolgreich abgeschlossen.

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

Für die ARCore API gelten die folgenden Kontingente für die Anfragebandbreite:

Kontingenttyp Maximum Dauer Gilt für:
Anzahl der Anker Unbegrenzt – Projekt
Anchor-Anfragen für host 30 Minute IP-Adresse und Projekt
resolve für Ankeranzeigen 300 Minute IP-Adresse und Projekt

Best Practices für eine gute Nutzererfahrung

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

  • Warten Sie nach dem Start der Sitzung einige Sekunden, bevor Sie versuchen, einen Anker zu hosten (durch Platzierung eines Objekts usw.). So bleibt etwas Zeit, sich das Tracking zu stabilisieren.
  • Versuchen Sie bei der Auswahl eines Ortes für die Ankeranzeige einen Bereich mit optischen Merkmalen zu finden, die leicht voneinander zu unterscheiden sind. Die besten Ergebnisse erzielen Sie, wenn Sie keine reflektierenden Oberflächen oder Oberflächen ohne optische Elemente wie z. B. leere weiße Wände verwenden.

  • Richten Sie die Kamera auf den gewünschten Mittelpunkt aus und bewegen Sie das Gerät um den Mittelpunkt, um die Umgebung aus verschiedenen Winkeln zu kartieren. Halten Sie dabei ungefähr die gleiche räumliche Distanz ein wie zuvor. So können mehr visuelle Daten erfasst werden und die Auflösung wird zuverlässiger.

  • Achten Sie darauf, dass in der realen Umgebung ausreichend Licht vorhanden ist, wenn Sie Cloud Anchors hosten und auflösen.

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 Anchors nicht gehostet oder aufgelöst werden, da das SDK eine ältere, eingestellte ARCore API verwendet.

Weiteres Vorgehen