Guida per gli sviluppatori di Cloud Anchors per Android (Kotlin/Java)

Scopri come utilizzare Cloud Anchors nelle tue app.

Prerequisiti

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

Se non hai mai utilizzato gli ancoraggi Cloud:

  • Assicurati di comprendere il funzionamento degli ancoraggi e dei Cloud Anchors.
  • Leggi la guida rapida di Cloud Anchors per i requisiti di sistema, la configurazione e le istruzioni di installazione.

Attiva l'API ARCore

Prima di utilizzare Cloud Anchors nella tua app, devi prima attivare l'API ARCore nella tua 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:

Java

Config config = new Config(session);
config.setCloudAnchorMode(Config.CloudAnchorMode.ENABLED);
session.configure(config);

Kotlin

val config = Config(session)
config.cloudAnchorMode = Config.CloudAnchorMode.ENABLED
session.configure(config)

Ospita un ancoraggio cloud

L'hosting inizia con una chiamata a 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 di elementi 3D, restituendo infine un ID Cloud Anchor univoco per l'ancora 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 hostCloudAnchorAsync().
  2. Attendi il callback o controlla continuamente lo stato Future finché non viene completato.
  3. Controllare lo stato dei risultati per stabilire 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 resolveCloudAnchorAsync()

Controllare la qualità della mappatura dei punti di interesse

Session.FeatureMapQuality indica la qualità dei punti di riferimento rilevati da ARCore nei pochi secondi precedenti da una determinata posizione della fotocamera. I cloud anchor ospitati utilizzando funzionalità di qualità superiore vengono generalmente risolti in modo più accurato. Utilizza Session.estimateFeatureMapQualityForHosting() per ottenere una stima della qualità della mappa di 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. Invita 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 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. Invita 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.

Risolvere un'ancora ospitata in precedenza

Chiama resolveCloudAnchorAsync() per risolvere un Cloud Anchor 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

Chiama cancel() per annullare un'operazione Cloud Anchor in attesa. Chiama detach() per rimuovere dall'app un Cloud Anchor già risolto.

Controllare lo stato del risultato di un'operazione Cloud Anchor

Utilizza Anchor.CloudAnchorState per controllare lo stato del risultato dell'operazione di hosting o risoluzione, inclusi gli errori.

Valore Descrizione
ERROR_CLOUD_ID_NOT_FOUND La risoluzione non è riuscita perché l'API ARCore non è riuscita a trovare l'ID ancoraggio Cloud fornito.
ERROR_HOSTING_DATASET_PROCESSING_FAILED Hosting non riuscito perché il server non è riuscito a elaborare correttamente il set di dati per l'anchor specificato. Riprova dopo che il dispositivo ha raccolto più dati dall'ambiente.
ERROR_HOSTING_SERVICE_UNAVAILABLE 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 aver superato il tempo di attesa senza ricevere 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.
ERROR_INTERNAL Un'attività di hosting o risoluzione per questa ancora è terminata con un errore interno. L'app non deve tentare di recuperare da questo errore.
ERROR_NOT_AUTHORIZED L'autorizzazione fornita dalla richiesta non è valida. Consulta la sezione Risoluzione dei problemi con l'autorizzazione dell'API ARCore.
ERROR_RESOLVING_SDK_VERSION_TOO_NEW Non è stato possibile risolvere l'ancora cloud perché la versione dell'SDK utilizzata per risolverlo è più recente e incompatibile con la versione utilizzata per ospitarlo.
ERROR_RESOLVING_SDK_VERSION_TOO_OLD Non è stato possibile risolvere l'anchor cloud perché la versione dell'SDK utilizzata per risolvere l'anchor è precedente e incompatibile con la versione utilizzata per ospitarlo.
ERROR_RESOURCE_EXHAUSTED 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 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
Richieste di hosting dell'ancora 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 avrà 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 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 l'illuminazione nell'ambiente reale sia sufficiente durante l'hosting e la risoluzione di Cloud Anchors.

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