Scopri come utilizzare gli ancoraggi Cloud nelle tue app.
Prerequisiti
Assicurati di aver compreso i concetti fondamentali di AR e di configurare una sessione ARCore prima di procedere.
Se non hai mai utilizzato gli ancoraggi Cloud, assicurati di capire 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.
Attiva le funzionalità di Cloud Anchor nella configurazione della sessione
Una volta abilitata la funzionalità Cloud Anchors nell'app, attivala 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 cloud anchor
Hosting inizia con una chiamata al numero ArSession_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 costruire una mappa delle funzionalità 3D, restituendo infine un ID Cloud Anchor univoco per l'ancoraggio al dispositivo.
Puoi anche estendere la durata di un anchor ospitato utilizzando l'API ARCore Cloud Anchor Management.
Per completare l'hosting di un ancoraggio Cloud, la tua app deve seguire questi passaggi:
- Chiama il numero
ArSession_hostCloudAnchorAsync(). - Attendi il callback o controlla continuamente lo stato Futuro fino al termine dell'operazione.
- Controlla lo stato del risultato per determinare se l'operazione è riuscita o interpreta il codice di errore in caso di errore.
- Condividi l'ID Cloud Anchor risultato con altri client e utilizzalo per risolvere l'ancoraggio Cloud con
ArSession_resolveCloudAnchorAsync().
Controlla la qualità della mappatura dei punti caratteristica
ArFeatureMapQuality indica la qualità dei punti di funzionalità rilevati da ARCore nei secondi precedenti da una determinata posizione della fotocamera. Gli ancoraggi Cloud ospitati utilizzando funzionalità di qualità superiore vengono generalmente risolti con maggiore precisione. Utilizza ArSession_estimateFeatureMapQualityForHosting() per ottenere una stima della qualità della mappa delle caratteristiche per una determinata posizione della fotocamera.
| Valore | Descrizione |
|---|---|
INSUFFICIENT |
La qualità dei feature point identificati nella posa negli ultimi secondi è bassa. Questo stato indica che ARCore avrà probabilmente maggiori difficoltà a risolvere l'ancoraggio Cloud. Incoraggiare l'utente a spostare il dispositivo in modo che la posizione desiderata dell'ancoraggio cloud che vuole ospitare possa essere vista da diverse angolazioni. |
SUFFICIENT |
La qualità dei punti di caratteristica identificati dalla posa nei secondi precedenti è probabilmente sufficiente per consentire ad ARCore di risolvere correttamente un Cloud Anchor, anche se probabilmente la precisione della posa risolta sarà ridotta. Incoraggiare l'utente a spostare il dispositivo in modo che la posizione desiderata dell'ancoraggio cloud che vuole ospitare possa essere vista da diverse angolazioni. |
GOOD |
La qualità dei feature point identificati dalla posa nei pochi secondi precedenti è probabilmente sufficiente per consentire ad ARCore di risolvere correttamente un Cloud Anchor con un elevato grado di precisione. |
Risolvere un ancoraggio precedentemente ospitato
Chiama ArSession_resolveCloudAnchorAsync() per risolvere un Cloud Anchor ospitato. L'API ARCore confronta periodicamente le funzionalità visive della scena con la mappa delle funzionalità 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'ancoraggio Cloud ospitato.
Puoi avviare le risoluzioni per più Cloud anchor in sequenza. Possono esistere fino a 40 operazioni simultanee di Cloud Anchor alla volta.
Annulla un'operazione o rimuovi un Cloud Anchor
Chiama ArFuture_cancel() per annullare un'operazione Cloud Anchor in attesa.
Chiama ArAnchor_detach() per interrompere il monitoraggio ed eliminare un Cloud Anchor già risolto. I riferimenti all'ancoraggio devono essere rilasciati separatamente chiamando ArAnchor_release().
Controllo dello stato del risultato di un'operazione Cloud Anchor
Utilizza ArCloudAnchorState per controllare lo stato del risultato dell'operazione di hosting o di risoluzione, inclusi gli errori.
| Valore | Descrizione |
|---|---|
AR_CLOUD_ANCHOR_STATE_ERROR_CLOUD_ID_NOT_FOUND |
Risoluzione non riuscita perché l'API ARCore non è riuscita a trovare l'ID Cloud Anchor fornito. |
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_DATASET_PROCESSING_FAILED |
Hosting non riuscito perché il server non è riuscito a elaborare il set di dati per l'ancoraggio specificato. Riprova dopo che il dispositivo ha raccolto altri dati dall'ambiente. |
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_SERVICE_UNAVAILABLE |
L'API ARCore non era raggiungibile. Questa condizione può verificarsi per diversi motivi. Il dispositivo potrebbe essere in modalità aereo o potrebbe non avere una connessione a Internet funzionante. La richiesta inviata al server potrebbe essere scaduta senza risposta. Potrebbe essersi verificata una connessione di rete lenta, una mancata disponibilità del DNS, problemi di firewall o qualsiasi altra cosa che possa influire sulla capacità del dispositivo di connettersi all'API ARCore. |
AR_CLOUD_ANCHOR_STATE_ERROR_INTERNAL |
Un'attività di hosting o risoluzione per questo anchor è stata completata con un errore interno. L'app non deve tentare di recuperare da questo errore. |
AR_CLOUD_ANCHOR_STATE_ERROR_NOT_AUTHORIZED |
Vedi Risolvere i problemi relativi all'autorizzazione dell'API ARCore. |
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_NEW |
Impossibile risolvere l'ancoraggio Cloud perché la versione dell'SDK utilizzata per risolvere l'ancoraggio è più recente e incompatibile con la versione utilizzata per l'hosting. |
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_OLD |
Impossibile risolvere l'ancoraggio Cloud perché la versione dell'SDK utilizzata per risolvere l'ancoraggio è precedente e incompatibile con la versione utilizzata per l'hosting. |
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 anchor è stata completata correttamente. |
Quote API per le 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/A | progetto |
| Richieste di ancoraggio host | 30 | minuto | Indirizzo IP e progetto |
| Richieste di ancoraggio resolve | 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'inizio 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'una dall'altra. Per risultati ottimali, evita superfici riflettenti o prive di caratteristiche visive, come pareti bianche e vuote.
Mantieni la fotocamera addestrata al centro di interesse e sposta il dispositivo al centro dell'interesse per mappare l'ambiente da diverse angolazioni, mantenendo all'incirca la stessa distanza fisica. In questo modo, sarà più facile acquisire più dati visivi e rendere la risoluzione più affidabile.
Assicurati che ci sia illuminazione sufficiente nell'ambiente reale durante l'hosting e la risoluzione degli ancoraggi Cloud.
Norme sul ritiro
- Le app create con ARCore SDK 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 precedente e deprecata.
Passaggi successivi
- Consulta la documentazione di riferimento di NDK per Android per scoprire altri modi per utilizzare ARCore nella tua app.