Azure-Raumanker in Unreal

Azure-Raumanker (Azure Spatial Anchors) sind ein Microsoft Mixed Reality-Dienst, mit dem Augmented Reality-Geräte Ankerpunkte in der physischen Welt ermitteln, teilen und speichern können. Die folgende Dokumentation enthält Anleitungen zum Integrieren des Azure Spatial Anchors-Diensts in ein Unreal-Projekt. Weitere Informationen finden Sie unter -Dienst.

Hinweis

Unreal Engine 4.26 verfügt jetzt über Plug-Ins für die Unterstützung von ARKit und ARCore, falls Sie mit den Zielplattformen iOS oder Android arbeiten.

Wichtig

Lokale Anker werden auf dem Gerät gespeichert, während Azure-Raumanker in der Cloud gespeichert werden. Wenn Sie Ihre Anker lokal auf einem Gerät speichern möchten, verfügen wir über das Dokument Lokale Raumanker, in dem Sie durch den Prozess geführt werden. Beachten Sie, dass Sie sowohl lokale als auch Azure-Anker im selben Projekt haben können, ohne dass Konflikte auftreten.

Voraussetzungen

Um diese Anleitung durchzuführen, stellen Sie sicher, dass Folgendes erfüllt ist:

• Das Microsoft OpenXR-Plug-In muss installiert sein (verfügbar über den Unreal Marketplace oder über GitHub).
• Unreal, Version 4.25 oder höher, ist installiert.
• Eine HoloLens 2-Projekteinrichtung in Unreal ist vorhanden.
• Sie haben die Azure-Raumanker: Übersicht gelesen.
• Grundkenntnisse in C++ und Unreal

Abrufen von Azure-Raumanker-Kontoinformationen

Bevor Sie Azure-Raumanker in Ihrem Projekt verwenden können, müssen Sie Folgendes erledigen:

• Erstellen Sie eine Raumankerressource, und kopieren Sie die unten aufgeführten Kontofelder. Diese Werte werden verwendet, um Benutzer mit dem Konto Ihrer Anwendung zu authentifizieren:
  • Konto-ID
  • Kontoschlüssel

Weitere Informationen finden Sie unter Azure-Raumanker: Authentifizierung.

Hinweis

Azure-Raumanker in Unreal 4.25 unterstützen keine Azure AD-Authentifizierungstoken, aber Unterstützung für diese Funktionalität wird in einer späteren Version verfügbar sein.

Aktivieren von Funktionen und Berechtigungen

HoloLens

Öffnen Sie Projekteinstellungen HoloLens, und aktivieren Sie die Funktion Internetclient:

Android

Damit eine Android-App einen Berechtigungsdialog anzeigt und Standortfunktionen zulässt, muss die Funktion Android-Berechtigungen anfordern aufgerufen werden, bevor versucht wird, die Azure Spatial Anchor-Sitzung zu starten:

Erstellen Sie eine lokale Variable für die Eingabeberechtigungen, und füllen Sie sie mit:

• android.permission.ACCESS_WIFI_STATE
• android.permission.CHANGE_WIFI_STATE
• android.permission.INTERNET
• android.permission.BLUETOOTH
• android.permission.BLUETOOTH_ADMIN
• android.permission.ACCESS_COARSE_LOCATION
• android.permission.ACCESS_FINE_LOCATION
• android.permission.CAMERA

Öffnen Sie abschließend Projekteinstellungen Android, und legen Sie die gleichen Berechtigungen im Feld Zusätzliche Berechtigungen unter Erweiterte APK-Verpackung fest:

iOS

Zum Erstellen einer Anwendung für iOS müssen Sie Unreal auf einem Mac verwenden. Zum Verpacken mit einem Apple-Entwicklerkonto öffnen Sie Projekteinstellungen iOS, und scrollen Sie nach unten zum Abschnitt Build. Aktivieren Sie das Kontrollkästchen Automatische Signierung, und füllen Sie die IOS-Team-ID mit Ihrer Team-ID auf.

Sie finden Ihre Team-ID, indem Sie sich bei developer.apple.com anmelden, zur Registerkarte Mitgliedschaft navigieren und nach Team-ID suchen.

Damit ein Berechtigungsdialogfeld angezeigt wird und das iOS-Gerät auf Standortinformationen zugreifen kann, müssen die Funktionen Init Location Services und Start Location Services aufgerufen werden, bevor versucht wird, die Azure Spatial Anchor-Sitzung zu starten:

Hinzufügen von Azure-Raumanker-Plug-Ins

Tipp

Wenn Sie Azure Spatial Anchors für Unreal verwenden, gibt es ein Azure Spatial Anchors-Plug-In und ein plattformspezifisches Plug-In (WMR, ARKit, ARCore, OpenXR). Es sollte jeweils nur ein plattformspezifisches Plug-In aktiviert sein.

HoloLens

Aktivieren Sie die Azure-Raumanker-Plug-Ins im Unreal-Editor wie folgt:

1. Klicken Sie auf Bearbeiten Plug-Ins, und suchen Sie nach Azure Spatial Anchors sowie Azure Spatial Anchors For WMR.
2. Aktivieren Sie das Kontrollkästchen Aktiviert für beide Plug-Ins, um den Zugriff auf die Azure-Raumanker-Blaupausenbibliotheken in Ihrer Anwendung zuzulassen.

Starten Sie anschließend den Unreal-Editor neu, damit die Plug-In-Änderungen wirksam werden. Das Projekt ist jetzt für die Verwendung von Azure-Raumankern bereit.

Android

Aktivieren Sie die Azure-Raumanker-Plug-Ins im Unreal-Editor wie folgt:

1. Klicken Sie auf Bearbeiten Plug-Ins, und suchen Sie nach Azure Spatial Anchors sowie Azure Spatial Anchors For ARCore.
2. Aktivieren Sie das Kontrollkästchen Aktiviert für beide Plug-Ins, um den Zugriff auf die Azure-Raumanker-Blaupausenbibliotheken in Ihrer Anwendung zuzulassen.

Starten Sie anschließend den Unreal-Editor neu, damit die Plug-In-Änderungen wirksam werden. Das Projekt ist jetzt für die Verwendung von Azure-Raumankern bereit.

iOS

Aktivieren Sie die Azure-Raumanker-Plug-Ins im Unreal-Editor wie folgt:

1. Klicken Sie auf Bearbeiten Plug-Ins, und suchen Sie nach Azure Spatial Anchors sowie Azure Spatial Anchors For ARKit.
2. Aktivieren Sie das Kontrollkästchen Aktiviert für beide Plug-Ins, um den Zugriff auf die Azure-Raumanker-Blaupausenbibliotheken in Ihrer Anwendung zuzulassen.

3. Suchen Sie außerdem nach Mobile Location Services und Mobile Location Services – IOS Implementation
4. Aktivieren Sie das Kontrollkästchen Aktiviert in beiden Plug-Ins, damit das iOS-Gerät auf den aktuellen Standort zugreifen kann.

Starten Sie anschließend den Unreal-Editor neu, damit die Plug-In-Änderungen wirksam werden. Das Projekt ist jetzt für die Verwendung von Azure-Raumankern bereit.

Starten einer Raumankersitzung

Eine Azure-Raumankersitzung ermöglicht Clientanwendungen die Kommunikation mit dem Azure Spatial Anchors-Dienst. Sie müssen eine Azure Spatial Anchors-Sitzung erstellen und starten, um Azure-Raumanker zu erstellen, zu speichern und zu teilen:

1. Öffnen Sie die Blaupause für den „Pawn“ (Bauer), den Sie in der Anwendung verwenden.
2. Fügen Sie zwei Zeichenfolgenvariablen für die Konto-ID und den Kontoschlüssel hinzu, und weisen Sie dann die entsprechenden Werte aus Ihrem Azure Spatial Anchors-Konto zu, um die Sitzung zu authentifizieren.

Starten Sie eine Azure Spatial Anchors-Sitzung wie folgt:

1. Überprüfen Sie, ob eine AR-Sitzung in der HoloLens-Anwendung ausgeführt wird, da die Azure Spatial Anchors-Sitzung erst gestartet werden kann, wenn eine AR-Sitzung ausgeführt wird. Wenn Sie keine eingerichtet haben, erstellen Sie eine AR-Sitzungsressource.
2. Fügen Sie das benutzerdefinierte Ereignis -Sitzung starten hinzu, und konfigurieren Sie es, wie im folgenden Screenshot gezeigt.
   • Beim Erstellen einer Sitzung wird die Sitzung nicht standardmäßig gestartet, sodass Sie die Sitzung für die Authentifizierung beim Azure Spatial Anchors-Dienst konfigurieren können.

3. Konfigurieren Sie die Azure Spatial Anchors-Sitzung so, dass sie die Konto-ID, den Kontoschlüssel die Kontodomäne und die Lokalisierungseinstellungen des Kurses angibt. Alle Kontrollkästchen in den Lokalisierungseinstellungen des Kurses sollten aktiviert sein, damit der Azure Spatial Anchor-Dienst Sensordaten zum Suchen von Ankern verwenden kann.

4. Starten Sie die Azure Spatial Anchors-Sitzung, was es der Anwendung ermöglicht, lokale Azure-Raumanker zu erstellen und aufzufinden.

Es hat sich bewährt, die Azure-Raumankerressourcen in Ihrer Ereignisdiagramm-Blaupause zu bereinigen, wenn Sie den Dienst nicht mehr verwenden:

1. Beenden Sie die Azure Spatial Anchors-Sitzung. Die Sitzung wird nicht mehr ausgeführt, aber die zugehörigen Ressourcen sind weiterhin im Azure-Raumanker-Plug-In vorhanden.

2. Zerstören Sie die Azure Spatial Anchors-Sitzung, um alle Azure Spatial Anchors-Sitzungsressourcen zu bereinigen, die im Azure-Raumanker-Plug-In noch bekannt sind.

Ihre Ereignisdiagramm-Blaupause sollte wie im folgenden Screenshot aussehen:

Erstellen eines Ankers

Ein Azure-Raumanker stellt eine physische Weltpose im Augmented Reality-Anwendungsraum dar, die Augmented Reality-Inhalte an physische Orte bindet. Azure-Raumanker können auch von verschiedenen Benutzern gemeinsam genutzt werden. Dieses Teilen ermöglicht es, dass Augmented Reality-Inhalte, die auf verschiedenen Geräten gezeichnet werden, am selben Ort in der physischen Welt positioniert werden können.

So erstellen Sie einen neuen Azure-Raumanker

1. Überprüfen Sie, ob eine Azure Spatial Anchors-Sitzung ausgeführt wird. Die Anwendung kann einen Azure-Raumanker nur erstellen oder speichern, wenn eine Azure Spatial Anchors-Sitzung ausgeführt wird.

2. Erstellen Sie eine Unreal- Szenenkomponente , oder rufen Sie eine ab, deren Ort gespeichert werden sollte.
   • Im folgenden Bild wird die Komponente Szenenkomponente, die einen Anker benötigt als Variable verwendet. Eine Unreal-Szenenkomponente ist erforderlich, um eine Anwendungswelttransformation für ein AR Pin und einen Azure-Raumanker einzurichten.

So erstellen und speichern Sie einen Azure-Raumanker für eine Unreal-Szenenkomponente

1. Rufen Sie die Pin-Komponente für die Unreal-Szenenkomponente auf, und geben Sie die Welttransformation der Szenenkomponente als die Welttransformation an, die für den AR Pin verwendet wird.
   • Unreal verfolgt AR-Punkte im Anwendungsraum mithilfe von AR Pins, die zum Erstellen eines Azure-Raumankers verwendet werden. In Unreal entspricht ein AR Pin analog einem SpatialAnchor (Raumanker) auf HoloLens.

2. Rufen Sie mithilfe des neu erstellten AR Pins Cloudanker erstellen auf.
   • „Cloudanker erstellen“ erstellt lokal einen Azure-Raumanker, aber nicht im Azure-Raumankerdienst. Parameter für den Azure-Raumanker, z. B. ein Ablaufdatum, können festgelegt werden, bevor der Azure-Raumanker mit dem Dienst erstellt wird.

3. Legen Sie den Ablauf des Azure-Raumankers fest. Der Parameter „Lifetime“ (Lebensdauer) dieser Funktion ermöglicht es dem Entwickler, in Sekunden anzugeben, wie lange der Anker vom Dienst erhalten werden soll.
   • Eine Ablaufzeit von einer Woche würde beispielsweise einen Wert von 60 Sekunden × 60 Minuten x 24 Stunden x 7 Tage = 604.800 Sekunden erfordern.

Nachdem Sie Ankerparameter festgelegt haben, deklarieren Sie den Anker als zum Speichern bereit. Im folgenden Beispiel wird der neu erstellte Azure-Raumanker zu einem Satz von Azure-Raumankern hinzugefügt, die gespeichert werden müssen. Dieser Satz wird als Variable für die Pawn-Blaupause deklariert.

Speichern eines Ankers

Nachdem Sie den Azure-Raumanker mit Ihren Parametern konfiguriert haben, rufen Sie Cloudanker speichern auf. „Cloudanker speichern“ deklariert den Anker im Azure Spatial Anchors-Dienst. Wenn der Aufruf von „Cloudanker speichern“ erfolgreich ist, steht der Azure-Raumanker anderen Benutzern des Azure Spatial Anchors-Diensts zur Verfügung.

Hinweis

„Cloudanker speichern“ ist eine asynchrone Funktion und kann nur für ein Spielthreadereignis wie EventTick aufgerufen werden. „Cloudanker speichern“ wird in benutzerdefinierten Blaupausenfunktionen möglicherweise nicht als verfügbare Blaupausenfunktion angezeigt. Es sollte jedoch im Blaupausen-Editor für das Pawn-Ereignisdiagramm verfügbar sein.

Im folgenden Beispiel wird der Azure-Raumanker während eines Eingabeereignisrückrufs in einem Satz gespeichert. Der Anker wird dann im EventTick gespeichert. Es kann mehrere Versuche benötigen, um einen Azure-Raumanker zu speichern, je nach der Menge von Raumdaten, die Ihre Azure Spatial Anchors-Sitzung erstellt hat. Aus diesem Grund empfiehlt es sich, zu überprüfen, ob der Speichernaufruf erfolgreich war.

Wenn der Anker nicht gespeichert wird, fügen Sie ihn erneut dem Satz von Ankern hinzu, die noch gespeichert werden müssen. Zukünftige EventTicks versuchen weiterhin, den Anker zu speichern, bis er erfolgreich gespeichert wird.

Nachdem der Anker gespeichert wurde, fungiert die Transformation des AR Pins als Verweistransformation, um Inhalt in Ihrer App abzulegen. Andere Benutzer können diesen Anker erkennen und AR-Inhalt für verschiedene Geräte in der physischen Welt ausrichten.

Löschen eines Ankers

Sie können Anker aus dem Azure Spatial Anchors-Dienst löschen, indem Sie Cloudanker löschen aufrufen.

Hinweis

„Cloudanker löschen“ ist eine latente Funktion und kann nur für ein Spielthreadereignis wie „EventTick“ aufgerufen werden. „Cloudanker löschen“ wird in benutzerdefinierten Blaupausenfunktionen möglicherweise nicht als verfügbare Blaupausenfunktion angezeigt. Es sollte jedoch im Blaupausen-Editor für das Pawn-Ereignisdiagramm verfügbar sein.

Im folgenden Beispiel ist der Anker für das Löschen in einem benutzerdefinierten Eingabeereignis gekennzeichnet. Der Löschvorgang wird dann bei EventTick versucht. Wenn das Löschen des Ankers fehlschlägt, fügen Sie den Azure-Raumanker dem Satz von Ankern hinzu, die zum Löschen gekennzeichnet sind, und versuchen Sie es noch mal mit späteren EventTicks.

Ihre Ereignisdiagramm-Blaupause sollte jetzt wie im folgenden Screenshot aussehen:

Auffinden bereits vorhandener Anker

Vorhandene Anker können von Peers mithilfe des Azure Spatial Anchors-Diensts erstellt werden:

1. Rufen Sie einen Azure-Raumankerbezeichner für den Anker ab, den Sie erkennen möchten.
   • Ein Ankerbezeichner kann für einen Anker abgerufen werden, der von demselben Gerät in einer früheren Azure Spatial Anchors-Sitzung erstellt wurde. Er kann außerdem von Peergeräten erstellt und geteilt werden, die mit dem Azure Spatial Anchors-Dienst interagieren.

2. Fügen Sie Ihrer Pawn-Blaupause eine AzureSpatialAnchorsEvent-Komponente hinzu.
   • Mit dieser Komponente können Sie verschiedene Azure-Raumankerereignisse abonnieren, z. B. Ereignisse, die aufgerufen werden, wenn Azure-Raumanker aufgefunden werden.

3. Abonnieren Sie den Delegaten für gefundene ASAAnchor für die AzureSpatialAnchorsEvent-Komponente.
   • Der Delegat teilt der Anwendung mit, wenn neue Anker gefunden wurden, die dem Azure Spatial Anchors-Konto zugeordnet sind.
   • Mit dem Ereignisrückruf werden für Azure-Raumanker, die von Peers mit der Azure Spatial Anchors-Sitzung erstellt wurden, standardmäßig keine AR Pins erstellt. Um einen AR Pin für den erkannten Azure-Raumanker zu erstellen, können Entwickler ARPin um Azure Cloud-Raumanker erstellen aufrufen.

Zum Auffinden von Azure-Raumankern, die von Peers mithilfe des Azure Spatial Anchors-Diensts erstellt wurden, muss die Anwendung einen Azure Spatial Anchors-Watcher erstellen:

1. Überprüfen Sie, ob eine Azure Spatial Anchors-Sitzung ausgeführt wird.
2. Erstellen Sie ein AzureSpatialAnchorsLocateCriteria.
   • Sie können verschiedene Standortparameter angeben, z. B. die Entfernung vom Benutzer oder die Entfernung von einem anderen Anker.
3. Deklarieren Sie den Azure Spatial Anchors-Bezeichner, nach dem Sie in AzureSpatialAnchorsLocateCritieria suchen.
4. Rufen Sie Watcher erstellen auf.

Die Anwendung beginnt nun, nach Azure-Raumankern zu suchen, die dem Azure Spatial Anchors-Dienst bekannt sind, was bedeutet, dass Benutzer von Peers erstellte Azure-Raumanker auffinden können.

Nachdem Sie den Azure-Raumanker gefunden haben, rufen Sie Watcher beenden auf, um den Azure-Raumanker-Watcher zu beenden und Watcherressourcen zu bereinigen.

Ihre endgültige Ereignisdiagramm-Blaupause sollte jetzt wie im folgenden Screenshot aussehen:

Nächster Entwicklungsprüfpunkt

Wenn Sie der Unreal-Entwicklungs-Journey folgen, die wir entworfen haben, befinden Sie sich mitten im Kennenlernen der MRTK-Grundbausteine. Von hier aus können Sie mit dem nächsten Baustein fortfahren:

Räumliche Abbildung

Oder fahren Sie mit den Funktionen und APIs der Mixed Reality-Plattform fort:

HoloLens-Kamera

Sie können jederzeit zu den Prüfpunkten für die Unreal-Entwicklung zurückkehren.

Nächste Schritte

• Lokale Raumanker
• Raumanker-Dokumentation
• Raumankerfunktionen
• Richtlinien für eine effektive Ankererfahrung