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:
// Create a new ARCore session.
ArSession* session = NULL;
CHECK(ArSession_create(env, context, &session) == AR_SUCCESS);
// Create a session config.
ArConfig* config = NULL;
ArConfig_create(session, &config);
ArSession_getConfig(session, config);
// Enable Cloud Anchor mode.
ArConfig_setCloudAnchorMode(session, config,
AR_CLOUD_ANCHOR_MODE_ENABLED);
// Configure the session.
ArSession_configure(session, config);
ArConfig_destroy(config);
Ospita un ancoraggio cloud
Hosting inizia con una chiamata a ArSession_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:
- Chiama il numero
ArSession_hostCloudAnchorAsync(). - Attendi che venga richiamato o controlla continuamente lo stato Futuro fino al termine dell'operazione.
- Controllare lo stato dei risultati per determinare se l'operazione è riuscita o interpretare il codice di errore se non è riuscita.
- Condividi il risultato dell'ID ancoraggio Cloud con altri client e utilizzalo per risolvere l'ancoraggio cloud con
ArSession_resolveCloudAnchorAsync()
Controllare la qualità della mappatura dei punti delle caratteristiche
ArFeatureMapQuality 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 ArSession_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 ArSession_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 ArFuture_cancel() per annullare un'operazione di Cloud Anchor in attesa.
Chiama ArAnchor_detach() per interrompere il monitoraggio ed eliminare un ancoraggio Cloud già risolto. I riferimenti all'ancoraggio devono essere rilasciati separatamente chiamando ArAnchor_release().
Verifica lo stato dei risultati di un'operazione Cloud Anchor
Utilizza ArCloudAnchorState per controllare lo stato dei risultati dell'operazione di hosting o di risoluzione, inclusi gli errori.
| Valore | Descrizione |
|---|---|
AR_CLOUD_ANCHOR_STATE_ERROR_CLOUD_ID_NOT_FOUND |
La risoluzione non è riuscita perché l'API ARCore non è riuscita a trovare l'ID ancoraggio Cloud fornito. |
AR_CLOUD_ANCHOR_STATE_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. |
AR_CLOUD_ANCHOR_STATE_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. |
AR_CLOUD_ANCHOR_STATE_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. |
AR_CLOUD_ANCHOR_STATE_ERROR_NOT_AUTHORIZED |
Consulta la sezione Risoluzione dei problemi con l'autorizzazione dell'API ARCore. |
AR_CLOUD_ANCHOR_STATE_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. |
AR_CLOUD_ANCHOR_STATE_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. |
AR_CLOUD_ANCHOR_STATE_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. |
AR_CLOUD_ANCHOR_STATE_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
- Consulta la documentazione di riferimento di Android NDK per scoprire altri modi per utilizzare ARCore nella tua app.