地面オーバーレイ

地面オーバーレイは、緯度と経度の座標に紐付けられたイメージ オーバーレイで、地図をドラッグしたりズームしたりすると連動して動きます。

コードサンプル

GitHub の ApiDemos リポジトリには、地面オーバーレイの機能を示すサンプルが含まれています。

• GroundOverlayDemoActivity - Java: Java での地面オーバーレイ機能とリスナー
• GroundOverlayDemoActivity - Kotlin: Kotlin での地面オーバーレイ機能とリスナー

はじめに

地面オーバーレイは、地図に固定されている画像です。地面オーバーレイは、マーカーとは異なり、画面ではなく地面の向きに合わせて表示されるため、地図を回転、傾斜、ズームすると、画像の向きが変わります。地面オーバーレイは、地図上の 1 か所に 1 枚の画像を固定したい場合に便利です。地図の大半を覆うような大きな画像を追加する場合は、タイル オーバーレイの使用をおすすめします。

オーバーレイを追加する

GroundOverlay を追加するには、画像と位置の両方を定義する GroundOverlayOptions オブジェクトを作成します。必要に応じて追加設定を指定して、地図上に配置する画像に反映することもできます。必要なオプションを定義したら、オブジェクトを GoogleMap.addGroundOverlay() メソッドに渡して、地図に画像を追加します。addGroundOverlay() メソッドから GroundOverlay オブジェクトが返されます。このオブジェクトを後で変更する場合は、このオブジェクトへの参照を保持しておく必要があります。

手順は次のとおりです。

1. GroundOverlayOptions オブジェクトの新しいインスタンスを生成します。
2. 画像を BitmapDescriptor として指定します。
3. 次の使用可能なメソッドのいずれかを使用して、画像の位置を設定します。
   • position(LatLng location, float width, float height)
   • position(LatLng location, float width)
   • positionFromBounds(LatLngBounds bounds)
4. 必要に応じて、transparency などの任意のプロパティを設定します。
5. GoogleMap.addGroundOverlay() を呼び出して、地図に画像を追加します。

次のコードは、既存の GoogleMap オブジェクトに地面オーバーレイを追加する方法を示します。

val newarkLatLng = LatLng(40.714086, -74.228697)
val newarkMap = GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .position(newarkLatLng, 8600f, 6500f)
map.addGroundOverlay(newarkMap)

      

LatLng newarkLatLng = new LatLng(40.714086, -74.228697);

GroundOverlayOptions newarkMap = new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .position(newarkLatLng, 8600f, 6500f);
map.addGroundOverlay(newarkMap);

      

地図に追加した後で地面オーバーレイを変更または削除する場合は、GroundOverlay オブジェクトを保持しておきます。地面オーバーレイを後から変更するには、このオブジェクトに変更を加えます。

// Add an overlay to the map, retaining a handle to the GroundOverlay object.
val imageOverlay = map.addGroundOverlay(newarkMap)

      

// Add an overlay to the map, retaining a handle to the GroundOverlay object.
GroundOverlay imageOverlay = map.addGroundOverlay(newarkMap);

      

オーバーレイを削除する

地面オーバーレイを削除するには GroundOverlay.remove() メソッドを使用します。

imageOverlay?.remove()

      

imageOverlay.remove();

      

オーバーレイを変更する

地面オーバーレイ画像を地図に追加した後で変更するには、GroundOverlay.setImage(BitmapDescriptor) メソッドを使用します。

// Update the GroundOverlay with a new image of the same dimension

// Update the GroundOverlay with a new image of the same dimension
imageOverlay?.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))

      

// Update the GroundOverlay with a new image of the same dimension
imageOverlay.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922));

      

setImage() メソッドで、既存の画像が、同じサイズの別の画像に置き換えられます。

地面オーバーレイを配置する

地面オーバーレイの位置を指定するには、次の 2 つの方法があります。

• LatLng を使ってオーバーレイの中心を指定し、メートル単位で画像のサイズを指定します。
• LatLngBounds を使って画像の北東と南西の角を指定します。

地面オーバーレイの位置は、地図に追加する前に指定する必要があります。

位置情報を使用して画像を配置する

画像を追加するときに、アンカーが固定される LatLng と、オーバーレイの幅（メートル単位）を指定します。anchor は、デフォルトで画像の中心に設定されます。必要に応じて、オーバーレイの高さ（メートル単位）を指定できます。オーバーレイの高さを指定しなかった場合は、画像のアスペクト比を保持するよう高さが自動的に計算されます。

以下のコードでは、画像が 40.714086, -74.228697 の位置に配置され、幅が 8.6 km、高さが 6.5 km になります。画像は左下に固定されます。

val newarkMap = GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .anchor(0f, 1f)
    .position(LatLng(40.714086, -74.228697), 8600f, 6500f)

      

GroundOverlayOptions newarkMap = new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .anchor(0, 1)
    .position(new LatLng(40.714086, -74.228697), 8600f, 6500f);

      

LatLngBounds を使用して画像を位置指定する

画像を含む LatLngBounds を指定します。LatLngBounds では、画像の北東と南西の隅を設定します。画像が地図に表示されると、その画像は表示範囲に収まるように回転します。表示範囲が元のアスペクト比と一致しない場合は、画像が歪みます。

以下のコードでは、地図上で南西の隅を 40.712216,-74.22655 に、北東の隅を 40.773941, -74.12544 に指定して画像を配置します。

val newarkBounds = LatLngBounds(
    LatLng(40.712216, -74.22655),  // South west corner
    LatLng(40.773941, -74.12544)   // North east corner
)
val newarkMap = GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .positionFromBounds(newarkBounds)

      

LatLngBounds newarkBounds = new LatLngBounds(
    new LatLng(40.712216, -74.22655),       // South west corner
    new LatLng(40.773941, -74.12544));      // North east corner
GroundOverlayOptions newarkMap = new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .positionFromBounds(newarkBounds);

      

データを地面オーバーレイに関連付ける

GroundOverlay.setTag() を呼び出して地面オーバーレイに任意のデータ オブジェクトを保存し、GroundOverlay.getTag() を使用してそのオブジェクトを取得できます。

地面オーバーレイに文字列の記述を保存するコードのサンプルを次に示します。

val sydneyGroundOverlay = map.addGroundOverlay(
    GroundOverlayOptions()
        .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge))
        .position(LatLng(-33.873, 151.206), 100f)
        .clickable(true)
)
sydneyGroundOverlay?.tag = "Sydney"

      

GroundOverlay sydneyGroundOverlay = map.addGroundOverlay(new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge))
    .position(new LatLng(-33.873, 151.206), 100)
    .clickable(true));

sydneyGroundOverlay.setTag("Sydney");

      

地面オーバーレイでデータを保存および取得する方法が役立つシナリオの例を、次にいくつか紹介します。

• アプリで複数の地面オーバーレイを提供し、それぞれがクリックされたときに異なった処理が行われるようにしたい場合。
• 一意の記録識別子を使用するシステムと連携し、そのシステムの記録をオーバーレイとして表示する場合。
• オーバーレイ データによって、オーバーレイの Z-Index の優先順位が決まる場合。

地面オーバーレイ イベントを処理する

デフォルトでは、地面オーバーレイはクリックできません。クリックを有効または無効にするには、GroundOverlay.setClickable(boolean) を呼び出します。

クリック可能な地面オーバーレイでクリック イベントをリッスンするには、OnGroundOverlayClickListener を使用します。このリスナーを地図に設定するには、GoogleMap.setOnGroundOverlayClickListener(OnGroundOverlayClickListener) を呼び出します。地面オーバーレイがクリックされると、onGroundOverlayClick(GroundOverlay) コールバックを受け取ります。