2 - ol3ex 31b - KML example 2

「kml.js（231-ol3ex.js）」は、マップを表示するための JavaScript ファイルです。

KML（Keyhole Markup Language） は、Google が開発しました。OGC と Google は、OGC 標準規格に沿うように作業が進められています。
「Open Geospatial Consortium（http://www.opengeospatial.org/）」の「KML（http://www.opengeospatial.org/standards/kml）」に次のようにあります。

*****
1) Overview の一部を抜粋

KML is an XML language focused on geographic visualization, including annotation of maps and images. Geographic visualization includes not only the presentation of graphical data on the globe, but also the control of the user's navigation in the sense of where to go and where to look.
KMLは、地図や画像の注釈を含む地理的可視化に焦点を当てたXML言語です。地理的可視化は、地球上のグラフィカルなデータの提示だけでなく、どこに行きどこを見るというユーザのナビゲーションの制御を含んでいます。

From this perspective, KML is complementary to most of the key existing OGC standards including GML (Geography Markup Language), WFS (Web Feature Service) and WMS (Web Map Service). Currently, KML 2.2 utilizes certain geometry elements derived from GML 2.1.2. These elements include point, line string, linear ring, and polygon.
このような観点から、KML は GML（Geography Markup Language）とWFS（Web Feature Service）、WMS（Web Map Service）を含む主要な既存のOGC 標準規格のほとんどに相補います。現在、KML2.2 が GML2.1.2 に由来し、特定のジオメトリ要素を利用しています。これらの要素は、ポイント、ラインストリング、リニアリング、およびポリゴンが含まれます。
*****

2012-02-10.kml の内容は、次のようになっています。

「2012-02-10.kml」

<kml>
 <Document>
  <name>Skimap.org OpenSkiMap </name>
  <description>Created from OpenStreetMap data. Renderer v0.5</description>

  <!-- 
Copyright (c) OpenStreetMap Contributors
http://www.openstreetmap.org/

This work is licensed under the
Creative Commons Attribution-ShareAlike 2.0 License.
http://creativecommons.org/licenses/by-sa/2.0/
 -->

  <ScreenOverlay id="CopyrightNotice">
   <name>Copyright Notice</name>
   <description>
    <![CDATA[The data in this KML file is Copyright <a href="http://www.openstreetmap.org/">OpenStreetMap</a> Contributors. It is available under the <a href="http://creativecommons.org/licenses/by-sa/2.0/">Creative Commons Attribution-ShareAlike (CC-BY-SA) Version 2.0 License</a>.]]>
   </description>
   <Snippet>Copyright (c) OpenStreetMap Contributors. CC-BY-SA 2.0 License.</Snippet>
   <Icon>
    <href>OSMCopyright.png</href>
   </Icon>
   <overlayXY x="0" xunits="fraction" y="1" yunits="fraction"/>
   <screenXY x="0" xunits="fraction" y="1" yunits="fraction"/>
   <size x="0" xunits="fraction" y="0" yunits="fraction"/>
  </ScreenOverlay>

  <Folder>
   <name>POI</name>
   <description>Points of Interest</description>
  <Folder>

  <name>Parking</name>
  <Style id="style-Parking">
   <IconStyle>
    <scale>0.2</scale>
    <Icon>
     <href>http://maps.google.com/mapfiles/kml/shapes/parking_lot.png</href>
    </Icon>
   </IconStyle>
  </Style>
  <Placemark>
   <styleUrl>#style-Parking</styleUrl>
   <Point>
    <coordinates>7.5584046,46.4880564,0</coordinates>
   </Point>
  </Placemark>
  <Placemark>

   <name>Coop</name>

---

「231-ol3ex.js」

var projection = ol.proj.get('EPSG:3857');
// EPSG:900913 -> EPSG:3857 コード名変更（内容は同じ）
/** ol.proj.get(projectionLike)
 * Fetches a Projection object for the code specified.
 * 指定されたコードのプロジェクション·オブジェクトを取得
 * （ol3 API）
 */

var raster = new ol.layer.Tile({
/** ol.layer.Tile 
 * For layer sources that provide pre-rendered, tiled 
 * images in grids that are organized by zoom levels for 
 * specific resolutions. 
 * プリレンダリング（事前描画）を提供するレイヤソースのための、
 * 特定の解像度でのズームレベルによって編成されているグリッドの
 * タイルイメージ。（ol3 API）
 */
 source: new ol.source.BingMaps({
 /** ol.source.BingMaps
  * Layer source for Bing Maps tile data.
  * Bing Maps タイルデータのレイヤソース。（ol3 API）
  */
  imagerySet: 'Aerial',
  key: 'Ak-dzM...（省略）'
 })
});

var vector = new ol.layer.Vector({
/** ol.layer.Vector
 * Vector data that is rendered client-side.
 * クライアント側で描画されるベクタデータ。（ol3 API）
 */

 source: new ol.source.KML({
 /** ol.source.KML 
  * Static vector source in KML format
  * KML フォーマットの静的ベクタソース（0l3 API）
  */

  projection: projection,
  // url: 'data/kml/2012-02-10.kml'
  url: 'v3.0.0/examples/data/kml/2012-02-10.kml' // 修正
 })
});

var map = new ol.Map({
 layers: [raster, vector],
 target: document.getElementById('map'),
 view: new ol.View({
  center: [876970.8463461736, 5859807.853963373],
  projection: projection,
  zoom: 10
 })
});

var displayFeatureInfo = function(pixel) {
 var features = [];

 map.forEachFeatureAtPixel(pixel, function(feature, layer) {
 /** forEachFeatureAtPixel
  * Detect features that intersect a pixel on the viewport, 
  * and execute a callback with each intersecting feature. 
  * Layers included in the detection can be configured 
  * through opt_layerFilter. Feature overlays will always 
  * be included in the detection.
  * ビューポート上のピクセルと交差する特徴を検出し、
  * 各交差するフィーチャとコールバックを実行します。
  * 検出に含まれるレイヤが opt_layerFilter を通じて
  * 設定することができます。フィーチャーオーバーレイは
  * 常に検出に含まれます。（ol3 API）
  */

  features.push(feature);
  /** push(elem)
   * Insert the provided element at the end of the 
   * collection.
   * コレクションの最後に供給されたエレメントに挿入します。
   * Name: elem, Type: T, Description: Element
   * （ol3 API）
   */

 });
 if (features.length > 0) {
  var info = [];
  var i, ii;
  for (i = 0, ii = features.length; i < ii; ++i) {
   info.push(features[i].get('name'));
   /** get(key)
    * Gets a value.
    * （ol3 API[説明は Stable Only のチェックを外すと表示]）
    */
   /** Array.push
    * 与えられた要素を追加することによって配列を変異させ、
    * （MDN [https://developer.mozilla.org/ja/docs/Web/
    * JavaScript/Reference/Global_Objects/Array/push]）
    */
  }

  document.getElementById('info').innerHTML = info.join(', ') || '(unknown)';
  /** Array.join
   * 配列の全ての要素を繋いで文字列にします。
   * （MDN [https://developer.mozilla.org/ja/docs/Web/
   * JavaScript/Reference/Global_Objects/Array/join]）
   */

  map.getTarget().style.cursor = 'pointer';
  /** getTarget()
   * Get the target in which this map is rendered. 
   * Note that this returns what is entered as an option or  
   * in setTarget: if that was an element, it returns an 
   * element; if a string, it returns that.
   * レンダリングされたこのマップのターゲットを取得します。
   * これはオプションとして、または setTarget に入力されている
   * ものを返すことに注意してください：それが要素ならば、要素を
   * 返します。文字列ならば、それを返します。（ol3 API）
   */

 } else {
  document.getElementById('info').innerHTML = ' ';
  map.getTarget().style.cursor = '';
 }
};

$(map.getViewport()).on('mousemove', function(evt) {
/** getViewport()
 * Return: Viewport （ol3 API）
 */
/** jQuery on イベント */

 var pixel = map.getEventPixel(evt.originalEvent);
 /** getEventPixel
  * Returns the map pixel position for a browser event.
  * ブラウザイベントに対して、マップのピクセル位置を返します。
  * （ol3 API）
  */

 displayFeatureInfo(pixel);
});

map.on('click', function(evt) {
/** on
 * Listen for a certain type of event.
 * あるタイプのイベントをリッスンします。（ol3 API）
 */

 displayFeatureInfo(evt.pixel);
});

var exportKMLElement = document.getElementById('export-kml');
if ('download' in exportKMLElement) {

 var vectorSource = /** @type {ol.source.Vector} */ (vector.getSource());
 /** @type 
  * 値のタイプ（型）の説明 - 式などで表示
  * ol.source.Vector の型を使用。
  * （@use JSDoc[http://usejsdoc.org/]より）
  */
 /** getSource()
  * Return: Source（ol3 API）
  */

 exportKMLElement.addEventListener('click', function(e) {
 /** EventTarget.addEventListener
  * addEventListener は、 1 つのイベントターゲットにイベント 
  * リスナーを1 つ登録します。イベントターゲットは、ドキュメント
  * 上の単一のノード、ドキュメント自身、ウィンドウ、あるいは、
  * XMLHttpRequest です。
  * （MDN[https://developer.mozilla.org/ja/docs/Web/API/
  * EventTarget.addEventListener]）
  */

  if (!exportKMLElement.href) {
   var features = [];

   vectorSource.forEachFeature(function(feature) {
   /** forEachFeature(callback, opt_this)
    * Iterate through all features on the source, calling 
    * the provided callback with each one. If the callback 
    * returns any "truthy" value, iteration will stop and 
    * the function will return the same value.
    * 提供されたコールバックを呼び出して、ソース上のすべてのフィー
    * チャを反復処理します。コールバックは「truthy」の値を返した
    * 場合、反復が停止し、関数は同じ値を返します。（ol3 API）
    */

    var clone = feature.clone();
    /** clone()
    * Clone this feature. If the original feature has a 
    * geometry it is also cloned. The feature id is not 
     * set in the clone.
     * このフィーチャを複製します。元のフィーチャは、ジオメトリ
     * を有する場合にも複製します。フィーチャ ID は、クローンに
     * 設定されていません。（ol3 API）
     */

    clone.setId(feature.getId()); //clone does not set the id
    /** setId()
     * Set a unique id for this feature. The id may be 
     * used to retrieve a feature from a vector source 
     * with the ol.source.Vector#getFeatureById method.
     * このフィーチャの一意のIDを設定します。 id は 
     * ol.source.Vector の getFeatureById メソッドによる
     * ベクタソースからフィーチャを取り出すために使用する
     * ことができます。（ol3 API）
     */

    /** getId()
     * Return: id（ol3 API）
     */

    clone.getGeometry().transform(projection, 'EPSG:4326');
    /** getGeometry()
     *  Returns the Geometry associated with this feature 
     * using the current geometry name property. By default, 
     * this is geometry but it may be changed by calling 
     * setGeometryName.
     * 現在のジオメトリネームプロパティを使用して、この
     * フィーチャに関連したジオメトリを返します。デフォルト
     * では、ジオメトリですが、setGeometryName を呼び出す
     * ことによって変更することができます。（ol3 API）
     */

    /** transform(source, destination)
     * Transform each coordinate of the geometry from one 
     * coordinate reference system to another. The 
     * geometry is modified in place. For example, a line 
     * will be transformed to a line and a circle to a 
     * circle. If you do not want the geometry modified in 
     * place, first clone() it and then use this function 
     * on the clone.
     * ある座標参照系から別のものへジオメトリの各座標を変換。ジオ
     * メトリは、所定の位置に修正されます。例えば、ラインはライン
     * に、円は円に変換されます。ジオメトリを所定の位置に修正した
     * くない場合、最初にそれを clone() し、それからクローンでこ
     * の関数を使用します。（ol3 API）
     */

    features.push(clone);
   });

   var node = new ol.format.KML().writeFeatures(features);
   /** writeFeatures
    * Encode an array of features in the KML format.
    * KML フォーマットのフィーチャの配列をエンコードします。
    * （ol3 API）
    */

   var string = new XMLSerializer().serializeToString(
   /** XMLSerializer()
    * XMLSerializer can be used to convert DOM subtree or 
    * DOM document into text. XMLSerializer is available to 
    * unprivileged scripts.
    * XmlSerializer は、DOM サブツリーや DOM ドキュメントを
    * テキストに変換するために使用することができます。
    * XmlSerializerを権限のないスクリプトで使用できます。
    * （MDN[https://developer.mozilla.org/en-US/docs/
    * XMLSerializer]）
    */

    /** @type {Node} */ (node));

    var base64 = exampleNS.strToBase64(string);
    /** 'example-behavior.js' により文字列を Base64 へ
     * エンコードします。
     */

    exportKMLElement.href =
     'data:application/vnd.google-earth.kml+xml;base64,' + base64;
  }
 }, false);
} else {
 var info = document.getElementById('no-download');
 /**
  * display error message
  */
 info.style.display = '';
}