Erste Schritte mit den APIs „Streetscape Geometry“ und „Rooftop Anchors“ in ARCore

1. Hinweis

ARCore ist das Framework von Google zum Erstellen von Augmented-Reality-Apps (AR) für Smartphones. Mit den APIs „Geospatial Streetscape Geometry“ und „Rooftop Anchor“ können Ihre AR-Anwendungen Gebäude in der Nähe Ihrer Nutzer erkennen.

In diesem Codelab erstellen Sie eine AR-App, mit der Sie die Geometrie von Straßen in Ihrer Umgebung visualisieren und die Seiten dekorieren können. Anschließend können Sie mit Dachankern Dekorationen auf Dächern in Ihrer Umgebung platzieren.

Vorbereitung

• Grundkenntnisse in AR
• Grundkenntnisse der ARCore Geospatial API

Lerninhalte

• Hier erfahren Sie, wie Sie ein Google Cloud-Projekt einrichten, in dem ARCore Geospatial APIs verwendet werden können.
• So rufen Sie die Streetscape-Geometrie über die Geospatial API ab.
• So visualisieren Sie Gebäude und Gelände, die aus der Streetscape-Geometrie stammen.
• So führen Sie grundlegende Berechnungen für die abgeleiteten Polygone durch.
• So führen Sie einen Hit-Test für die Geometrie durch.
• So verwenden Sie Dachanker, um Inhalte oben auf Gebäuden zu platzieren.

Voraussetzungen

• Ein unterstütztes ARCore-Android-Gerät, das über ein USB-Kabel mit Ihrem Entwicklungscomputer verbunden und für USB-Debugging konfiguriert ist.
• Google Play-Dienste für AR 1.37 oder höher auf dem Android-Entwicklungsgerät installiert.
• Android Studio ist installiert und für die Entwicklung von Android-Apps konfiguriert.

2. Umgebung einrichten

Wenn Sie die Geospatial APIs mit Kotlin und Android Studio verwenden möchten, benötigen Sie ein Google Cloud-Projekt und unser Starterprojekt.

Google Cloud-Projekt einrichten

Die ARCore Geospatial API stellt eine Verbindung zu Google Cloud her, um Lokalisierungsinformationen aus dem Visual Positioning System (VPS) von Google in Gebieten bereitzustellen, die von Google Street View abgedeckt werden.

So verwenden Sie diesen Server in Ihrem Projekt:

1. Erstellen Sie ein Projekt in Google Cloud.
2. Geben Sie im Feld Project name (Projektname) einen geeigneten Namen ein, z. B. ARCore Geospatial API project, und wählen Sie einen beliebigen Ort aus.
3. Klicken Sie auf Erstellen.
4. Klicken Sie in der Google Cloud Console auf der Seite für die Projektauswahl auf Projekt erstellen.
5. Klicken Sie auf den folgenden Link, um die ARCore API für dieses Projekt aufzurufen, und klicken Sie auf Aktivieren:
   ARCore API aktivieren
6. Erstellen Sie einen API-Schlüssel für Ihr Projekt:
   1. Wählen Sie unter APIs & Dienste die Option Anmeldedaten aus.
   2. Klicken Sie auf Anmeldedaten erstellen und wählen Sie den API-Schlüssel aus.
   3. Notieren Sie sich den Schlüssel, da Sie ihn später benötigen.

Sie haben ein Google Cloud-Projekt mit API-Schlüssel-Autorisierung erstellt und können die Geospatial API im Beispielprojekt verwenden.

Android Studio einrichten

Um Ihnen den Einstieg in die Geospatial API zu erleichtern, haben wir ein Starterprojekt bereitgestellt, das die Grundlagen eines ARCore-Projekts enthält, das in die Geospatial API eingebunden ist.

So richten Sie Android Studio ein:

1. Öffnen Sie Android Studio und führen Sie einen der folgenden Schritte aus:
   • Wenn Sie bereits ein Projekt geöffnet haben, klicken Sie auf File > New > Project from version control (Datei > Neu > Projekt aus der Versionskontrolle).
   • Wenn das Fenster Welcome to Android Studio angezeigt wird, klicken Sie auf Get from VCS.
2. Wählen Sie Git aus und geben Sie https://github.com/google-ar/codelab-streetscape-geometry-rooftop-anchors.git ein, um das Projekt zu importieren.

API-Schlüssel in das Android Studio-Projekt einbinden

So verknüpfen Sie den API-Schlüssel aus Google Cloud mit Ihrem Projekt:

1. Klicken Sie in Android Studio auf app > src und doppelklicken Sie auf AndroidManifest.xml.
2. Suchen Sie nach den folgenden meta-data-Einträgen:

   <meta-data
       android:name="com.google.android.ar.API_KEY"
       android:value="API_KEY" />
   

3. Ersetzen Sie den Platzhalter API_KEY durch den API-Schlüssel, den Sie in Ihrem Google Cloud-Projekt erstellt haben. Der in com.google.android.ar.API_KEY gespeicherte Wert autorisiert diese App zur Verwendung der Geospatial API.

Projekt bestätigen

• Um Ihr Projekt zu bestätigen, führen Sie Ihre App auf Ihrem Entwicklungsgerät aus. Oben auf dem Bildschirm sollten Sie eine Kameraansicht und Geodaten-Debugging-Informationen sehen. Außerdem sollten Sie Schaltflächen und Steuerelemente sehen, die scheinbar keine Funktion haben. Sie programmieren diese Funktionen im Laufe dieses Codelabs in Ihr Projekt.

Achtung:Wenn die Geospatial API nicht initialisiert wird, prüfen Sie, ob der API-Schlüssel in Ihre Datei AndroidManifest.xml genau so eingefügt wurde, wie er in Google Cloud angezeigt wird.

3. Streetscape-Geometriedaten visualisieren

Nachdem Sie bestätigt haben, dass die Geospatial API auf Ihrem Gerät funktioniert, rufen Sie die Streetscape-Geometrie über die Geospatial API ab.

Streetscape-Geometrie aktivieren

1. Suchen Sie in der Datei StreetscapeGeometryActivity.kt nach der folgenden Zeile:

   // TODO: Enable Streetscape Geometry.
   

2. Aktivieren Sie nach dieser Zeile den Modus „streetscape-geometry“:

   streetscapeGeometryMode = Config.StreetscapeGeometryMode.ENABLED
   

   Wenn die Geospatial API und der Streetscape-Geometriemodus aktiviert sind, kann Ihre App Streetscape-Geometrieinformationen in der Nähe des Nutzers empfangen.

Streetscape-Geometrie abrufen

1. Suchen Sie in der Datei StreetscapeGeometryActivity.kt nach der folgenden Zeile:

   // TODO: Obtain Streetscape Geometry.
   

2. Rufen Sie nach dieser Zeile die Streetscape-Geometrie ab, indem Sie alle Trackable-Objekte abrufen und nach StreetscapeGeometry filtern:

   val streetscapeGeometry = session.getAllTrackables(StreetscapeGeometry::class.java)
   

   Sie verwenden diese Geometrien in einer einfachen Visualisierung, die im Beispielprojekt enthalten ist. In dieser Visualisierung wird jedes Gebäude- oder Geländepolygon in einer anderen Farbe dargestellt.
3. Fügen Sie in der nächsten Zeile den folgenden Code hinzu:

   streetscapeGeometryRenderer.render(render, streetscapeGeometry)
   

4. Führen Sie Ihre App aus und rufen Sie ein Gebäude in Ihrer Nähe auf.
5. Tippen Sie nach Abschluss der raumbezogenen Lokalisierung auf  Einstellungen und aktivieren Sie die Visualisierung der Streetscape-Geometrie.
6. Gebäude in AR ansehen Jedes segmentierte Gebäude hat eine eigene Farbe und die Quality- und Type-Enums der mittigsten Geometrie werden angezeigt.

Achtung:Wenn Sie die Streetscape-Geometrie nicht sehen oder keine Dekoration angezeigt wird, wenn Sie auf den Bildschirm tippen, gehen Sie so vor, um den Codelab-Checkpoint zurückzusetzen:

1. Klicken Sie in Android Studio auf VCS > Git > Branches > Checkout > step-3. Damit wird der dritte Schritt wiederholt.
2. Fügen Sie der Datei AndroidManifest.xml Ihren API-Schlüssel hinzu, wie in der Einrichtungsanleitung beschrieben.

4. Hit-Test mit Streetscape-Geometriedaten durchführen

Nachdem Sie die Geometrie der Straßenansicht sehen, können Sie einen Treffertest verwenden, um das Gebäude zu dekorieren. Bei einem Treffertest wird eine Überschneidung zwischen virtueller Geometrie und einem Strahl ermittelt. Mit einem Treffertest wird die Geometrie ermittelt, auf die ein Nutzer tippt.

Hit-Test durchführen

In diesem Abschnitt platzieren Sie einen Stern auf der Fassade des Gebäudes, wenn der Nutzer auf die Geometrie tippt. Dazu führen Sie einen Hit-Test aus der Perspektive des Nutzers in der Welt durch und registrieren, auf welche AR-Objekte er trifft. Anschließend prüfen Sie anhand dieser Informationen, ob der Nutzer auf ein Gebäude-Polygon getippt hat.

1. Suchen Sie in der Datei StreetscapeCodelabRenderer.kt nach der folgenden Zeile:

   // TODO: determine the Streetscape Geometry at the center of the viewport
   

2. Fügen Sie nach dieser Zeile den folgenden Code ein:

   val centerHits = frame.hitTest(centerCoords[0], centerCoords[1])
   val hit = centerHits.firstOrNull {
     val trackable = it.trackable
     trackable is StreetscapeGeometry && trackable.type == StreetscapeGeometry.Type.BUILDING
   } ?: return
   

   In diesem Code werden die Koordinaten des Zentrums verwendet, um eine Streetscape-Geometrie zu finden, die ein Gebäude ist. Sie verwenden dieses Ergebnis, um Dekorationen hinzuzufügen.

Beim Tippen einen Stern hinzufügen

1. Suchen Sie in der Datei StreetscapeCodelabRenderer.kt nach der folgenden Zeile:

   // TODO: Create an anchor for a star, and add it to the starAnchors object.
   

2. Fügen Sie nach dieser Zeile den folgenden Code ein:

   val transformedPose = ObjectPlacementHelper.createStarPose(hit.hitPose)
   val anchor = hit.trackable.createAnchor(transformedPose)
   starAnchors.add(anchor)
   

   Die Klasse ObjectPlacementHelper bestimmt anhand der Trefferposition einen geeigneten Ort für den Stern. Das starAnchors-Objekt wird verwendet, um die Sterne in der AR-Ansicht zu rendern.

Jetzt ausprobieren

1. Führen Sie Ihre App aus und rufen Sie ein Gebäude in Ihrer Nähe auf.
2. Wenn die georäumliche Lokalisierung abgeschlossen ist, richten Sie die Kamera auf das Gebäude und tippen Sie auf den Bildschirm. Auf dem Gebäude in der Mitte des Bildschirms wird ein Stern angezeigt.

Achtung:Wenn Sie die Streetscape-Geometrie nicht sehen oder keine Dekoration angezeigt wird, wenn Sie auf den Bildschirm tippen, gehen Sie so vor:

1. Klicken Sie in Android Studio auf VCS > Git > Branches > Checkout > step-4.
2. Fügen Sie der Datei AndroidManifest.xml Ihren API-Schlüssel hinzu, wie in der Einrichtungsanleitung beschrieben.

5. Dachankerdaten verwenden

Schließlich verwenden Sie Dachanker, um das Dach des Gebäudes zu dekorieren. Mit Dachanker können Sie AR-Anker an der Oberseite von Gebäuden mit Breiten- und Längengrad anbringen. Mit diesen Ankern können Sie Ballons an Gebäuden in der Nähe des Nutzers befestigen.

Ballonmodus Verhaltensweisen hinzufügen

Das Projekt hat zwei Modi für die Platzierung von Assets: den Sonnenblumenmodus, den Sie bereits verwendet haben, und den Ballonmodus.

So programmieren Sie das Verhalten für den Ballmodus:

1. Suchen Sie in der Datei StreetscapeCodelabRenderer.kt nach der folgenden Zeile:

   // TODO: Create an anchor for a balloon and add it to the balloonAnchors object.
   

2. Verwenden Sie die Trefferposition, um einen guten Platz für Ihren Ballon zu finden:

   val transformedPose = ObjectPlacementHelper.createBalloonPose(frame.camera.pose, hit.hitPose)
   

3. Wandeln Sie die Variable transformedPose in eine raumbezogene Position um:

   val earth = session?.earth ?: return
   val geospatialPose = earth.getGeospatialPose(transformedPose)
   

4. Erstellen Sie einen Dachanker mit dem transformierten Breiten- und Längengrad:

   earth.resolveAnchorOnRooftopAsync(
     geospatialPose.latitude, geospatialPose.longitude,
     0.0,
     transformedPose.qx(), transformedPose.qy(), transformedPose.qz(), transformedPose.qw()
   ) { anchor, state ->
     if (!state.isError) {
       balloonAnchors.add(anchor)
     }
   }
   

Jetzt ausprobieren

1. Führen Sie Ihre App aus und rufen Sie ein Gebäude in Ihrer Nähe auf.
2. Wenn die geospatiale Lokalisierung abgeschlossen ist, wechseln Sie in den Ballonmodus und tippen Sie auf ein Gebäude. Über dem Gebäude wird ein Ballon angezeigt.

Wenn Sie das erwartete Verhalten nicht reproduzieren können, gehen Sie so vor:

1. Klicken Sie in Android Studio auf VCS > Git > Branches > Checkout > step-5.
2. Fügen Sie der Datei AndroidManifest.xml Ihren API-Schlüssel hinzu, wie in der Einrichtungsanleitung beschrieben.

6. Fazit

Glückwunsch! Sie haben eine AR-App entwickelt, die die Geometrie des Straßenbilds in Ihrer Umgebung visualisiert und es Ihnen ermöglicht, die Seiten mit Sternen zu dekorieren. Außerdem haben Sie Dachanker verwendet, um Ballons auf Dächern in Ihrer Nähe zu platzieren.

Weitere Informationen

• Entwicklerhandbuch für Streetscape Geometry
• Entwicklerleitfaden für Dachanker
• Geospatial API – Übersicht