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

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

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

• 地図上の地点は、マーカーを使用して表示されます。この地点には多くの場合カスタムアイコンが表示されます。マーカーはタイプ GMarker のオブジェクトで、GIcon タイプを使用することもあります。
• 地図上の線はポリラインを使用して表示されます (点の集合で表現されます)。線は、タイプ GPolyline のオブジェクトです。
• 地図上の領域は、領域の形状が不特定の場合にはポリゴンで表示され、画像の場合にはグラウンド オーバーレイで表示されます。ポリゴンは、閉じた境界線で囲まれた点の集合で形成され、任意の形状を表現できるという点でポリラインと似ています。グラウンド オーバーレイは一般に、地図の前面に画像を重ねて配置するのに便利です (特定の GLatLngBounds にまたがって)。
• 地図自体は、タイル オーバーレイで表示されます。GTileLayerOverlay を使用して、独自の一連のタイルを追加できます。
• 情報ウィンドウも特殊な種類のオーバーレイです。ただし、情報ウィンドウは自動的に地図に追加され、地図に添付できるのはタイプ GInfoWindow のオブジェクト 1 つだけです。

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

マーカー

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

マーカーはユーザーが操作できるように設計されています。デフォルトでは、"click" イベントなどを取得します。また、イベント リスナで情報ウィンドウを表示するためによく使用されます。

次の例では 10 個のマーカーをランダムな位置に表示します。

var map = new GMap2();

map.getBoundsAsync(function(bounds) {
  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.xml)

ドラッグ可能マーカー

マーカーは、クリックして別の場所にドラッグできる、操作可能なオブジェクトです。この例では、地図上にドラッグ可能なマーカーを配置して、いくつかの単純なイベントの発生を待機します。ドラッグ可能マーカーは、ドラッグのステータスを示す click、dragstart、dragend の数種類のイベントを実装します（マプレット キューが大量のイベント要求であふれることを防ぐため、Maps API の場合とは異なりドラッグ時に drag イベントを生成しません）。デフォルトでは、マーカーはクリック可能ですがドラッグできないため、true に設定された追加のマーカーオプション draggable を使用して初期化される必要があります。ドラッグ可能マーカーはデフォルトでバウンドします。この動作が必要ない場合は、bouncy オプションを false に設定します。これにより、マーカーをドラッグしてドロップしたときにバウンドしなくなります。

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

var marker = new GMarker(center, {draggable: true, bouncy: true});
map.addOverlay(marker);

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

GEvent.addListener(marker, "dragend", function() {
  marker.openInfoWindowHtml("Just bouncing along...");
});

この例を実行する (marker-drag.xml)

アイコン

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

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

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

var map = new GMap2();
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.xml)

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

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

var map = new GMap2();

// 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);

// Add 10 markers to the map at random locations
map.getBoundsAsync(function(bounds) {
  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, {icon:tinyIcon}));
  }
});

この例を実行する (icon-complex.xml)

カスタム アイコン

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

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

var map = new GMap2();

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

// 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 letterIcon = new GIcon(baseIcon);
  letterIcon.image = "http://www.google.com/mapfiles/marker" + letter + ".png";
  return new GMarker(point, {icon:letterIcon});
}

// Add markers A - J to the map at random locations
map.getBoundsAsync(function(bounds) {
  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.xml)

ポリライン

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

ポリラインを描画

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

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

次の例では 5 個のランダムな点を結ぶポリラインを表示します。このポリラインは赤色で、太さは 5 ピクセルで、透明度は 70% です。

var map = new GMap2();

map.getBoundsAsync(function(bounds) {
  var southWest = bounds.getSouthWest();
  var northEast = bounds.getNorthEast();
  var lngSpan = northEast.lng() - southWest.lng();
  var latSpan = northEast.lat() - southWest.lat();

  var points = [];
  for (var i = 0; i < 5; i++) {
    points.push(new GLatLng(southWest.lat() + latSpan * Math.random(),
                            southWest.lng() + lngSpan * Math.random()));
  }

  map.addOverlay(new GPolyline(points, "#ff0000", 5, 0.7));
});

この例を実行する (polyline-simple.xm)

測地線ポリライン

地図上で表現されるポリラインは、現在の投影図法に従った直線です。このため、地図上に直線的に表示されますが、実際には地球の湾曲を適切に反映していないことがあります。代わりに測地線 (地球表面の 2 点間の最短距離を表す「大圏」の一部) を描画するには、GPolyline の GPolylineOptions 引数に geodesic:true を渡す必要があります。

GPolylineOptions オブジェクトは、オブジェクト リテラルの例です。オブジェクト リテラルを使用する場合、オブジェクトを構築 (コンストラクタを使用) する必要はありません。代わりに、名前/値ペア (複数可) を波かっこで囲んだ引数を渡します。オブジェクト リテラルは、オブジェクトのインスタンス化が必要ない場合に多く使用されます。

var map = new GMap2();
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.xml)

ポリゴン

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

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

次の例では 3 個のランダムな頂点を結ぶポリゴンを表示します。この輪郭線は赤色で、太さは 5 ピクセルで、透明度は 70% です。このポリゴンは透明度が 40% の青色で塗りつぶされています。

var map = new GMap2();

map.getBoundsAsync(function(bounds) {
  var southWest = bounds.getSouthWest();
  var northEast = bounds.getNorthEast();
  var lngSpan = northEast.lng() - southWest.lng();
  var latSpan = northEast.lat() - southWest.lat();

  var points = [];
  for (var i = 0; i < 3; i++) {
    points.push(new GLatLng(southWest.lat() + latSpan * Math.random(),
                            southWest.lng() + lngSpan * Math.random()));
  }
  points.push(points[0]);   // Close the polygon

  map.addOverlay(new GPolygon(points, "#ff0000", 5, 0.7, "#0000ff", 0.4));
});

この例を実行する (polygon-simple.xml)

グラウンド オーバーレイ

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

次の例では、地図上にニュージャージー州ニューアークの古い地図をオーバーレイとして表示します。

var map = new GMap2();
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.addOverlay(oldmap);

この例を実行する (groundoverlay-simple.xml)

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

マプレットは、メイン地図上に独自のカスタム タイルを表示することもあります。その画像が単一の画像である場合はグラウンド オーバーレイを使用しますが、多くの画像を別々のズーム レベルで表示する場合もあります。その場合は、Google マップ上でメイン地図のタイルが表示される方法とよく似たタイル レイヤー オーバーレイを使用できます。

適切な一連のタイル レイヤー オーバーレイを作成するには、これらを表示するズーム レベルごとに一連のタイルを作成し、その後、現在のビューポートに基づいてこれらを整理して表示するための方式を定義する必要があります。このような方式を作成するには、Google マップ座標について理解する必要があります。Google マップ座標に関する知識がない場合は、先に進む前にこのセクションを参照してください。

タイル オーバーレイを実装するには、提供するタイル画像の決定ロジックを追加する必要があり、いくつかの単純なズーム レベルを除いて面倒な作業になります。マプレットはテンプレート システムに基づいて GTileLayer を構築し、テンプレートに引数をオブジェクト リテラルとして渡すための方法を提供しています。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(tileLayerOverlay); 

このテンプレート方式を使用すると、Google マップ内で行われるのと同じように、タイル座標を使用して名前が付けられたタイル画像の集合の場所を指定できます。

Mapplet サービスに続きます。