マップオーバーレイ

マップオーバーレイの概要

オーバーレイは、経緯度座標に固定された地図上のオブジェクトです。地図をドラッグしたりズームしたりすると、オーバーレイが移動します。オーバーレイは、地点、線、領域を指定するために地図に「追加」されたオブジェクトを反映します。

マップ API には、さまざまなタイプのオーバーレイがあります。

• 地図上の地点は、マーカーを使用して表示します。この地点には多くの場合カスタムアイコンが表示されます。マーカーは、タイプ GMarker のオブジェクトで、GIcon タイプを使用することができます。
• 地図上の線はポリラインを使用して表示します (点の集合で表現されます)。線は、タイプ GPolyline のオブジェクトです。
• 地図上の領域は、領域の形状が不特定の場合にはポリゴンで表示し、四角形の場合にはグラウンドオーバーレイで表示します。ポリゴンは、閉じた境界線に囲まれ、ポリラインと同じように点の集合で形成されます。任意の形状を表現することができます。グラウンドオーバーレイは、多くの場合、地図上のタイルに直接または間接的にオーバーレイをマッピングする領域に使用されます。
• 地図自体は、タイルオーバーレイで表示されています。この地図の表示は、GTileLayerOverlay を使用して独自のタイルに変更したり、GMapType を使用して独自のマップタイプによって変更したりすることができます。
• 情報ウィンドウも特殊な種類のオーバーレイです。ただし、情報ウィンドウは自動的に地図に追加され、タイプ GInfoWindow の1つのオブジェクトだけを地図に添付できます。

各オーバーレイは、GOverlay インターフェイスを使って実装します。オーバーレイは、GMap2.addOverlay() メソッドを使用して地図に追加し、GMap2.removeOverlay() メソッドを使用して削除します (情報ウィンドウはデフォルトで地図に追加されます)。

マーカー

マーカーは地図上の地点を指定します。マーカーはデフォルトで、G_DEFAULT_ICON を使用しますが、カスタムアイコンを指定することもできます。GMarker コンストラクタは、引数に GLatLng オブジェクトと、省略可能な GMarkerOptions オブジェクトを取ります。

マーカーはインタラクティブに操作できるように設計されています。デフォルトでは、"click" イベントを取得します。たとえば、イベントリスナー内で情報ウィンドウを表示するためにしばしば使用されます。

var map = new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(37.4419, -122.1419), 13);
 
// 地図のランダムな場所に10個のマーカーを追加します
var bounds = map.getBounds();
var southWest = bounds.getSouthWest();
var northEast = bounds.getNorthEast();
var lngSpan = northEast.lng() - southWest.lng();
var latSpan = northEast.lat() - southWest.lat();
for (var i = 0; i < 10; i++) {
  var point = new GLatLng(southWest.lat() + latSpan * Math.random(),
	southWest.lng() + lngSpan * Math.random());
map.addOverlay(new GMarker(point));
}

例を表示 (marker-simple.html)

ドラッグできるマーカー

マーカーは、クリックしたり、新しい場所へドラッグしたりできる操作が可能なオブジェクトです。この例では、地図上にドラッグできるマーカーを配置して、いくつかの単純なイベントの発生を待機します。ドラッグできるマーカーは、ドラッグのステータスを示す click、dragstart、drag、および dragend の4種類のイベントを実装します。マーカーは、デフォルトでクリックできますが、ドラッグはできません。このため、追加のマーカー オプション draggable を true に設定して初期化する必要があります。ドラッグできるマーカーは、デフォルトで弾みます（バウンド）。この動作が必要ない場合は、bouncy オプションを false に設定すると、マーカーが地図の表面で弾まずに動くようになります。

var map = new GMap2(document.getElementById("map_canvas"));
var center = new GLatLng(37.4419, -122.1419);
map.setCenter(center, 13);

var marker = new GMarker(center, {draggable: true});

GEvent.addListener(marker, "dragstart", function() {
  map.closeInfoWindow();
  });

GEvent.addListener(marker, "dragend", function() {
  marker.openInfoWindowHtml("飛び跳ねてみます...");
  });

map.addOverlay(marker);

例を表示 (marker-drag.html)

アイコン

マーカーには、アイコンを定義して、デフォルトのアイコンとして表示することができます。1つのアイコンは複数の画像で構成されているため、マップ API でアイコンを定義するのは単純ではありません。最低でも、1つのアイコンには、前面の画像、タイプ GSize のサイズ、およびアイコンの位置を指定するためのアイコンオフセットを定義する必要があります。

最も単純なアイコンは、G_DEFAULT_ICON タイプを基に作成します。このタイプを基にアイコンを作成することにより、いくつかのプロパティを変更するだけでデフォルトのアイコンを簡単に変更できます。

次の例では、G_DEFAULT_ICON タイプを使用してアイコンを作成し、他の画像を使用するように変更しています (別の画像を使用するには、デフォルト画像と正確に同じサイズに設定して適切に表示する必要があるため、注意が必要です)。

var map = new GMap2(document.getElementById("map_canvas"));
map.addControl(new GSmallMapControl());
map.setCenter(new GLatLng(37.4419, -122.1419), 13);

// 「小さな」マーカーアイコンを作成します
var blueIcon = new GIcon(G_DEFAULT_ICON);
blueIcon.image = "http://www.google.com/intl/en_us/mapfiles/ms/micons/blue-dot.png";
		
// GMarkerOptions オブジェクトを設定します
markerOptions = { icon:blueIcon };

// 地図のランダムな場所に10個のマーカーを追加します
var bounds = map.getBounds();
var southWest = bounds.getSouthWest();
var northEast = bounds.getNorthEast();
var lngSpan = northEast.lng() - southWest.lng();
var latSpan = northEast.lat() - southWest.lat();
for (var i = 0; i < 10; i++) {
  var point = new GLatLng(southWest.lat() + latSpan * Math.random(),
    southWest.lng() + lngSpan * Math.random());
  map.addOverlay(new GMarker(point, markerOptions));
}

例を表示 (icon-simple.html)

ほとんどのアイコンには前面の画像と影の画像が含まれています。影の画像は、前面の画像から45度の角度 (右上) に作成し、影の画像の左下の角を前面の画像の左下の角と合わせる必要があります。さらに、画像の境界が地図上に正しく表示されるように、アルファ透明の24ビット PNG 画像にする必要があります。

この例では、Google Ride Finder の「ミニ」マーカーを使用して新しいタイプのアイコンを作成しています。前面の画像、影の画像、アイコンのアンカー地点、およびアイコンの情報ウィンドウのアンカー地点を指定する必要があります。アイコンは、GMarkerOptions オブジェクトに定義されたオプションで渡されます。

var map = new GMap2(document.getElementById("map"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.setCenter(new GLatLng(37.4419, -122.1419), 13);

// 「小さな」マーカーアイコンを作成します
var tinyIcon = new GIcon();
tinyIcon.image = "http://labs.google.com/ridefinder/images/mm_20_red.png";
tinyIcon.shadow = "http://labs.google.com/ridefinder/images/mm_20_shadow.png";
tinyIcon.iconSize = new GSize(12, 20);
tinyIcon.shadowSize = new GSize(22, 20);
tinyIcon.iconAnchor = new GPoint(6, 20);
tinyIcon.infoWindowAnchor = new GPoint(5, 1);

// GMarkerOptions のオブジェクトリテラルを設定します
markerOptions = { icon:tinyIcon };

// 地図のランダムな場所に10個のマーカーを追加します
var bounds = map.getBounds();
var southWest = bounds.getSouthWest();
var northEast = bounds.getNorthEast();
var lngSpan = northEast.lng() - southWest.lng();
var latSpan = northEast.lat() - southWest.lat();
for (var i = 0; i < 10; i++) {
  var point = new GLatLng(southWest.lat() + latSpan * Math.random(),
                          southWest.lng() + lngSpan * Math.random());
  map.addOverlay(new GMarker(point, markerOptions));
}

GMarkerOptions オブジェクトの定義では、オブジェクトリテラルの記述方法を示しています。このオブジェクトはコンストラクタでインスタンス化するのではなく、単純に一対の名前と値で宣言します。

例を表示 (icon-complex.html)

カスタムアイコン

GIcon オブジェクトには、その他にもいくつかのプロパティがあり、アイコンに対するブラウザの互換性や機能を最大限高めるために設定する必要があります。たとえば、imageMap プロパティは、アイコン画像の透明でない部分の形状を指定します。アイコンでこのプロパティを設定しないと、(透明部分を含む) アイコン全体の画像が、Firefox/Mozilla でクリック可能になります。詳細については、GIcon クラスのリファレンスを参照してください。

複数のアイコンの前面の画像は違っても、形状と影が同じ場合が多くあります。これらのアイコンを作成する最も簡単な方法は、GIcon クラスのコピーコンストラクタを使用してすべてのプロパティを新しいアイコンにコピーすることです。その後で新しいアイコンをカスタマイズします。

var map = new GMap2(document.getElementById("map_canvas"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.setCenter(new GLatLng(37.4419, -122.1419), 13);

// すべてのマーカーの基本となるアイコンを作成し、
// 影やアイコンのサイズなどを指定します
var baseIcon = new GIcon();
baseIcon.shadow = "http://www.google.com/mapfiles/shadow50.png";
baseIcon.iconSize = new GSize(20, 34);
baseIcon.shadowSize = new GSize(37, 34);
baseIcon.iconAnchor = new GPoint(9, 34);
baseIcon.infoWindowAnchor = new GPoint(9, 2);
baseIcon.infoShadowAnchor = new GPoint(18, 25);

// マーカーを作成し、情報ウィンドウに
// 指定されたインデックスに対応する文字を表示します。
function createMarker(point, index) {
// アイコンクラスを使用して、この地点に文字のアイコンを作成します
  var letter = String.fromCharCode("A".charCodeAt(0) + index);
  var letteredIcon = new GIcon(baseIcon);
  letteredIcon.image = "http://www.google.com/mapfiles/marker" + letter + ".png";

// GMarkerOptions オブジェクトを設定します
  markerOptions = { icon:letteredIcon };
  var marker = new GMarker(point, markerOptions);

  GEvent.addListener(marker, "click", function() {
    marker.openInfoWindowHtml("Marker <b>" + letter + "</b>");
  });
  return marker;
}

// 地図のランダムな場所に10個のマーカーを追加します
var bounds = map.getBounds();
var southWest = bounds.getSouthWest();
var northEast = bounds.getNorthEast();
var lngSpan = northEast.lng() - southWest.lng();
var latSpan = northEast.lat() - southWest.lat();
for (var i = 0; i < 10; i++) {
  var point = new GLatLng(southWest.lat() + latSpan * Math.random(),
                          southWest.lng() + lngSpan * Math.random());
  map.addOverlay(createMarker(point, i));
}

例を表示 (icon-custom.html)

マーカーマネージャを使用

Google マップに多数のマーカーを追加すると、地図のレンダリングが遅くなり、表示が大きく乱れる場合があります。これらは特定のズームレベルで顕著に起こります。マーカーマネージャユーティリティは、これら両方の問題を解決します。1つの地図に多数のマーカーを効率良く表示できるようになり、マーカーを表示するズームレベルを指定できるようになります。

マーカーマネージャユーティリティは、 GMaps Utility Library で提供されています。 このライブラリはオープンソースであり、Google マップ API のコアでは使用されていないユーティリティを含んでいます。このライブラリに含まれているユーティリティを追加するには、<script> タグで JavaScript ソースディレクトリを追加してください。

<script src="http://gmaps-utility-library.googlecode.com/svn/trunk/markermanager/release/src/markermanager.js">

markermanager.js ライブラリ内の MarkerManager オブジェクトは、このユーティリティに登録されたマーカーの管理をオフロードします。現在のビュー内の特定のズームレベルで、どのマーカーを表示するかを監視し、描画用にこれらのマーカーのみを地図に渡します。マネージャは、地図の現在のビューポートとズームレベルを監視し、アクティブになる地図に合わせて、動的にマーカーを追加したり、地図からマーカーを削除したりします。さらに、マーカーを表示するズームレベルを指定することにより、マーカーのクラスタリングを実装できます。このような管理により、大幅に地図のレンダリングが高速化され、表示の乱れが少なくなります。

マーカーマネージャを使用するには、MarkerManager オブジェクトを作成します。最も単純な状況では、地図をこのオブジェクトに渡すだけです。

var map = new GMap2(document.getElementById("map_canvas"));
var mgr = new MarkerManager(map);

また、マーカーマネージャの性能を調整するためにいくつかのオプションを指定することもできます。これらのオプションは、次のフィールドを含む MarkerManagerOptions オブジェクトで渡します。

• maxZoom: このマーカーマネージャで監視する最大のズームレベルを指定します。デフォルト値は、Google マップでサポートされている最大のズームレベルです。
• borderPadding: マネージャが監視する、現在のビューポイントの外側の拡張パディングをピクセル単位で指定します。これにより、表示領域のわずかに外側にあるマーカーを地図に表示するときの狭い範囲でのパンの処理が向上します。デフォルト値は100です。
• trackMarkers: マーカーの動作で、マーカーマネージャが追跡する必要がある動作を指定します。setPoint() メソッドで管理対象マーカーの位置を変更する場合には、この値を true に設定します。デフォルトでは、このフラグが false に設定されています。この値を false に設定してマーカーを動かすと、元の場所と新しい場所の両方に表示されます。

MarkerManagerOptions オブジェクトはオブジェクトリテラルなので、 コンストラクタを使わずに単純にこのオブジェクトを宣言してください。

var map = new GMap2(document.getElementById("map_canvas"));
var mgrOptions = { borderPadding: 50, maxZoom: 15, trackMarkers: true };
var mgr = new MarkerManager(map, mgrOptions);

マネージャを作成したら、マーカーをそのマネージャに追加します。MarkerManager は、addMarker() メソッドで1つずつマーカーを追加する方法と、addMarkers() メソッドでコレクションを配列として渡す方法をサポートしています。addMarker() で1つのマーカーを追加するとき、そのマーカーが現在のビュー内にあり、指定されたズームレベルに当てはまる場合には、地図上にすぐに表示されます。

addMarkers() を使って複数のマーカーを一括追加する方法は効率的なため、この方法をお勧めします。addMarkers() メソッドで追加されたマーカーは 、MarkerManager の refresh() メソッドを明示的に呼び出すまで表示されません。このメソッドにより、現在のビューポイント内にあるすべてのマーカーと、境界パディングの区域が地図に追加されます。この最初の表示後、MarkerManager は地図の "moveend" イベントを監視して、すべての表示上の更新を管理します。

ズームレベルの例: 天気予報図

次の例は、ヨーロッパの天気予報図の見本を作成しています。ズームレベル3で、ランダムに配置された20個のお天気アイコンが表示されます。人口30万人を超える200都市を容易に区別できるレベル6では、追加の200個のマーカーが表示されます。最後に、レベル8では、1,000個のマーカーが表示されます (注: 例を単純化するために、マーカーはランダムな場所に追加します)。

function setupMap() {
  if (GBrowserIsCompatible()) {
    map = new GMap2(document.getElementById("map_canvas"));
    map.addControl(new GLargeMapControl());
    map.setCenter(new GLatLng(41, -98), 4);
    window.setTimeout(setupWeatherMarkers, 0);
  }
}

function getWeatherMarkers(n) {
  var batch = [];
  for (var i = 0; i < n; ++i) {
    batch.push(new GMarker(getRandomPoint(), { icon: getWeatherIcon() }));
  }
  return batch;
}

function setupWeatherMarkers() {
  mgr = new MarkerManager(map);
  mgr.addMarkers(getWeatherMarkers(20), 3);
  mgr.addMarkers(getWeatherMarkers(200), 6);
  mgr.addMarkers(getWeatherMarkers(1000), 8);
  mgr.refresh();
}

例を表示 (weather_map.html)

クラスタリングの例: Google のオフィス

マーカーマネージャは、マーカーの単純クラスタリングを実現することもできます。これは自動的には行われませんが、特定のマーカーを表示する最小と最大のズームを設定することにより目的の効果を実現できます。この例では、北米の Google のオフィスの地図を作成します。最上位のレベルでは、オフィスがある国のフラグを表示します。ズームレベル3～7では、1つ以上のオフィスがある人口密集地域を表示します。最後にレベル8以上では、各オフィスのマーカーを個別に表示します。

var officeLayer = [
  {
    "zoom": [0, 3],
    "places": [
      { "name": "US Offices", "icon": ["us", "flag-shadow"], "posn": [40, -97] },
      { "name": "Canadian Offices", "icon": ["ca", "flag-shadow"], "posn": [58, -101] }
    ]
  },
  ...
};

function setupOfficeMarkers() {
  var mgr = new MarkerManager(map);
  for (var i in officeLayer) {
    var layer = officeLayer[i];
    var markers = [];
    for (var j in layer["places"]) {
      var place = layer["places"][j];
      var icon = getIcon(place["icon"]);
      var posn = new GLatLng(place["posn"][0], place["posn"][1]);
      markers.push(new GMarker(posn, { title: place["name"], icon: icon }));
    }
    mgr.addMarkers(markers, layer["zoom"][0], layer["zoom"][1]);
  }
  mgr.refresh();
}

例を表示 (google_northamerica_offices.html)

詳細については、オープンソースのマーカーマネージャのリファレンスドキュメントを参照してください。

ポリライン

GPolyline オブジェクトは、地図上に直線のオーバーレイを作成します。GPolyline は、連続する点から成り、これらの点を指定された順序で結ぶ連続する線のセグメントを形成します。

ポリラインを描画

ポリラインは、地図上に連続する直線のセグメントを描画します。線には、カスタムカラー、重み (太さ)、および透明度を指定することができます。カラーは、HTML 方式の16進数値で表現します。たとえば、red ではなく #ff0000 を使用します。GPolyline は色の名前を認識できません。

GPolyline オブジェクトは、ブラウザのベクター描画機能が利用できる場合はこれを利用します。Google マップは、Internet Explorer の場合、VML ( XHTML と VML を参照) を使用してポリラインを描画します。他のブラウザの場合、SVG が利用できる場合は、これを利用します。これら以外の状況では、線の画像を Google サーバーに要求し、その画像を地図上にオーバーレイします。地図をズームやドラッグするたびに、画像の更新が必要になります。

次のコードスニペットは、2点間に10ピクセル幅の赤いポリラインを作成します。

var polyline = new GPolyline([
  new GLatLng(37.4419, -122.1419),
  new GLatLng(37.4519, -122.1519)
], "#ff0000", 10);
map.addOverlay(polyline);

例を表示 (polyline-simple.html)

測地線ポリライン

地図上で表現されるポリラインは、現在の投影に合わせた直線です。このため、地図上に直線で表示され、実際には地球の曲面が適切に考慮されていません。この代わりに測地線 (地球表面の2点間の最短距離を表す「巨大な円」の部分線) を描画したい場合は、GPolyline の GPolylineOptions 引数に geodesic:true を渡す必要があります。

GPolylineOptions オブジェクトは、オブジェクトリテラルの例を示しています。オブジェクトリテラルを使用する場合、オブジェクトを構造化 (コンストラクタを使用) する必要はありません。その代わりに、名前と値の対 (複数可) をカッコで囲んだ引数を渡します。オブジェクトリテラルは、オブジェクトのインスタンス化が必要ない場合に多く使用されます。

var map = new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(45.828799,-105.292969), 2);

// GPolylineOptions の引数をオブジェクトリテラルで作成します。
// コンストラクタは使用しません。

var polyOptions = {geodesic:true};
var polyline = new GPolyline([
  new GLatLng(40.65642, -73.7883),
  new GLatLng(61.1699849, -149.944496)
  ], "#ff0000", 10, 1, polyOptions);
  map.addOverlay(polyline);

例を表示 (polyline-geodesic.html)

エンコード化ポリライン

Google マップ内の GPolyline オブジェクトは線を連続する点で表すため、使用が簡単ですが、データ量が比較的多くなります。長く複雑な線には、相当量のメモリが必要になり、多くの場合描画時間が長くなります。また、エンコードされていないポリラインの個々のセグメントは、詳細なズームレベルでも解像度に関係なく地図上に描画されます。

Google マップ API では、エンコード化ポリラインを使用してルートを表現することができます。これは圧縮フォーマットの ASCII 文字によって、GPolyline 内に連続する点が指定されることで実現されます。エンコード化ポリラインによって、線のセグメントを描画するときに無視するズームレベルのグループを指定することもできます。これにより、特定のズームレベルにおけるポリラインの細密度を指定することができます。エンコード化ポリラインは、設定が難しくなりますが、オーバーレイの描画効率を向上することができます。

たとえば、3点 (2本の線セグメント) の GPolyline は通常次のように記述します。

var polyline = new GPolyline([
    new GLatLng(37.4419, -122.1419),
    new GLatLng(37.4519, -122.1519),
    new GLatLng( 37.4619, -122.1819)
], "#FF0000", 10);
map.addOverlay(polyline);

これらの同じ点をエンコードされた GPolyline で記述すると次のようになります (この時点では、エンコーディングアルゴリズムの内容について考慮しなくてもかまいません)。

var encodedPolyline = new GPolyline.fromEncoded({
    color: "#FF0000",
    weight: 10,
    points: "yzocFzynhVq}@n}@o}@nzD",
    levels: "BBB",
    zoomFactor: 32,
    numLevels: 4
});
map.addOverlay(encodedPolyline);

このコードについては2つの点を考慮する必要があります。

1. 1つは、基本的な GPolyline では使い慣れた経度と緯度が使用されていましたが、エンコード化ポリラインでは、一連の ASCII 文字で連続する点が表現されます。一連のエンコードされた ASCII 文字でこれらの点を作成するアルゴリズムについては、このドキュメントを参照してください。このアルゴリズムは、たとえば、サーバー処理でエンコード化ポリラインを直接計算したい場合などに必要になります。ただし、経度と緯度で指定された既存の地点を変換したいだけなら、対話型のユーティリティを使用することができます。
2. もう1つは、エンコード化ポリラインでは、Google マップに描画する最大ズームレベルを線セグメントごとに指定することができます。広域のズームレベルで特定の地点が表示されない場合、単純にその前の表示可能な地点から次の表示可能な地点までのルートで描画されます。この機能は、エンコードされていない GPolyline では利用できず、特に、一部の詳細な線セグメントが重要でない広域のズームレベルで、高速に描画する場合に有効です。たとえば、エンコードされていないポリラインがニューヨークからシカゴまでの運転ルートを表す場合、地図が州レベルまで広域の表示になったときに、マンハッタンの特定の街路を表す線セグメントを再現する必要はありません。

例を表示 (polyline-encoding.html)

対話型のエンコード化ポリラインユーティリティ

基になるエンコード化ポリラインアルゴリズムについては、ポリラインアルゴリズムに関するページを参照してください。

ポリゴン

GPolygon オブジェクトは、指定された順序の連続する点で形成されるという点で GPolyline オブジェクトと似ています。ただしポリゴンは、始点と終点が存在する線ではなく、閉じた境界線内の区域を定義するように設計されています。ポリラインと同様に、ポリゴンの辺 (「線」) にはカスタムカラー、重み (太さ)、および透明度を定義することができます。囲まれた区域内の塗りつぶす領域にはカスタムカラーと透明度を定義することができます。カラーは、HTML 方式の16進数値で表現します

GPolygon オブジェクトは、GPolyline オブジェクトと同様に、ブラウザのベクター描画機能が利用できる場合はこれを利用します。

次のコードスニペットは、4つの点が囲む領域に境界線が10ピクセル幅のボックスを作成します。ポリゴンは、セグメントのルートが始点へ戻ることで、閉じた領域になります。定義されていない動作を避けるために、ポリゴンは常に閉じた領域にする必要があります。

var map = new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(37.4419, -122.1419), 13);
map.addControl(new GSmallMapControl());
GEvent.addListener(map, 'click', function(overlay,point) {
  var latOffset = 0.01;
  var lonOffset = 0.01;
  var polygon = new GPolygon([
    new GLatLng(point.y, point.x - lonOffset),
  	new GLatLng(point.y + lonOffset, point.x),
  	new GLatLng(point.y, point.x + lonOffset),
  	new GLatLng(point.y - lonOffset, point.x),
  	new GLatLng(point.y, point.x - lonOffset)
  ], "#f33f00", 5, 1, "#ff0000", 0.2);
  map.addOverlay(polygon);
});

例を表示 (polygon-simple.html)

グラウンドオーバーレイ

ポリゴンは、任意のサイズの領域を表現するオーバーレイとしては便利ですが、画像を表示することができません。地図上に表示したい画像がある場合は、GGroundOverlay オブジェクトを使用します。GGroundOverlay のコンストラクタは、引数に画像の URL と、画像の GLatLngBounds を取ります。

次の例は、地図上にニュージャージー州ニューアークの古い地図を表示します。

var map = new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(40.740, -74.18), 12);
// グラウンドオーバーレイ
 
var boundaries = new GLatLngBounds(new GLatLng(40.716216,-74.213393), new GLatLng(40.765641,-74.139235));
var oldmap = new GGroundOverlay("http://www.lib.utexas.edu/maps/historical/newark_nj_1922.jpg", boundaries);
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.addOverlay(oldmap);

例を表示 (groundoverlay-simple.html)

タイルオーバーレイ

Google マップ API 内の地図は多数のタイルで構成されており、それぞれのズームレベルで地球の全表面がタイルで覆われています。タイルは、G_NORMAL_MAP、G_SATELLITE_MAP、G_HYBRID_MAP などの現在使用されているマップタイプごとに存在します。すべてのズームレベルのすべての区域にタイルが割り当てられているわけではありません。たとえば、太平洋の多くの領域では詳細のズームレベルは表示されません。

最も広域のズームレベル (レベル0) では、1つのタイルで地球全体が表示されます。

下位のズームレベルではそれぞれ、地図が4 N 個のタイルに分割されます。N はズームレベルを表します。たとえば、ズームレベル1では、Google マップが2×2のグリッドに分割され、合計で4つのタイルになります。ズームレベル3では、Google マップが4×4のグリッドに分割され16個のタイルに分割されます。

これらのタイルの表示を変更したい場合は、2種類の方法で変更できます。

• 独自のタイルオーバーレイを GTileLayerOverlay を使用して既存のマップタイプに実装します。
• 独自のカスタムマップタイプを GMapType を使用して実装します。

最初の方法は簡単ですが使用上の制限が多くなります。2番目の方法ではアプリケーション内での表示をより厳密に制御できます。それぞれの方法について以下で説明しますが、カスタムマップタイプの完全な実装方法の説明については、このドキュメントでは省略します。

それぞれの方法では、GTileOverlay インターフェイスから3つの抽象メソッドを実行する必要があります。

• getTileUrl() は、GPoint とズームレベルを渡すと、タイル画像を含む URL を地図に返します。
• isPng() は、画像が PNG ファイル (透明で表示可能) かどうかを示す Boolean を地図に返します。true の場合は、画像が PNG と見なされます。
• getOpacity() は、画像を表示する透明度のレベルを表す0.0～1.0の値を返します。

以降の2つのセクションではこれらの方法について説明します。

タイルレイヤオーバーレイ

オーバーレイを既存のマップタイプ上に表示したい場合は、GTileLayerOverlay オブジェクトを使用します。このオブジェクトを使うときには、GCopyrightCollection を作成して、タイルレイヤに追加し、画像 (複数可) の使用についての許可を示す必要があります。

次のコードは、単純な透明オーバーレイをすべてのズームレベルのタイルごとに表示し、フローティング状態の十字線で、タイルのアウトラインを表現します。

// 著作権情報を設定します
// 使用されている各画像では、著作権許可を表示する必要があります
var myCopyright = new GCopyrightCollection("© ");
myCopyright.addCopyright(new GCopyright('Demo',
  new GLatLngBounds(new GLatLng(-90,-180), new GLatLng(90,180)),
  0,'©2007 Google'));

// タイルレイヤ オーバーレイを作成し、 
// 3つの抽象メソッドを実装します   		
var tilelayer = new GTileLayer(myCopyright);
tilelayer.getTileUrl = function() { return "../include/tile_crosshairs.png"; };
tilelayer.isPng = function() { return true;};
tilelayer.getOpacity = function() { return 1.0; }

var myTileLayer = new GTileLayerOverlay(tilelayer);
var map = new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(37.4419, -122.1419), 13);
map.addOverlay(myTileLayer);

例を表示 (tileoverlay-simple.html)

カスタムマップタイプ

注: このトピックは高度な内容になります

GTileLayerOverlay に限界がある場合は、独自のカスタムマップを作成して、まったく新しい表示方式を確立することができます。これには、GMapType オブジェクトを構造化し、GMap2.addMapType() メソッドを使用して地図に追加します。

なにもない状態からマップタイプを作成するのは複雑な作業です。動的なデータを定義および取得して、指定された現在の地図の座標に表示する方法を確立する必要があり、タイル画像を参照および表示する方法を独自に決定する必要があります。これらをどのように決定するかは自由ですが、参考までに Google マップでのタイルの参照方法を説明します。

Google マップ座標

Google マップ API では、3つの座標系が使用されています。

• 画像タイル上の地点を参照するピクセル座標
• タイルレイヤ内のタイルを参照するタイル座標
• タイルの合計数を定義するズームレイヤ

それぞれの座標系について以下で説明します。

ピクセル座標

Google マップ内の各タイルは256×256ピクセルで構成されています。したがって、特定のタイル上の地点は、GPoint で一対の x、y を使用して参照できます。各タイルの原点 (0,0) はタイルの北西の角を表します。地球全体を表す1つのタイルの場合、原点は、アラスカが表示されている、北極点の経度 -180度になるように設定されています。南東の地点 (255,255) まで、x (経度) の値は東に向かって増え、y (緯度) の値は南に向かって増えます。

詳細なズームレベルでは、ピクセル空間が x と y の両方の方向で倍になります。たとえば、ズームレベル1は、地図が256×256ピクセルのタイル4個から成り、ピクセル空間は512×512になります。ズームレベル19では、地図上の各 x と y のピクセルは0～256×219の値を使って参照できます。

タイル座標

地図全体の地点を一意に参照することができない場合も多くあります。詳細のズームレベルでは、Google マップ API は、地図全体を表示するのに1つの画像ファイルを使用することはできません。このため、現在使用されている画像を判定して、そのタイルの原点からの相対的なピクセル座標を計算する方法が有効です。実装するカスタムマップには、これと同じ評価を実施する必要があります。

Google マップのタイルは、ピクセルの原点と同じ原点から番号が付けられ、原点のタイルは、常に地図の北西の角になります。タイルには、原点からの x,y 座標を使用してインデックスが付けられます。たとえば、ズームレベル2では、地球が16タイルに分割され、各タイルを固有の x,y の対で参照できます。

特定のズームレベルの特定の地点にインデックスを作成することにより、2つの GPoint 値を使用できます。1つは使用中のタイルを参照するためのもので、もう1つは、タイル内の256×256画像でのピクセル座標を参照するためのものです。

タイルオーバーレイを実装するには、提供するタイル画像の決定ロジックを追加する必要があり、いくつかの単純なズームレベルを除いて面倒な作業になります。Google マップ API では、GTileLayerOptions 引数をオブジェクトリテラルとして渡す GTileLayer の構造化が可能です。GTileLayerOptions 引数は、tileUrlTemplate プロパティを含みます。このプロパティによって、要求がタイル座標に基づいて URL にマッピングされます。オーバーレイのコンストラクタは、次のようになります。

var tileLayerOverlay = new GTileLayerOverlay(
  new GTileLayer(null, null, null, {
    tileUrlTemplate: 'http://domain.com/myimage_{Z}_{X}_{Y}.png', 
    isPng:true,
    opacity:1.0
  })
);

map.addOverlay(tlo); 

このテンプレートによって、Google マップ内の処理と同じようにタイル座標で指定された画像の集合を処理できます。

著作権情報の処理

地図には、通常、購入した画像、生成した画像、または外部機関からライセンス許諾を受けた画像があります。これらの画像は多くの場合、著作権情報を表示する必要があり、航空写真などの特定のデータに関しては地図上の場所に応じて異なる提供者からデータを取得している場合もあります。動的に著作権情報をカスタムマップタイプ上に表示する機能を提供するために、マップ API には、著作権情報を保持するいくつかのオブジェクトがあります。また、現在のビューポイントとズームレベルに従って、著作権情報を取得するメソッドとインターフェイスも提供されています。

著作権オブジェクト

GCopyright オブジェクトは、基本的な著作権情報を保持する単純なオブジェクトです。このオブジェクトの minZoom と bounds プロパティには、この著作権情報の対象を限定する制約を定義します。text はその条件のもとで表示する著作権表記のテキストを格納します。

一連の GCopyright オブジェクトは、GCopyrightCollection に収集されます。GCopyrightCollection コンストラクタは、すべての著作権表記に付加するテキストプレフィックス (「Imagery © 2007」など) を定義するために使用します。著作権を、コンストラクタ内の GCopyrightCollection に直接追加することはできません。コレクションを構造化した後に、addCopyright メソッドを呼び出して、個々の GCopyright オブジェクトに追加する必要があります。

GTileLayer インターフェイスは、コンストラクタの copyrights 引数を要求します。これらのタイルレイヤを処理するクラス (GTileLayerOverlay や GMapType) では、GCopyrightCollection オブジェクトを作成してから、そのオブジェクトをタイルレイヤのコンストラクタに渡す必要があります。

Google マップ API によって、著作権情報を表示する次のメソッドが実装されます。これらには、カスタム動作を指定して強制できます。

• GMapType.getCopyrights() は、下位のすべてタイルレイヤに対して GTileLayer.getCopyright() を呼び出します。
• 各 GTileLayer.getCopyright() は、著作権のコレクションに対して GCopyrightCollection.getCopyrightNotice() を呼び出します。
• GCopyrightCollection.getCopyrightNotice() は、著作権表記をこのオブジェクトに添付して返し、指定された bounds と zoom が、子の各 GCopyright オブジェクトに適用されているかどうかをチェックします。

これらのメソッドにはそれぞれ、bounds と zoom パラメータが含まれており、表示する著作権情報の決定を強制および検証することができます。

デフォルトでは、Google マップ API が、マップタイプ内のタイルレイヤを表示するたびに、GTileLayer.getCopyright() メソッド経由で、現在使用中の著作権を取得します。マップタイプによっては、複数のタイルレイヤを含んでいる場合があり、複数の GCopyrightCollection オブジェクトの情報を同時に表示することが必要であることを意味しています (たとえば、G_HYBRID_MAP マップタイプは、航空写真レイヤと地図レイヤの両方を実装します)。この結合された情報は、複数の著作権コレクションからの連結された著作権記述によって表示されます。

投影座標を変換

地球は球体ですが、地図は平面の2次元のオブジェクトです。Google マップ API 内に表示される地図は、球を平面に投影したものです。Google マップ API における投影は、GProjection インターフェイスによって実装されています。現在、GMercatorProjection の1つの投影だけが Google マップ API に実装されています。簡単に言うと、投影は、GLatLng の値を地図上の座標に一対一の対応で定義できます。GProjection インターフェイスは、この目的の変換機能を提供します。

GProjection.fromLatLngToPixel() メソッドは、GLatLng の値を特定のズームレベルのピクセル座標に変換します。同様に、GProjection.fromPixelToLatLng() メソッドは、特定のズームレベルのピクセル座標を GLatLng の値に変換します。これらのメソッドは、マップタイプを実装するときに便利です。表示するタイルの決定や、表示方法、表示するときのオフセットなどを決定できます。

次の例は、現在のズームレベルのピクセル座標を計算し、その場所のピクセル座標とタイル座標の両方を返すことで、クリックイベントを処理します。

例を表示 (tile-detector.html)

マップタイプの実装方法の詳細については、GMapType のリファレンスを参照してください。

カスタムオーバーレイ

Google マップ API は、GOverlay インターフェイスを実装することによって、カスタムオーバーレイオブジェクトを作成するために使用することもできます。Google マップ API は、GOverlay インターフェイスの実装により、GTrafficOverlay や GGeoXml オブジェクトなどのいくつかのサービスを提供します (これらのサービスは、サービスのセクションで説明されています)。

GOverlay インターフェイスには、次の4つの抽象メソッドを実装する必要があります。

• initialize() は、GMap2.addOverlay() への応答で呼び出されます
• remove() は、GMap2.removeOverlay() への応答で呼び出されます
• copy() は新しいオーバーレイのテンプレートの作成に使用します
• redraw() は、地図内での表示変更への応答で呼び出されます

Google マップ API インターフェイスは、継承したオブジェクトに prototype プロパティを代入することで JavaScript 内に実装します。たとえば、次のコードで Rectangle オブジェクトを GOverlay インターフェイスから継承します。

OverlaySubclass.prototype = new GOverlay();

GOverlay インターフェイスの抽象メソッドは、オブジェクトの prototype にこれらのメソッドを代入することで実装できます。

OverlaySubclass.prototype.initialize = myInitializeMethod;
OverlaySubclass.prototype.remove = myRemoveMethod;
OverlaySubclass.prototype.copy = myCopyMethod;
OverlaySubclass.prototype.redraw = myRedrawMethod;

次の例では、地図上の特定の区域を囲む Rectangle オーバーレイを作成します。Rectangle クラスは、GOverlay インターフェイスの4つの必須メソッドを定義します。特に、initialize() メソッドはオーバーレイを表す DOM 要素を作成し、redraw() メソッドは、現在の投影とズームレベルを基に地図上のオーバーレイの位置とサイズを指定します。

オーバーレイを形成する各 DOM 要素はマップペイン上に存在し、z 軸での描画順序を定義します。たとえば、ポリラインは地図に対して水平なので、最下層の G_MAP_MAP_PANE に描画されます。マーカーの影の要素は G_MAP_MARKER_SHADOW_PANE に配置され、前面の要素は G_MAP_MARKER_PANE に配置されます。オーバーレイ要素を正しいペインに配置することで、ポリラインをマーカーの影の下に描画し、情報ウィンドウを地図上の他のオーバーレイよりも上に描画します。この例では、オーバーレイは地図に対して水平なので、GPolyline と同じように、z 軸での最下層のペイン G_MAP_MAP_PANE に追加します。マップペインの完全なリストについては、クラスのリファレンスを参照してください。

// 四角形は、地図上の緯度と経度の境界を示す簡単なオーバーレイ
// です。境界線に重み (太さ) と色を指定でき、オプションで
// 半透明の背景色を指定できます。
function Rectangle(bounds, opt_weight, opt_color) {
  this.bounds_ = bounds;
  this.weight_ = opt_weight || 2;
  this.color_ = opt_color || "#888888";
}
Rectangle.prototype = new GOverlay();

// 四角形を表す DIV を作成します。
Rectangle.prototype.initialize = function(map) {
// 四角形を表す DIV を作成します。
  var div = document.createElement("div");
  div.style.border = this.weight_ + "px solid " + this.color_;
  div.style.position = "absolute";

// 四角形は地図に対して水平なので、その四角形自体を
// MAP_PANE ペインに追加します。これは、地図自体と同じ z 軸のインデックスになります 
// (つまりマーカーの影よりも下になります)
  map.getPane(G_MAP_MAP_PANE).appendChild(div);

  this.map_ = map;
  this.div_ = div;
}

// 地図のペインから DIV を削除します
Rectangle.prototype.remove = function() {
  this.div_.parentNode.removeChild(this.div_);
}

// データを新しい Rectangle にコピーします
Rectangle.prototype.copy = function() {
  return new Rectangle(this.bounds_, this.weight_, this.color_,
                       this.backgroundColor_, this.opacity_);
}

// 四角形を現在の投影とズームレベルを基に再描画します
Rectangle.prototype.redraw = function(force) {
  // We only need to redraw if the coordinate system has changed
  if (!force) return;

// 境界の2つの相対する角の DIV 座標を計算し
// 四角形のサイズと位置を算出します
  var c1 = this.map_.fromLatLngToDivPixel(this.bounds_.getSouthWest());
  var c2 = this.map_.fromLatLngToDivPixel(this.bounds_.getNorthEast());

// ここで境界の DIV 座標を基に DIV の位置を決定します
  this.div_.style.width = Math.abs(c2.x - c1.x) + "px";
  this.div_.style.height = Math.abs(c2.y - c1.y) + "px";
  this.div_.style.left = (Math.min(c2.x, c1.x) - this.weight_) + "px";
  this.div_.style.top = (Math.min(c2.y, c1.y) - this.weight_) + "px";
}

var map = new GMap2(document.getElementById("map"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.setCenter(new GLatLng(37.4419, -122.1419), 13);

// 地図の中央に、地図の1/4のサイズの
// 四角形を表示します
var bounds = map.getBounds();
var southWest = bounds.getSouthWest();
var northEast = bounds.getNorthEast();
var lngDelta = (northEast.lng() - southWest.lng()) / 4;
var latDelta = (northEast.lat() - southWest.lat()) / 4;
var rectBounds = new GLatLngBounds(
    new GLatLng(southWest.lat() + latDelta, southWest.lng() + lngDelta),
    new GLatLng(northEast.lat() - latDelta, northEast.lng() - lngDelta));
map.addOverlay(new Rectangle(rectBounds));

例を表示 (overlay-custom.html)