地面オーバーレイ

地面オーバーレイは緯度と経度で表される座標に紐付いた画像オーバーレイで、マップをドラッグしたりズームしたりすると連動して動きます。

コードサンプル

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

はじめに

地面オーバーレイは、マップに固定されている画像です。マーカーとは異なり、地面オーバーレイは画面ではなく地表面に平行に配置されるため、マップを回転、チルト、ズームすると画像の向きが変わります。地面オーバーレイは、マップ上の 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 オブジェクトに地面オーバーレイを追加する方法を示しています。

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 インデックスを決定するための優先度を指定する。

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

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

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