地面オーバーレイ

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

コードサンプル

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

はじめに

地面オーバーレイは、地図に固定されている画像です。地面オーバーレイは、マーカーとは異なり、画面ではなく地面の向きに合わせて表示されるため、地図を回転、傾斜、ズームすると、画像の向きが変わります。地面オーバーレイは、地図上のいずれかの領域に 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 オブジェクトに地面オーバーレイを追加する方法を示したコードの例を次に示します。

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

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

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

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

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

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

オーバーレイを削除する

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

imageOverlay.remove();

オーバーレイを変更する

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

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

// Update the GroundOverlay with a new image of the same dimensions.
imageOverlay = map.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1975));

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

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

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

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

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

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

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

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

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 に指定して画像を配置します。

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() を使用します。

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

private GoogleMap mMap;
private GroundOverlay mSydneyGroundOverlay;

mSydneyGroundOverlay = mMap.addGroundOverlay(new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge))
    .position(new LatLng(-33.873, 151.206))
    .clickable(true));

mSydneyGroundOverlay.setTag("Sydney");

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

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

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

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

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