アプリに 3D 地図を追加する

プラットフォームを選択: Android iOS JavaScript

ニューヨーク市を示す 3D 地図

このページでは、Maps 3D SDK for Android を使用して Android アプリに基本的な 3D 地図を追加する方法の例について説明します。このページの手順では、 セットアップ ページの手順を完了し、 次のものが用意されていることを 前提としています。

  • Maps 3D SDK for Android が有効になっている Google Cloud プロジェクト
  • Maps 3D SDK for Android で使用するように構成された API キー
  • Maps 3D SDK for Android で使用するように設定された Android Studio プロジェクト

これらの前提条件の詳細については、 セットアップをご覧ください。

パート 1: レイアウト ファイル（activity_main.xml）を更新して Map3DView コンポーネントを追加する

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:mapMode="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 コンポーネントを初期化し、コンポーネントのライフサイクル イベントを管理します。

Maps 3D SDK for Android では、一度に 1 つのアクティブな Map3DView インスタンスのみがサポートされます。複数の Map3DView インスタンスを同時に表示する（同じレイアウト、異なる表示アクティビティ、フラグメントなど）ことはサポートされていません。また、セカンダリ ビューに黒い画面が表示されるなど、レンダリングの問題が発生する可能性があります。

さらに、すべての Map3DView は同じ地図の状態（ カメラの位置、追加されたマーカー、ポリゴンなど）を共有して反映します。これは、 手動でクリアしない限り、1 つの Map3DView が破棄（onDestroy を使用）されて別の が作成された場合でも保持されます。たとえば、Map3DView1 にマーカーを追加してから破棄して Map3DView2 を作成した場合、同じマーカーが Map3DView2 にも表示されます。

開発者の責任:

  • 一度に 1 つのビュー:常に 1 つの Map3DView のみがビュー階層のアクティブな部分にあるようにします。
  • 手動クリーンアップ: 1 つの Map3DView（Map3DView1 など）から別の（Map3DView2 など）に切り替える場合は、古いインスタンス（Map3DView1）で onDestroy() を呼び出す必要があります。基盤となる地図の状態は共有されるため、Map3DView2 が新しい状態または特定の状態から開始されるようにするには、Map3DView1 によって設定された状態を手動でクリアする必要があります。これには、マーカーやオーバーレイの削除、OnMap3DViewReadyCallback で取得した GoogleMap3D オブジェクトを使用したカメラの位置のリセットなどが含まれます。

  1. MainActivity.kt ファイルを開きます。通常は app/src/main/java/com/example/yourpackagename/MainActivity.kt にあります。

  2. Maps 3D SDK for Android に必要なインポートを追加します。

    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.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 に追加して、Activity から 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 地図がアプリに表示されます。

地図の読み込みとエラーの状態

Maps 3D SDK for Android は、地図の状態を管理しながら、組み込みの視覚的なフィードバックを自動的に表示します。

  • 読み込みオーバーレイ: 地図ビューが最初に初期化されたとき、または最初のビューポートを読み込んでいるときに、中央に進行状況インジケーターが表示されます。
  • エラー オーバーレイ: 無効な API キー、ネットワーク エラー、サポートされていないデバイスでの実行など、重大なエラーが発生した場合は、スタイル設定されたエラーカードが表示されます。

これらの初期化エラーまたは読み込みエラーは、 onError(error: Exception) を OnMap3DViewReadyCallback 実装内でオーバーライドすることで、プログラムでキャプチャできます。

地図のクリック イベントをリッスンする

地図のクリック イベントをリッスンするには、 setMap3DClickListener で GoogleMap3Dを呼び出します。 ユーザーが地図をクリックすると、 onMap3DClick コールバックは、クリックしたポイントの location と placeId を提供する Map3DClickEvent オブジェクトを受け取り、Booleanを返します（デフォルトの プレイス UI ウィジェットを非表示にする場合はtrue、表示する場合はfalse）。詳細については、 スポットを操作するをご覧ください。

次の例は、地図のクリック リスナーを設定する方法を示しています。

googleMap3D.setMap3DClickListener { event: Map3DClickEvent ->
    Log.d(
        "MainActivity",
        "Clicked at ${event.location}, placeId: ${event.placeId}"
    )
    false
}

次のステップ

アプリに基本的な 3D 地図を追加したので、Maps 3D SDK for Android の 高度な機能（ カメラパス アニメーション、 3D マーカー、 ポリゴンなど）について学習できます。