Ancoraggi nello spazio di Azure in Unreal

  • Articolo

Ancoraggi nello spazio di Azure è un servizio di Realtà mista di Microsoft che consente ai dispositivi di realtà aumentata di individuare, condividere e salvare in modo permanente i punti di ancoraggio nel mondo fisico. La documentazione seguente fornisce istruzioni utili per l'integrazione del servizio Ancoraggi nello spazio di Azure in un progetto Unreal. Per altre informazioni, vedere il servizio Ancoraggi nello spazio di Azure.

Nota

Unreal Engine 4.26 è ora dotato di plug-in per il supporto di ARKit e ARCore nel caso in cui la destinazione sia un dispositivo iOS o Android.

Importante

Gli ancoraggi locali vengono archiviati nel dispositivo, mentre i dati relativi ad Ancoraggi nello spazio di Azure vengono archiviati nel cloud. Se si vuole archiviare gli ancoraggi in locale in un dispositivo, è disponibile il documento Ancoraggi nello spazio locali che fornisce informazioni dettagliate per l'esecuzione del processo. Si noti che è possibile includere ancoraggi locali e ancoraggi di Azure nello stesso progetto senza che si verifichino conflitti.

Prerequisiti

Per completare le procedure contenute in questa guida, verificare che siano soddisfatti i requisti seguenti:

Recupero delle informazioni sull'account di Ancoraggi nello spazio di Azure

Prima di usare Ancoraggi nello spazio di Azure nel progetto, è necessario:

Per altre informazioni, vedere la documentazione relativa all'autenticazione di Ancoraggi nello spazio di Azure.

Nota

Ancoraggi nello spazio di Azure in Unreal 4.25 non supporta i token di autenticazione di Azure AD. Il supporto per questa funzionalità, tuttavia, sarà disponibile in una versione successiva.

Abilitare funzionalità e autorizzazioni

HoloLens

Aprire Impostazioni > progetto HoloLens e abilitare la funzionalità Client Internet :

Impostazioni del progetto HoloLens con funzionalità evidenziate

Android

Per visualizzare una finestra di dialogo di autorizzazione e consentire le funzionalità di posizione, è necessario chiamare la funzione Richiedi autorizzazioni Android prima di tentare di avviare la sessione di ancoraggio nello spazio di Azure:

Richiedere le autorizzazioni Android

Creare una variabile locale per le autorizzazioni di input e popolare con:

  • 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

Impostare le autorizzazioni Android

Infine, aprire Impostazioni > progetto Android e impostare le stesse autorizzazioni nel campo Autorizzazioni aggiuntive in Creazione di pacchetti APK avanzati:

Impostazioni del progetto ANDROID APK

iOS

Per creare un'applicazione per iOS, è necessario usare Unreal in un Mac. Per creare un pacchetto con un account sviluppatore Apple, aprire Impostazioni progetto > iOS e scorrere verso il basso fino alla sezione Compilazione . Abilitare la casella di controllo Firma automatica e popolare l'ID team IOS con l'ID team.

È possibile trovare l'ID team accedendo a developer.apple.com, passando alla scheda Appartenenza e cercando l'ID team.

Per visualizzare un dialogo di autorizzazione e consentire al dispositivo iOS di accedere alle informazioni sulla posizione, è necessario chiamare le funzioni Init Location Services e Start Location Services prima di tentare di avviare la sessione di ancoraggio spaziale di Azure:

Avviare i servizi di posizione iOS

Aggiunta di plug-in di Ancoraggi nello spazio di Azure

Suggerimento

Quando si usano ancoraggi nello spazio di Azure per Unreal, è disponibile un plug-in Ancoraggi nello spazio di Azure e un plug-in specifico della piattaforma (WMR, ARKit, ARCore, OpenXR). È necessario disporre di un solo plug-in specifico della piattaforma abilitato alla volta.

HoloLens

Abilitare i plug-in di Ancoraggi nello spazio di Azure nell'editor Unreal nel modo seguente:

  1. Fare clic su Modifica > plug-in e cercare ancoraggi nello spazio di Azure e ancoraggi nello spazio di Azure per WMR.
  2. Selezionare la casella di controllo Enabled (Abilitato) di entrambi i plug-in per consentire l'accesso alle librerie del progetto di Ancoraggi nello spazio di Azure nell'applicazione.

Screenshot dei plug-in di Ancoraggi nello spazio nell'editor di Unreal

Al termine, riavviare l'editor Unreal per rendere effettive le modifiche apportate ai plug-in. Il progetto è ora pronto per l'uso di Ancoraggi nello spazio di Azure.

Android

Abilitare i plug-in di Ancoraggi nello spazio di Azure nell'editor Unreal nel modo seguente:

  1. Fare clic su Modifica > plug-in e cercare ancoraggi nello spazio di Azure e ancoraggi nello spazio di Azure per ARCore.
  2. Selezionare la casella di controllo Enabled (Abilitato) di entrambi i plug-in per consentire l'accesso alle librerie del progetto di Ancoraggi nello spazio di Azure nell'applicazione.

Plug-in Android nell'editor Unreal

Al termine, riavviare l'editor Unreal per rendere effettive le modifiche apportate ai plug-in. Il progetto è ora pronto per l'uso di Ancoraggi nello spazio di Azure.

iOS

Abilitare i plug-in di Ancoraggi nello spazio di Azure nell'editor Unreal nel modo seguente:

  1. Fare clic su Modifica > plug-in e cercare ancoraggi nello spazio di Azure e ancoraggi nello spazio di Azure per ARKit.
  2. Selezionare la casella di controllo Enabled (Abilitato) di entrambi i plug-in per consentire l'accesso alle librerie del progetto di Ancoraggi nello spazio di Azure nell'applicazione.

Plug-in iOS ASA nell'editor Unreal

  1. Cercare anche Servizi location per dispositivi mobili e Servizi di posizione mobile - Implementazione IOS
  2. Selezionare la casella di controllo Abilitato in entrambi i plug-in per consentire al dispositivo iOS di accedere alla posizione corrente.

Plug-in Percorso iOS nell'editor Unreal

Al termine, riavviare l'editor Unreal per rendere effettive le modifiche apportate ai plug-in. Il progetto è ora pronto per l'uso di Ancoraggi nello spazio di Azure.

Avvio di una sessione di Ancoraggi nello spazio

Una sessione di Ancoraggi nello spazio di Azure consente alle applicazioni client di comunicare con il servizio Ancoraggi nello spazio di Azure. È necessario creare e avviare una sessione di Ancoraggi nello spazio di Azure per creare, salvare in modo permanente e condividere Ancoraggi nello spazio di Azure:

  1. Aprire il progetto per il pedone che si sta usando nell'applicazione.
  2. Aggiungere due variabili di stringa per ID account e Chiave dell'account e quindi assegnare i valori corrispondenti dell'account di Ancoraggi nello spazio di Azure per eseguire l'autenticazione della sessione.

Screenshot del riquadro dei dettagli con l'ID e la chiave dell'account di Ancoraggi nello spazio di Azure e il tipo di variabile evidenziati

Avviare una sessione di Ancoraggi nello spazio di Azure nel modo seguente:

  1. Verificare che nell'applicazione HoloLens sia in esecuzione un'istanza di AR Session (Sessione AR) poiché la sessione di Ancoraggi nello spazio di Azure non può essere avviata fino a quando non è in esecuzione una sessione AR. Creare un asset di sessione AR se non ne è stato configurato nessuno.
  2. Aggiungere l'evento personalizzato Start Azure Spatial Anchors Session (Avvia sessione di Ancoraggi nello spazio di Azure) e configurarlo nel modo illustrato nello screenshot seguente.
    • La creazione di una sessione non determina l'avvio della sessione per impostazione predefinita, che consente di configurare la sessione per l'autenticazione con il servizio Ancoraggi nello spazio di Azure.

Progetto dell'evento personalizzato di avvio della sessione di Ancoraggi nello spazio di Azure

  1. Configurare la sessione ancoraggi nello spazio di Azure per specificare l'ID account, la chiave dell'account, il dominio account e le impostazioni di localizzazione del corso. Tutte le caselle di controllo devono essere abilitate nelle impostazioni di localizzazione del corso in modo che il servizio di ancoraggio spaziale di Azure possa usare i dati del sensore per individuare gli ancoraggi.

Progetto della funzione di configurazione della sessione con ID e chiave dell'account aggiunti

  1. Avviare la sessione di Ancoraggi nello spazio di Azure, consentendo all'applicazione di creare e individuare Ancoraggi nello spazio di Azure.

Progetto della funzione di avvio della sessione di Ancoraggi nello spazio di Azure

Quando non si usa più il servizio, è consigliabile pulire le risorse di Ancoraggi nello spazio di Azure presenti nel progetto Event Graph (Grafico eventi):

  1. Arrestare la sessione di Ancoraggi nello spazio di Azure. La sessione non sarà più in esecuzione, ma le risorse associate saranno ancora presenti nel plug-in di Ancoraggi nello spazio di Azure.

Progetto dell'evento personalizzato di arresto della sessione di Ancoraggi nello spazio di Azure e della funzione di arresto della sessione

  1. Eliminare la sessione di Ancoraggi nello spazio di Azure per eseguire la pulizia di tutte le risorse della sessione ancora note al plug-in di Ancoraggi nello spazio di Azure.

Progetto della funzione di eliminazione della sessione

Il progetto Event Graph (Grafico eventi) dovrebbe avere un aspetto simile allo screenshot seguente:

Progetto del grafico eventi completo per la configurazione della sessione di Ancoraggi nello spazio di Azure

Creazione di un ancoraggio

Un ancoraggio nello spazio di Azure rappresenta una posa del mondo fisico nello spazio dell'applicazione di realtà aumentata, che blocca il contenuto della realtà aumentata nelle posizioni fisiche. È anche possibile condividere Ancoraggi nello spazio di Azure tra diversi utenti. Questa condivisione consente al contenuto della realtà aumentata progettato su dispositivi diversi di essere posizionato come nel mondo fisico.

Per creare un nuovo ancoraggio nello spazio di Azure:

  1. Verificare che sia in esecuzione una sessione di Ancoraggi nello spazio di Azure. L'applicazione non può creare o salvare in modo permanente un ancoraggio nello spazio di Azure quando non è in esecuzione alcuna sessione di Ancoraggi nello spazio di Azure.

Progetto dell'evento personalizzato di creazione dell'ancoraggio nello spazio di Azure

  1. Creare oppure ottenere un componente scena di Unreal di cui deve essere salvata la posizione in modo permanente.
    • Nell'immagine seguente il componente Scene Component Needing Anchor (Componente scena con necessità di ancoraggio) viene usato come variabile. È necessario un componente scena Unreal per stabilire una trasformazione globale dell'applicazione per un segnaposto AR e un ancoraggio nello spazio di Azure.

Progetto dell'evento personalizzato di creazione dell'ancoraggio nello spazio di Azure con il componente scena

Per costruire e salvare un ancoraggio nello spazio di Azure per un componente scena Unreal:

  1. Chiamare Pin Component (Componente segnaposto) per il componente scena Unreal e specificare World Transform (Trasformazione globale) come trasformazione globale usata per il segnaposto AR.
    • Unreal tiene traccia dei punti AR nello spazio dell'applicazione con i segnaposto AR, usati per creare un ancoraggio nello spazio di Azure. In Unreal un segnaposto AR è analogo a un ancoraggio nello spazio di HoloLens.

Progetto del componente scena collegato alla funzione del componente segnaposto

  1. Chiamare Create Cloud Anchor (Crea ancoraggio cloud) usando il segnaposto AR appena creato.
    • La chiamata a Create Cloud Anchor (Crea ancoraggio cloud) consente di creare un ancoraggio nello spazio di Azure in locale, ma non nel servizio Ancoraggi nello spazio di Azure. È possibile impostare i parametri relativi all'ancoraggio nello spazio di Azure, ad esempio una data di scadenza, prima di creare l'ancoraggio nello spazio di Azure con il servizio.

Progetto della funzione del componente segnaposto collegata per creare una funzione di ancoraggio cloud che restituisca il segnaposto AR

  1. Impostare la scadenza dell'ancoraggio nello spazio di Azure. Il parametro Lifetime (Durata) di questa funzione consente allo sviluppatore di specificare l'intervallo di tempo in secondi durante il quale l'ancoraggio deve essere mantenuto dal servizio.
    • Ad esempio, per una durata di una settimana è richiesto un valore di 60 secondi x 60 minuti x 24 ore x sette giorni = 604.800 secondi.

Progetto dell'ancoraggio cloud collegato per impostare la funzione di scadenza con valore di durata pari a 604.800 secondi

Dopo aver impostato i parametri di ancoraggio, dichiarare l'ancoraggio come pronto per il salvataggio. Nell'esempio seguente, l'ancoraggio nello spazio di Azure appena creato viene aggiunto a un set di ancoraggi nello spazio di Azure per i quali è necessario eseguire il salvataggio. Questo set viene dichiarato come variabile per il progetto Pawn.

Progetto dell'ancoraggio pronto per essere salvato nella variabile del set

Salvataggio di un ancoraggio

Dopo aver configurato l'ancoraggio nello spazio di Azure con i parametri, chiamare Save Cloud Anchor (Salva ancoraggio cloud). La chiamata a Save Cloud Anchor (Salva ancoraggio cloud) dichiara l'ancoraggio al servizio Ancoraggi nello spazio di Azure. Se la chiamata a Save Cloud Anchor (Salva ancoraggio cloud) ha esito positivo, l'ancoraggio nello spazio di Azure sarà disponibile per altri utenti del servizio Ancoraggi nello spazio di Azure.

Progetto della funzione di salvataggio dell'ancoraggio cloud chiamata

Nota

Save Cloud Anchor (Salva ancoraggio cloud) è una funzione asincrona e può essere chiamata solo in un evento thread di gioco, ad esempio EventTick. È possibile che Save Cloud Anchor (Salva ancoraggio cloud) non venga visualizzata come funzione disponibile tra le funzioni di progetto personalizzate. Dovrebbe essere disponibile, tuttavia, nell'editor del progetto Pawn Event Graph (Grafico eventi Pawn).

Nell'esempio seguente l'ancoraggio nello spazio di Azure viene archiviato in un set durante un callback dell'evento di input. L'ancoraggio viene quindi salvato in EventTick. Per salvare un ancoraggio nello spazio di Azure, possono essere necessari più tentativi a seconda della quantità di dati spaziali creati dalla sessione di Ancoraggi nello spazio di Azure. Per questo motivo è consigliabile controllare se la chiamata di salvataggio ha avuto esito positivo.

Se l'ancoraggio non viene salvato, aggiungerlo nuovamente al set di ancoraggi ancora da salvare. EventTick futuri continueranno a provare a salvare l'ancoraggio fino a quando non viene archiviato.

Progetto degli ancoraggi non salvati che vengono salvati nuovamente nella variabile del set

Dopo il salvataggio dell'ancoraggio, la trasformazione dei segnaposto AR funge da trasformazione di riferimento per inserire contenuto nell'app. Altri utenti possono rilevare questo ancoraggio e allineare il contenuto AR per dispositivi diversi nel mondo fisico.

Eliminazione di un ancoraggio

È possibile eliminare gli ancoraggi dal servizio Ancoraggi nello spazio di Azure chiamando Delete Cloud Anchor (Elimina ancoraggio cloud).

Progetto della funzione di eliminazione dell'ancoraggio cloud chiamata

Nota

Delete Cloud Anchor (Elimina ancoraggio cloud) è una funzione latente e può essere chiamata solo nel caso di un evento thread di gioco, ad esempio EventTick. È possibile che Delete Cloud Anchor (Elimina ancoraggio cloud) non venga visualizzata come funzione disponibile tra le funzioni di progetto personalizzate. Dovrebbe essere disponibile, tuttavia, nell'editor del progetto Pawn Event Graph (Grafico eventi Pawn).

Nell'esempio seguente l'ancoraggio viene contrassegnato per l'eliminazione in un evento di input personalizzato. L'eliminazione viene quindi tentata in EventTick. Se l'eliminazione dell'ancoraggio non riesce, aggiungere l'ancoraggio nello spazio di Azure al set di ancoraggi contrassegnati per l'eliminazione e riprovare in EventTick successivi.

Il progetto Event Graph (Grafico eventi) dovrebbe ora avere un aspetto simile allo screenshot seguente:

Progetto del grafico eventi completo per la gestione di ancoraggi cloud

Individuazione di ancoraggi preesistenti

Gli ancoraggi esistenti possono essere creati da peer con il servizio Ancoraggi nello spazio di Azure:

  1. Ottenere un identificatore di ancoraggio nello spazio di Azure per l'ancoraggio da rilevare.
    • È possibile ottenere un identificatore per un ancoraggio creato dallo stesso dispositivo in una precedente sessione di Ancoraggi nello spazio di Azure. Può anche essere creato e condiviso da dispositivi peer che interagiscono con il servizio Ancoraggi nello spazio di Azure.

Progetto dell'evento personalizzato di archiviazione dell'identificatore dell'ancoraggio nello spazio di Azure con la funzione per ottenere l'identificatore cloud di Azure

  1. Aggiungere un componente AzureSpatialAnchorsEvent al progetto Pawn.
    • Questo componente consente di effettuare la sottoscrizione a diversi eventi di Ancoraggi nello spazio di Azure, ad esempio eventi chiamati quando vengono individuati gli ancoraggi nello spazio di Azure.

Screenshot di BP_Pawn aperto nell'editor di progetto con i componenti e i riquadri dei dettagli aperti

  1. Effettuare la sottoscrizione ad ASAAnchor Located Delegate per il componente AzureSpatialAnchorsEvent.
    • Il delegato consente all'applicazione di stabilire quando sono stati individuati nuovi ancoraggi associati all'account di Ancoraggi nello spazio di Azure.
    • Con il callback dell'evento, gli ancoraggi nello spazio di Azure creati dai peer con la sessione di Ancoraggi nello spazio di Azure non avranno segnaposto AR creati per impostazione predefinita. Per creare un segnaposto AR per l'ancoraggio nello spazio di Azure rilevato, gli sviluppatori possono chiamare la funzione Create ARPin Around Azure Cloud Spatial Anchor (Crea segnaposto AR attorno all'ancoraggio nello spazio cloud di Azure).

Progetto dell'evento BeginPlay collegato al delegato posizionato da ASAAnchor

Per individuare gli ancoraggi nello spazio di Azure creati da peer con il servizio Ancoraggi nello spazio di Azure, l'applicazione dovrà creare un elemento Azure Spatial Anchors Watcher (Watcher ancoraggi nello spazio di Azure):

  1. Verificare che sia in esecuzione una sessione di Ancoraggi nello spazio di Azure.
  2. Creare AzureSpatialAnchorsLocateCriteria.
    • È possibile specificare diversi parametri di posizione, ad esempio la distanza dall'utente o la distanza da un altro ancoraggio.
  3. Dichiarare in AzureSpatialAnchorsLocateCritieria l'identificatore dell'ancoraggio nello spazio di Azure che si sta cercando.
  4. Chiamare Create Watcher (Crea Watcher).

Progetto dell'evento personalizzato di avvio di Azure Spatial Anchors Watcher

L'applicazione ora inizia a cercare gli ancoraggi nello spazio di Azure noti al servizio Ancoraggi nello spazio di Azure. In altre parole, gli utenti possono individuare gli ancoraggi nello spazio di Azure creati dai relativi peer.

Dopo aver individuato l'ancoraggio nello spazio di Azure, chiamare Stop Watcher (Arresta Watcher) per arrestare Azure Spatial Anchors Watcher (Watcher ancoraggi nello spazio di Azure) e pulire le risorse Watcher.

Progetto della funzione di arresto del watcher chiamata

Il progetto Event Graph (Grafico eventi) finale dovrebbe ora avere un aspetto simile allo screenshot seguente:

Progetto del grafico eventi completo per la gestione degli eventi del delegato degli ancoraggi

Successivo checkpoint di sviluppo

Se si segue il percorso delineato per lo sviluppo con Unreal, tenere presente che si stanno esplorando i blocchi predefiniti fondamentali di MRTK. Da qui è possibile passare al blocco predefinito successivo:

Mapping spaziale

In alternativa, passare alle API e alle funzionalità della piattaforma di realtà mista:

Fotocamera HoloLens

È sempre possibile tornare ai checkpoint per lo sviluppo con Unreal in qualsiasi momento.

Passaggi successivi