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

Cloud-Anker in Ihren eigenen Anwendungen verwenden

Vorbereitung

Machen Sie sich mit den grundlegenden AR-Konzepten vertraut. und Konfigurieren einer ARCore-Sitzung beschrieben, bevor du fortfährst.

Wenn Sie Cloud-Anker noch nicht kennen:

ARCore API aktivieren

Bevor Sie Cloud-Markierungen 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:

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 Anruf bei hostCloudAnchorAsync(). ARCore lädt visuelle Daten sowie Gerätepositionen und Ankerpositionen in die ARCore API hoch. Die API verarbeitet diese Informationen dann, um eine 3D-Feature-Map zu erstellen, und gibt schließlich eine eindeutige Cloud-Anchor-ID für den Anker an das Gerät zurück.

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

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

  1. Rufen Sie hostCloudAnchorAsync() auf.
  2. Warten Sie auf den Callback oder prüfen Sie den Status „Future“ kontinuierlich, bis er abgeschlossen ist.
  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 resolveCloudAnchorAsync()

Kartierungsqualität von Featurepunkten prüfen

Session.FeatureMapQuality gibt die Qualität der Merkmals-/Markierungspunkte an, die ARCore in den letzten Sekunden aus einer bestimmten Kamerapose gesehen hat. Cloud Anchors, die mithilfe von Funktionen höherer Qualität gehostet werden, werden im Allgemeinen genauer aufgelöst. Verwenden Sie Session.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 ermittelten Merkmalspunkte ist niedrig. Dieser Status bedeutet, dass ARCore wahrscheinlich mehr Schwierigkeiten beim Auflösen des Cloud-Ankers haben wird. Ermutigen Sie den Nutzer, das Gerät so zu bewegen, dass die gewünschte Position des Cloud-Ankers, 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. Ermutigen Sie den Nutzer, das Gerät so zu bewegen, dass die gewünschte Position des Cloud-Ankers, den er hosten möchte, aus verschiedenen Blickwinkeln betrachtet werden kann.
GOOD Die Qualität der in den letzten Sekunden anhand der Positionsbestimmung ermittelten Merkmals-Punkte ist wahrscheinlich ausreichend, damit ARCore einen Cloud-Anker mit hoher Genauigkeit ermitteln kann.

Zuvor gehostete Ankeranzeigen auflösen

Rufen Sie resolveCloudAnchorAsync() an, um einen gehosteten Cloud-Anchor aufzulösen. Die ARCore API vergleicht regelmäßig visuelle Merkmale aus der Szene mit der 3D-Merkmalkarte des Ankers, um die Position und Ausrichtung des Nutzers relativ zum Anker zu ermitteln. 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 Cloud Anchor-Vorgänge gleichzeitig ausgeführt werden.

Vorgang abbrechen oder Cloud-Anker entfernen

Rufen Sie cancel() auf, um einen ausstehenden Cloud-Anchor-Vorgang abzubrechen. Rufen Sie detach() auf, um einen bereits behobenen Cloud-Anchor aus der Anwendung 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 überprüfen.

Wert Beschreibung
ERROR_CLOUD_ID_NOT_FOUND Der Vorgang konnte nicht behoben 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 erfolgreich verarbeiten konnte. Versuchen Sie es noch einmal, wenn das Gerät mehr Daten aus der Umgebung erfasst hat.
ERROR_HOSTING_SERVICE_UNAVAILABLE Die ARCore API war nicht erreichbar. Hierfür können verschiedene Ursachen vorliegen. Möglicherweise befindet sich das Gerät im Flugmodus oder verfügt nicht über eine funktionierende Internetverbindung. 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.
ERROR_INTERNAL Eine Hosting- oder Auflösungsaufgabe für diesen Anker wurde mit einem internen Fehler abgeschlossen. Die App sollte nicht versuchen, diesen Fehler zu beheben.
ERROR_NOT_AUTHORIZED Die von der Anwendung bereitgestellte Autorisierung ist ungültig. Weitere Informationen finden Sie unter Fehlerbehebung bei der ARCore API-Autorisierung.
ERROR_RESOLVING_SDK_VERSION_TOO_NEW Der Cloud-Anchor konnte nicht aufgelöst werden, da die SDK-Version, die zum Auflösen des Anchors verwendet wurde, neuer ist als die Version, die zum Hosten verwendet wurde, und nicht mit dieser kompatibel ist.
ERROR_RESOLVING_SDK_VERSION_TOO_OLD Cloud Anchor konnte nicht aufgelöst werden, da die SDK-Version, die zum Auflösen des Ankers verwendet wurde, älter als die Version ist, die zum Hosten verwendet wurde, und damit nicht kompatibel ist.
ERROR_RESOURCE_EXHAUSTED 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 Auflösungsaufgabe für diesen Anker 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
host-Anfragen verankern 30 Minute IP-Adresse und Projekt
Anfragen an Anchor bearbeiten 300 Minute IP-Adresse und Projekt

Best Practices für eine positive Nutzererfahrung

Bitten Sie die Nutzer, Folgendes zu tun, um für eine gute Nutzererfahrung mit Ihrer App zu sorgen:

  • Warten Sie nach dem Start der Sitzung einige Sekunden, bevor Sie versuchen, einen Anchor zu hosten (durch Platzieren eines Objekts usw.). Dadurch hat das Tracking etwas Zeit, sich zu stabilisieren.
  • Versuchen Sie bei der Auswahl eines Standorts, an dem der Anker platziert werden soll, einen Bereich mit optischen Merkmalen, die leicht voneinander zu unterscheiden sind. 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 Beleuchtung in der realen Umgebung für das Hosten und Auflösen der Cloud-Anker ausreicht.

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