Android NDK 앱에 Geospatial API 사용 설정 (C)

Geospatial API를 사용할 수 있도록 앱 설정을 구성합니다.

기본 요건

계속하기 전에 기본 AR 개념과 ARCore 세션을 구성하는 방법을 이해해야 합니다.

여기에 설명된 기능을 보여주는 샘플 앱을 실행하려면 Java용 Android용 ARCore Geospatial 빠른 시작을 참고하세요. 빠른 시작의 샘플 앱은 Java로 작성되어 있습니다. 이 문서의 코드 샘플은 C로 작성된 동일한 기능을 위한 것입니다.

Geospatial API에 관한 자세한 내용은 Geospatial API 소개를 참고하세요.

ARCore를 사용한 개발이 처음이라면 시작하기에서 소프트웨어 및 하드웨어 요구사항, 기본 요건, 사용 중인 플랫폼과 관련된 기타 정보에 관해 알아보세요.

개발 환경이 Java용 빠른 시작에 설명된 대로 ARCore SDK 요구사항을 충족하는지 확인합니다.

ARCore API 사용 설정

앱에서 VPS (Visual Positioning System)를 사용하려면 먼저 새 Google Cloud 프로젝트 또는 기존 Google Cloud 프로젝트에서 ARCore API를 사용 설정해야 합니다. 이 서비스는 지리적 앵커를 호스팅, 저장, 확인합니다.

키 없는 승인이 권장되지만 API 키 승인도 지원됩니다.

앱에 필요한 라이브러리 추가

앱이 ARCore API를 호출하도록 승인한 후에는 앱에서 지리정보 기능을 사용 설정할 라이브러리를 추가해야 합니다.

앱의 build.gradle 파일에서 Play 서비스 위치 라이브러리를 포함하도록 Google Play 서비스를 설정합니다.

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)'
}

세션 구성에서 Geospatial 기능 사용 설정

세션을 만들기 전에 세션 구성에서 GeospatialMode를 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);

Geospatial 모드가 ENABLED로 설정된 동안 애플리케이션은 VPS (Visual Positioning System)에서 지리 정보를 가져올 수 있습니다.

사용자에게 기기 데이터 사용을 허용하라는 메시지 표시

ARCore Geospatial API를 사용하는 앱은 사용자에게 기기의 데이터 사용을 확인하고 허용하라는 메시지를 표시해야 합니다. 자세한 내용은 사용자 개인 정보 보호 요구사항을 참고하세요.

기기 호환성 확인

Java용 빠른 시작에 설명된 대로 ARCore를 지원하는 모든 기기가 Geospatial API를 지원하는 것은 아닙니다.

사용자 기기의 호환성을 확인하려면 ArSession_isGeospatialModeSupported()를 호출합니다. false가 반환되면 아래와 같이 세션을 구성하려고 하면 ArStatus에서 AR_ERROR_UNSUPPORTED_CONFIGURATION를 보고하므로 시도하지 마세요.

런타임 시 사용자에게 위치 정보 액세스 권한 요청

앱은 런타임에 위치 정보 액세스 권한을 요청해야 합니다.

ARCore Geospatial API를 사용하려면 앱에서 다음과 같은 추가 권한을 등록해야 합니다.

  • ACCESS_FINE_LOCATION를 사용하여 사용자의 위치를 정확하게 확인합니다.

  • ACCESS_COARSE_LOCATION: 사용자의 위치를 정확하게 파악하지 못하고 사용자 개인 정보 보호 요구사항을 준수하기 위해 그러나 대략적인 위치로 작동하도록 Geospatial API를 구성할 수는 없으며 사용자가 이 권한을 설정하면 API 요청이 실패합니다. 자세한 정보는 아래를 참고하세요.

  • ACCESS_INTERNET를 사용하여 ARCore Geospatial API 서비스에 문의합니다.

<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>

Android 버전 12 이상을 실행하는 기기에서는 앱이 대략적인 위치 정보에만 액세스하도록 사용자가 요청할 수 있습니다. 이 요청을 수용하려면 앱에 위에 표시된 대로 ACCESS_FINE_LOCATION와 함께 ACCESS_COARSE_LOCATION 권한이 구성되어 있어야 합니다. 두 위치 권한을 모두 구성해야 합니다.

그러나 사용자가 대략적인 위치를 지정하면 Geospatial API에서 필요한 정확한 위치를 가져올 수 없습니다. 앱에서 대략적인 위치만 제공하는 경우 Geospatial 서비스는 구성할 수 없습니다. 앱에서 대략적인 위치로 Geospatial API를 사용할 수 없습니다.

기기의 현재 위치에서 Geospatial 사용 가능 여부 확인

Geospatial API는 VPS와 GPS를 조합하여 Geospatial 포즈를 결정하므로 기기가 위치를 파악할 수 있는 한 API를 사용할 수 있습니다. 실내 공간 및 인구 밀집 도시 환경과 같이 GPS 정확도가 낮은 지역에서는 API가 VPS 노출 영역을 사용하여 고정밀도 포즈를 생성합니다. 일반적인 조건에서 VPS는 약 5미터의 위치 정확도와 5도 이하의 회전 정확도를 제공할 수 있습니다. ArSession_checkVpsAvailabilityAsync()를 사용하여 지정된 위치에 VPS 적용 범위가 있는지 확인합니다.

Geospatial API는 VPS 적용 범위가 없는 지역에서도 사용할 수 있습니다. 상단에 장애물이 거의 없거나 없는 야외 환경에서는 GPS만으로도 높은 정확도로 포즈를 생성할 수 있습니다.

다음 단계