マップ オーバーレイ

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

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

Maps 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);
 
// Add 10 markers to the map at random locations
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 種類のイベントを実装します。デフォルトでは、マーカーはクリック可能ですがドラッグできないため、true に設定された追加のマーカー オプション draggable を使用して初期化する必要があります。ドラッグ可能マーカーはデフォルトでバウンドします。この動作が必要ない場合は、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("Just bouncing along...");
  });

map.addOverlay(marker);

例を表示 (marker-drag.html)

アイコン

マーカーでは、デフォルト アイコンの代わりに表示するアイコンを定義できます。Maps API では、1 つのアイコンは複数の画像で構成されているため、アイコンを定義するのは単純ではありません。最低でも、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);

// Create our "tiny" marker icon
var blueIcon = new GIcon(G_DEFAULT_ICON);
blueIcon.image = "http://www.google.com/intl/en_us/mapfiles/ms/micons/blue-dot.png";
		
// Set up our GMarkerOptions object
markerOptions = { icon:blueIcon };

// Add 10 markers to the map at random locations
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);

// Create our "tiny" marker icon
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);

// Set up our GMarkerOptions object literal
markerOptions = { icon:tinyIcon };

// Add 10 markers to the map at random locations
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);

// Create a base icon for all of our markers that specifies the
// shadow, icon dimensions, etc.
var baseIcon = new GIcon(G_DEFAULT_ICON);
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);

// Creates a marker whose info window displays the letter corresponding
// to the given index.
function createMarker(point, index) {
  // Create a lettered icon for this point using our icon class
  var letter = String.fromCharCode("A".charCodeAt(0) + index);
  var letteredIcon = new GIcon(baseIcon);
  letteredIcon.image = "http://www.google.com/mapfiles/marker" + letter + ".png";

  // Set up our GMarkerOptions object
  markerOptions = { icon:letteredIcon };
  var marker = new GMarker(point, markerOptions);

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

// Add 10 markers to the map at random locations
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 Maps 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 個の天気アイコンが表示されます。レベル 6 では、人口 30 万人を超える 200 都市が容易に区別でき、さらに 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 進数値で表現します。たとえば、#ff0000 ではなく red を使用します。GPolyline は色の名前を認識しません。

GPolyline オブジェクトは、ブラウザのベクター描画機能が利用できる場合はこれを利用します。Internet Explorer の場合、Google マップは 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);

// Create GPolylineOptions argument as an object literal.
// Note that we don't use a constructor.

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 Maps 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, latlng) {
  var lat = latlng.lat();
  var lon = latlng.lng();
  var latOffset = 0.01;
  var lonOffset = 0.01;
  var polygon = new GPolygon([
    new GLatLng(lat, lon - lonOffset),
    new GLatLng(lat + latOffset, lon),
    new GLatLng(lat, lon + lonOffset),
    new GLatLng(lat - latOffset, lon),
    new GLatLng(lat, lon - 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);
// ground overlay
 
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 Maps API 内の地図は多数のタイルで構成されており、それぞれのズーム レベルで地球の全表面をタイルで覆っています。タイルは G_NORMAL_MAP、G_SATELLITE_MAP、G_HYBRID_MAP、G_PHYSICAL_MAP など、使用されているマップ タイプごとに存在します。すべての区域のすべてのズーム レベルにタイルが割り当てられているわけではありません。たとえば、太平洋の多くの領域は詳細のズーム レベルでは表示されません。

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

下位のズーム レベルではそれぞれ、地図が 4 N 個のタイルに分割されます。N はズーム レベルを表します。たとえば、ズーム レベル 1 では、Google マップが 2×2 のグリッドに分割され、合計で 4 個のタイルになります。ズーム レベル 2 では、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 を作成してタイル レイヤーに追加し、画像（複数可）の使用についての許可を示す必要があります。

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

// Set up the copyright information
// Each image used should indicate its copyright permissions
var myCopyright = new GCopyrightCollection("© ");
myCopyright.addCopyright(new GCopyright('Demo',
  new GLatLngBounds(new GLatLng(-90,-180), new GLatLng(90,180)),
  0,'©2007 Google'));

// Create the tile layer overlay and 
// implement the three abstract methods   		
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 Maps API では、3 つの座標系が使用されています。

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

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

ピクセル座標

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

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

タイル座標

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

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

したがって、特定のズーム レベルで特定の地点をインデックス付けするには 2 つの GPoint 値を使用します。1 つの値は使用中のタイルを参照し、もう 1 つの値は 256×256 の画像のタイルのピクセル内の座標を参照します。

タイル オーバーレイを実装するには、提供するタイル画像の決定ロジックを追加する必要があり、いくつかの単純なズーム レベルを除いて面倒な作業になります。Google Maps API では、GTileLayer 引数をオブジェクト リテラルとして渡す GTileLayerOptions の構築が可能です。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 マップ内で行われるのと同じように、タイル座標を使用して名前が付けられたタイル画像の集合の場所を指定できます。

著作権情報の処理

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

著作権オブジェクト

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

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

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

Google Maps API は著作権情報を表示する次のメソッドを実装します。これらのメソッドはカスタム動作を行うために無効化することも可能です。

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

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

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

投影座標を変換

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

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

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

例を表示 (tile-detector.html)

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

レイヤー

GLayer オブジェクトはサードパーティの地理情報を格納するオーバーレイ オブジェクトです。「レイヤー」は地理に関連した機能のセットで、いくつかの機能を共有し地図上ではグループとして表示されます。Google はこれらのセットを他のソースからデータを取得して提供し、1 つのレイヤーにまとめます。

マーカー、ポリライン、ポリゴンなど、通常、レイヤーにはさまざまなアイテムが含まれますが、これらは個別のオブジェクトとして見なされていません。レイヤー自体（およびその構成要素すべて）が Maps API の 1 つのオーバーレイと見なされ、標準的な addOverlay() メソッドを使用して地図に追加されます。レイヤーは操作可能で、たとえば情報ウィンドウを立ち上げるといった処理を構成要素にすることができます。

各レイヤーには一意の名前空間 ID があるため、容易に参照したり一意的に特定することができます。この名前空間 ID は現時点では、ソース レイヤーのドメインに基づいています。たとえば英語版の Geotagged Wikipedia © Articles のレイヤーには「org.wikipedia.en」という名前空間 ID があります。

Google Maps API は現在、これらの公開レイヤーにアクセスできます。Maps API には新しいレイヤーが定期的に追加されます。アクセスできるレイヤーのリストはこのスプレッド シートで管理しています。

次のコード スニペットはニューヨーク シティのグリニッジビレッジに英語版 Wikipedia レイヤーを追加します。

function initialize() {
  if (GBrowserIsCompatible()) {
    var map = new GMap2(document.getElementById("map_canvas"));
    map.setCenter(new GLatLng(40.730885,-73.997383), 15);
    var myLayer = new GLayer("org.wikipedia.en");
    map.addOverlay(myLayer);
  }
}

例を表示 (layer-simple.html)

カスタム オーバーレイ

Google Maps API は GOverlay インターフェースを実装しているので、カスタム オーバーレイ オブジェクトを作成することもできます。Google Maps API は GOverlay インターフェースを実装することで、GTrafficOverlay、GGeoXml、GStreetviewPanorama などのサービスの提供が可能になっています (これらのサービスの説明は、サービスのセクションをご覧ください)。

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

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

Google Maps 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 つの必須メソッドを定義します。具体的には、オーバーレイを表す DOM 要素を作成する initialize() メソッドと現在の投影とズーム レベルに基づいて地図上のオーバーレイの位置とサイズを指定しする redraw() メソッドを記録します。

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

// A Rectangle is a simple overlay that outlines a lat/lng bounds on the
// map. It has a border of the given weight and color and can optionally
// have a semi-transparent background color.
function Rectangle(bounds, opt_weight, opt_color) {
  this.bounds_ = bounds;
  this.weight_ = opt_weight || 2;
  this.color_ = opt_color || "#888888";
}
Rectangle.prototype = new GOverlay();

// Creates the DIV representing this rectangle.
Rectangle.prototype.initialize = function(map) {
  // Create the DIV representing our rectangle
  var div = document.createElement("div");
  div.style.border = this.weight_ + "px solid " + this.color_;
  div.style.position = "absolute";

  // Our rectangle is flat against the map, so we add our selves to the
  // MAP_PANE pane, which is at the same z-index as the map itself (i.e.,
  // below the marker shadows)
  map.getPane(G_MAP_MAP_PANE).appendChild(div);

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

// Remove the main DIV from the map pane
Rectangle.prototype.remove = function() {
  this.div_.parentNode.removeChild(this.div_);
}

// Copy our data to a new Rectangle
Rectangle.prototype.copy = function() {
  return new Rectangle(this.bounds_, this.weight_, this.color_,
                       this.backgroundColor_, this.opacity_);
}

// Redraw the rectangle based on the current projection and zoom level
Rectangle.prototype.redraw = function(force) {
  // We only need to redraw if the coordinate system has changed
  if (!force) return;

  // Calculate the DIV coordinates of two opposite corners of our bounds to
  // get the size and position of our rectangle
  var c1 = this.map_.fromLatLngToDivPixel(this.bounds_.getSouthWest());
  var c2 = this.map_.fromLatLngToDivPixel(this.bounds_.getNorthEast());

  // Now position our DIV based on the DIV coordinates of our bounds
  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);

// Display a rectangle in the center of the map at about a quarter of
// the size of the main map
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)