앱에 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 지도를 렌더링하는 뷰입니다. 다음 단계에서는 구성요소를 추가하고 카메라 위치 및 관련 속성을 비롯한 지도의 초기 상태를 구성합니다.

참고: 이 섹션의 단계에서는 설정에 설명된 프로세스를 사용하여 Android 스튜디오 프로젝트를 만들고 구성했거나 기존 프로젝트에 새 뷰 활동을 추가했다고 가정합니다. 뷰 활동을 추가하지 않고 새 Android 스튜디오 프로젝트를 만드는 경우 프로젝트에 activity_main.xml 파일이 포함되지 않습니다.

기본 활동의 레이아웃 파일을 엽니다. 일반적으로 app/src/main/res/layout/activity_main.xml에 있습니다.
루트 ConstraintLayout (또는 루트 레이아웃 요소)에서 map3d XML 네임스페이스를 추가합니다.
```
xmlns:map3d="http://schemas.android.com/apk/res-auto"
```
'Hello World!'를 표시하는 기본 <TextView>를 삭제합니다.

레이아웃에 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: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 객체를 사용하여 마커, 오버레이 등을 삭제하고 카메라 위치를 재설정하는 것이 포함됩니다.

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

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

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

MainActivity 클래스를 수정하여 OnMap3DViewReadyCallback을 구현합니다.
```
class MainActivity : AppCompatActivity(), OnMap3DViewReadyCallback {
```

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

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

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

onMap3DViewReady 메서드를 재정의합니다. 지도를 사용할 준비가 되면 이 콜백이 트리거됩니다.

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 { ... })
}

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 지도 뷰를 확인할 수 있습니다.

프로젝트를 Gradle과 동기화하려면 File > Sync Project with Gradle Files 를 선택합니다.
에뮬레이터 또는 실제 기기에서 앱을 빌드하고 실행하려면 Run > Run 을 선택합니다.

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

다음 단계

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

지도 클릭 이벤트 수신 대기

지도에서 클릭 이벤트를 수신 대기하려면 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 지도 추가 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

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

2부: MainActivity.kt 업데이트

3부: Gradle 동기화 및 실행

다음 단계

지도 클릭 이벤트 수신 대기

앱에 3D 지도 추가

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