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

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 comprendere come funzionano gli ancoraggi e gli ancoraggi Cloud.
  • Leggi la guida rapida degli ancoraggi Cloud per conoscere i requisiti di sistema, la configurazione e le istruzioni di installazione.

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:

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

Hosting inizia con una chiamata a 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 hostCloudAnchorAsync().
  2. Attendi che venga richiamato o controlla continuamente lo stato Futuro fino al termine dell'operazione.
  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 resolveCloudAnchorAsync()

Controllare la qualità della mappatura dei punti delle caratteristiche

Session.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 Session.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 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

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

Verifica lo stato dei risultati di un'operazione Cloud Anchor

Utilizza Anchor.CloudAnchorState per controllare lo stato dei risultati dell'operazione di hosting o di 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 avrà 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 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.
ERROR_INTERNAL 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.
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'anchor cloud perché la versione dell'SDK utilizzata per risolvere l'anchor è 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 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