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 conoscere i concetti fondamentali dell'AR e come configurare una sessione ARCore.

Se non hai mai utilizzato Cloud Anchors:

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

Abilita 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)

Ospitare un Cloud Anchor

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 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 Cloud Anchor, la tua app deve seguire questi passaggi:

  1. Chiama il numero hostCloudAnchorAsync().
  2. Attendi il callback o controlla continuamente lo stato Futuro fino al termine dell'operazione.
  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 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. In genere, gli ancoraggi cloud ospitati utilizzando funzionalità di qualità superiore vengono risolti con maggiore precisione. 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 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'anchor cloud che vuole ospitare possa essere visualizzata da diverse angolazioni.
GOOD La qualità dei punti di riferimento identificati dalla posa nei pochi secondi precedenti è probabilmente sufficiente per consentire ad ARCore di risolvere correttamente un ancoraggio cloud con un elevato grado di precisione.

Risolvere un'ancora ospitata in precedenza

Chiama resolveCloudAnchorAsync() per risolvere un ancoraggio Cloud 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 la risoluzione di più Cloud Anchor in sequenza. Possono esistere fino a 40 operazioni Cloud Anchor in contemporanea.

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 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.
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 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.
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 dall'applicazione 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'ancora cloud perché la versione dell'SDK utilizzata per risolverlo è 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 ancore 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 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 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