Ativar a API Geospatial no app Android NDK (C)

Configure as configurações do app para que ele possa usar a API Geospatial.

Pré-requisitos

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

Se você quiser executar um app de exemplo que demonstre a funcionalidade descrita aqui, consulte o Guia de início rápido da API Geospatial do ARCore para Android para Java. O app de exemplo no guia de início rápido é escrito em Java. Os exemplos de código neste documento são para a mesma funcionalidade escrita em C.

Consulte a Introdução à API Geospatial para mais informações.

Se você é iniciante no desenvolvimento com o ARCore, consulte Primeiros passos para informações sobre requisitos de software e hardware, pré-requisitos e outras informações específicas das plataformas que você está usando.

Verifique se o ambiente de desenvolvimento atende aos requisitos do SDK do ARCore, conforme descrito no Guia de início rápido para Java.

Ativar a API ARCore

Antes de usar o sistema de posicionamento visual (VPS) no seu app, é necessário ativar a API ARCore em um projeto novo ou existente do Google Cloud. Esse serviço é responsável por hospedar, armazenar e resolver âncoras geoespaciais.

A autorização sem chave é a preferida, mas a autorização com chave de API também é aceita.

Adicionar as bibliotecas necessárias ao app

Depois de autorizar o app a chamar a API ARCore, adicione bibliotecas para ativar os recursos geoespaciais no app.

No arquivo build.gradle do app, configure o Google Play Services para incluir a biblioteca de localização do Play Services.

dependencies {
  // Apps must declare play-services-location version >= 16.
  // In the following line, substitute `16 (or later)` with the latest version.
  implementation 'com.google.android.gms:play-services-location:16 (or later)'
}

Ativar recursos geoespaciais na configuração da sessão

Antes de criar a sessão, mude o GeospatialMode na configuração da sessão para ENABLED:

// Create a session config.
ArConfig* ar_config = NULL;
ArConfig_create(ar_session, &ar_config);

// Enable the Geospatial API.
ArConfig_setGeospatialMode(ar_session, ar_config, AR_GEOSPATIAL_MODE_ENABLED);
CHECK(ArSession_configure(ar_session, ar_config) == AR_SUCCESS);

// Release config resources.
ArConfig_destroy(ar_config);

Enquanto o modo geoespacial estiver definido como ENABLED, o aplicativo poderá receber informações geográficas do sistema de posicionamento visual (VPS).

Pedir ao usuário para permitir o uso de dados do dispositivo

Os apps que usam a API Geoespacial do ARCore precisam apresentar ao usuário uma solicitação para confirmar e permitir o uso de dados do dispositivo. Consulte Requisitos de privacidade do usuário para mais informações.

Verificar a compatibilidade do dispositivo

Nem todos os dispositivos compatíveis com o ARCore também são compatíveis com a API Geospatial, conforme descrito no Programa de treinamento para Java.

Para verificar a compatibilidade do dispositivo do usuário, chame ArSession_isGeospatialModeSupported(). Se isso retornar falso, não tente configurar a sessão (abaixo), porque isso fará com que o ArStatus informe um AR_ERROR_UNSUPPORTED_CONFIGURATION.

Pedir permissões de localização ao usuário no momento da execução

O app precisa solicitar permissões de localização no momento da execução.

Para usar a API Geospatial do ARCore, seu app precisa registrar as seguintes permissões extras:

  • ACCESS_FINE_LOCATION para determinar com precisão a localização do usuário.

  • ACCESS_COARSE_LOCATION para determinar o local do usuário de maneira imprecisa e obedecer aos requisitos de privacidade do usuário. No entanto, a API Geospatial não pode ser configurada para funcionar com a localização aproximada, e as solicitações de API vão falhar quando o usuário tiver definido essa permissão. Veja mais informações a seguir.

  • ACCESS_INTERNET para entrar em contato com o serviço da API ARCore Geospatial.

<manifest ... >
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  <uses-permission android:name="android.permission.INTERNET" />
</manifest>

Em dispositivos com o Android versão 12 ou mais recente, os usuários podem solicitar que o app tenha acesso apenas a informações de localização aproximada. Para atender a essa solicitação, o app precisa ter a permissão ACCESS_COARSE_LOCATION configurada, junto com ACCESS_FINE_LOCATION, conforme mostrado acima. É necessário configurar as duas permissões de localização.

No entanto, quando os usuários especificam a localização aproximada, isso impede que a API Geospatial obtenha a localização precisa necessária. O serviço geoespacial não vai permitir a configuração se o app fornecer apenas a localização aproximada. O app não pode usar a API Geospatial com localização aproximada.

Verificar a disponibilidade geoespacial no local atual do dispositivo

Como a API Geospatial usa uma combinação de VPS e GPS para determinar uma pose geoespacial, ela pode ser usada desde que o dispositivo consiga determinar a própria localização. Em áreas com baixa precisão de GPS, como espaços internos e ambientes urbanos densos, a API vai depender da cobertura do VPS para gerar poses de alta precisão. Em condições típicas, o VPS pode fornecer uma precisão posicional de aproximadamente 5 metros e uma precisão rotacional de 5 graus. Use ArSession_checkVpsAvailabilityAsync() para determinar se um determinado local tem cobertura de VPS.

A API Geospatial também pode ser usada em áreas sem cobertura de VPS. Em ambientes externos com poucas ou nenhuma obstrução acima, o GPS pode ser suficiente para gerar uma pose com alta precisão.

A seguir