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

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

Pré-requisitos

Entenda os conceitos fundamentais de RA. e como configurar uma sessão do ARCore antes de continuar.

Se você não tem experiência com o Cloud Anchors, entenda como as anchors e Cloud Anchors funcionam.

Ativar a API ARCore

Antes de usar o Cloud Anchors no seu app, ative a API ARCore nele.

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

Depois de ativar os recursos do Cloud Anchors no seu app, ative os recursos do Cloud Anchors 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 posições de âncora para a API do ARCore. A API processa essas informações para criar um mapa de recursos 3D e, por fim, retorna ao dispositivo um ID exclusivo do Cloud Anchor para a âncora.

Você também pode estender o ciclo de vida de uma âncora hospedada usando a API ARCore Cloud Anchor Management.

Seu app deve 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. Verificar o estado do resultado para determinar se a operação foi bem-sucedida ou interpretar o código do erro em caso de falha.
4. Compartilhar o ID do Cloud Anchor resultante com outros clientes e usá-lo para resolver o Cloud Anchor com ArSession_resolveCloudAnchorAsync()

Verificar a qualidade do mapeamento de pontos de destaque

ArFeatureMapQuality indica a qualidade dos pontos de recursos vistos pelo ARCore nos segundos anteriores a partir de uma determinada pose da câmera. Âncoras do Cloud hospedadas usando recursos de maior qualidade costumam ser resolvidas com mais precisão. Use ArSession_estimateFeatureMapQualityForHosting() para ter uma estimativa da qualidade do mapa de recursos para uma determinada pose da câmera.

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 à âncora. Quando encontra uma correspondência, a API retorna a posição do Cloud Anchor hospedado.

É possível iniciar resoluções para vários Cloud Anchors em sequência. É possível ter 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.

Cotas de API para solicitações de host e resolução

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

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

Instrua os usuários a fazer o seguinte para garantir uma boa experiência do usuário no seu app:

• Aguarde alguns segundos após o início da sessão antes de tentar hospedar uma âncora (posicionando um objeto etc.). Isso dá ao acompanhamento algum tempo para se estabilizar.
• Ao selecionar um local para hospedar a âncora, tente encontrar uma área com elementos visuais que sejam facilmente distinguíveis 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 movimente o dispositivo o centro de interesse para mapear o ambiente de diferentes ângulos, mantendo aproximadamente a mesma distância física que você faz isso. Isso ajudará a capturar mais dados visuais e a tornar a resolução mais robusta.

• Confira se há iluminação suficiente no ambiente real enquanto hospeda e resolve âncoras do Cloud.

Política de descontinuação

• Os apps criados com o SDK do ARCore 1.12.0 ou mais recente 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 ou resolver âncoras do Cloud devido ao uso de uma API do ARCore mais antiga e descontinuada pelo SDK.

A seguir

• Consulte a documentação de referência do Android NDK para ver mais maneiras de usar o ARCore no seu app.