Guida per gli sviluppatori di Cloud Anchors per Unity (AR Foundation)

Scopri come utilizzare Cloud Anchor nelle tue app.

Prerequisiti

Assicurati di comprendere i concetti fondamentali della realtà aumentata e su come configurare una sessione ARCore prima di procedere.

Se non hai mai utilizzato gli ancoraggi Cloud, assicurati di aver compreso come funzionano gli ancoraggi e gli ancoraggi Cloud.

Abilita l'API ARCore

Prima di utilizzare gli ancoraggi Cloud nella tua app, devi abilitare l'API ARCore nell'applicazione.

Abilita le funzionalità di Cloud Anchor nella configurazione della sessione

Dopo aver abilitato le funzionalità di Cloud anchor nell'app, attivale nella configurazione della sessione AR dell'app, in modo che possa comunicare con l'API ARCore:

Ospita un ancoraggio cloud

Hosting inizia con una chiamata a ARAnchorManager.HostCloudAnchorAsync(). ARCore caricherà i dati visivi, le pose dei dispositivi e la posa di ancoraggio nell'API ARCore. L'API elabora quindi queste informazioni per creare una mappa delle caratteristiche 3D, restituendo infine un ID ancoraggio Cloud univoco per l'ancoraggio al dispositivo.

Puoi anche estendere la durata di un ancoraggio ospitato utilizzando l'API Cloud Anchor Management di ARCore.

Per completare l'hosting di un ancoraggio cloud, la tua app deve seguire questi passaggi:

  1. Chiama il numero ARAnchorManager.HostCloudAnchorAsync().
  2. Inizia una coroutine e attendi che la Promessa dia un risultato. Per ulteriori informazioni, vedi Coroutines in Unity.
  3. Controllare lo stato dei risultati per determinare se l'operazione è riuscita o interpretare il codice di errore se non è riuscita.
  4. Condividi il risultato dell'ID ancoraggio Cloud con altri client e utilizzalo per risolvere l'ancoraggio cloud con ARAnchorManagerExtensions.ResolveCloudAnchorAsync()

Controllare la qualità della mappatura dei punti delle caratteristiche

ARCoreExtensions.FeatureMapQuality indica la qualità dei punti delle caratteristiche rilevati da ARCore nei pochi secondi precedenti da una determinata posa della fotocamera. I cloud anchor ospitati utilizzando funzionalità di qualità superiore vengono generalmente risolti in modo più accurato. Utilizza ARAnchorManagerExtensions.EstimateFeatureMapQualityForHosting() per ottenere una stima della qualità della mappa delle caratteristiche per una determinata posa della fotocamera.

Valore Descrizione
Insufficient La qualità dei punti delle caratteristiche identificati dalla posa nei secondi precedenti è bassa. Questo stato indica che ARCore avrà probabilmente maggiori difficoltà a risolvere l'anchor cloud. Incoraggia l'utente a spostare il dispositivo in modo che la posizione desiderata dell'anchor cloud che vuole ospitare possa essere visualizzata da diverse angolazioni.
Sufficient La qualità dei punti delle caratteristiche identificati dalla posa nei secondi precedenti è probabilmente sufficiente per consentire ad ARCore di risolvere correttamente un ancoraggio cloud, anche se la precisione della posa risolta verrà probabilmente ridotta. Incoraggia l'utente a spostare il dispositivo in modo che la posizione desiderata dell'anchor cloud che vuole ospitare possa essere visualizzata da diverse angolazioni.
Good La qualità dei punti delle caratteristiche identificati dalla posa nei secondi precedenti è probabilmente sufficiente affinché ARCore risolva correttamente un ancoraggio cloud con un elevato grado di precisione.

Risolvi un ancoraggio ospitato in precedenza

Chiama ARAnchorManagerExtensions.ResolveCloudAnchorAsync() per risolvere un ancoraggio Cloud ospitato. L'API ARCore confronta periodicamente le caratteristiche visive della scena con la mappa delle caratteristiche 3D dell'ancoraggio per individuare la posizione e l'orientamento dell'utente rispetto all'ancoraggio. Quando trova una corrispondenza, l'API restituisce la posa dell'anchor cloud ospitato.

Puoi avviare risoluzioni per più ancoraggi Cloud in sequenza. Possono esistere fino a 40 operazioni Cloud Anchor simultanee alla volta.

Annulla un'operazione o rimuovi un ancoraggio Cloud

ARCloudAnchor.OnDestroy() viene chiamato automaticamente quando il componente ARCloudAnchor viene rimosso dall'oggetto gioco che lo contiene. Questa operazione scollegherà e rilascerà l'oggetto Cloud Anchor nativo sottostante.

Verifica lo stato dei risultati di un'operazione Cloud Anchor

Utilizza CloudAnchorState per controllare lo stato dei risultati dell'operazione di hosting o di risoluzione, inclusi gli errori.

Valore Descrizione
ErrorResolvingCloudIdNotFound La risoluzione non è riuscita perché l'API ARCore non è riuscita a trovare l'ID ancoraggio Cloud fornito.
ErrorHostingDatasetProcessingFailed Hosting non riuscito perché il server non è riuscito a elaborare correttamente il set di dati per l'anchor specificato. Riprova dopo che il dispositivo avrà raccolto più dati dall'ambiente.
ErrorHostingServiceUnavailable L'API ARCore non è raggiungibile. Questa condizione può verificarsi per diversi motivi. Il dispositivo potrebbe essere in modalità aereo o non disporre di una connessione a internet funzionante. La richiesta inviata al server potrebbe essere scaduta senza risposta. Potrebbero verificarsi problemi di connessione di rete, mancata disponibilità del DNS, problemi del firewall o altri problemi che potrebbero influire sulla capacità del dispositivo di connettersi all'API ARCore.
ErrorInternal Un'attività di hosting o risoluzione per questo ancoraggio è stata completata con un errore interno. L'app non deve tentare di recuperare a seguito di questo errore.
ErrorNotAuthorized L'app non può comunicare con l'API ARCore a causa di autorizzazioni non valide. Controlla in Impostazioni progetto > XR > ARCore Extensions per una strategia di autorizzazione valida.
ErrorResolvingPackageTooNew Non è stato possibile risolvere l'anchor cloud perché il pacchetto delle estensioni ARCore utilizzato per risolvere l'anchor cloud è più recente e incompatibile con la versione utilizzata per ospitarlo.
ErrorResolvingPackageTooOld Non è stato possibile risolvere l'anchor cloud perché il pacchetto delle estensioni ARCore utilizzato per risolvere l'anchor cloud è precedente e incompatibile con la versione utilizzata per ospitarlo.
ErrorResourceExhausted L'applicazione ha esaurito la quota di richieste assegnata al progetto Google Cloud specificato. Devi richiedere una quota aggiuntiva per l'API ARCore per il tuo progetto da Google Developers Console.
Success Un'attività di hosting o risoluzione per questo ancoraggio è stata completata correttamente.

Quote API per richieste host e di risoluzione

L'API ARCore prevede le seguenti quote per la larghezza di banda delle richieste:

Tipo di quota Massimo Durata Si applica a
Numero di ancoraggi Nessun limite N/D progetto
Ancorare le richieste host 30 minuto Indirizzo IP e progetto
Richieste di risoluzione di ancoraggio 300 minuto Indirizzo IP e progetto

Best practice per una buona esperienza utente

Chiedi agli utenti di procedere nel seguente modo per garantire una buona esperienza utente sulla tua app:

  • Attendi qualche secondo dopo l'avvio della sessione prima di tentare di ospitare un ancoraggio (posizionando un oggetto e così via). In questo modo il rilevamento ha un po' di tempo per stabilizzarsi.
  • Quando selezioni una posizione in cui ospitare l'ancoraggio, cerca di trovare un'area con elementi visivi facilmente distinguibili l'uno dall'altro. Per ottenere risultati ottimali, evita superfici riflettenti o prive di caratteristiche visive, come pareti bianche vuote.

  • Tieni la fotocamera centrata sul centro di interesse e muovi il dispositivo il centro di interesse per mappare l'ambiente da diverse angolazioni, mantenendo all'incirca la stessa distanza fisica. Ciò consentirà di acquisire più dati visivi e rendere più efficace la risoluzione.

  • Assicurati che ci sia sufficiente illuminazione nell'ambiente reale durante l'hosting e la risoluzione degli ancoraggi Cloud.

Norme sul ritiro

  • Le app create con l'SDK ARCore 1.12.0 o versioni successive sono coperte dalle norme sul ritiro dell'API Cloud Anchor.
  • Le app create con ARCore SDK 1.11.0 o versioni precedenti non sono in grado di ospitare o risolvere gli ancoraggi Cloud a causa dell'utilizzo da parte dell'SDK di un'API ARCore meno recente e deprecata.

Passaggi successivi