Azure Spatial Anchors in Unreal

Azure Spatial Anchors is een Microsoft Mixed Reality-service, waardoor augmented reality-apparaten ankerpunten in de fysieke wereld kunnen detecteren, delen en behouden. De onderstaande documentatie bevat instructies voor het integreren van de Azure Spatial Anchors-service in een Unreal-project. Als u op zoek bent naar meer informatie, bekijkt u de Azure Spatial Anchors-service.

Notitie

Unreal Engine 4.26 heeft nu invoegtoepassingen voor ARKit- en ARCore-ondersteuning als u iOS of Android wilt gebruiken.

Belangrijk

Lokale ankers worden opgeslagen op het apparaat, terwijl Azure Spatial Anchors worden opgeslagen in de cloud. Als u uw ankers lokaal wilt opslaan op een apparaat, hebben we een lokaal Spatial Anchors-document waarmee u het proces kunt doorlopen. Houd er rekening mee dat u lokale en Azure-ankers in hetzelfde project kunt hebben zonder conflict.

Vereisten

Om deze zelfstudie te voltooien, moet u ervoor zorgen dat u:

Azure Spatial Anchors-accountgegevens ophalen

Voordat u Azure Spatial Anchors in uw project gebruikt, moet u het volgende doen:

Bekijk de azure Spatial Anchors-verificatiedocumenten voor meer informatie.

Notitie

Azure Spatial Anchors in Unreal 4.25 biedt geen ondersteuning voor Azure AD-verificatietokens, maar ondersteuning voor deze functionaliteit wordt later uitgebracht.

Mogelijkheden en machtigingen inschakelen

HoloLens

Open Project Instellingen HoloLens > en schakel de internetclientfunctie in:

HoloLens project settings with capabilities highlighted

Android

Voor een Android-app om een machtigingsdialoog weer te geven en locatiemogelijkheden toe te staan, moet de functie Android-machtigingen aanvragen worden aangeroepen voordat u probeert de Azure Spatial Anchor-sessie te starten:

Request Android permissions function

Maak een lokale variabele voor de invoermachtigingen en vul het volgende in:

  • 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

Set Android permissions

Open ten slotte Project Instellingen > Android en stel dezelfde machtigingen in het veld Extra machtigingen in onder Advanced APK Packaging:

Android APK project settings

iOS

Als u een toepassing voor iOS wilt maken, moet u Unreal op een Mac gebruiken. Als u een Apple-ontwikkelaarsaccount wilt verpakken, opent u Project Instellingen > iOS en schuift u omlaag naar de sectie Build. Schakel het selectievakje Automatische ondertekening in en vul de IOS-team-id in met uw team-id.

U kunt uw team-id vinden door u aan te melden bij developer.apple.com, naar het tabblad Lidmaatschap te navigeren en naar team-id te zoeken.

Als u een machtigingsdialoog wilt weergeven en het iOS-apparaat toegang wilt geven tot locatiegegevens, moeten de functies Init Location Services en Start Location Services worden aangeroepen voordat u de Azure Spatial Anchor-sessie start:

Start iOS location services

Azure Spatial Anchors-invoegtoepassingen toevoegen

HoloLens

Schakel de Azure Spatial Anchors-invoegtoepassingen in de Unreal-editor in door:

  1. Klik op Invoegtoepassingen bewerken > en zoek naar Azure Spatial Anchors en Azure Spatial Anchors voor WMR.
  2. Schakel het selectievakje Ingeschakeld in beide invoegtoepassingen in om toegang te verlenen tot de Azure Spatial Anchors-blauwdrukbibliotheken in uw toepassing.

Screenshot of spatial Anchors plugins in Unreal editor

Zodra dat is gebeurd, start u de Unreal Editor opnieuw zodat de invoegtoepassing van kracht wordt. Het project is nu klaar om Azure Spatial Anchors te gebruiken.

Android

Schakel de Azure Spatial Anchors-invoegtoepassingen in de Unreal-editor in door:

  1. Klik op Invoegtoepassingen bewerken > en zoek naar Azure Spatial Anchors en Azure Spatial Anchors for ARCore.
  2. Schakel het selectievakje Ingeschakeld in beide invoegtoepassingen in om toegang te verlenen tot de Azure Spatial Anchors-blauwdrukbibliotheken in uw toepassing.

Android plugins in Unreal editor

Zodra dat is gebeurd, start u de Unreal Editor opnieuw zodat de invoegtoepassing van kracht wordt. Het project is nu klaar om Azure Spatial Anchors te gebruiken.

iOS

Schakel de Azure Spatial Anchors-invoegtoepassingen in de Unreal-editor in door:

  1. Klik op Invoegtoepassingen bewerken > en zoek naar Azure Spatial Anchors en Azure Spatial Anchors for ARKit.
  2. Schakel het selectievakje Ingeschakeld in beide invoegtoepassingen in om toegang te verlenen tot de Azure Spatial Anchors-blauwdrukbibliotheken in uw toepassing.

iOS ASA plugins in Unreal editor

  1. Zoek ook naar Mobile Location Services en Mobile Location Services - IOS-implementatie
  2. Schakel het selectievakje Ingeschakeld in beide invoegtoepassingen in om het iOS-apparaat toegang te geven tot de huidige locatie.

iOS Location plugins in Unreal editor

Zodra dat is gebeurd, start u de Unreal Editor opnieuw zodat de invoegtoepassing van kracht wordt. Het project is nu klaar om Azure Spatial Anchors te gebruiken.

Een Spatial Anchors-sessie starten

Met een Azure Spatial Anchors-sessie kunnen clienttoepassingen communiceren met de Azure Spatial Anchors-service. U moet een Azure Spatial Anchors-sessie maken en starten om Azure Spatial Anchors te maken, te behouden en te delen:

  1. Open de blauwdruk voor het Pawn dat u in de toepassing gebruikt.
  2. Voeg twee tekenreeksvariabelen toe voor de account-id en accountsleutel en wijs vervolgens de bijbehorende waarden toe vanuit uw Azure Spatial Anchors-account om de sessie te verifiëren.

Screenshot of details panel with azure spatial anchors account id, key, and variable type highlighted

Start een Azure Spatial Anchors-sessie door:

  1. Controleren of een AR-sessie wordt uitgevoerd in de HoloLens-toepassing, omdat de Azure Spatial Anchors-sessie pas kan worden gestart als er een AR-sessie wordt uitgevoerd. Als u nog geen installatie hebt, maakt u een AR-sessieasset.
  2. Voeg de aangepaste gebeurtenis Start Azure Spatial Anchors Session toe en configureer deze, zoals wordt weergegeven in de onderstaande schermopname.
    • Als u een sessie maakt, wordt de sessie niet standaard gestart. Hiermee kunt u de sessie configureren voor verificatie met de Azure Spatial Anchors-service.

Blueprint of starting azure spatial anchors session custom event

  1. Configureer de Azure Spatial Anchors-sessie om de account-id, accountsleutel, accountdomein en cursuslokalisatie op te geven Instellingen. Alle selectievakjes moeten worden ingeschakeld in de lokalisatie-instellingen van de cursus, zodat de Azure Spatial Anchor-service sensorgegevens kan gebruiken om ankers te vinden.

Blueprint of config session function with account id and key added

  1. Start de Azure Spatial Anchors-sessie, zodat de toepassing Azure Spatial Anchors kan maken en vinden.

Blueprint of the azure spatial anchors session start function

Het is een goede gewoonte om Azure Spatial Anchors-resources op te schonen in uw Event Graph-blauwdruk wanneer u de service niet meer gebruikt:

  1. Stop de Azure Spatial Anchors-sessie. De sessie wordt niet meer uitgevoerd, maar de bijbehorende resources bestaan nog steeds in de Azure Spatial Anchors-invoegtoepassing.

Blueprint of stop azure spatial anchors sessions custom event and stop session function

  1. Vernietig de Azure Spatial Anchors-sessie om alle Azure Spatial Anchors-sessiebronnen op te schonen die nog steeds bekend zijn bij de Azure Spatial Anchors-invoegtoepassing.

Blueprint of destroy session function

Uw blauwdruk voor gebeurtenis Graph moet er als volgt uitzien:

Blueprint of complete event graph of azure spatial anchor session setup

Een anker maken

Een Azure Spatial Anchor vertegenwoordigt een fysieke wereldpositie in de augmented reality-toepassingsruimte, waarmee augmented reality-inhoud wordt vergrendeld voor fysieke locaties. Azure Spatial Anchors kan ook worden gedeeld tussen verschillende gebruikers. Met dit delen kunnen augmented reality-inhoud die op verschillende apparaten wordt getekend, op dezelfde locatie in de fysieke wereld worden weergegeven.

Een nieuw Azure Spatial Anchor maken:

  1. Controleer of een Azure Spatial Anchors-sessie wordt uitgevoerd. De toepassing kan geen Azure Spatial Anchor maken of behouden wanneer er geen Azure Spatial Anchors-sessie wordt uitgevoerd.

Blueprint of create azure spatial anchor custom event

  1. Maak of haal een Unreal Scene-onderdeel op waarop de locatie moet worden bewaard.
    • In de onderstaande afbeelding wordt het onderdeel Scene Component Need Anchor gebruikt als variabele. Er is een Unreal Scene-onderdeel nodig om een toepassingswereldtransformatie tot stand te brengen voor een AR-pin en Azure Spatial Anchor.

Blueprint of create azure spatial anchor custom event with scene component

Een Azure Spatial Anchor maken en opslaan voor een Unreal Scene-onderdeel:

  1. Roep het speldonderdeel aan voor het Unreal Scene-onderdeel en geef de wereldtransformatie van het scèneonderdeel op als de wereldtransformatie die wordt gebruikt voor de AR-pin.
    • Unreal houdt AR-punten in de toepassingsruimte bij met behulp van AR Pins, die worden gebruikt om een Azure Spatial Anchor te maken. In Unreal is een AR Pin vergelijkbaar met een SpatialAnchor op HoloLens.

Blueprint of scene component connected to pin component function

  1. Roep Cloud Anchor maken aan met behulp van de zojuist gemaakte AR-pincode.
    • Cloud Anchor maken maakt lokaal een Azure Spatial Anchor, maar niet in de Azure Spatial Anchor-service. Parameters voor Azure Spatial Anchor, zoals een vervaldatum, kunnen worden ingesteld voordat u Azure Spatial Anchor maakt met de service.

Blueprint of pin component function connected to create cloud anchor function returning ARPin

  1. Stel de vervaldatum van Azure Spatial Anchor in. Met de parameter Levensduur van deze functie kan de ontwikkelaar in seconden opgeven hoe lang het anker moet worden onderhouden door de service.
    • Een week lang verlopen duurt bijvoorbeeld een waarde van 60 seconden x 60 minuten x 24 uur x zeven dagen = 604.800 seconden.

Blueprint of cloud anchor connected to set expiration function with lifetime value set to 604,800 seconds

Nadat u ankerparameters hebt ingesteld, declareert u het anker als gereed om op te slaan. In het onderstaande voorbeeld wordt het zojuist gemaakte Azure Spatial Anchor toegevoegd aan een set Azure Spatial Anchors die moet worden opgeslagen. Deze set wordt gedeclareerd als een variabele voor de Pawn-blauwdruk.

Blueprint of anchor ready to be saved in set variable

Een anker opslaan

Nadat u Azure Spatial Anchor met uw parameters hebt geconfigureerd, roept u Save Cloud Anchor aan. Cloud Anchor declareert het anker naar de Azure Spatial Anchors-service. Wanneer de aanroep om Cloud Anchor opslaan slaagt, is Azure Spatial Anchor beschikbaar voor andere gebruikers van de Azure Spatial Anchor-service.

Blueprint of save cloud anchor function being called

Notitie

Save Cloud Anchor is een asynchrone functie en kan alleen worden aangeroepen op een gamethreadgebeurtenis, zoals EventTick. Cloud Anchor opslaan wordt mogelijk niet weergegeven als een beschikbare blauwdrukfunctie in aangepaste blauwdrukfuncties. Deze moet echter beschikbaar zijn in de Pawn-gebeurtenis Graph blauwdrukeditor.

In het onderstaande voorbeeld wordt het Azure Spatial Anchor opgeslagen in een set tijdens een callback van invoergebeurtenissen. Het anker wordt vervolgens opgeslagen op EventTick. Het opslaan van een Azure Spatial Anchor kan meerdere pogingen duren, afhankelijk van de hoeveelheid ruimtelijke gegevens die uw Azure Spatial Anchors-sessie heeft gemaakt. Daarom is het een goed idee om te controleren of de aanroep opslaan is geslaagd.

Als het anker niet wordt opgeslagen, hebt u het gelezen naar de set ankers die nog steeds moeten worden opgeslagen. Toekomstige EventTicks proberen het anker op te slaan totdat het is opgeslagen.

Blueprint of unsaved anchors being saved again in set variable

Zodra het anker is opgeslagen, fungeert de transformatie van de AR Pins als referentietransformatie voor het plaatsen van inhoud in uw app. Andere gebruikers kunnen dit anker detecteren en AR-inhoud uitlijnen op verschillende apparaten in de fysieke wereld.

Een anker verwijderen

U kunt ankers verwijderen uit de Azure Spatial Anchor-service door Delete Cloud Anchor aan te roepen.

Blueprint of delete cloud anchor function being called

Notitie

Cloud Anchor verwijderen is een latente functie en kan alleen worden aangeroepen op een gamethreadgebeurtenis, zoals EventTick. Cloud Anchor verwijderen wordt mogelijk niet weergegeven als een beschikbare blauwdrukfunctie in aangepaste blauwdrukfuncties. Deze moet echter beschikbaar zijn in de Pawn-gebeurtenis Graph blauwdrukeditor.

In het onderstaande voorbeeld wordt het anker gemarkeerd voor verwijdering bij een aangepaste invoergebeurtenis. De verwijdering wordt vervolgens uitgevoerd op EventTick. Als het verwijderen van het anker mislukt, voegt u Azure Spatial Anchor toe aan de set ankers die zijn gemarkeerd voor verwijdering en probeert u het later opnieuw op EventTicks.

Uw blauwdruk voor gebeurtenis Graph moet er nu uitzien zoals in de onderstaande schermopname:

Blueprint of complete event graph for handling cloud anchors

Bestaande ankers zoeken

Bestaande ankers kunnen worden gemaakt door peers met de Azure Spatial Anchors-service:

  1. Haal een Azure Spatial Anchor-id op voor het anker dat u wilt detecteren.
    • Een anker-id kan worden verkregen voor een anker dat is gemaakt door hetzelfde apparaat in een eerdere Azure Spatial Anchors-sessie. Het kan ook worden gemaakt en gedeeld door peerapparaten die communiceren met de Azure Spatial Anchors-service.

Blueprint of store azure spatial anchor identifier custom event with get azure cloud identifier function

  1. Voeg een AzureSpatialAnchorsEvent-onderdeel toe aan uw Pawn-blauwdruk.
    • Met dit onderdeel kunt u zich abonneren op verschillende Azure Spatial Anchors-gebeurtenissen, zoals gebeurtenissen die worden aangeroepen wanneer Azure Spatial Anchors zich bevindt.

Screenshot of BP_Pawn open in blueprint editor with components and detail panels open

  1. Abonneer u op de ASAAnchor Located Delegate voor het AzureSpatialAnchorsEvent-onderdeel .
    • De gedelegeerde laat de toepassing weten wanneer er nieuwe ankers zijn gevonden die zijn gekoppeld aan het Azure Spatial Anchors-account.
    • Bij het terugbellen van gebeurtenissen worden in Azure Spatial Anchors die zijn gemaakt door peers met behulp van de Azure Spatial Anchors-sessie, standaard geen AR-pins gemaakt. Ontwikkelaars kunnen ARPin maken rond Azure Cloud Spatial Anchor om een AR Pin te maken voor het gedetecteerde Azure Spatial Anchor.

Blueprint of begin play event connected to ASAAnchor located delegate

Als u Azure Spatial Anchors wilt zoeken die zijn gemaakt door peers met behulp van de Azure Spatial Anchor-service, moet de toepassing een Azure Spatial Anchors Watcher maken:

  1. Controleer of een Azure Spatial Anchors-sessie wordt uitgevoerd.
  2. Maak een AzureSpatialAnchorsLocateCriteria.
    • U kunt verschillende locatieparameters opgeven, zoals afstand van de gebruiker of afstand van een ander anker.
  3. Declareer de Azure Spatial Anchor-id die u zoekt in de AzureSpatialAnchorsLocateCritieria.
  4. Roep Watcher maken aan.

Blueprint of start azure spatial anchors watcher custom event

De toepassing begint nu met het zoeken naar Azure Spatial Anchors die bekend is bij de Azure Spatial Anchors-service, wat betekent dat gebruikers Azure Spatial Anchors kunnen vinden die zijn gemaakt door hun peers.

Nadat u Azure Spatial Anchor hebt gezocht, roept u Stop Watcher aan om de Azure Spatial Anchors Watcher te stoppen en watcher-resources op te schonen.

Blueprint of stop watcher function being called

De uiteindelijke blauwdruk voor gebeurtenis Graph moet er nu uitzien zoals in de onderstaande schermopname:

Blueprint of complete event graph for handling anchor delegate events

Volgende controlepunt voor ontwikkeling

Als u het Unreal-ontwikkelingstraject volgt dat we hebben opgesteld, bevindt u zich midden in het verkennen van de basisbouwstenen van MRTK. Vanaf hier kunt u doorgaan naar de volgende bouwsteen:

Of ga naar Mixed Reality platformmogelijkheden en API's:

U kunt altijd op elk gewenst moment teruggaan naar de Unreal development checkpoints .

Volgende stappen