앱에서 Geospatial API 설정

적용 가능한 XR 기기

이 가이드는 이러한 유형의 XR 기기를 위한 환경을 빌드하는 데 도움이 됩니다.

XR 기기 유형 알아보기 →

XR 기기 유형 알아보기 →

앱에서 Geospatial API를 사용하려면 Google Cloud에서 ARCore API에 액세스하도록 앱을 설정해야 합니다. 이 API에는 Google 스트리트 뷰의 데이터를 사용하여 정확한 위치를 제공하는 시각적 위치 지정 서비스가 포함되어 있습니다.

이 가이드는 API에 액세스하기 위해 올바른 API 및 승인 메서드를 사용 설정한 Google Cloud 프로젝트를 설정하는 데 도움이 됩니다.

Google Cloud 프로젝트 설정 또는 기존 프로젝트 사용

기존 Google Cloud 프로젝트가 있으면 선택합니다.

프로젝트 선택기로 이동

기존 프로젝트가 없으면 프로젝트를 만듭니다.

새 프로젝트 만들기

ARCore API 사용 설정

ARCore API를 사용하려면 프로젝트에서 사용 설정해야 합니다.

ARCore API 사용 설정

Google Cloud 승인 설정

Android 애플리케이션은 권장되는 방법인 키 없는 승인 (OAuth 2.0)과 API 키 승인이라는 두 가지 승인 방법을 사용하여 ARCore API와 통신할 수 있습니다.

• 키 없는 승인은 애플리케이션의 패키지 이름과 서명 키의 디지털 지문을 조합하여 애플리케이션을 승인합니다.

• API 키는 Google Cloud 프로젝트를 식별하는 문자열입니다. API 키는 일반적으로 클라이언트가 액세스할 수 있으므로 안전하지 않은 것으로 간주됩니다. ARCore API와 통신하려면 키 없는 승인을 사용하는 것이 좋습니다.

<meta-data
  android:name="com.google.android.ar.API_KEY"
  android:value="API_KEY"/>

필수 권한 요청

Jetpack XR을 사용하여 ARCore에서 Geospatial API를 사용하려면 앱에서 다음 런타임 권한을 요청해야 합니다.

• ACCESS_FINE_LOCATION: 사용자의 정확한 위치를 확인하는 데 필요합니다.

휴대기기에서 Geospatial API를 사용하려면 다음 권한도 필요합니다.

• android.permission.CAMERA: 기기의 카메라에 액세스하는 데 필요합니다.
• android.permission.INTERNET: Google Cloud 서비스와 통신하는 데 필요합니다.

세션 액세스하기

앱에서 만들어야 하는 Jetpack XR 런타임 Session을 통해 Geospatial 정보에 액세스합니다.

세션 구성

Geospatial API는 XR 세션에서 기본적으로 사용 설정되지 않습니다. 앱은 Session에서 GeospatialMode를 구성하여 명시적으로 사용 설정해야 합니다. 사용 가능한 모드는 다음과 같습니다.

• GeospatialMode.SPATIAL: Geospatial API가 사용 설정됩니다. Geospatial API는 VPS (Visual Positioning System), 위성 위치 확인 시스템 (GPS) 데이터, 기기의 움직임 감지 센서를 사용하여 기기의 지리 공간적 포즈를 결정합니다. 이 모드는 지능형 글라스 기기에서 사용할 수 없습니다.
• GeospatialMode.INERTIAL: Geospatial API가 저전력 모드로 사용 설정됩니다. Geospatial API는 GPS와 기기의 움직임 감지 센서만 사용하여 기기의 지리 공간적 포즈를 결정합니다. 이 모드는 지능형 글라스 기기에서만 사용할 수 있습니다.
• GeospatialMode.DISABLED: Geospatial API가 사용 중지됩니다. 다른 모드에서 이 모드로 전환하면 Geospatial API가 획득한 모든 리소스를 해제하고 추적을 중지합니다.

일부 기기는 일부 Geospatial 모드를 지원하지 않습니다. 자세한 내용은 GeospatialMode를 참고하세요. XrDevice.isGeospatialSupported를 사용하여 지정된 GeospatialMode가 지원되는지 확인합니다.

다음 코드 샘플은 Session.configure를 사용하여 GeospatialMode를 설정하는 방법을 보여줍니다.

// Define the configuration object to enable Geospatial features.
val newConfig = Config.Builder(session.config)
    .setGeospatial(GeospatialMode.SPATIAL)
    .build()
// Apply the configuration to the session.
try {
    when (val configResult = session.configure(newConfig)) {
        is SessionConfigureSuccess -> {
            // The session is now configured to use the Geospatial API.
        }

        else -> {
            // Handle other configuration errors (e.g., missing library dependencies).
        }
    }
} catch (e: UnsupportedOperationException) {
    // Handle configuration failure if the mode is not supported.
}
Setup.kt

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

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

Geospatial 객체 사용

세션이 구성되면 Geospatial.getInstance를 사용하여 Geospatial 객체를 가져옵니다. 상태가 GeospatialTrackingState.RUNNING인 경우에만 Geospatial 객체를 사용합니다.

다음 코드 샘플은 Geospatial.state를 사용하여 Geospatial 상태를 모니터링하는 방법을 보여줍니다.

val geospatial = remember { Geospatial.getInstance(session) }
val geospatialState by geospatial.state.collectAsStateWithLifecycle()
if (geospatialState.geospatialTrackingState == Geospatial.GeospatialTrackingState.RUNNING) {
    // Queries to the Geospatial API are only valid when the state is RUNNING.
}
Setup.kt

val geospatial = Geospatial.getInstance(session)
lifecycleScope.launch {
    geospatial.state.collect { geospatialState ->
        if (geospatialState == Geospatial.GeospatialTrackingState.RUNNING) {
            // Queries to the Geospatial API are only valid when the state is RUNNING.
        }
    }
}
Setup.kt

정확도 값 이해하기

Geospatial API가 사용 설정되어 있는 동안에는 가로, 세로, 방향 정확도라는 세 가지 정확도 값을 제공합니다. 이러한 정확도 값은 시간이 지남에 따라 업데이트되며 더 많은 데이터가 획득되면 더 정확해질 수 있습니다. 값이 클수록 정확도가 낮으며 68% 신뢰도 수준의 반경으로 정의됩니다. 즉, 실제 값이 추정 값의 지정된 반경 내에 있을 확률은 68% 입니다.

현재 정확도 값을 가져오려면 Geospatial.State.horizontalAccuracy, verticalAccuracy, orientationYawAccuracy를 사용합니다.

앱이 제대로 작동하려면 특정 수준의 정밀도가 필요할 수 있습니다. 예를 들어 앱은 가상 콘텐츠를 렌더링하기 전에 수평 정확도가 5미터 미만이 될 때까지 기다릴 수 있습니다. 더 높은 정확도의 데이터를 얻을 가능성을 높이려면 앱에서 사용자에게 주변을 둘러보도록 안내해야 합니다. 가급적이면 Google 스트리트 뷰에 표시되는 시각적 세부정보가 많은 건물이나 기타 지형지물을 보도록 안내하는 것이 좋습니다. Geospatial.checkVpsAvailability를 사용하여 지정된 위치에서 VPS를 사용할 수 있는지 확인합니다.

다음 단계

앱에서 Geospatial API가 올바르게 설정되면 앱은 다음을 실행할 수 있습니다.

• 기기 로컬 포즈와 지리 공간 포즈 간 변환
• 지리 공간 포즈에서 콘텐츠 렌더링