Cloud Anchors-Entwicklerleitfaden für Android NDK (C)

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

// Create a new ARCore session.
ArSession* session = NULL;
CHECK(ArSession_create(env, context, &session) == AR_SUCCESS);

// Create a session config.
ArConfig* config = NULL;
ArConfig_create(session, &config);
ArSession_getConfig(session, config);

// Enable Cloud Anchor mode.
ArConfig_setCloudAnchorMode(session, config,
                            AR_CLOUD_ANCHOR_MODE_ENABLED);

// Configure the session.
ArSession_configure(session, config);
ArConfig_destroy(config);

Cloud-Anchor hosten

Das Hosting beginnt mit einem Anruf bei ArSession_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-Featuremap zu erstellen, die schließlich eine eindeutige Cloud Anchor-ID für den Anker an das Gerät zurückgibt.

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

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

  1. Rufen Sie ArSession_hostCloudAnchorAsync() auf.
  2. Warten Sie auf den Callback oder prüfen Sie den Status „Future“ kontinuierlich, bis er abgeschlossen ist.
  3. Ergebnisstatus prüfen um festzustellen, ob der Vorgang erfolgreich war, oder den Fehlercode zu interpretieren, wenn 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 für ArSession_resolveCloudAnchorAsync()

Kartierungsqualität von Featurepunkten prüfen

ArFeatureMapQuality gibt die Qualität der Elementpunkte an, die ARCore in den letzten Sekunden ab einer bestimmten Kameraposition erkannt hat. Cloud Anchors, die mithilfe von Funktionen höherer Qualität gehostet werden, werden im Allgemeinen genauer aufgelöst. Mit ArSession_estimateFeatureMapQualityForHosting() lässt sich die Qualität der Featurekarte für eine bestimmte Kameraposition schätzen.

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 Featurepunkte, die in den letzten Sekunden von der Pose erkannt wurden, reicht wahrscheinlich aus, damit ein Cloud-Anker mit ARCore aufgelöst werden kann. Die Genauigkeit der aufgelösten Pose wird jedoch wahrscheinlich vermindert sein. 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 ermittelten Funktionspunkte reicht wahrscheinlich aus, damit ein Cloud-Anker mit hoher Genauigkeit mit ARCore aufgelöst werden kann.

Zuvor gehostete Ankeranzeigen auflösen

Rufen Sie ArSession_resolveCloudAnchorAsync() auf, um einen gehosteten Cloud-Anchor aufzulösen. Die ARCore API vergleicht die visuellen Elemente 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 Position des gehosteten Cloud-Ankers 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-Anchor entfernen

Rufen Sie ArFuture_cancel() auf, um einen ausstehenden Cloud-Anchor-Vorgang abzubrechen. Rufen Sie ArAnchor_detach() auf, um das Tracking zu beenden und einen bereits behobenen Cloud-Anchor zu entfernen. Verweise auf den Anker müssen separat durch Aufrufen von ArAnchor_release() freigegeben werden.

Ergebnisstatus eines Cloud-Anchor-Vorgangs prüfen

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

Wert Beschreibung
AR_CLOUD_ANCHOR_STATE_ERROR_CLOUD_ID_NOT_FOUND Der Vorgang konnte nicht behoben werden, da die ARCore API die angegebene Cloud-Anchor-ID nicht finden konnte.
AR_CLOUD_ANCHOR_STATE_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.
AR_CLOUD_ANCHOR_STATE_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. Bei der an den Server gesendeten Anfrage ist möglicherweise eine Zeitüberschreitung ohne Antwort aufgetreten. Möglicherweise gibt es eine schlechte Netzwerkverbindung, DNS-Nichtverfügbarkeit, Firewallprobleme oder andere Faktoren, die die Verbindung des Geräts zur ARCore API beeinträchtigen können.
AR_CLOUD_ANCHOR_STATE_ERROR_INTERNAL Ein Hosting- oder Aufklärungsaufgabe für diesen Anchor wurde mit einem internen Fehler abgeschlossen. Die App sollte nicht versuchen, diesen Fehler zu beheben.
AR_CLOUD_ANCHOR_STATE_ERROR_NOT_AUTHORIZED Weitere Informationen finden Sie unter Fehlerbehebung bei der ARCore API-Autorisierung.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_NEW Cloud Anchor konnte nicht aufgelöst werden, da die SDK-Version, die zum Auflösen des Ankers verwendet wurde, neuer als die Version ist, die zum Hosten verwendet wurde, und nicht mit ihr kompatibel ist.
AR_CLOUD_ANCHOR_STATE_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.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOURCE_EXHAUSTED Die Anwendung hat das für das jeweilige Google Cloud-Projekt zugewiesene Anfragekontingent ausgeschöpft. Sie sollten in der Google Developers Console ein zusätzliches Kontingent für die ARCore API für Ihr Projekt anfordern.
AR_CLOUD_ANCHOR_STATE_SUCCESS Eine Hosting- oder Aufklärungsaufgabe für diesen Anchor wurde erfolgreich abgeschlossen.

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

Die ARCore API hat 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
Anker klärt Anfragen 300 Minute IP-Adresse und Projekt

Best Practices für eine positive Nutzererfahrung

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

  • 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. Vermeiden Sie für optimale Ergebnisse reflektierende Oberflächen oder Oberflächen, die keine optischen Merkmale aufweisen, z. B. leere weiße Wände.

  • Achte darauf, dass die Kamera auf den zentralen Bereich ausgerichtet ist, und bewege das Gerät den Mittelpunkt, um die Umgebung aus verschiedenen Blickwinkeln zu kartieren. Dabei bleibt ungefähr dieselbe physische Entfernung erhalten. Dies trägt dazu bei, mehr visuelle Daten zu erfassen und die Auflösung zuverlässiger zu machen.

  • 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.

Nächste Schritte