앱에 3D 지도 추가

플랫폼 선택: Android iOS JavaScript

뉴욕시를 보여주는 3D 지도

이 페이지에서는 Android용 지도 3D SDK를 사용하여 Android 앱에 기본 3D 지도를 추가하는 방법을 보여주는 예를 안내합니다. 이 페이지의 안내는 설정 페이지의 단계를 이미 완료했으며 다음이 있다고 가정합니다.

  • Android용 지도 3D SDK가 사용 설정된 Google Cloud 프로젝트
  • Android용 지도 3D SDK와 함께 사용하도록 구성된 API 키
  • Android용 지도 3D SDK와 함께 사용하도록 설정된 Android 스튜디오 프로젝트

이러한 기본 요건에 대한 자세한 내용은 설정을 참고하세요.

1부: Map3DView 구성요소를 추가하도록 레이아웃 파일 (activity_main.xml) 업데이트

Map3DView 구성요소는 앱 내에서 3D 지도를 렌더링하는 뷰입니다. 다음 단계에서는 구성요소를 추가하고 카메라 위치 및 관련 속성을 비롯한 지도의 초기 상태를 구성합니다.

  1. 기본 활동의 레이아웃 파일을 엽니다. 일반적으로 app/src/main/res/layout/activity_main.xml에 있습니다.

  2. 루트 ConstraintLayout (또는 루트 레이아웃 요소)에서 map3d XML 네임스페이스를 추가합니다.

    xmlns:map3d="http://schemas.android.com/apk/res-auto"

  3. 'Hello World!'를 표시하는 기본 <TextView>를 삭제합니다.

  4. 레이아웃에 Map3DView 구성요소를 추가합니다. 카메라 위치 및 기타 속성을 맞춤설정할 수 있습니다.

    <?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:app="http://schemas.android.com/apk/res-auto"
  xmlns:map3d="http://schemas.android.com/apk/res-auto" xmlns:tools="http://schemas.android.com/tools"
  android:id="@+id/main"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  tools:context=".MainActivity">

  <com.google.android.gms.maps3d.Map3DView
    android:id="@+id/map3dView"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    map3d:mode="hybrid"
    map3d:centerLat="38.544012"
    map3d:mode="hybrid"
    map3d:centerLng="-107.670428"
    map3d:centerAlt="2427.6"
    map3d:heading="310"
    map3d:tilt="63"
    map3d:range="8266"
    map3d:roll="0"
    map3d:minAltitude="0"
    map3d:maxAltitude="1000000"
    map3d:minHeading="0"
    map3d:maxHeading="360"
    map3d:minTilt="0"
    map3d:maxTilt="90"
    app:layout_constraintBottom_toBottomOf="parent"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintTop_toTopOf="parent" />
</androidx.constraintlayout.widget.ConstraintLayout>

2부: MainActivity.kt 업데이트

다음 단계에서는 1부에서 activity_main.xml 파일에 추가된 Map3DView 구성요소를 초기화하고 구성요소 수명 주기 이벤트를 관리합니다.

Android용 지도 3D SDK는 한 번에 하나의 활성 Map3DView 인스턴스만 지원합니다. 동시에 여러 Map3DView 인스턴스를 표시하는 것은 지원되지 않으며(예: 동일한 레이아웃 또는 서로 다른 표시되는 활동 또는 프래그먼트) 보조 뷰의 검은 화면과 같은 렌더링 문제가 발생할 수 있습니다.

또한 모든 Map3DView는 동일한 지도 상태(예: 카메라 위치, 추가된 마커, 다각형 등)를 공유하고 반영하며, 수동으로 삭제하지 않는 한 하나의 Map3DView가 삭제 (onDestroy 사용)되고 다른 Map3DView가 생성되더라도 유지됩니다. 예를 들어 Map3DView1에 마커를 추가한 후 삭제하고 Map3DView2를 만들면 동일한 마커가 Map3DView2에 계속 표시됩니다.

개발자 책임:

  • 한 번에 하나의 뷰: 언제든지 뷰 계층 구조의 활성 부분에 하나의 Map3DView만 있는지 확인합니다.
  • 수동 정리: 한 Map3DView (예: Map3DView1)에서 다른 Map3DView2 (예: Map3DView2)로 전환할 때는 이전 인스턴스(Map3DView1)에서 onDestroy()를 호출해야 합니다. 기본 지도 상태가 공유되므로 Map3DView2가 새 상태 또는 특정 상태로 시작되도록 하려면 Map3DView1에서 설정한 상태를 수동으로 삭제해야 합니다. 여기에는 OnMap3DViewReadyCallback에서 가져온 GoogleMap3D 객체를 사용하여 마커, 오버레이 등을 삭제하고 카메라 위치를 재설정하는 작업이 포함됩니다.

  1. MainActivity.kt 파일을 엽니다. 일반적으로 app/src/main/java/com/example/yourpackagename/MainActivity.kt에 있습니다.

  2. Android용 지도 3D SDK에 필요한 가져오기를 추가합니다.

    import android.util.Log
import com.google.android.gms.maps3d.GoogleMap3D
import com.google.android.gms.maps3d.Map3DView
import com.google.android.gms.maps3d.OnMap3DViewReadyCallback

  3. MainActivity 클래스를 수정하여 OnMap3DViewReadyCallback을 구현합니다.

    class MainActivity : AppCompatActivity(), OnMap3DViewReadyCallback {

  4. Map3DView 및 GoogleMap3D의 변수를 선언합니다.

    private lateinit var map3DView: Map3DView
private var googleMap3D: GoogleMap3D? = null

  5. onCreate 메서드에서 setContentView(...) 및 ViewCompat.setOnApplyWindowInsetsListener 블록 후에 map3DView를 초기화하고 onCreate 수명 주기 메서드를 호출하고 지도를 비동기식으로 요청합니다.

    override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    enableEdgeToEdge()
    setContentView(R.layout.activity_main)
    ViewCompat.setOnApplyWindowInsetsListener(findViewById(R.id.main)) { v, insets ->
        val systemBars = insets.getInsets(WindowInsetsCompat.Type.systemBars())
        v.setPadding(systemBars.left, systemBars.top, systemBars.right, systemBars.bottom)
        insets
    }

    map3DView = findViewById(R.id.map3dView)
    map3DView.onCreate(savedInstanceState)
    map3DView.getMap3DViewAsync(this)
}

  6. onMap3DViewReady 및 onError 메서드를 재정의합니다. 이러한 콜백은 지도를 사용할 준비가 되거나 초기화 중에 오류가 발생할 때 트리거됩니다.

    override fun onMap3DViewReady(googleMap3D: GoogleMap3D) {
    // Interact with the googleMap3D object here
    this.googleMap3D = googleMap3D
    // You can now make calls to the googleMap3D object, e.g.,
    // googleMap3D.cameraController.flyTo(camera { ... })
}

override fun onError(error: Exception) {
    // Handle the error gracefully here (for example, show an error dialog or log the error).
    Log.e("MainActivity", "Error loading 3D map", error)
}

  7. 다음 재정의를 MainActivity에 추가하여 활동에서 Map3DView로 수명 주기 이벤트를 전달합니다.

    override fun onStart() {
    super.onStart()
    map3DView.onStart()
}

override fun onResume() {
    super.onResume()
    map3DView.onResume()
}

override fun onPause() {
    map3DView.onPause()
    super.onPause()
}

override fun onStop() {
    map3DView.onStop()
    super.onStop()
}

override fun onDestroy() {
    map3DView.onDestroy()
    super.onDestroy()
}

override fun onSaveInstanceState(outState: Bundle) {
    super.onSaveInstanceState(outState)
    map3DView.onSaveInstanceState(outState)
}

override fun onLowMemory() {
    super.onLowMemory()
    map3DView.onLowMemory()
}

3부: Gradle 동기화 및 실행

이제 앱의 레이아웃과 활동을 업데이트했으므로 앱을 빌드하고 실행하여 3D 지도 뷰를 확인할 수 있습니다.

  1. 프로젝트를 Gradle과 동기화하려면 File > Sync Project with Gradle Files 를 선택합니다.

  2. 에뮬레이터 또는 실제 기기에서 앱을 빌드하고 실행하려면 Run > Run 을 선택합니다.

모든 항목이 올바르게 구성되면 activity_main.xml에 지정된 좌표 근처에 중심이 맞춰진 3D 지도가 앱에 표시됩니다.

지도 로드 및 오류 상태

Android용 지도 3D SDK는 지도의 상태를 관리하는 동안 기본 제공 시각적 의견을 자동으로 표시합니다.

  • 오버레이 로드: 지도 뷰가 처음 초기화되거나 초기 표시 영역을 로드할 때 가운데에 진행률 표시기가 표시됩니다.
  • 오류 오버레이: 잘못된 API 키, 네트워크 오류 또는 지원되지 않는 기기에서 실행하는 경우와 같은 심각한 오류가 발생하면 스타일이 지정된 오류 카드가 표시됩니다.

`OnMap3DViewReadyCallback` 구현 내에서 `onError(error: Exception)`을 재정의하여 이러한 초기화 또는 로드 오류를 프로그래매틱 방식으로 캡처할 수 있습니다.

지도 클릭 이벤트 수신 대기

지도에서 클릭 이벤트를 수신 대기하려면 GoogleMap3D.setMap3DClickListener를 사용합니다. 이 리스너는 사용자가 지도를 클릭할 때 트리거되며 클릭된 지점의 위치와 장소 ID를 제공합니다.

다음 예에서는 지도 클릭 리스너를 설정하는 방법을 보여줍니다.

googleMap3D.setMap3DClickListener { location, placeId ->
    lifecycleScope.launch(Dispatchers.Main) {
        if (placeId != null) {
            Toast.makeText(this@MainActivity, "Clicked on place with ID: $placeId", Toast.LENGTH_SHORT).show()
        } else {
            Toast.makeText(this@MainActivity, "Clicked on location: $location", Toast.LENGTH_SHORT).show()
        }
    }
}

클릭 핸들러는 기본 (또는 UI) 스레드에서 실행되지 않습니다. Toast 메시지 표시와 같이 UI를 변경하려면 기본 스레드로 전환해야 합니다. Kotlin의 경우 lifecycleScope.launch(Dispatchers.Main)을 사용하여 이 작업을 실행할 수 있습니다.

다음 단계

이제 앱에 기본 3D 지도를 추가했으므로 카메라 경로 애니메이션, 3D 마커 또는 다각형과 같은 Android용 지도 3D SDK의 고급 기능을 살펴볼 수 있습니다.