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:
- Rufen Sie
hostCloudAnchorAsync()
auf. - Warten Sie auf den Callback oder prüfen Sie regelmäßig den Status „Future“, bis der Vorgang abgeschlossen ist.
- Prüfen Sie den Ergebnisstatus, um festzustellen, ob der Vorgang erfolgreich war, oder interpretieren Sie den Fehlercode, wenn er fehlgeschlagen ist.
- 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
- Erstellen Sie eine Cloud Anchors App mit dem ARCore-Codelab zu Cloud Anchors mit persistentem Cloud Anchors.
- Gehen Sie die Schritte zum Hosten und Auflösen von Cloud-Ankern anhand von zwei Beispielanwendungen in der Kurzanleitung zu Cloud-Ankern durch.
- Mit der Cloud Anchors Management API kannst du Cloud Anchors außerhalb deiner ARCore-App verwalten.
- Weitere Informationen zur Verwendung von ARCore in Ihrer App finden Sie in der Android-Referenzdokumentation.