Geospatial Developer Guide für Unity (AR Foundation) mit Ausrichtung auf Android

Weitere Informationen zur Nutzung der Geospatial API in Ihren Apps

Voraussetzungen

Bevor Sie fortfahren, sollten Sie sich mit den grundlegenden AR-Konzepten und der Konfiguration einer ARCore-Sitzung vertraut machen.

Weitere Informationen zur Geospatial API findest du unter Introduction to the Geospatial API.

Wenn Sie noch keine Erfahrung mit der Entwicklung von ARCore haben, finden Sie unter Erste Schritte Informationen zu Software- und Hardwareanforderungen, Voraussetzungen und anderen Informationen für die von Ihnen verwendeten Plattformen.

Damit du die ARCore Geospatial API verwenden kannst, muss dein Projekt die AR Foundation und die ARCore-Erweiterungen für AR Foundation unterstützen.

Google Cloud-Projekt einrichten

Damit das Visual Positioning System (VPS) verwendet werden kann, muss Ihre App mit einem Google Cloud-Projekt verknüpft sein, das für die ARCore API aktiviert ist.

Sie müssen in Ihrem Google Cloud-Projekt die ARCore API aktivieren. Wenn Sie das Projekt erstellen müssen, gehen Sie so vor:

  1. Rufen Sie den Hilfeartikel Projekt in der Google Cloud Platform erstellen auf.

  2. Geben Sie einen geeigneten Projektnamen ein und wählen Sie einen Speicherort aus.

  3. Klicken Sie auf Erstellen.

  4. Wähle in der Seitenleiste APIs & Services und dann Bibliothek aus.

  5. Suchen Sie nach der ARCore API, wählen Sie sie aus und klicken Sie auf Aktivieren.

Autorisierung einrichten

Damit Geospatial API-Aufrufe an den VPS gesendet werden können, muss Ihre App autorisiert werden. Die Autorisierung per Schlüsselschlüssel wird bevorzugt, aber auch die Autorisierung für API-Schlüssel wird unterstützt.

Die Standardautorisierungsstrategie für neue Unity-Projekte mit ARCore SDK 1.24.0 oder höher ist DoNotUse. Dadurch wird verhindert, dass Anwendungen mit unnötigen Bibliotheken erstellt werden.

Schlüssellose Autorisierung

Wenn du einen API-Schlüssel bereits verwendet hast und ihn nicht mehr benötigst, kannst du ihn in der Google Cloud Platform Console löschen und aus deiner App entfernen.

Du musst dich für alle verschiedenen Kombinationen des verwendeten Paketnamens und Signaturschlüssels separat registrieren, etwa für „Debugging“, „Release“ usw.

Gehen Sie so vor, um Ihr Projekt ohne Schlüsselautorisierung zu verwenden:

  1. Rufen Sie in Unity Edit > Project Settings > XR > ARCore Extensions auf.

  2. Wählen Sie im Drop-down-Menü Android Authentiation Strategy die Option Keyless aus.

  3. Klicken Sie unter Optional Features die Kästchen für die APIs an, die Sie in Ihrem Projekt verwenden.

  4. SHA-1-Fingerabdruckschlüssel generieren

    1. Wählen Sie im Menü Edit die Option Project Settings > Player > Publishing Settings aus.

    2. Klicken Sie auf das Keystore Manager und erstellen Sie einen neuen Schlüssel.

    3. Kopieren Sie den SHA-1-Fingerabdruckschlüssel (wird in einem späteren Schritt eingefügt).

  5. Erstellen Sie die OAuth-Client-ID.

    1. Erstellen Sie eine OAuth-Client-ID in Ihrem Google Cloud-Projekt.

    2. Fügen Sie im Feld SHA-1 fingerprint den SHA-1-Fingerabdruck für die entsprechende Variante aus dem vorherigen Schritt ein.

    3. Klicken Sie auf CREATE, um die OAuth-Client-ID zu erstellen.

API-Schlüsselautorisierung

Führe die folgenden Schritte aus, um einen API-Schlüssel abzurufen und deinem Projekt hinzuzufügen:

  1. Rufen Sie den Schlüssel von der Google Cloud Platform ab, wie in der Google Cloud Platform Console-Hilfe beschrieben.

  2. Rufen Sie in Unity Edit > Project Settings > XR > ARCore Extensions auf.

  3. Wählen Sie im Drop-down-Menü Android Authentiation Strategy die Option API Key aus.

  4. Füge im Feld Android API Key den API-Schlüssel ein, den du von der Google Cloud Platform erhalten hast.

  5. Klicken Sie unter Optional Features die Kästchen für die APIs an, die Sie in Ihrem Projekt verwenden.

Nutzer auffordern, die Nutzung von Gerätedaten zu erlauben

In Apps, die die ARCore Geospatial API verwenden, muss der Nutzer aufgefordert werden, die Datennutzung auf seinem Gerät zu bestätigen und zuzulassen. Weitere Informationen finden Sie unter Anforderungen an den Datenschutz für Nutzer.

Gerätekompatibilität prüfen

Nicht alle Geräte, die ARCore unterstützen, unterstützen auch die Geospatial API. Rufe AREarthManager.IsGeospatialModeSupported() auf, um die Kompatibilität des Nutzers zu prüfen. Wenn FeatureSupported.Unsupported zurückgegeben wird, versuche nicht, die Sitzung zu konfigurieren.

Nutzer zur Laufzeit um Berechtigungen zur Standortermittlung bitten

ARCore-Erweiterungen fordern automatisch die entsprechenden Berechtigungen zur Standortermittlung an, wenn der räumliche Modus in ARCoreExtensions.Update() aktiviert ist. Wenn der Nutzer keine Berechtigung zur genauen Standortermittlung erteilt, wird die Sitzung nicht fortgesetzt und der Fehler „Berechtigung nicht gewährt“ wird zurückgegeben. Dies ist ein Beendigungsfehler und ein Neustart ist erforderlich, um die Berechtigungsanfrage noch einmal auszulösen.

Genaue Standortbestimmung

Die CameraGeospatialPose beschreibt eine bestimmte Richtung, Höhen und Kompassrichtung in Bezug auf die Erde. Sie wird in einem AREarthManager-Objekt verwaltet.

Tracking-Status prüfen

Raumbezogene Werte sind nur gültig, während TrackingState.EarthTrackingState TrackingState.Tracking ist. Andernfalls kann TrackingState Limited oder None sein. Sie müssen die Geospatial API-Aufrufe immer in einem TrackingState-Steuerblock zusammenfassen.

var earthTrackingState = EarthManager.EarthTrackingState;
if (earthTrackingState == TrackingState.Tracking)
{
     // Values obtained by the Geospatial API are valid as long as
     // earthTrackingState is TrackingState.Tracking.
     // Use Geospatial APIs in this block.
}

Weitere Fehlerstatus und -bedingungen können auch unter AREarthManager.EarthState aufgeführt sein. Wenn TrackingState den Wert Limited oder None hat, kann AREarthManager.EarthState die Ursache dieses Fehlers beschreiben.

Geospatiale Kameraposition erhalten

Wenn TrackingState den Wert Tracking hat, fordern Sie die Positionierung der Kamera im Verhältnis zur Erde an:

var earthTrackingState = EarthManager.EarthTrackingState;
if (earthTrackingState == TrackingState.Tracking)
{
  // camera_geospatial_pose contains geodetic location, rotation, and
  // confidences values.
  var cameraGeospatialPose = EarthManager.CameraGeospatialPose;
}

Du erhältst dann ein GeospatialPose-Element mit den folgenden Informationen:

  • Standort in Breiten- und Längengraden Eine Schätzung der Standortgenauigkeit wird ebenfalls bereitgestellt.
  • Höhe und eine Schätzung der Genauigkeit
  • Richtung, Näherung der Richtung, in die das Gerät gerichtet ist, und eine Schätzung der Genauigkeit der Richtung.

Für Positionsgenauigkeit anpassen

Die Genauigkeit der Pose vom VPS kann aufgrund der Verfügbarkeit von VPS-Daten für den Standort oder aufgrund zeitlicher Bedingungen am Standort variieren. Unter Umständen muss deine App Anpassungen für die Genauigkeit der Position vornehmen (siehe Geospatial API).

Die Geospatial API bietet eine Schätzung für die Genauigkeit der von den VPS zurückgegebenen Breiten-/Längengrad-, Höhen- und Überschriftenwerte.

Wenn der Überschriftswert von GeospatialPose.Heading beispielsweise 60 Grad und der Wert von GeospatialPose.HeadingAccuracy 10 % beträgt, besteht eine Wahrscheinlichkeit von 68 %, dass die VPS-Überschrift innerhalb von 10 Grad der beobachteten Überschrift liegt (siehe Grafik links).

Genauigkeit des Überschriften

Wenn der Wert für GeospatialPose.HeadingAccuracy 15 beträgt, besteht eine Wahrscheinlichkeit von 68 %, dass die tatsächliche Richtung innerhalb von 15 Grad bei 60 Grad liegt (siehe Grafik rechts). Je höher der von GeospatialPose.HeadingAccuracy zurückgegebene Wert, desto niedriger ist die Genauigkeit des Überschriftswerts von GeospatialPose.Heading.

Auf ähnliche Weise gibt GeospatialPose.HorizontalAccuracy die Anzahl der Meter an, innerhalb derer der tatsächliche Breiten-/Längengradwert eine Wahrscheinlichkeit von 68% innerhalb der angegebenen Entfernung aufweist, und GeospatialPose.VerticalAccuracy gibt die Anzahl der Meter an, in denen die tatsächliche Höhenhöhe mit einer Wahrscheinlichkeit von 68 % innerhalb des angegebenen Abstands liegt.

Geospatial API in Ihrem Projekt aktivieren

  1. Achte darauf, dass der Ordner Assets des Projekts ein skriptfähiges ARCoreExtensionsConfig-Objekt enthält.

    Klicken Sie im Bereich Assets mit der rechten Maustaste und wählen Sie Create > ARCore Extensions > ARCore Extensions Config aus, um einen zu erstellen.

  2. Wählen Sie das skriptfähige Objekt ARCoreExtensionsConfig aus und wählen Sie im Fenster Inspector für das Drop-down-Menü Geospatial Mode Enabled aus.

  3. Konfiguriere das Spieleobjekt ARCore Extensions, um die Konfiguration ARCoreExtensionsConfig zu verwenden:

    1. Suche im Bereich Hierarchy das ARCore Extensions-Spielobjekt, das du bei der Einrichtung von ARCore-Erweiterungen erstellt hast.

    2. Verbinde das Feld ARCore Extensions Config mit dem Skriptskript ARCoreExtensionsConfig im Asset-Ordner.

Raumbezogene Ankeranzeigen

Zum Platzieren eines raumbezogenen Ankers müssen Sie eine Position (Breitengrad, Längengrad und Höhe) und eine Ausrichtung (Quartal) angeben. Gemeinsam bilden sie die Pose für den Anker.

Der Breiten- und Längengrad sowie die Höhe werden im WGS84-Koordinatensystem angegeben. Die Höhe wird in Metern über dem WGS84-Ellipsoid als Referenz angegeben, sodass der Bodenniveau nicht null beträgt. Diese Koordinaten werden von Ihrer App für jeden erstellten Anker bereitgestellt.

Breiten- und Längengrad eines Standorts ermitteln

Es gibt drei Möglichkeiten, den Breiten- und Längengrad eines Standorts zu berechnen:

  • Google Maps verwenden
  • Verwenden Sie Google Earth. Wenn Sie diese Koordinaten nicht mit Google Maps, sondern mit Google Earth abrufen, erhalten Sie eine Fehlerspanne von bis zu mehreren Metern.
  • Zum Standort

Google Maps verwenden

So rufen Sie den Längen- und Breitengrad eines Standorts in Google Maps ab:

  1. Rufen Sie auf Ihrem Computer Google Maps auf.

  2. Gehen Sie zu Ebenen & Mehr.

  3. Ändern Sie den Kartentyp zu Satellit und entfernen Sie das Häkchen aus dem Kästchen Globusansicht links unten auf dem Bildschirm.

    Dadurch wird eine 2D-Perspektive erzwungen. Fehler, die aus einer 3D-Ansicht entstehen, werden entfernt.

  4. Klicken Sie auf der Karte mit der rechten Maustaste auf den Ort und wählen Sie die Längen- und Breitengrade aus, um sie in die Zwischenablage zu kopieren.

Google Earth verwenden

Sie können den Breiten- und Längengrad eines Orts in Google Earth berechnen, indem Sie auf einen Ort in der Benutzeroberfläche klicken und die Daten aus den Details der Ortsmarkierung lesen.

So rufen Sie den Längen- und Breitengrad eines Ortes in Google Earth ab:

  1. Öffnen Sie Google Earth auf dem Computer.

  2. Öffnen Sie das Hamburger-Menü und wählen Sie Kartenstil aus.

  3. Deaktivieren Sie die Option 3D-Gebäude.

  4. Wenn der Schalter 3D-Gebäude ausgeschaltet ist, klicken Sie auf das Stecknadelsymbol , um eine Ortsmarkierung an der ausgewählten Position hinzuzufügen.

  5. Wählen Sie ein Projekt für die Ortsmarkierung aus und klicken Sie auf Speichern.

  6. Geben Sie in das Feld Titel einen Namen für die Ortsmarkierung ein.

  7. Klicken Sie im Projektbereich auf den Zurückpfeil und wählen Sie das Menü Weitere Aktionen aus.

  8. Wählen Sie im Menü Als KML-Datei exportieren aus.

Die KLM-Datei gibt den Breiten-, Längengrad und die Höhe einer Ortsmarkierung im <coordinates>-Tag durch Kommas getrennt an. Das Beispiel sieht wie folgt aus:

<coordinates>-122.0755182435043,37.41347299422944,7.420342565583832</coordinates>

Verwende nicht den Breiten- und Längengrad aus den <LookAt>-Tags, die die Kameraposition angeben, nicht den Standort.

Zum Standort

Sie können die Höhe eines Standorts berechnen, indem Sie sich physisch vor Ort aufhalten.

Höhe eines Standorts ermitteln

Es gibt mehrere Möglichkeiten, die Höhe eines Ortes zu bestimmen.

  • Wenn sich der Ankerpunkt in der Nähe des Nutzers befindet, können Sie eine Höhe verwenden, die der Höhe des Nutzergeräts entspricht.
  • Sobald Sie den Längen- und Breitengrad erhalten, können Sie mit der Elevation API eine Höhe berechnen, die auf der Spezifikation EGM96 basiert. Für einen Vergleich mit der Höhe GeospatialPose muss die Maps API EGM96-Höhe in WGS84 konvertiert werden. Siehe GeoidEval mit einer Befehlszeile und einer HTML-Schnittstelle. Die Google Maps API erfasst den Breiten- und Längengrad gemäß der WGS84-Spezifikation.
  • Diese Informationen finden Sie in Google Earth. Dies führt zu einer Fehlerspanne von bis zu mehreren Metern. Verwenden Sie den Breiten- und Längengrad sowie die Höhen der <coordinates>-Tags, nicht die <LookAt>-Tags in der KML-Datei.
  • Wenn ein vorhandener Anker nahe und nicht in einer steilen Steigung liegt, können Sie möglicherweise die Höhe aus dem GeospatialPose der Kamera nutzen, ohne dafür eine andere Quelle wie die Google Maps API zu verwenden.

Rotationsquaternion abrufen

Verwenden Sie die folgende Formel, um eine Pose.rotation-Quartale zu erstellen, bei der die +Z-Achse in dieselbe Richtung wie die Überschrift von GeospatialPose zeigt.

Quaternion quaternion =
                Quaternion.AngleAxis(180f - (float)pose.Heading, Vector3.up);

Sobald du die Breiten-, Längengrad-, Höhen- und Rotationsquarantäne erhalten hast, kannst du mit ARAnchorManager.AddAnchor aus ARAnchorManagerExtensions ein ARGeospatialAnchor erstellen, um Inhalte in von dir angegebenen geografischen Koordinaten zu verankern.

if (earthTrackingState == TrackingState.Tracking)
{
  var anchor =
      AnchorManager.AddAnchor(
          latitude,
          longitude,
          altitude,
          quaternion);
  var anchoredAsset = Instantiate(GeospatialAssetPrefab, anchor.transform);
}

Wenn Sie einen Anker an der angegebenen Position und Ausrichtung relativ zur Erde platzieren, werden Breiten- und Längengrad in der WGS84-Spezifikation definiert. Der Höhenwert wird wiederum durch die Höhe über dem WGS84-Ellipid in Metern definiert. Die angegebene Rotationsquarantäne bezieht sich in Bezug auf den Koordinatenframe Ost-Auf-Süd. Eine Identitätsrotation ist so verankert, dass X+ nach Osten, Y+ nach oben und von der Mitte der Erde nach oben zeigt und Z+ nach Süden zeigt.

API-Nutzungskontingent

Das ARCore SDK begrenzt API-Anfragen auf den ARCore-Dienst für jedes Projekt, das das ARCore SDK verwendet, auf folgende Limits:

  • 1.000 Sitzungen pro Minute
  • 100.000 Anfragen pro Minute

API-Anfragen, die diese Beschränkungen überschreiten, können dazu führen,

als Fehler und nicht gefüllte Anfrage EarthState.ErrorResourcesExhausted.