Guia do desenvolvedor do Cloud Anchors para Android NDK (C)

Aprenda a usar o Cloud Anchors nos seus próprios apps.

Pré-requisitos

Verifique se você entendeu os conceitos fundamentais de RA e como configurar uma sessão do ARCore antes de continuar.

Se você nunca usou o Cloud Anchors, saiba como funcionam as Âncoras e as Cloud Anchors.

Ativar a API ARCore

Antes de usar o Cloud Anchors no seu app, você precisa ativar a API ARCore no seu aplicativo.

Ativar os recursos do Cloud Anchor na configuração da sessão

Depois que a funcionalidade do Cloud Anchors for ativada no seu app, ative os recursos dele na configuração da sessão de RA do app para que ele possa se comunicar com a 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);

Hospedar um Cloud Anchor

O Hosting começa com uma chamada para ArSession_hostCloudAnchorAsync(). O ARCore fará o upload de dados visuais, poses do dispositivo e pose da âncora para a API ARCore. Em seguida, a API processa essas informações para criar um mapa de recursos 3D e, por fim, retorna um ID exclusivo do Cloud Anchor para a âncora no dispositivo.

Também é possível estender o ciclo de vida de uma âncora hospedada usando a API ARCore Cloud Anchor Management.

Seu app precisa seguir estas etapas para concluir a hospedagem de um Cloud Anchor:

  1. Chame ArSession_hostCloudAnchorAsync().
  2. Aguarde o callback ou verifique continuamente o estado Future até que ele seja concluído.
  3. Verifique o estado do resultado para determinar se a operação foi bem-sucedida ou interprete o código do erro se ela falhou.
  4. Compartilhe o ID do Cloud Anchor resultante com outros clientes e use-o para resolver o Cloud Anchor com ArSession_resolveCloudAnchorAsync().

Verificar a qualidade do mapeamento de pontos de recurso

ArFeatureMapQuality indica a qualidade dos pontos de recursos vistos pelo ARCore nos segundos anteriores de uma determinada pose da câmera. Os Cloud Anchors hospedados com recursos de alta qualidade geralmente são resolvidos com mais precisão. Use ArSession_estimateFeatureMapQualityForHosting() para ter uma estimativa de qualidade do mapa de elementos para uma determinada posição da câmera.

Valor Descrição
INSUFFICIENT A qualidade dos pontos de destaque identificados pela pose nos segundos anteriores é baixa. Esse estado indica que o ARCore provavelmente terá mais dificuldade para resolver o Cloud Anchor. Incentive o usuário a mover o dispositivo para que a posição desejada do Cloud Anchor que ele quer hospedar possa ser vista de diferentes ângulos.
SUFFICIENT A qualidade dos pontos de recurso identificados na pose nos segundos anteriores é provavelmente suficiente para que o ARCore resolva com sucesso um Cloud Anchor, embora a precisão da pose resolvida provavelmente vai ser reduzida. Incentive o usuário a mover o dispositivo para que a posição desejada do Cloud Anchor que ele quer hospedar possa ser vista de diferentes ângulos.
GOOD A qualidade dos pontos de recurso identificados na pose nos segundos anteriores é provavelmente suficiente para que o ARCore resolva com sucesso um Cloud Anchor com um alto grau de precisão.

Resolver uma âncora hospedada anteriormente

Chame ArSession_resolveCloudAnchorAsync() para resolver um Cloud Anchor hospedado. A API ARCore compara periodicamente os recursos visuais da cena com o mapa de recursos 3D da âncora para identificar a posição e a orientação do usuário em relação a ela. Quando encontra uma correspondência, a API retorna a pose do Cloud Anchor hospedado.

É possível iniciar soluções para vários Cloud Anchors em sequência. Podem existir até 40 operações simultâneas do Cloud Anchor por vez.

Cancelar uma operação ou remover um Cloud Anchor

Chame ArFuture_cancel() para cancelar uma operação pendente do Cloud Anchor. Chame ArAnchor_detach() para interromper o rastreamento e esquecer um Cloud Anchor já resolvido. As referências à âncora precisam ser liberadas separadamente chamando ArAnchor_release().

Verificar o estado do resultado de uma operação do Cloud Anchor

Use ArCloudAnchorState para verificar o status do resultado da operação de hospedagem ou resolução, incluindo erros.

Valor Descrição
AR_CLOUD_ANCHOR_STATE_ERROR_CLOUD_ID_NOT_FOUND A resolução falhou porque a API ARCore não conseguiu encontrar o ID do Cloud Anchor fornecido.
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_DATASET_PROCESSING_FAILED A hospedagem falhou porque o servidor não conseguiu processar o conjunto de dados da âncora especificada. Tente de novo depois que o dispositivo coletar mais dados do ambiente.
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_SERVICE_UNAVAILABLE Não foi possível acessar a API ARCore. Isso pode acontecer por uma série de motivos. O dispositivo pode estar no modo avião ou não ter uma conexão de Internet. A solicitação enviada ao servidor pode ter expirado sem resposta. Pode haver uma conexão de rede ruim, indisponibilidade de DNS, problemas com o firewall ou qualquer outra coisa que possa afetar a capacidade do dispositivo de se conectar à API ARCore.
AR_CLOUD_ANCHOR_STATE_ERROR_INTERNAL Uma tarefa de hospedagem ou resolução para essa âncora foi concluída com um erro interno. O app não deve tentar se recuperar desse erro.
AR_CLOUD_ANCHOR_STATE_ERROR_NOT_AUTHORIZED Consulte Solução de problemas com a autorização da API ARCore.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_NEW Não foi possível resolver o Cloud Anchor porque a versão do SDK usada para resolver a âncora é mais recente e incompatível com a versão usada para hospedá-lo.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_OLD Não foi possível resolver o Cloud Anchor porque a versão do SDK usada para resolver a âncora é mais antiga e é incompatível com a versão usada para hospedá-lo.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOURCE_EXHAUSTED O aplicativo esgotou a cota de solicitações alocada ao projeto do Google Cloud especificado. Solicite uma cota adicional para a API ARCore para seu projeto no Google Developers Console.
AR_CLOUD_ANCHOR_STATE_SUCCESS Uma tarefa de hospedagem ou resolução para essa âncora foi concluída.

Cotas de API para hospedar e resolver solicitações

A API ARCore tem as seguintes cotas para largura de banda de solicitação:

Tipo da cota Máxima Duração Válido para
Número de âncoras unlimited N/A projeto
Solicitações de host âncora 30 minuto Endereço IP e projeto
Solicitações resolve de âncora 300 minuto Endereço IP e projeto

Práticas recomendadas para uma boa experiência do usuário

Oriente os usuários a fazer o seguinte para garantir uma boa experiência no app:

  • Aguarde alguns segundos após o início da sessão antes de tentar hospedar uma âncora (colocando um objeto etc.). Isso dá algum tempo para que o rastreamento se estabilize.
  • Ao selecionar um local para hospedar a âncora, tente encontrar uma área com elementos visuais que possam ser facilmente diferenciados uns dos outros. Para melhores resultados, evite superfícies reflexivas ou que não tenham recursos visuais, como paredes brancas.

  • Mantenha a câmera treinada no centro de interesse e mova o dispositivo pelo centro de interesse para mapear o ambiente de diferentes ângulos, mantendo aproximadamente a mesma distância física. Isso ajudará a capturar mais dados visuais e a tornar a resolução mais robusta.

  • Verifique se há iluminação suficiente no ambiente real ao hospedar e resolver âncoras do Cloud.

Política de descontinuação

  • Os apps criados com o SDK do ARCore 1.12.0 ou versões mais recentes são cobertos pela política de descontinuação da API Cloud Anchor.
  • Os apps criados com o SDK 1.11.0 ou anterior do ARCore não podem hospedar nem resolver os Cloud Anchors devido ao uso de uma API ARCore mais antiga e descontinuada.

A seguir