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

Scopri come utilizzare Cloud Anchor nelle tue app.

Prerequisiti

Prima di procedere, assicurati di conoscere i concetti fondamentali dell'AR e come configurare una sessione ARCore.

Se non hai mai utilizzato Cloud Anchors, assicurati di comprendere come funzionano gli ancoraggi e Cloud Anchors.

Attiva l'API ARCore

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

Attiva le funzionalità di Cloud Anchor nella configurazione della sessione

Dopo aver attivato la funzionalità Cloud Anchors nell'app, abilita le funzionalità Cloud Anchors nella configurazione della sessione AR dell'app in modo che possa comunicare con l'API ARCore:

Ospitare un Cloud Anchor

L'hosting inizia con una chiamata a ARAnchorManager.HostCloudAnchorAsync(). ARCore caricherà i dati visivi, le pose del dispositivo 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'ancora ospitata utilizzando l'API ARCore Cloud Anchor Management.

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

  1. Chiama il numero ARAnchorManager.HostCloudAnchorAsync().
  2. Avvia una coroutine per attendere che la promessa restituisca un risultato. Per ulteriori informazioni, consulta Coroutine in Unity.
  3. Controlla lo stato del risultato per determinare se l'operazione è riuscita o interpreta il codice di errore se non è riuscita.
  4. Condividi l'ID Cloud Anchor risultante con altri client e utilizzalo per risolvere Cloud Anchor con ARAnchorManagerExtensions.ResolveCloudAnchorAsync().

Controllare la qualità della mappatura dei punti di interesse

ARCoreExtensions.FeatureMapQuality indica la qualità dei punti di riferimento rilevati da ARCore nei pochi secondi precedenti da una determinata posizione della fotocamera. In genere, gli ancoraggi cloud ospitati utilizzando funzionalità di qualità superiore vengono risolti con maggiore precisione. 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 di riferimento identificati dalla posa nei pochi secondi precedenti è bassa. Questo stato indica che ARCore avrà probabilmente più difficoltà a risolvere l'ancora nel cloud. Incoraggia l'utente a spostare il dispositivo in modo che la posizione desiderata dell'ancora cloud che vuole ospitare possa essere visualizzata da angolazioni diverse.
Sufficient La qualità dei punti di riferimento identificati dalla posa nei secondi precedenti è probabilmente sufficiente per consentire ad ARCore di risolvere correttamente un'ancora nel cloud, anche se la precisione della posa risolta potrebbe essere ridotta. Incoraggia l'utente a spostare il dispositivo in modo che la posizione desiderata dell'ancora cloud che vuole ospitare possa essere visualizzata da angolazioni diverse.
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 Cloud Anchor ospitato. L'API ARCore confronta periodicamente le caratteristiche visive della scena con la mappa di caratteristiche 3D dell'ancora per individuare la posizione e l'orientamento dell'utente rispetto all'ancora. Quando trova una corrispondenza, l'API restituisce la posa dell'ancora cloud ospitata.

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

Annullare un'operazione o rimuovere un ancoraggio cloud

ARCloudAnchor.OnDestroy() viene chiamato automaticamente quando il componente ARCloudAnchor viene rimosso dall'oggetto di gioco che lo contiene. Verrà scollegato e rilasciato l'oggetto Cloud Anchor nativo sottostante.

Controllare lo stato del risultato di un'operazione Cloud Anchor

Utilizza CloudAnchorState per controllare lo stato del risultato dell'operazione di hosting o 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 L'hosting non è riuscito perché il server non è riuscito a elaborare correttamente il set di dati per l'ancora specificata. Riprova dopo che il dispositivo ha 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 avere una connessione a internet funzionante. La richiesta inviata al server potrebbe essere scaduta senza risposta. Potrebbe esserci una connessione di rete debole, DNS non disponibile, problemi di firewall o qualsiasi altro elemento che potrebbe influire sulla capacità del dispositivo di connettersi all'API ARCore.
ErrorInternal Un'attività di hosting o risoluzione per questa ancora è terminata con un errore interno. L'app non deve tentare di recuperare da questo errore.
ErrorNotAuthorized L'app non può comunicare con l'API ARCore a causa di un'autorizzazione non valida. Controlla Impostazioni progetto > XR > Estensioni ARCore 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'ancora cloud perché il pacchetto delle estensioni ARCore utilizzato per risolvere l'ancora 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 le richieste di host e risoluzione

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

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

Best practice per un'esperienza utente ottimale

Per garantire un'esperienza utente positiva nella tua app, chiedi agli utenti di svolgere le seguenti operazioni:

  • Attendi qualche secondo dall'avvio della sessione prima di tentare di ospitare un'ancora (posizionando un oggetto e così via). In questo modo il monitoraggio ha il tempo di stabilizzarsi.
  • Quando selezioni una posizione per l'ancora, cerca un'area con elementi visivi facilmente distinguibili tra loro. Per ottenere risultati ottimali, evita superfici riflettenti o prive di elementi visivi, come pareti bianche vuote.

  • Mantieni la fotocamera puntata sul centro di interesse e sposta il dispositivo intorno al centro di interesse per mappare l'ambiente da angolazioni diverse, mantenendo approssimativamente la stessa distanza fisica. In questo modo, potrai acquisire più dati visivi e migliorare la risoluzione.

  • Assicurati che ci sia abbastanza 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 relative al ritiro dell'API Cloud Anchor.
  • Le app create con l'SDK ARCore 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 precedente e deprecata.

Passaggi successivi