2024年9月17日 (火) 02:56時点における版

SVGMap.js (Level0.1フレームワーク)解説書

2018年現在のSVGMapのデータ形式、およびそれを実装した初歩的なフレームワーク(SVGMap Level0.1 Revision*)の解説を行います。

第一章：SVGMapの基本機構と、更新部分

この章は、JIS化されたSVGMap (JIS X.7197)や、W3C Member Submissionに対する、近年の開発成果に基づいたSVGMapのアップデートを解説しています。

JIS X.7197もしくは、W3C Member Submissionに記載されているように、SVGMapの基本機構は主に以下の機能を　汎用的なグラフィイクスデータ記述形式SVGに拡張することです。

• 地理座標処理
  • SVGの座標系と地理座標系との間の関係を記述する globalCoordinateSystems要素
• タイルピラミッド（タイリングとLevel of Detail）
  • コンテンツを埋め込むimage要素、animation要素のx,y,width,height属性への追加の振る舞いと、visible-min-zoom, visible-max-zoom属性の追加
  • 詳細は こちらの論文を参照
• 拡張されたレイヤー
  • ルートコンテナにおけるimage, animation要素の扱い
  • ルートコンテナが埋め込むsvgコンテンツ(レイヤーsvgコンテンツ)の処理

地理座標系の処理

SVG2では地理空間座標を記述するスペック(metadata geospatial coordinate systems)が削除されました。これは、W3C SVG仕様の範囲では単なるメタデータであり、ユーザエージェントの振る舞いに何ら影響を及ぼさないことが理由です。　また、JIS SVGMapにおいては、coordinateReferenceSystem 要素が定義され、それに基づくユーザエージェントの振る舞いが規定されていますが、これは一方でW3Cのスペックではないという課題を持ちます。

これを受けて、現在提案されているSVGMapのデータ仕様では、SVG1.1の段階ですでに標準化と実装が行われたスペックを注意深く活用することにより、JIS SVGMapで規定された地理座標系に関する機能のいくつか（すべてではない）を実現する方法を用いることとしています。（globalView spec）

なお、JIS SVGMapのcoordinateReferenceSystem要素もサポートしています。

メルカトル図法を含む任意の図法の定義とその合成機能(＞rev16)

従来のSVGMapでは、グローバル座標系に緯度経度座標を用いた場合、使用できる図法はPlateCarreeや正距円筒図法でした。

一方、rev16ではコンテナsvgコンテンツを含む任意のSVGMapコンテンツ(レイヤーsvgコンテンツやサブレイヤー、タイルなど)のglobalCoordinateSystem 要素のtransform属性に、下記のように"mercator"を指定することで、そのコンテンツの座標系がメルカトル図法(web mercator)であることを宣言できます。

<globalCoordinateSystem srsName="http://purl.org/crs/84" transform="mercator" />

この記述がされたコンテンツのSVGの座標空間はメルカトル図法上のものとなり、この座標系上でのx,y=0,0は西経180.0度,北緯85.051129度、x,y=1,1は東経180.0度,南緯85.051129度に対応します。

メルカトル図法での地図表示

コンテナsvgコンテンツで先述の宣言を行うことで、SVGMap0.1.jsはメルカトル図法で画面上に地図を表示します。このとき、コンテナsvgコンテンツが参照する各レイヤーはメルカトル図法であっても、それ以外であっても構いません。フレームワーク内でオンザフライの図法変換が実行されます。（逆にコンテナsvgコンテンツがPlateCarreeでレイヤーがメルカトルでも同様）

メルカトル図法のドキュメントルート要素のviewBox属性

• コンテナsvgコンテンツにおいて、地図の初期表示状態を記述するドキュメントルート要素(<svg>要素)のviewBoxに記述する座標も先述のメルカトル座標系で記述する必要があります。
• 一方、緯度経度で初期表示領域を記述したい場合に対応する仕様が拡張されており、その記述例は下記のとおり、globalを追加します。

<svg viewBox="global,138,35,2,2">

プロキシの設定

オンザフライでの図法変換では、多くのケースで非線形の座標変換が必要となります。ビットイメージ（タイルを含む）に対して子の座標変換を実行するためにSVGMap.jsではビット委イメージのピクセルにアクセスしています。これを実現するにはビットイメージがSVGMap.jsと同一オリジンにある必要があります。この条件を満たせないケースに対してフレームワークにはプロキシを設定する機能があります。(setProxyURLFactory APIを参照)

詳細な情報をこちらに掲載しました

多様な図法の定義と利用

javascriptコードに記載されたscript要素内に定義した関数の関数名をglobalCoordinateSystem要素のtransform属性に記述することで、その関数を図法変換に用いた図法定義が可能となります。(先述のmercator属性は、フレームワークに特別に組み込まれた関数です）

たとえば、日本の平面直角座標系の地図(固有の基準点を持つ横メルカトル図法)をPlateCarreeやメルカトル図法の地図として合成・表示するケースなどに有効でしょう。

ユーザが定義できるこの関数は引数を持たない関数であり、返り値として以下の３つの関数を返す必要があります。

• {x,y} transform({x,y}) : グローバル座標(WGS84経度緯度)から、そのコンテンツの図法の座標への変換関数 入出力値は.x,.yメンバを持つオブジェクト。
• {x,y} inverse({x,y}) : 同、逆変換関数
• number get scale : グローバル座標系に対するコンテンツの図法の座標系の座標値のスケール（グローバル座標系で1変化すると、コンテンツの座標系でいくつ変化するのかを表す）
• 記述例

<svg ...>
  <script>
  function azimuthalEquidistant(){
    ...
    return{
      transform:function(inp){
        var xy = transform_int(inp.y, inp.x, ...);
        return{ x:xy.x, y:xy.y}
      },
      inverse:function(inp){
        var latLng = inverse_int(inp.x, inp.y, ...);
        return{ x:latLng.lng, y:latLng.lat }
      },
      scale: 1.0
    }
  }
  </script>
  <globalCoordinateSystem srsName="http://purl.org/crs/84" transform="azimuthalEquidistant" />
  ...map contents in projected coordinate system...
</svg>

ウェブアプリケーションによる動的な地図レイヤーと、そのハイパーレイヤリング

SVG2(SVG1.1 2nd Edition)では、SVG単独によるユーザエージェントという実装想定は撤廃され、よく知られているウェブブラウザの機能の一部としてのSVGデータの描画機能、HTMLやCSSと一体化されたデータ・コンテンツ　へと変化しました。一方、近代のウェブブラウザにおけるコンテンツでは古典的なhtmlに基づくコンテンツデータに対して、javascriptとDOM APIによるプログラムでコンテンツをブラウザ上で動的に生成する（ウェブアプリケーション）機構を備えます。すなわちSVGを実装する現代のユーザエージェントは例外なくウェブアプリケーションの実行が可能となりました。

そこで、SVGMapでは静的なSVGによる地図コンテンツに加え javascriptで動的に生成されるコンテンツ(ウェブアプリケーション)も地図コンテンツ（地図のレイヤー）として扱えることとしました。それにもかかわらず SVGMapは依然として複数のウェブ上で分散する地図データを一つの画面上にレイヤリングする機能（ハイパーレイヤリング）を維持しています。すなわち、ウェブアプリケーションとしての地図レイヤーをレイヤリング（マッシュアップ）する機能が拡張されます。これは、SVGMapのマッシュアップ・ハイパーレイヤリングの概念を、単に地図画像データのレイヤリングから、地図上に表現された動的なオブジェクトのマッシュアップ・レイヤリングに広げています。SVGMapではこのコンセプトを"Layers as WebApps"(ウェブアプリケーションとしてのレイヤー)と呼んでいます。

このようなウェブアプリケーションは、レイヤーごとにカプセル化されることになります。これにより、グローバル空間(コンテナsvgコンテンツとそれを起動する、svgMap.jsフレームワークを読み込んだウェブページ)のスパゲッティ化なしに、多様な機能を実装していくことが可能になります。

こちらの論文も参考にしてください。

ウェブアプリケーションによる地図レイヤーを構築するには二つの方法があります。

• svg要素のdata-controller属性で参照されたhtml文書
  • #レイヤー固有ユーザインターフェースと呼ばれる機構です。この方法を用いること推奨します。
• svg要素内のscript子要素 (将来廃止予定)
  • htmlによるUIを伴わない実装の場合はscript要素を用いることができます。ただしsrcは属性には非対応、直接コードを埋め込む必要があります。

この機能を用いるにはSVGMapLevel0.1フレームワークを使用する場合は、拡張フレームワーク(SVGMapLv0.1_LayerUI2_r*.js)を更にロードする必要があります。SVGMapLevel0.2フレームワークの場合はデフォルトで機能します。

レイヤー固有ユーザインターフェース

SVGMap.jsではさらに、個々の地図レイヤー(レイヤーSVGコンテンツ)がそれぞれのレイヤーに特化した固有の演算ロジックだけでなく、ユーザーインターフェースも備えたHTMLを紐づけることができる機能が拡張されています。UIも備えた より完全なwebAppをレイヤーとして実装できるため、カプセル化がより効果的に実現されます。

たとえば気象情報のレイヤーに対して気象情報の時間変化を表示するアニメーションのコントローラ(スライダーバー)や、気象情報の種類を選択するプルダウンメニュー　などのUIやロジックを任意に構築できます。

レイヤー固有ユーザーインターフェースは、グローバル空間(SVGMap.jsをロードしたhtml)のレイヤー選択UIを通してwindowに設置されたiframe中に呼び出されます。詳細は #レイヤー固有のUI を参照してください。

このフレームワークでは、#svgMapLayerUI.で呼び出せるAPIが利用可能です。

例

以下に、いくつかのこのような動的な地図コンテンツの例を示しましょう。

検索によって表示スタイルを変更する機能を持ったレイヤー

例えばコンビニエンスストアのＰＯＩレイヤーを表示したとして、そのメタデータを読み取り、検索条件に基づいて（例えば深夜営業している店舗）の表示スタイルを変更するような検索機能を実装したレイヤー　メタデータは書くレイヤーごとに独特の値を持つため、その検索ロジックはレイヤーに固有のものとなることがあります。このケースではそのような機能をレイヤーに組み込むことを可能にします。

CSVデータなどのレガシーな非SVGデータをHXRで取得し、ブラウザ上でSVG DOMツリーを生成するようなSVG地図コンテンツ。

このケースでは、サーバからクライアントに送信されるデータの実体はSVG形式の地図データではなく、CSVなどのレガシーなデータです。SVG地図コンテンツには、CSVデータをSVGとして描画するためのデータ読み込み・解読・SVG DOMツリー生成機構を備えたjavascriptコードが含まれます。また、これよりはモダンなgeoJsonやKML等のデータをSVG DOMに変換することも容易に可能でしょう。これをより簡単に実現するためのライブラリもsvgMapGIStoolに準備されています。

タイリングされた地図コンテンツ

それは、たとえばOpenStreepMapのTile Serverや、Tile Map Serviceのような、特定のロジックによる数列のような法則性を持ったピラミッド状の地図タイルリソースをタイリングする地図コンテンツのことです。

更新されたSVGMapでは、地図コンテンツに内蔵されたjavascriptによるアプリケーションロジックとしてそれらを取り扱うことができます。タイリング規則をそのままウェブアプリケーションとしてで書き下し、スケールやビューポートに応じて適切なタイリング(配置)を行うSVG DOMツリーを生成するSVG地図コンテンツが構築できます。

タイリングに関するノート

svgMapにおけるタイリングは従来の地図フレームワークより柔軟で汎用的な概念に基づいています。 openLayersやleafletなどの従来の地図フレームワークでは、このようなタイリング機能は特定の固定的なタイリングロジックとパラメータを伴った機能として地図フレームワーク本体にハードコードされて提供されてきました。さらには地図フレームワークがこれらのタイリングロジックに強く依存したアーキテクチャを持っていました。一方、これらのロジックにはさまざまなバリエーションや最適化のための調整パラメータが存在し、これまで長らくその互換性や相互運用、更には効率の問題を抱えてきました。次のリンクでその多くの議論や多様な提案を参照できるでしょう。TMSspecs@osgeowiki, tiling@osgeowiki ベクターデータのタイリングにおいては、これらの課題はさらに増幅され、いまだ手法は確立していないといっても良いでしょう。たとえば、我々の研究では、Quad Tree Composite Tiling(スライド、、ペーパー)のような用途によってはもっと優れたタイリングの手法も見いだされています。

一方、これらのロジックはその多様なバリエーションを含め、javascriptによるプログラムコードとしては容易に記述可能です。多くの場合わずか数十行のロジックで記述できるでしょう。この程度のコードで多くのタイリングの手法が包含できるのであれば、特定のタイリング手法をフレームワークのコアに内包する・さらにはこれら特定のタイリングの手法にコアが依存する必要はなく、先述のウェブアプリケーションによる動的な地図レイヤーとして実装すれば良いであろうというのがSVGMapにおけるタイリング扱いです。3DマップのフレームワークであるCesiumはこれに似たタイリングポリシーを持っているようです。

SVG以外のデータサポートに関するノート

前章に記載した方針と同様、他の地図表示フレームワークと異なりSVGMapではSVGとして規定されたコンテンツ(もちろんビットイメージの埋め込みは可能)以外のネイティブサポートは行いません。例えばgeoJsonやKML, WKTなど地図業界でしばしば用いられるデータをSVGMapで表示したい場合は、変換ルーチンを埋め込んだ動的な地図コンテンツ（webAppレイヤー）としてそれらを扱います。SVGMap.jsの拡張モジュールであるSVGMapGIS.jsには、これらのデータをwebAppsで読み込みSVGに変換するためのAPIがあります。

トポロジースイート(地理空間情報処理)

Rev.13で拡張

SVGMapLevel0.1 Revision 13以降では、SVGMapコンテンツに対してトポロジー演算機能(地理空間情報処理機能)を適用する拡張フレームワークが提供されます。この機能を用いるにはSVGMapLevel0.1フレームワークに加えて、拡張フレームワーク(SVGMapLv0.1_GIS_r*.js)をロードする必要があります。 このフレームワークでは、拡張されたAPIが利用可能です。 フレームワークに内蔵された基本的な演算機能に加え、geoJSONと整合するインターフェースを備え、jstsを組み込み、より高度な機能を実装するための機構も持ちます。

この機能を用いると、特定のレイヤーに登録されているポリゴンの範囲に入っている、特定のレイヤーのポイントをフィルタリングして表示の色を変更する。といったことが可能です。ただし、これらはすべてすでにブラウザ上にロードされている限られた量のコンテンツの中での演算に限定されます。もしもサーバ上にしかないデータに対してこれらの演算を試みたい場合、従来通りサーバサイド技術によってそれは実現すべきです。

また、主題情報を含むウェブマップコンテンツの多くのレイヤーがラスタータイルによって提供されているという現状を考慮し、このスイートはラスターレイヤーをカバレッジとして扱った空間情報処理を行う機能の実装も進められています。現在のところ、カバレッジとポイントとの間での演算が可能です。また、そのために便利なカラーピッカー等の付加的な機能の実装も進められています。

オーサリングシステム

Rev.14で拡張

SVGMapLevel0.1 Revision 14以降では、SVGMapコンテンツを編集するツール機能が実装された拡張フレームワークが提供されます。フレームワークが提供するAPIを使って、オーサリング機能を持ったレイヤーを作ることが可能です。コンテンツは、SVG DOMとして構築されます。なお編集したオブジェクトを保存したり登録するためには別のサービスやアプリケーションの開発が必要です。

3D可視化システム

Rev.15で拡張

Cesium.jsを用いて、SVGMap.jsが表示できるすべてのコンテンツを3D可視化するシステムです。詳細解説はTBD (フレームワークが提供するAPI)

プログレッシブウェブアプリケーション

Rev.16で拡張

Progressive Web Appsをサポートしたブラウザにおいて、SVGMap.jsをオフラインでも利用可能にする拡張機能です。詳細解説はTBD (フレームワークが提供するAPI)

SVGMapコンテンツのバックエンドソフトウェア (参考)

本解説書は主にコンテンツ形式とユーザーエージェント側のソフトウェアについて解説していますが、サーバ・バックエンド側についてもここで少し言及します。

shapefileやcsvなどから、静的なSVGMapコンテンツを生成するためのソフトウェアがオープンソースで準備されています。これらのソフトウェアでは、高度なタイリング手法を用いた地図タイルを生成することができます。使用方法などは同リポジトリに用意されているチュートリアルを参照してください。

一方、もちろんSVGMapの仕様に準拠すれば、これらのソフトウェアに頼らず、自由にバックエンドを構築することができます。例えばよく知られた地図タイルサービスを用いたり、古典的なWFS やWMSのような動的地図・地理空間情報サービスをベースにして比較的容易にそれらを構築することもできます。SVGMap.jsのリポジトリのappLayersディレクトリにはそのようなシステムを構築する際のフロントエンド側の動的レイヤーのサンプルが掲載されています。

第二章：SVGMap Revsion 0.1フレームワーク

SVGMapは究極的には既存のすべてのウェブブラウザがネイティブの機能としてそれを備えることを目標とし、既存のHTML,CSS,SVGなどのウェブブラウザの標準規格との整合性を備え、且つ既存のWeb Mappingの規格との整合性をも備えた仕様として検討と標準化を進めています。しかし今のところまだその標準化は完遂されていないため、その完全な実装がなされたウェブブラウザは存在しません。一方、既存のウェブブザでSVGMapの機能が実行可能となるような拡張をJavascriptによるフレームワークとして構築することが可能です。SVGMap Revision 0.1フレームワークは、このようなJavascriptによるSVGMapの仕様に基づいた初歩的な制限と拡張がされた実装です。その実装はオープンソースとしてこちらのgitubリポジトリで公開されています。

そのアーキテクチャの特徴は、ブラウザネイティブのSVGレンダラーを使用せず、HTML,CSS,HTMLCanvas2DAPIを用いてSVGMapが実装されている点です。この特徴は主にこのフレームワークの開発が開始された時期に起因しています。当時のウェブブラウザの多くはSVGが実装されていませんでした。また実装されていたとしても、大規模なベクトルデータのレンダリング、および伸縮スクロール・インタラクティブな操作に対する性能面での処理制御に問題がありました。これらの問題のいくつかは現在のブラウザで解消されているものがあるかもしれません。またこれらの問題の解決とともに、SVGMapフレームワークはLevel番号を上げつつよりネイティブの機能に基づいた実装に移行するかもしれません。参考までに、実験的なネイティブのレンダラを用いた実装(2010年)があります。

SVGのベクトル描画機能はcanvgのpathパーサなどを引用することで実装されています。一方、地図としてあまり用いられないと想定された 多くの要素やプロパティ、アトリビュートの実装が省略されています。

追加・拡張された機能：

フレームワークの呼び出し

本フレームワークを用いる場合、SVGMapコンテンツをブラウザに直接読み込ませることはできません。フレームワークを動作させるjavascriptライブラリをロードしたhtmlコンテンツ(WebApps)を準備し、そこからSVGMapコンテンツを呼び出します。利用者には、このhtmlコンテンツのURLを告知します。このhtmlコンテンツを以降ルートhtml文書と呼ぶことにします。

SVGMapのフレームワークはgithubリポジトリ：https://github.com/svgmap/svgmapjs　で公開されています。

htmlコンテンツの<body>要素直下に以下の要素を配置します。

フレームワークを実装したjavascriptライブラリを読み込むscript要素

これがSVGMap.jsのコアのフレームワークを構成します。

<script type="module">
  import { svgMap } from 'https://cdn.jsdelivr.net/gh/svgmap/svgmapjs@latest/SVGMapLv0.1_r18module.js';
  window.svgMap=svgMap
</script>

上のスクリプトで必要なモジュールが読み込まれます。グローバル空間のwindowのメンバには、svgMapオブジェクトを設定しています。

実働サンプル(tutorial5_esm)

もしくは https://github.com/svgmap/svgmapjs の内容を独自のウェブホストにコピーしそれを用いることもできます。(下の例はグローバル空間のhtmlに対して、svgmapサブディレクトリにjsを置いた場合)

<script type="module">
  import { svgMap } from './svgmapjs/SVGMapLv0.1_r18module.js';
  window.svgMap=svgMap
</script>

GISモジュールを利用する場合

svgMap.jsの地理空間演算機能(GISモジュール)では、jsts.jsを使用しています。そのためGISモジュールを機能させるにはjsts.jsの読み込みが必要です。下記のようになります。もちろん独自のウェブホストにjstsをコピーしてそれを利用することも可能です。

<script type="text/javascript" src="https://unpkg.com/jsts@1.6.1/dist/jsts.min.js"></script>
<script type="module">
  import { svgMap } from 'https://cdn.jsdelivr.net/gh/svgmap/svgmapjs@latest/SVGMapLv0.1_r18module.js';
  window.svgMap=svgMap
</script>

その他、各種の拡張フレームワークのjavascriptコードを読み込むscript要素(必要に応じて)

ECMA Script Module対応の内容に現在更新中

SVGMapLv0.1_Authoring_r*.js、SVGMapLv0.1_GIS_r*.js他がある。

<script type="text/javascript" src="拡張フレームワークファイル.js"></script>
注記:拡張フレームワークファイル.jsは用いる拡張によって変化する。

本解説書でAPIを説明している、現在利用可能な拡張フレームワーク

ECMA Script Module対応の内容に現在更新中

• SVGMapLv0.1_Authoring_r*.js
  • https://cdn.jsdelivr.net/gh/svgmap/svgMapLv0.1@latest/SVGMapLv0.1_Authoring_r7.js
• SVGMapLv0.1_GIS_r*.js
  • https://cdn.jsdelivr.net/gh/svgmap/svgMapLv0.1@latest/SVGMapLv0.1_GIS_r3.js
• SVGMapLv0.1_LayerUI2_r*.js
  • https://cdn.jsdelivr.net/gh/svgmap/svgMapLv0.1@latest/SVGMapLv0.1_LayerUI2_r4.js
• SVGMapLv0.1_CesiumWrapper_r*.js (実験的)
  • https://cdn.jsdelivr.net/gh/svgmap/svgMapLv0.1@latest/experimental/Cesium3D/SVGMapLv0.1_CesiumWrapper_r3.js
• SVGMapLv0.1_PWA_r*.js (実験的)
  • https://cdn.jsdelivr.net/gh/svgmap/svgMapLv0.1@latest/experimental/PWA/SVGMapLv0.1_PWA_r5.js

まだ実験的なsvgMapCesiumWrapperは、svgMap cesium visualizerページを参照ください。 SVGMapPWA(ProgressiveWebApp)については、SVGMap PWA Testページを参照ください。

SVGMapコンテンツを配置するためのdiv要素

id属性に"mapcanvas"を設定し、data-src属性(もしくはtitle属性(to be obsoluted))には、地図フレームワークが最初に読み込む、SVGMap.jsが表示する地図コンテンツの起点となるSVGコンテンツ（以降コンテナsvgコンテンツと呼びます）のパスを指定したdiv要素を設置します。

コンテナsvgコンテンツはまた、ここで記述するレイヤーを持つことができる特別のコンテンツです。

（要確認：地図のサイズ・配置はこのdiv要素のサイズとなります。無指定の場合は全ウィンドサイズ）

<div id="mapcanvas" title="Container.svg"></div>

<div id="mapcanvas" data-src="Container.svg"></div>

差分データの指定

data-custom-layers-root属性でContainer.svgに対するレイヤーの差分情報のパスを指定することができます。 もしくは、data-custom-layers-root属性に、レイヤーの差分情報が保管されているディレクトリを記述した場合、URLハッシュで差分ファイルを指定することもできます。 差分データは、カスタムレイヤーマネージャで作成することが可能。（データ形式は後述）

<div id="mapcanvas" data-src="Container.svg" data-custom-layers-root="./containerDif/dif0.json"></div>

地図中心の照準イメージ。

参照する画像はあらかじめ用意されたもの以外も利用できます。

<img id="centerSight" style="opacity:0.5" src="Xcursor.png" width="15" height="15"/>

任意で設置できる要素：

LayerUIフレームワークを実装したjavascriptコードを読み込むscript要素（本フレームワークについては後述）

下記のレイヤーリストUIおよびレイヤーに特化したUIを設置する場合、このscriptの読み込みは必須です。

<script type="text/javascript" src="SVGMapLv0.1_LayerUI2_r2.js"></script>

伸縮ボタン

<img id="zoomupButton" style="left: 5px; top: 5px; position: absolute;" src="zoomup.png" onclick="svgMap.zoomup()" width="20" height="20" />
<img id="zoomdownButton" style="left: 5px; top: 25px; position: absolute;" src="zoomdown.png" onclick="svgMap.zoomdown()" width="20" height="20" />

img要素かつidが上記の値である必要があります。

　伸縮ボタンを一回押すたびに伸縮する比率は、別途svgMap.setZoomRatio(ratio)で設定可能。 　デフォルトの比率はsqrt(3) 　

測位ボタン

<img id="gpsButton" style="left: 5px; top: 45px; position: absolute;" src="gps.png" onclick="svgMap.gps()" width="20" height="20" />

img要素かつidが上記の値である必要があります。ボタン押下で測位し、測位点を中心にして地図を表示する機能。表示の範囲は測位制度に応じて適当に設置されます。

グローバルメッセージ

レイヤー固有UIが任意のメッセージを出力可能にするために設置するエリア　#レイヤー固有のUIのAPI putGlobalMessage 参照

<span id="globalMessage" style="font-size:10px;left:5px;bottom:16px;position:absolute;"></span>

idが上記の値である必要があります。

　styleは任意

地図中心の緯度経度値表示

<font id="centerPos" size="-2" color="brown" style="left: 50px; bottom: 5px; position: absolute;" ></font>

idが上記の値である必要があります。

　styleは任意

レイヤーリストUI(後述)を設置するdiv要素

<div id="layerList" style="left :30px; top: 10px; width:300px;height:90%; position: absolute; "></div>

idが上記の通りである必要があります。

　 styleは任意だが、heightはレイヤリストUIが展開された状態におけるサイズとなります。格納された状態のサイズは、この要素における文字の縦幅となります。 　

レイヤー固有のUI(後述)を設置するdiv要素

レイヤー固有のUIを使用するために設置するdiv要素です。

<div id="layerSpecificUI" style="right :10px; top: 40px; width:400px;height:400px; position: absolute; background-color: white;opacity:0.8;display:none;">
</div>

idが上記の通りである必要があります。styleは任意だが、heightはレイヤリストUIが展開され得る最大のサイズとなります。

レジューム機能のためのチェックボックス

<form style="right:10px;top:20px;position:absolute;opacity:0.8" >
<input type="checkBox" id="resumeBox" onChange="svgMap.resumeToggle(event)" autocomplete="off"/>
<label for="resumeBox"/>Keep and Resume view</label>
</form>

checkboxタイプのform要素であり、idが上記の通りである必要があります。レジューム機能とは、(rev16以前ではcookie、rev17以降ではlocalStorage)を用いて、前回最後に表示された状態（レイヤーの表示非表示状態、表示領域（view port）を再現する機能です。スタイルおよびlabel要素は任意

レイヤーリストUIのためのスタイル

<style>
body {
	font-family: Meiryo;
}
#layerTable{
	background:#ffE0E0;
	border: 2px solid #bbb;
}
.layerItem{
	background-color: white;
}
.noGroup{
	background-color: #fff0f0;
}
#layerList{
	background-color: #ffff80;opacity:0.8;
}
</style>

レイヤーリストUIを用いる場合、例えば上記のようなスタイルの定義が必要です。

• layerList：レイヤーリストUI全体に対するスタイル
• layerTable：レイヤーリストUIの中のテーブルに対するスタイル。
• layerItem：同テーブルに表示される個々のレイヤー表示に対するスタイル
• noGroup：同レイヤー表示のうち、グループに属さないレイヤーに対するスタイル

レイヤー

SVGMapは古典的な地図情報システムのようなレイヤーの概念を備えていません。一方その上位概念ともみなせる、任意のドキュメントをツリー状に埋め込む機能を備えています。しかしそれでは古典的なユースケースを平易に表現しているとはいえないため、それをラップする古典的なレイヤーの概念と、それに基づくレイヤーユーザインターフェースのフレームワークを持ちます。

フレームワークが最初に読み込む地図コンテンツの起点となるコンテナsvgコンテンツの中で、animationもしくはiframeを用いて（準拠規格に依る）埋め込まれるsvgコンテンツが、自動的にレイヤーとみなされます。いうまでもなくレイヤーの上下順はSVGコンテンツのスクリプト中での埋め込みの順番の逆順になります。

また、このコンテナsvgコンテンツが参照し埋め込んでいる、各レイヤーのSVGコンテンツのことを、レイヤーsvgコンテンツと呼ぶこととします。ここで、各レイヤーsvgコンテンツはさらに別のsvgコンテンツを埋め込むことがあります。これらのコンテンツはよくサブレイヤーSVGコンテンツもしくは単にサブレイヤーと呼ばれることもあります。

なお、Rev12以降のSVGMapLv0.1フレームワークではレイヤーフレームワークは本体と独立した実装となり、拡張や切り離しが可能となりました。以下は、標準で提供されるレイヤーフレームワークのVer2 (SVGMapLv0.1_LayerUI2_r*.js)に関して解説します。

レイヤーUIフレームワークが提供するUIは、先述のレイヤーリストUIを設置するdiv要素によって提供されます。このUIは以下の機能を持ちます。

• 折り畳み可能なレイヤーの一覧を表示する機能
• 各レイヤーの表示非表示を切り替える機能
• グルーピングされたレイヤー(後述)をグループとして表現、折り畳み、一括表示非表示する機能。
• そのレイヤーに紐づけられた#レイヤー固有のUIを出現させる機能。
• 表示されているレイヤーの個数などの情報を表示する機能

コンテナsvgコンテンツの記述内容とレイヤーフレームワークの振る舞い

• animation要素：　レイヤーとみなされる
  • title属性: レイヤーの名称となる。(必須属性) title属性値は他のレイヤーと重複してはならない(ID(このコンテンツ内でのレイヤーの識別子)として振る舞う)
  • xlink:href属性: レイヤーsvgコンテンツへの参照
  • visibility属性 : レイヤーの初期の表示状態。UIにより変更できる (hidden or visible)
  • opacity属性 : レイヤーの透明度
  • x,y,width,height属性の振る舞いは共通(viewportがこの属性の値とintersectしていただロードされる)
  • class属性: スペース区切りで規定値(複数)と任意値(一つ)を記述できる
    • 詳細は後述の#class属性によるレイヤーのグルーピング・クリッカブル機能の提供を参照
  • data-controller属性: (Optional) #レイヤー固有のUI　の　#詳細参照
• globalCoordinateSystem要素：(1個つだけ必須要素)
  • (コンテナsvgコンテンツにおける)本要素が、このフレームワークによってUser Agentに表示される地図の図法を規定する。
    • なお、それ以外のSVGコンテンツのglobalCoordinateSystem要素は、コンテナsvgコンテンツの図法への変換のために用いられる
    • より詳細は#地理座標系の処理を参照
• svg要素: (documentRoot要素)
  • viewBox属性: 初期の表示範囲を指定。
    • ここに記述する座標値は、SVGの仕様に準ずるが、　拡張記述形式も使用可能　参照：#メルカトル図法のドキュメントルート要素のviewBox属性

レイヤーsvgコンテンツ

レイヤーsvgコンテンツは、レイヤー固有のUIを紐づけることができます。

クリッカブルオブジェクト

グラフィックスオブジェクトをクリック（タブレットの場合は、タップもしくは照準アイコンに合わせたうえでタップ）することでそれに紐づけられたインタラクティブ動作を実行する。インタラクティブ動作はフレームワークが独自に提供する、metadataフレームワークに基づく、メタデータの表示機能を対象とします。

なお、image要素(useによって間接的に設置されたimage要素を含む)は、a要素によるハイパーリンクが加えて実装されています。metadaとa要素の双方が設定されているimage要素では、どちらのインタラクティビティを発動させるかをモーダルダイアログによるユーザへの問い合わせが行われます。

class属性によるレイヤーのグルーピング・クリッカブル機能の提供

コンテナsvgコンテンツが参照するレイヤー（レイヤーsvgコンテンツ）へのリンクを記述する要素(animationもしくはiframe要素)は、class属性によって、各レイヤーに特性を与えることができます。classはスペース区切りで複数指定することができますが、グループ名は一つしか認識されません。

グルーピング

以下の属性値以外の値を記述すると、グループ名として認識され、同じグループ名を持ったレイヤーたちをグルーピングすることができます。グルーピングの効果はレイヤーＵＩにおけるグループ表現と、下記のbatch,switch特性です。グループはレイヤーリストUI上の表現に反映されます。最初に現れたグループ名がこのUIの下に表示されます。ただし地図画面上の描画の順番はこれとは別、SVGの基本的な描画順(Painter Model)に準じます。

batch

グルーピングとともに使用します。そのグループに属するレイヤーを一括で表示非表示するための機能がレイヤーＵＩに付加されます。

switch

グルーピングとともに使用します。そのグループに属するレイヤーは、どれか一つしか表示されません。batchとの併存はできません。（無視されます（要確認））

clickable

Pathなどのベクトル図形要素はデフォルトではインタラクティビティが提供されません。クラス値にclickableを指定することでこのレイヤー（子供のsvgコンテンツを含む）の図形要素においてのみ、インタラクティビティが提供されます。提供されるインタラクティビティは、マウスによって図形をクリックしたとき、そのグラフィックス要素がクリッカブルな要因を備えているかどうかを検索し、備えている場合それに対応するアクションを起こします。

　なお、image要素(useによって間接的に設置されたimage要素を含む)は、このクラスの設定に依らず、a要素によるハイパーリンク、およびmetadataフレームワークを用いたクリッカブルオブジェクトとして機能します。

editable

当該レイヤのレイヤー固有UIにsvgMapAuthoringToolの図形編集オブジェクトを設置する場合、それを有効に機能させるためにはこの属性が必要です。(なお再編集機能を有効にするにはclickableも必要)

data-nocache

コンテナsvgコンテンツが参照するレイヤー（レイヤーsvgコンテンツ）へのリンクを記述する要素(animationもしくはiframe要素)に、data-nocache属性をつけることによって、クライアントのコンテンツキャッシュを無効にすることができます。なお、無効化手段はunix-timeクエリパートをそのレイヤー下のすべてのリソースへのアクセスに付加させることによります。

metadataフレームワーク

データ格納効率に優れたメタデータのフレームワークが提供されます。このメタデータは先述のクリッカブルオブジェクトとしてインタラクティビティの実装に用いられます。 svgドキュメントルート要素のproperty属性にメタデータの属性名をカンマ区切りで列挙。同文書の図形要素のproperty属性に同じ順序でメタデータの値を記述します。(なお、xlink:title属性でマウスオーバーで機能する吹き出しを設置できます)

ひとつの文書に対して一つのスキーマ（メタデータの属性名とその順番）しか与えられないという制約を持ちます。（その代わり格納効率が高い）クリックやタッチ等によってデフォルトの状態ではブラウザが備えるモーダルダイアログに属性名と属性値がそれぞれ列挙された形で表示されます。metadata表示機能の拡張/カスタマイズについては、ウェブアプリケーションの開発の章で別途解説するsetShowPoiProperty()関数を参照してください。

データ自体にカンマが含まれる場合はエスケープが必要です。

例：

<svg property="id,type,latitude,longitude,title,address,spec" ... >
...
<use transform="ref(svg,14118.37511,-4524.39994)" x="0" y="0" xlink:href="#syl8"
content="RIS/RJER,地方管理,45.2439994,141.1837511,利尻空港,北海道利尻郡利尻富
士町,1800×45(07/25)" xlink:title="利尻空港"/>
...
</svg>

動作の制限・差異

再描画の制限

• ブラウザネイティブのSVG描画機能に対して注意すべき点として、このSVGDOMの描画は、基本的に伸縮スクロールのタイミングでしか行われない点です。（ネイティブのSVG描画機能は60fpsで再描画する努力を行っている) そのため、再描画タイミングを意識・明示(refreshScreen関数を使用)したアプリケーションの構築が必要になるケースがあります。
• 関連情報
  • 内部機構解説#Zoom.2FPan_Controller:
  • refreshScreen
  • setPreRenderController
  • preRenderFunction
  • 動的な地図レイヤー
  • レイヤー固有のUI
  • 拡張イベント

実装されている機能

多くの機能が実装されていないため、実装されている機能、および拡張された機能をここでは列挙することとします。

要素

• path
• globalCoordinateSystem
• circle
• text
• defs
• animation
  • 別のsvgコンテンツを取得して埋め込みます。
  • コンテナsvgコンテンツで使用した場合は埋め込んだコンテンツは「レイヤー」と見做されます。
  • それ以外で使用した場合はタイルやサブレイヤーとして使用できます。
  • x,y,width,height属性は、SVGの仕様に基づき埋め込むコンテンツのtransformに影響を与えるとともに、下記の通り動的なコンテンツの読み込み機構が制御されます。
    • この属性で示された領域がtransform後のviewportと交差・包含した場合、その埋め込みコンテンツは動的に取得され表示されます。lazy loadの機構に相当し、タイリングメカニズムを構成します。
    • ただし、visible-min-zoom およびvisible-max-zoom属性で示された拡大率による表示条件を満たしていない場合は取得されません。level of detailの機構に相当します。（x.y,width,height属性と組み合わせることで、タイルピラミッド（ラスター、ベクターを含む）機構を実現します。詳しくはJISX.7197、Tiling and Layering Moduleサブミッション、もしくはこちらの論文を参照
  • commonQuery属性：レイヤールートSVGMapコンテンツのanimation要素でこの属性を設置すると、そのレイヤーのコンテンツを取得するすべてのGETリクエストのクエリパートにこの属性で設定した値が共通付加されます。(もしKey=Valueの形のクエリを追加したい場合は文字列として"Key="の部分も含めてこの属性値に設定します。)
• iframe
  • animationと同等
• image
  • 別のビットイメージコンテンツを取得して埋め込みます。
  • animation属性のx,y,width,height属性と同様の追加のlazy loadの振る舞いを持ちます。
  • visible-min-zoom およびvisible-max-zoom属性の振る舞いも同等です。
  • xlink:href属性はspatial fragment をサポートし、(xywhによっ参照されるimageの部分を埋め込む機能をサポートします。)。もしもアスペクト比が異なった場合（ＴＢＤ）
  • style:filterプロパティによる画像処理をサポートします。
  • data-mercator-tile="true"　属性が設定されている場合、そのビットイメージはメルカトル図法で描画されていることを示します。
  • htmlのimg要素のcrossoriginに対応する属性を持つことができます（この場合ビットイメージの埋め込みに際しoriginヘッダが送信）
• view

属性

• ref(svg,x,y) ：SVG1.2TのTransformRef属性により、non-scaling objectが設置できます。Pointフィーチャの可視化に効果的です。　

TBD

• fill
• stroke
• arrow
• dasharray
• viewvox
• opacity
• style
  • image-rendering : pixelated / image要素
  • fill
  • stroke
  • opacity
• meta
  • http-equiv="refresh" : レイヤーsvgコンテンツのみ。contentに秒数を設定することで、そのレイヤーを指定秒数ごとに(再読み込み)更新する。script要素はonloadが再実行される。　注：ブラウザのキャッシュが効く可能性を考慮して実装する必要がある。

第三章：ウェブアプリケーションの開発

本章はSVGMap Revsion 0.1フレームワークを用いたウェブアプリケーションの開発について解説します。 本フレームワークによる開発部分は以下に分類されます。

• ルートhtml文書によるウェブアプリケーション(SVGMapフレームワーク)
• 動的な地図レイヤー(Layers as WebApps) : SVGコンテンツに以下のいずれかの情報を設定する
  • レイヤーsvgコンテンツのドキュメントルート要素のdata-controller属性　レイヤー固有のUI
  • svgドキュメントに設置されたscript要素 script要素による動的な地図レイヤー

SVGMapフレームワーク

ルートhtml文書によるウェブアプリケーションはSVGMapLv0.1フレームワークを用いたウェブアプリケーションの基本であり、そのhtml文書と底傘参照されたjavascriptライブラリを読み込んだwindowが持つ'svgMap'という名前のインスタンスを用いてフレームワークのための拡張機能を利用することができます。

SVGMapが持つ基幹オブジェクト

SVGMapLv0.1フレームワークのインスタンス'svgMap'が持つ基幹のオブジェクトを解説します。これらの基幹オブジェクトはそれぞれゲッター(getSvgImages, getSvgImagesProps)によって取得できます。

svgImages[]

getSvgImages()により取得できる。svgImages[hashID]は、 現在ローディングされているSVGドキュメント(“XML” DOMツリー(SVG DOMツリーというよりむしろ))が蓄積されているハッシュテーブル

• ハッシュID：フレームワークが任意に付番した文書ID。ただし、最初にロードされるルートのドキュメントのハッシュキーは、”root”
• なお、#レイヤー固有のUIのwebAppでは、そのレイヤーに該当するSVGドキュメントがsvgImageで取得できる。

svgImagesProps[]

getSvgImagesProps()によって取得できる。 同、個々のSVGドキュメントが持つ、各種プロパティが蓄積されているハッシュテーブル

• ハッシュID： svgImages同様
• なお、#レイヤー固有のUIのwebAppでは、そのレイヤーに該当するSVGドキュメントが持つ、各種プロパティがsvgImagePropsで取得できる。

プロパティリスト

• .Path コンテンツのパス（webAppsのdocument(html) rootに対する相対パス。Originが違う場合は絶対パス
• .CRS 地理座標からSVG座標に変換するための変換パラメータ
• .script SVG文書がscript要素を持つとき、そのscriptへのインターフェースが登録される。同script要素で生成されるオブジェクトに暗黙に登録されるメンバー変数については、script要素による動的な地図レイヤーの章を参照
• .editable 編集可能レイヤーを示す　レイヤーのclass = editableに対応
• .editing 編集可能レイヤーを編集中
• .isClickable クリッカブルなレイヤーを示す
  • true:設定　レイヤーのclass = clickableに対応
  • 以下をメンバーに持つオブジェクト:ハイライト時のスタイルを設定可能(rev18以降)
    • .hilightFillStyle : ポリゴンオブジェクトのハイライト時スタイル（以下のメンバーが無い場合はハイライトしない）
      • .color : 塗りの色 (CSS の color値として解釈される文字列)
      • .lineWidth : 線幅
    • .hilightStrokeStyle : 線オブジェクトのハイライト時スタイル（以下のメンバーが無い場合はハイライトしない）
      • .color : 線の色 (CSS の color値として解釈される文字列)
      • .widthIncrement : 線幅の増加値
• .parentDocId このSVG文書を埋め込んでいる、親のSVG文書のハッシュID
• .childImages[hashID] このSVG文書が読み込んでいる、子のSVG文書(複数)
• .refresh
  • .loadScript
  • .timeout
  • .start
• .controller レイヤー固有のUIへの(web appsのdoc rootに対する)相対パス
• .isSVG2 その文書がSVG2タイプの文書であるかどうか(CRSとembedの仕方がちがう）
• .rootLayer そのSVG文書が属する「レイヤー」を示す文書
• .scale そのSVG文書の現在のスケール。スケールはそのSVG文書の座標系と画面の座標系との間の値（地理座標系ではない）。拡大するとスケール値は大きくなる
• .preRenderControllerFunction そのSVG文書の再描画(画面更新)シーケンスの直前に実行される関数

利用可能API

【TBD】 APIのリストは下記の通りです。

SVGMap.で呼び出せるAPI

Geo2SVG

• Geo2SVG( lat , lng , crs ) : 指定された緯度(lat)・経度(lng)・CRSより、SVG座標を計算する

POIviewSelection

• POIviewSelection( poi ) : 指定されたPOIの属性・リンクの表示選択画面を表示する。また、選択したイベントに従い、属性の表示または、リンク先のページを表示する。

SVG2Geo

• SVG2Geo ( svgX , svgY , crs , inv ) : 指定されたSVG座標(svgX , svgY)をCRSにより、GEO座標に変換する。または、invにより逆変換する

addEvent

• addEvent(elm,listener,fn) : 指定された要素(elm)にイベント属性(listener)時の呼び出す関数(fn)を設定する (addEventListenerが実装されていなかったブラウザサポートの名残です)

callFunction

• callFunction( fname ,p1,p2,p3,p4,p5) : 指定した関数(fname)を引数(p1,p2,p3,p4,p5)を渡してフレームワーク内の任意の関数を実行する。(フレームワークの内部関数も呼び出すことができる)

captureGISgeometries

• captureGISgeometries( cbFunc , prop1 , prop2 , prop3 , prop4 , prop5 , prop6 , prop7 ): 現在画面上に表示中の地図コンテンツに対応した、GeoJsonのGeometryデータ構造に準拠のGISgeomerry情報をがレイヤ単位でまとまった連想配列の形で取り出す。非同期処理で、cbFuncの最初の引数に返却される。
  • 連想配列のハッシュ値：レイヤID
  • geomeryには、src(そのジオメトリのもととなっているSVGの図形要素), href(ビットイメージの場合のリンク)が付加される
  • display="none"の図形要素は表示されていないとみなされる。また画面外にある図形要素も表示されていないとみなされる。画面に部分的に表示されている要素は表示されているものとみなされるとともにクリッピングも行われない。

captureGISgeometriesOption

• captureGISgeometriesOption(BitImageGeometriesCaptureFlg, TreatRectAsPolygonFlg, SkipVectorRenderingFlg, captureAlsoAsBitImage): captureGISgeometriesでキャプチャするデータの取得条件を設定する。
  • BitImageGeometriesCaptureFlg: ビットイメージタイルをカバレッジとして取得するか(Default:false)。captureGISgeometriesを呼び出す前に使用する。
    • 2019.5.17アップデートで、transform matrix(非対角要素あり)を持つビットイメージタイルについても必要な情報を得られるようになった。
  • TreatRectAsPolygonFlg: rect要素をポリゴンとして扱う(デフォルトは円もrectもPointとして扱われる)
  • SkipVectorRenderingFlg: ベクトル図形の描画をスキップする
  • captureAlsoAsBitImage: polygon/polylineの図形を描画したビットイメージをレイヤー単位でカバレッジデータとして取得
• captureGISgeometriesOption(captureGISgeometriesOptionObject) : オブジェクトでも設定できる(rev18以降)（以下そのメンバー変数：全て値はboolean）
  • .BitImageGeometriesCaptureFlag, .TreatRectAsPolygonFlag, .SkipVectorRendering, .captureAlsoAsBitImage　上と同様

checkSmartphone

• checkSmartphone() : タッチに対応したスマホブラウザなのかどうかを判別

childDocOp

• childDocOp(func , docHash , param1, param2 , param3 , param4 , param5) : 指定した文書をルートにして、DOM操作をその子文書に対して実行する。なおこれはlinkedDocOpの直系の子供のみ適用版(自身も適用しない)

dynamicLoad

• dynamicLoad( docId , parentElem ) : 指定した文書ID(docId)以下の表示に必要な文書を読み込み、指定したdiv要素(parentElem)に表示する

escape

• escape(str) : 以下の文字をHTMLエスケープする(&:&amp,":&quot;,':&#039;,<:&lt;,>:&gt;)

geo2Screen

• geo2Screen( lat ,lng ) : 地理座標を指定すると、その画面上のキャンバスの座標(px)を返す

getBBox

• getBBox( x , y , width , height ) : 指定された値でviewBoxを作成する

getBasicPermanentLink

• getBasicPermanentLink(copyLinkTextToClipboard) : 現在の表示状態(レイヤーの表示非表示および表示領域)を反映した基本的なパーマリンクを生成する
  • URLオブジェクトが返却される
  • copyLinkTextToClipboardがtrue場合、クリップボードにもURLがコピーされる。
  • 生成されるURLは、#起動URLによるオプション指定の仕様に基づく

getCentralGeoCoorinates

• getCentralGeoCoorinates() : グローバル変数 rootViewBox,rootCrsから画面中心地理座標を得る

getConversionMatrixViaGCS

• getConversionMatrixViaGCS( fromCrs , toCrs ) : 元座標変換行列(fromCrs)から先座標変換行列(toCrs)への変換行列を作成する

getCORSURL

• getCORSURL(originalURL, alsoCrossoriginParam) : クロスオリジンアクセス用URLを生成する。(setProxyURLFactoryの第4,5引数が設定されている場合)
  • alsoCrossoriginParam クロスオリジンアクセスに際してoriginヘッダが必要かを取得する(この引数がある場合は.url, .crossorigin メンバを持つオブヘクトが返却される)
  • レイヤー固有UIのウェブアプリなどで独自にクロスオリジンアクセスを行ってデータを取得するような場合にプロキシ経由のURLを生成するのに利用できます。
  • 参考：クロスオリジンアクセスのためのプロキシ設定

getDevicePixelRatio

• getDevicePixelRatio( docId ) : setDevicePixelRatioで設定した値を取得できる。 docIdが指定されなかった場合は全ての値が得られる

getElementByImageId

• getElementByImageId( XMLNode , searchId ) : 指定されたSVG文書群ノード(XMLNode)以下の属性iidが指定されたID(searchId)と等しいノードを返す

getLoadErrorStatistics

• getLoadErrorStatistics() : 伸縮スクロール、refreshScreenごとの、リソースの読み込み状況を取得する。
  • メンバー変数: timeoutBitImagesCount,timeoutSvgDocCount,otherBitImagesCount,otherSvgDocCount

getGeoViewBox

• getGeoViewBox() : コンテナsvgのviewBoxをgeo変換したgeoのviewBoxを取得

getHashByDocPath

• getHashByDocPath ( docPath ) : ターゲットのレイヤーのハッシュをPath名(docPath)から探し出す

getHyperLink

• getHyperLink( svgNode ) : 指定されたsvg文書(svgNode)から、親文書をたどり最初に取得できたハイパーリンクを取得

getInverseMatrix

• getInverseMatrix(matrix) : 逆行列を求める(matrix.a..f)

getLayer

• getLayer(layerID_Numb_Title) : layerID,title,番号,href(URI)のいずれかで、コンテナsvgコンテンツSVGDOMにおけるレイヤーの(svg:animation or svg:iframe)要素を取得する。getLayersと似ているが、getLayersのほうは任意のsvg文書(オプションなしではroot container)に対して、内包されるレイヤーのリストを返却。こちらはコンテナsvgコンテンツに対して検索キーに基づいてレイヤーを返却する

getLayerId

• getLayerId( layerKey ) : コンテナsvgコンテンツにおける"レイヤ"概念のレイヤidを検索する。検索に用いることができるのは、getLayerと同じtitle,url,もしくはルートレイヤの要素
• layerIDはレイヤー名とは異なる、フレームワークによって任意に附番された、そのSVGMapドキュメントを識別するための文字列。このlayerIDを基に動作するAPIが多くあります。
• #レイヤー固有のUI　の　#layerID も参照

getLayers

• getLayers( id ) : オプションなしの場合、コンテナsvgコンテンツのレイヤーに該当する要素をリストアップし、返却する。 オプションアリの場合、そのidを持つ要素を返却

getLinearTransformMatrix

• getLinearTransformMatrix(x1i,y1i,x2i,y2i,x3i,y3i,x1o,y1o,x2o,y2o,x3o,y3o) : ３つの基準点の変換前後の座標を与えると、それに適合する1次変換行列が得られる。(*i:変換前の座標, *o:変換後の座標)

getMapCanvas

• getMapCanvas() : 地図キャンバスとなる、おおもとのdiv要素の取得

getMapCanvasSize

• getMapCanvasSize() : 地図キャンバスのサイズ(画面サイズ)を取得

getMouseXY

• getMouseXY( evt ) : 指定されたイベント時のマウスの画面上の座標(px)を返す

getNonScalingOffset

• getNonScalingOffset(svgPoiNode) : 拡大縮小しても伸縮しない図形要素のオフセット値を取得する

getObject

• getObject( oname ) : 指定されたオブジェクト(oname)を取得

getPoiPos

• getPoiPos( svgPoiNode ) : =getNonScalingOffset

getRoot2Geo

• getRoot2Geo() : コンテナsvgのCRSの逆変換CRS( rootのsvg - > geo )を取得

getRootCrs

• getRootCrs() : コンテナsvgのCRS ( geo->rootのsvg )を取得

getRootLayersProps

• getRootLayersProps() : コンテナsvgコンテンツの(animetion||iframeで構成される)レイヤー情報を取得する。Arrayが返却、並び順はsvgのコンテナsvgコンテンツと同じ（最初のレイヤーが一番下。selectメニュー創るときはひっくり返して使うこと）レイヤー情報：名称、表示非常時状態、レイヤーグループ、グループのフィーチャ(バッチ||スイッチ||ふつう)、編集可、編集中、対応SVGドキュメント、個別ユーザインターフェース、個別凡例

getRootViewBox

• getRootViewBox() : aspectを加味し実際に開いているコンテナsvgのviewBoxを取得

getSvgImages

• getSvgImages() : svg文書群(XML)の連想配列を取得(ハッシュキーはlayerID("root"以外は"i"+連番))
• (参考:svgImages)

getSvgImagesProps

• getSvgImagesProps() : svg文書群のプロパティ( .Path,.CRS,.script,.editable,.editing,.isClickable,.parentDocId,.childImages,.controller)の連想配列を取得(ハッシュキーはlayerID("root"以外は"i"+連番))
• (参考:svgImagesProps)

getSvgTarget

• getSvgTarget( htmlImg ) : html文書中のimg要素(POI)を入力すると、対応するSVG文書の文書番号とその要素(use)が出力される。対応するuse要素を持つsvg文書自体を取得したい場合は.ownerDocumentする。idからhtml文書のimg要素を取得するには、Document.gelElementById(id)

getSwLayers

• getSwLayers ( cat ) : swLayers[クラス名]に、クラス名ごとのレイヤー(のSVG要素)の全リストを構築する。catがある場合は、catの名称を持つもののリストのみを構築する

getSymbols

• getSymbols(svgDoc) : POI編集のsymbol選択を可能にするとともに、defsは、useより前に無いといけないという制約を払った

getTickerMetadata

• getTickerMetadata() : 現在Tickerが表示されているグラフィックスオブジェクトのメタデータを取得する

getTransformedBox

• getTransformedBox ( inBox , matrix ) : 指定されたviewBox(inBox)を変換行列にてサイズ変更と移動のみでの座標変換する。b=0、c=0の場合のみ利用可能。たとえば、matrixには、svgImagePropsのCRSを設定することで、そのSVGMapコンテンツのSVG座標系でのviewPortが計算できる。このときmatrixは線形変換の係数が含まれたオブジェクトでも良いし、非線形変換のための関数が含まれたオブジェクトでも良い。　svgMap.getTransformedBox(svgMap.getGeoViewBox(),svgImageProps.CRS)

getUaProp

• getUaProp() : ブラウザの種類(isIE：IEかどうか、isSP：スマートフォンかどうか)を取得する

getVerticalScreenScale

• getVerticalScreenScale(screenLength) : 垂直(緯度)方向のscreenLengthに対する長さを取得する(input: px, return : Km)

getViewBox

• getViewBox( svgDoc ) : 指定したSVG文書のviewBoxを取得

gps

• gps() : ブラウザの測位APIによって測位しその点を中心に表示、表示縮尺は測位精度を元に適当に決定

gpsCallback

• gpsCallback(position) : GPS測位が成功した後に実行されるコールバック関数で、positionを中心とした場所を表示させる

handleResult

• handleResult( docId , docPath , parentElem , httpRes , parentSvgDocId ) : SVG文書を(docPathから)svg文書群とそのプロパティをHTTPXMLRequest(httpRes)から親文書(parentSvgDocId)の子文書(docId)として読込み、指定されたHTML要素(parentElem)に貼り付ける

ignoreMapAspect

• ignoreMapAspect() : 地図のアスペクト比を、rootSVGのviewBox( or hashのviewBox)そのものに設定する

initLoad

• initLoad() : load時に"一回だけ"呼ばれる初期化関数

isIntersect

• isIntersect( rect1, rect2 ): rect1(x,y,width,height)とrect2が交差(包含も含む)しているかどうかを返却

linkedDocOp

• linkedDocOp( func , docHash , param1, param2 , param3 , param4 , param5 ) : 再帰実行のルートになる文書のハッシュ(docHash)以下の子・孫・・・文書に対して、同じ処理(func( docHash , param1, param2 , param3 , param4 , param5 ))を再帰実行する関数

loadSVG

• loadSVG( path , id , parentElem , parentSvgDocId) : SVG文書を(pathから)svg文書群とそのプロパティを親文書(parentSvgDocId)の子文書(id)として読込み、指定されたHTML要素(parentElem)に貼り付ける

matMul

• matMul( m1 , m2 ) : 行列の積 x',y' = m2(m1(x,y)) = m(x,y) となる変換行列を構築

numberFormat

• numberFormat( number , digits ) : 指定された数値(number)を小数点以下第digit+1位を四捨五入した値を取得

override

• override( mname , mval ) : グローバルオブジェクトの関数プロパティでmnameという変数にmvalの値を代入する

parseEscapedCsvLine

• parseEscapedCsvLine(csv) : CSV 1行分文字列データ(csv)をエスケープを考慮して配列にパースする。

refreshScreen

• refreshScreen() : 画面の再描画を実行する （参考情報）

registLayerUiSetter

• registLayerUiSetter( layerUIinitFunc, layerUIupdateFunc ) : レイヤー選択UI初期化関数と更新用関数を設定する

reLoadLayer

• reLoadLayer(layerID_Numb_Title) : 指定したレイヤー(コンテナsvgコンテンツのレイヤーのみ。小孫レイヤーはNG)をリロードする

resumeToggle

• resumeToggle(evt) : 引数のイベント(evt)ターゲットのチェックボックスのチェック状態により、setResumeを実行する

screen2Geo

• screen2Geo( screenX , screenY ) : 画面上の座標(px)を指定すると、その地理座標を返す

setCustomModal

• setCustomModal( messageHTML , buttonMessages , callback,callbackParam) : モーダル画面を出現させ、指定されたメッセージ(messageHTML(String)もしくはdomオブジェクト(Object))、指定されたボタン(buttonMessages(Array))を表示する。ボタンが押された場合、コールバック関数(callback)を引数(クリックしたボタンのインデックス, callbackParam)を渡し呼び出す。

messageにHTML Stringだけではなく、DOM objectが使える点、ボタンに対するcallbackを設定できる点。ただしモーダルダイアログになる点が#showModalと異なる。

setDevicePixelRatio

• setDevicePixelRatio( dpr (, layerId) ) : zoom計算時に用いる(たとえば２にするとzoom値が本来の２分の１になる)変数を指定値(dpr)に設定する。ズームに応じた表示制御(visible*zoom属性等のLevel of Detail機能)に影響を与える。オプションのlayerIdを指定すると、指定したlayerに対して別個の値を設定する。dprにnullを与えると初期値(1)にクリア。

setGeoCenter

• setGeoCenter( lat , lng , radius) : 中心地理座標を指定して地図を移動 (radiusは緯度方向の度1≒110Km) lat,lng:必須 radius:オプション(今の縮尺のまま移動)

setGeoViewPort

• setGeoViewPort( lat, lng, latSpan , lngSpan , norefresh) : 地理(グローバル)座標系で指定したエリアを包含する最小のviewportを設定する

setLayerVisibility

• setLayerVisibility(layerID_Numb_Title) : 指定したコンテナsvgコンテンツのレイヤーの表示非表示を設定し、layerListUIのアップデートも行う

setMapCanvas :

• setMapCanvas : ( mc ) : 地図キャンバスとなる、おおもとのdiv要素を指定した要素(mc)に設定

setMapCanvasCSS

• setMapCanvasCSS(mc) : マップキャンバスのCSS(postion、overflow、top、left、width、height)を設定

setMapCanvasSize

• setMapCanvasSize( mcs ) : 地図キャンバスのサイズを指定したサイズ(mcs)に設定

setPreRenderController

• setPreRenderController( layerID, cntFunc ) : 再描画(画面更新)シーケンスの直前に実行する関数(cntFunc)を設定する。　layerIDが指定されていると、そのIDをもつSVG文書に対して設定する。指定されていない場合は、全てのSVG文書に対して指定した関数が描画前に実行される。cnfFuncが無い場合は設定を解除する。また、cntFuncには再描画前制御の際に必要になるかもしれないいくつかの変数が第一引数にオブジェクトの形で渡される。(docId,scale,actualViewBox,geoViewBox,viewChanged(zoom|scroll|false) なお、SVGMapLayerUI.jsが有効化されている場合、レイヤ固有UIのhtml文書中のscript内にpreRenderFunctionという関数がある場合、そのレイヤーを指定したsetPreRenderControllerでの関数設定と同じ振る舞いをする。なお、この処理内容は、動的レイヤー(<script>を持つSVGコンテンツ)のonload関数と同じタイミングで呼び出される関数をレイヤ固有UI等に設置できるものと考えると良い。

setResume

• setResume( stat ) : レジュームを実行するかどうかを引数(stat)によって設定し、cookieにレイヤー情報を保存する

setRootLayersProps

• setRootLayersProps(layerID_Numb_Title, visible , editing ) : コンテナsvgコンテンツの(animetion||iframeで構成される)レイヤー情報を設定する。layerID_Numb_Titleは、レイヤー番号(root svg container内での順番)、layerID(svg文書のiid = htmlのid = selectのvalue)、タイトル名(不確実-同じ名前があるかもしれない。最初に当たったものを選択)。変化があるとtrueが返却される。visible , editingはtrue,false,nullのいずれか。nullの場合、その値を変化させないという意味。もしくは不合理の場合はfalseが返却される。この時classで設定されているレイヤーグループの特性(switch)に基づいた制御がかかる　ただしsetLayerVisibilityと異なり、アップデート(refreshScreen())は別途行う必要がある

setRootViewBox

• setRootViewBox ( rvb ) : aspectを加味し実際に開いているコンテナsvgのviewBoxを指定したコンテナsvgのviewBox(rvg)に設定*setShowPoiProperty( func , docId ) : 特定のレイヤー・svg文書(docId)もしくは、全体に対して別のprop.表示関数(func)を指定する。funcが未指定の場合、設定された関数をクリアする。指定した関数は、帰り値がfalseだった場合、デフォルトprop.表示関数を再度呼び出す

setShowPoiProperty

• setShowPoiProperty(func , docId ): 特定のレイヤー・svg文書(いずれもdocIDで指定)もしくは、全体に対してPOIをクリックした時の表示関数をセットする
  • セットされていないときは内蔵のデフォルト関数が使用される
  • docId: セットされていないときはすべてのレイヤの docIdがルートレイヤに対応するものの場合はそのレイヤー下の子孫文書に対しても
  • func: コールバック関数
    • funcがセットされいていないときはクリアする
    • funcの第一引数にはクリックされた要素が入る

setSmoothZoomInterval

• setSmoothZoomInterval(zoomInterval) : ズームアニメーションの設定(ズームイン／アウト後のタイル読み込み開始タイマー(ms))(Default:20ms)

setSmoothZoomTransitionTime

• setSmoothZoomTransitionTime(zoomTransitionTime) : ズームイン／アウト時の遷移時間(Default:300ms)

setSummarizeCanvas

• setSummarizeCanvas( val ) : 2Dベクトル図形描画用に統合キャンバス(レイヤー単位でのキャンバス統合)の使用有無を設定する。デフォルトは統合する

setUpdateCenterPos

• setUpdateCenterPos(func) : 中心座標書き換え関数を指定した関数に設定(デフォルト:id="centerPos"要素の文字列を適当に書き換える)

setProxyURLFactory

• setProxyURLFactory( documentURLviaProxyFunction, imageURLviaProxyFunction, imageCrossOriginAnonymous, imageURLviaProxyFunctionForNonlinearTransformation, imageCrossOriginAnonymousForNonlinearTransformation ): コンテンツの取得をプロキシ経由にする。
  • documentURLviaProxyFunction : svgドキュメント用のプロキシ経由のURLを生成する関数をここに設定する。URLviaProxy = documentURLviaProxyFunction(URL)
  • imageURLviaProxyFunction : 同ビットイメージ用
  • imageCrossOriginAnonymous : ビットイメージのコンテンツ取得に際しcrossorigin = "anonymous"を設定
  • imageURLviaProxyFunctionForNonlinearTransformation: ビットイメージへの非線形図法変換専用のプロキシ経由URL生成関数を設定する。
  • imageCrossOriginAnonymousForNonlinearTransformation : 同上のコンテンツ取得に際しcrossorigin = "anonymous"を設定
  • 参考：クロスオリジンアクセスのためのプロキシ設定

setZoomRatio

• setZoomRatio ( ratio ) : zoomUp、zoomDownボタン押下時のズームレシオを指定した値(ratio)に設定する

showModal

• showModal( htm , maxW, maxH) : ダイアログ表示フレームワークを呼び出し、指定したhtm文字列を最大maxW,H値の中で表示する。closeボタンはフレームワークで設置される （参考#setCustomModal）（API名に反して、この関数はモーダルダイアログではない、ダイアログボックスの挙動を取る）
  • htm：ダイアログ内に表示するhtmlのソース文字列
  • maxW, maxH : ダイアログのサイズ（もしウィンドサイズに収まらない場合は、このサイズを下回ることがある
  • Note: ダイアログに設置できる情報は、文字列で与えたhtmlのソースだけに限定される。　もしこのダイアログ内にボタン等を設け、処理を実行したい場合は、#setCustomModalを用いるか、<input onclick="javascriptソースコード">　のようにインラインで処理を埋め込むかする

showPage

• showPage( hyperLink ) : 指定されたハイパーリンク先のページを表示する。ハッシュだけの場合は viewPort変化をさせる

showUseProperty

• showUseProperty( target ) : 指定されたPOI( target )の属性情報を表示する

transform

• transform ( x , y , mat , calcSize , nonScaling) : 指定された座標を変換する。

updateLayerListUI

• updateLayerListUI() : レイヤーリストのUIの表示を更新したりレイヤー固有UIを設定したりする
  • ルートコンテナのsvgmap文書をDOMで直接編集したり、setRootLayersPropsで操作した場合、この関数を呼ばないとレイヤ固有UIが正しく設定されないなど多くの処理が破綻するので、必ず呼ぶ必要がある。(近い将来refreshScreenで自動的に反映されるようにする予定)

zoomdown

• zoomdown() : 同ズームダウン

zoomup

• zoomup() : 地図をズームアップ：倍率は1.732倍固定

svgMapAuthoringTool.で呼び出せるAPI

以下のAPIは、SVGMapLv0.1_Authoring_r*.jsを用いた場合に使える

cancelPointingPoiRegister

• cancelPointingPoiRegister: initPOIregistToolで設置したUIの地図クリック・タッチでの座標入力イベント(click, touchend)をキャンセルする

clearTools

• clearTools: オーサリングツールを除去する。

initGenericTool

• initGenericTool(targetDiv,poiDocId,cbFunc,cbFuncParam,options): 点、線、多角形（オプションでそれらのバッファ付き）の総合オーサリングツールを初期化する。
  • targetDiv: 編集ツールを設置するDIV要素
  • poiDocId : 対象とするDocId　文書にはuse要素でPointを設置するため、defs要素によって少なくとも一個以上のアイコンがあらかじめ定義されている必要がある
  • cbFunc : 編集完了時に呼び出すコールバック関数(Optional)　第一引数にはツールの完了状態が文字列で返却される
  • cbFuncParam : 同コールバック関数に渡す引数(Optional)
  • options: {withBufferedTools,editingStyle,shapeStyle}　その他オプションをオブジェクトで指定(Optional)
    • withBufferedTools: boolean: trueでバッファ付きツールを追加
    • shapeStyle: {opacity,strokeWidth,stroke,fill}：描画スタイルをブジェクトで指定
    • editingStyle: {opacity,strokeWidth,stroke,fill}：編集中の表示スタイルをブジェクトで指定

initPOItools

• initPOItools(targetDiv,poiDocId,cbFunc,cbFuncParam,getPointOnly,returnSvgElement,options)　: 複数のPOIを編集するツールを初期化する (このツールは一個しか設置できない)
  • targetDiv: 編集ツールを設置するDIV要素
  • poiDocId : 対象とするDocId　文書にはuse要素でPointを設置するため、defs要素によって少なくとも一個以上のアイコンがあらかじめ定義されている必要がある
  • cbFunc : 編集完了時に呼び出すコールバック関数(Optional)　第一引数にはツールの完了状態が文字列で返却される
  • cbFuncParam : 同コールバック関数に渡す引数(Optional)
  • getPointOnly : ポイントを取得するのみで、その点にuse要素を設置することはしない(Optional)
  • returnSvgElement : trueで編集したSVG要素などがコールバック関数に構造化され返却される(Optional)
  • options : {bufferOption,editingStyle,shapeStyle}: その他のオプションをオブジェクトで指定(Optional)
    • bufferOption : trueでバッファ付きツール
    • shapeStyle: {opacity,strokeWidth,stroke,fill}：描画スタイルを指定 (buffer指定時に有効)

initPOIregistTool

• initPOIregistTool(targetDiv,poiDocId,poiId,iconId,title,metaData,cbFunc,cbFuncParam,getPointOnly,returnSvgElement): 一個のPOINTオブジェクトの登録ツール・座標入力ツールを初期化する
  • initPOItoolsと異なりこちらのツールは複数個設置できる
  • targetDiv: 編集ツールを設置するDIV要素
  • poiDocId : 対象とするDocId　文書にはuse要素でPointを設置するため、defs要素によって少なくとも一個以上のアイコンがあらかじめ定義されている必要がある
  • poiId : 登録するPOIのIDを指定
  • iconId : 対象文書内のアイコンのIDを指定
  • title : アイコンのタイトルを指定
  • metaData : アイコンのメタデータ文字列を指定
  • cbFunc : 編集完了時に呼び出すコールバック関数(Optional)
  • cbFuncParam : 同コールバック関数に渡す引数(Optional)
  • getPointOnly : ポイントを取得するのみで、その点にuse要素を設置することはしない(Optional)
  • returnSvgElement : trueで編集したSVG要素などがコールバック関数に構造化され返却される(Optional)

initPolygonTools

• initPolygonTools(targetDiv,poiDocId,cbFunc,cbFuncParam,isPolylineMode,options): POLYGONオブジェクトの"編集"ツール 新規追加、削除、変更などが可能　ただし一個しか設置できない
  • コンテナsvgコンテンツでclickable及びeditableを設定したレイヤーで再編集可能
  • targetDiv: 編集ツールを設置するDIV要素
  • poiDocId : 対象とするDocId　文書にはuse要素でPointを設置するため、defs要素によって少なくとも一個以上のアイコンがあらかじめ定義されている必要がある
  • cbFunc : 編集完了時に呼び出すコールバック関数(Optional)　第一引数にはツールの完了状態が文字列で返却される
    • 第一引数に成否、第二引数にcbFuncParam が入る。作成したPOIの情報は、SVGDOMから得るか、指定したdiv内に生成されているフォームから得る（少し使いづらいので、今後もう少し便利にするかもしれません）
  • cbFuncParam : 同コールバック関数に渡す引数(Optional)
  • isPolylineMode : ポリゴンではなくポリラインの編集ツールとする
  • options : {bufferOption,editingStyle,shapeStyle}: その他のオプションをオブジェクトで指定(Optional)
    • bufferOption : trueでバッファ付きツール
    • shapeStyle: {opacity,strokeWidth,stroke,fill}：描画スタイルを指定
    • editingStyle: {opacity,strokeWidth,stroke,fill}：編集中の表示スタイルを指定

setTargetObject

• setTargetObject: TBD プログラムから編集対象オブジェクトを指示する（ただし編集中レイヤのオブジェクトに限る）

isEditingGraphicsElement

• isEditingGraphicsElement: 編集中のオブジェクトがあるかどうかを確認する

svgMapGIStool.で呼び出せるAPI

以下のAPIは、SVGMapLv0.1_GIS_r*.jsを用いた場合に使える。なお本機能拡張はJSTS(jsts.min.js)の読み込みがさらに必要。

参考：JSTS

JSTS(JavaScript Topology Suite)は、JTS(Java Topology Suite)をjavaScriptに移植した地理空間情報処理ライブラリです。地理空間情報の標準に準拠したAPIを備えています。

• JSTSのプロジェクトページ
• API(JTS用、JSTSもこれに準ずる)
• JTSの機能概要スライド

buildDifference

• buildDifference( sourceId1, sourceId2, targetId , strokeColor, strokeWidth, fillColor, progrssCallback, getResultAsGeoJsonCallback,getResultAsGeoJsonCallbackParam)
  • JSTSのDifferenceを実行
  • 引数はbuildIntersectionの該当引数に対応

buildIntersection

• buildIntersection( sourceId1, sourceId2, targetId , strokeColor, strokeWidth, fillColor, progrssCallback, addSourceMetadata, getResultAsGeoJsonCallback, getResultAsGeoJsonCallbackParam, options )
  • sourceId1とsourceId2のレイヤーに対してJSTSのIntersectionを実行し、結果をtargetIdレイヤーにコンテンツとして出力する。性能はgetIncludedPointsより低いことが多い intersection処理の振る舞いはJSTSを参照
  • sourceId1: sourceId1レイヤーのレイヤーID
  • sourceId2: sourceId2レイヤーのレイヤーID
  • targetId : targetId レイヤーのレイヤーID
  • strokeColor : 線の色 (なお、strokeColor, strokeWidth, fillColor のいずれも指定ない場合は描画しない(getResultAsGeoJsonCallbackがあればそこに結果を変換するのみ))
  • strokeWidth : 線幅（ただし、nonScalingStrokeのため px)
  • fillColor : 塗りの色
  • progrssCallback: 変換途中の状況が返されるコールバック関数。
  • addSourceMetadata: sourceId1とsourceId2の各図形要素に付随しているメタデータ(contentアトリビュートの値)を演算結果の該当する図形要素に結合して付加する。
  • getResultAsGeoJsonCallback: 演算結果をgeoJsonで返却を受けたい場合にコールバック関数を指定する。第一引数に結果が返る
  • getResultAsGeoJsonCallbackParam : 上記コールバック関数に送りたい引数(第二引数に入力される)
  • options: その他のオプションを指定するオブジェクト(下記、メンバ変数)
    • uniteSource1: trueでsourceId1のジオメトリ群をuniteしてから演算する
    • uniteSource2: trueでsourceId2のジオメトリ群をuniteしてから演算する
    • areaCompare: trueで演算結果と元のジオメトリとの面積比をメタデータに付与
    • resultGroupId: 演算結果を生成するグループを指定
    • opacity: 透明度

captureGeometries

• captureGeometries( cbFunc , opt ) : svgMap.captureGISgeometriesの引用

coverageImageXY2LatLng

• coverageImageXY2LatLng(pixWidth , pixHeight, px,py,targetCoverage) : ビットイメージカバレッジのピクセル座標から地理座標を算出する関数
  • pixWidth, pixHeight : ビットイメージカバレッジのサイズ
  • px,py : ビットイメージカバレッジのピクセル座標
  • targetCoverage : getInRangePolygonParts で得られた返り値を設定する

drawGeoJson

• drawGeoJson( geojson , targetSvgDocId, strokeColor, strokeWidth, fillColor, POIiconId, poiTitle, metadata, parentElm, metaDictionary) : geojsonのgeomerty を指定したレイヤーに描画する
  • geojson : geojson データのgeopmetry
    • メタデータ : メタデータはgeojsonの本来のメタデータ仕様(type:Featureのオブジェクトにpropertiesを設置する)で設定可能
      • また、連想配列もしくは配列の形で、関数の呼び出し時のmetadataパラメータでデフォルトのメタデータを指定できる。
      • また、geoJSONの任意のデータ階層にmetadataプロパティとしても埋め込める。
      • 加えて、propertiesを同様に任意のデータ階層に設定できる(この場合、上の階層の値は下の階層の値で上書きされる)
    • スタイリング : メタデータ仕様を拡張した、geojsonのmapbox拡張仕様に基づいて、描画スタイルを各Featureに設定可能　上記の拡張properties拡張により、デフォルト描画スタイルを設定することも可能。
      • marker-sizeは未実装。marker-symbolではsvgコンテンツのdefsで登録済みのアイコンのIDを指定する。
      • 参考: properties.で設定できる、スタイル属性名: title, description, marker-size, marker-symbol, marker-color, stroke, stroke-opacity, stroke-width, fill, fill-opacity
  • targetSvgDocId : 描画先のレイヤーID
  • strokeColor : 線の色
  • strokeWidth : 線幅（ただし、nonScalingStrokeのため px)
  • fillColor : 塗りの色
  • POIiconId :　Pointの場合のアイコンID(あらかじめ指定した描画先のレイヤーのコンテンツに該当IDのアイコンが定義されている必要がある)
  • poiTitle : POIのタイトル
  • metadata : POIのメタデータ（連想配列）
  • parentElm : (Optional) 指定した要素の子要素として描画
  • metaDictionary: (Optional) メタデータとして要素に埋め込みたい属性名のリストを配列で指定する（これ以外の属性は無視するようになる）

drawKml

• drawKml( kml , targetSvgDocId, strokeColor, strokeWidth, fillColor, POIiconId, poiTitle, metadata, parentElm,styleData) : KMLを指定したレイヤーに描画する
  • KML : KML 描画するKMLデータのXML DOM
  • targetSvgDocId : 描画先のレイヤーID
  • strokeColor : 線の色
  • strokeWidth : 線幅（ただし、nonScalingStrokeのため px)
  • fillColor : 塗りの色
  • POIiconId :　Pointの場合のアイコンID(あらかじめ指定した描画先のレイヤーのコンテンツに該当IDのアイコンが定義されている必要がある)
  • poiTitle : POIのタイトル
  • metadata : POIのメタデータ文字列
  • parentElm : (Optional) 指定した要素の子要素として描画
  • styleData : TBD

getBufferedPolygon

• getBufferedPolygon(geom,bufferLength) : 任意のジオメトリ(geom)に対して、指定のバッファ長[m]のポリゴンジオメトリを生成する。
  • Note: #captureGISgeometriesで取得したデータ等も演算対象にすることができる。

getColorString

• getColorString(r,g,b) : r,g,b値から、webColor文字列を生成する

getExcludedPoints

• getExcludedPoints(poiID, polyID, cbFunc, param , progrssCallback , pointOnly ) : 指定したpoiID検索対象レイヤーのうち、指定したpolyIDポリゴンコンテンツレイヤーのポリゴンに内包されないものを抽出する。
  • パラメータはinverseを除きgetIncludedPointsと同じ。

getImage

• getImage(sourceData, renderingOptions ) : メッシュデータからビットイメージ(mage/pngのdataURL)を生成
  • sourceData : 以下のデータ構造を持つオブジェクト
    • width, height メッシュのピクセル数
    • rasterData[py][px] 以下のデータ構造を持つオブジェクト
      • color 以下のデータ構造を持つオブジェクト
        • r,g,b,a
      • inRange : boolean
  • renderingOptions : 以下のデータ構造を持つオブジェクト
    • drawOutOfRange : boolean レンジ内ではなくレンジ外を描画する
    • fillColor : boolean 上記条件のピクセルを指定した色で描画する
    • useCoverageColor 上記条件のピクセルをカバレッジの色で描画する

getIncludedPoints

• getIncludedPoints(poiID, polyID, cbFunc, param , progrssCallback , inverse , pointOnly ) : 指定したpoiID検索対象レイヤーのうち、指定したpolyIDポリゴンコンテンツレイヤーのポリゴンに内包されるものを抽出する。
  • poiID : 検索対象コンテンツレイヤーのレイヤID
  • polyID : ポリゴンコンテンツレイヤーのレイヤID
  • cbFunc : 検索完了後の結果を返却するコールバック関数　第一引数にポイントがGeoJasonのGeometry形式で返却され、第二引数にその個数、第三引数に(あれば)下記paramが返却される
  • param : cbFuncに渡す任意パラメータ(第三引数に入る)
  • progrssCallback : 変換途中の状況が返されるコールバック関数。　変換中　時々呼び出され、変換状態[%]が第一引数に渡される。
  • inverse : trueで getExcludedPoints
  • pointOnly : trueの場合検索対象コンテンツレイヤーのジオメトリがPoint以外の物は無視、false(もしくは未設定)の場合はPolygonやMultiLineStringのデータの場合中心点をPointと見立てて検索 なお、ポリゴンやポリラインのしっかりした処理を期待する場合は下記のbuildIntersectionを使用すべき。

getInRangePoints

• getInRangePoints(poiID_or_points, coverID, rangeData, cbFunc, param , progrssCallback , preCapturedGeometry , computingOptions ) : 検索対象のPointジオメトリが、検索条件としてのラスターデータ(カバレッジ)の特定色域に入っているものを検索する（ラスターGIS機能）
  • poiID_or_points : 検索対象のPointジオメトリのあるレイヤIDもしくは、geoJsonのPointジオメトリ自体
  • coverIDラスターデータ(カバレッジ)のレイヤーID
  • rangeData : 色域 .hue, .satulation, .value, .alphaをそれぞれ指定する
    • hue: 0..360
    • satulation, value, alpha : 0..100
    • .hue, .satulation, .value, .alphaそれぞれのレンジは[[range1Min,Max],[range2Min,Max],...[rangenMin,Max]]の形で指定する。
    • データがない場合のデフォルトは{hue:[[0,360]],satulation: [[10,100]],value:[[10,100]],alpha:[[10,100]]} : アルファが10以上の全ての色
    • .outOfBoundsColor : TBD {r:255,g:0,b:0} の形で色を指定するとその色のピクセルは領域外(存在しないもの)として評価をスキップする
  • cbFunc : 検索完了後の結果を返却するコールバック関数　第一引数にポイントがGeoJasonのGeometry形式で返却され、第二引数にその個数、第三引数に(あれば)下記paramが返却される
  • param : cbFuncに渡す任意パラメータ(第三引数に入る)
  • progrssCallback : 変換途中の状況が返されるコールバック関数。　変換中　時々呼び出され、変換状態[%]が第一引数に渡される。
  • preCapturedGeometry : svgMap.captureGISgeometries()であらかじめ取得したgeometryがある場合、それを投入するとそれを用いて処理する
  • computingOptions : getInRangeGeometriesOnCoverageを参照

getInRangeLineParts

• getInRangeLineParts(poiID_or_points, coverID, rangeData, cbFunc, param , progrssCallback , preCapturedGeometry , computingOptions ) : ラインストリングジオメトリ用のラスターGIS機能 パラメータはgetInRangePoints()と同じ

getInRangePolygonParts

• getInRangePolygonParts(poiID_or_points, coverID, rangeData, cbFunc, param , progrssCallback , preCapturedGeometry , computingOptions ) : ポリゴンジオメトリ用のラスターGIS機能 パラメータはgetInRangePoints()と同じ

getInRangeGeometriesOnCoverage

• getInRangeGeometriesOnCoverage(poiID_or_points, coverID, rangeData, cbFunc, param , progrssCallback , preCapturedGeometry, computingOptions ) : getInRange*を包含する関数
  • computingOptions.targetVectorTypeで以下を設定することでそれぞれの機能を動かすことができる
    • 0:point,1:polyline(multiLineString),2:polygon
  • computingOptions:
    • overlappingCoverage : "or"
    • splitByCoverage : boolean カバレッジが複数のビットイメージ(タイル)で構成されている場合、タイルごとに分割した答えを返す

haltComputing

• haltComputing() : getIncludedPoints, getExcludedPoints, buildIntersectionを中断する

imageUrlEncoder

• imageUrlEncoder : オリジナルのURLから、setImageProxyの設定を加味したURLを生成する関数

latLng2coverageImageXY

• latLng2coverageImageXY(pixWidth , pixHeight, lng,lat,targetCoverage) : 地理座標からビットイメージカバレッジのピクセル座標を算出する関数
  • pixWidth, pixHeight : ビットイメージカバレッジのサイズ
  • lng,lat : 地理座標
  • targetCoverage : getInRangePolygonParts で得られた返り値を設定する

latLng2GeoJsonPoint

• latLng2GeoJsonPoint(lat , lng ) : 緯度経度をGeoJsonのPointジオメトリに変換する

renderImages

• renderImages(sourceDataArray, parentElment, crs, renderingOptions) : ビットイメージカバレッジ×ポリゴンGIS(getInRangePolygonParts)の結果を直接可視化する
  • sourceDataArray : #getInRangePolygonPartsの結果を設定
  • parentElment: SVGMapコンテンツ内で描画する親要素を設定
  • crs: 描画するSVGMapコンテンツのCRS matrix(a,b,c,d,e,f)を設定
  • renderingOptions : #getImageを参照

setImageProxy

• setImageProxy( url , directURLls , useAnonProxy): getInRangePointsは、canvasを使った処理のため、CORSの制約にかかる場合、proxyを設定して回避できる。
  • url : encodeURIComponent()でエンコードしたカバレッジのレイヤーのビットイメージのURLを付加すると、proxyとしてimageを返却してくれるURL文字列を指定
  • directURLls : proxyを使わず直接アクセスするコンテンツを判定するための文字列の配列（この文字列のどれかが含まれていたら直接アクセス）
  • useAnonProxy : Image.crossOrigin = "anonymous"を指定してアクセスする

hsv2rgb

• hsv2rgb(h, s, v) : hsv値からrgb値の色情報変換
  • h (hue): 0..360
  • s (saturation): 0..100
  • v (value): 0..100
  • 帰り値 : {r,g,b}: いずれも0..255

rgb2hsv

• rgb2hsv(r, g, b): RGB値からHSV値の色情報変換
  • rgb: いずれも0..255
  • 帰り値:{h,s,v}
    • h:0..360
    • s,v: いずれも0..100

svgMapLayerUI.で呼び出せるAPI

以下のAPIは、SVGMapLv0.1_LayerUI2_r*.jsを用いた場合に使える。

assignLayerSpecificUiElement

• >r4
• assignLayerSpecificUiElement( targetElement , isInline , autoSizing) : レイヤ固有UIを出力する先のDOM要素を指定する
  • この関数は、レイヤーUIの初期化前～コンテナsvgコンテンツ読み込み前に呼ばれる必要がある（すなわち、load時のみ有効）
  • targetElement : 出力先要素：出力先はsvgMapオブジェクトを持つwindowでなくても良い
  • isInline : boolean 指定した要素をインライン要素として扱い、UIが存在しえない場合は消える。レイヤ固有UIを消すボタンも付与される
  • autoSizing : boolean 自動リサイズを有効化

customEvents

• customEvents() : サポートしているイベントを返却

launchController

• >r4
• launchController(layerID, cbf) : レイヤ固有UIを出現させる。ただしそのレイヤーがレイヤー固有UIを持っており、且つ表示状態になっている必要がある。
  • layerID : レイヤーのID
  • cbf (optional) : レイヤー固有UIが生成されたとき、第一引数にレイヤー固有UIのwindowオブジェクトが返却される。

layerSpecificUIhide

• layerSpecificUIhide() : レイヤ固有UIを隠す

setLayerListmessage

• setLayerListmessage( head , foot ) : head 及び footで指定した文字列を　レイヤリストUIのトップのメッセージに設定する。[head]numberOfVisibleLayers[foot] : デフォルトはhead :"Layer List: ", foot :" layers visible"

svgMapCesiumWrapper.で呼び出せるAPI

実験的機能段階 :

- 以下のAPIは、SVGMapLv0.1_CesiumWrapper_r*.jsを用いた場合に使える。

- また、ここから呼び出されるCesiumビジュアライザーは、それ専用のwebApps(cesiumWindow*.jsを読み込んだもの)を備えた別のブラウジングコンテキストで起動される。

- 詳細はサンプルページを参照。(TBD)

- CESIUM起動用のボタンやパラメータ設定用UIはライブラリが

- svgMapCesiumWrapper.setCesiumWindowHtmlLocationで連携用WebAppsを指定

-

<img id="3DviewButton" .../>

で3D可視化アイコンを設置することで3D可視化機能が起動

• openCesium(callBackFunc)

  cesiumのオブジェクトが構築されるのを待ちつつcesiumのwindowをオープンする。 callBackFuncがある場合は、cesiumWindowが準備されたらそれを実行する

• visualizeCurrentSvgMap(complex)

  3D可視化ボタンを押したときに最初に呼び出される関数 complex:"true"の場合POIのバーグラフ化を行う

• getCesiumWindow()

  連携用CesiumビジュアライザーのWindowオブジェクトを取得

• setCesiumWindowHtmlLocation(path)

  pathで連携Cesiumビジュアライザーを指定する

  • 連携用Cesiumビジュアライザーの説明

    連携用ライブラリcesiumWindow*.jsが読み込まれた、WebApps(htmlコンテンツ)

    reldir2imageUrlグローバル変数に、SVGMapコンテンツのコンテナsvgコンテンツのあるディレクトリを指定

    directURLlistでプロキシへ接続しなくて良いデータのURLのキーワードを指定

    cesiumProxyURLでプロキシ―サーバの相対パスを指定(cesiumはビットイメージデータもCORに則ったコンテンツでないと読み込めないため)

    cesiumWindow*.jsは上記のパスの後に、取得すべきコンテンツのURLを単純に文字列として追加してプロキシにリクエストを出す

svgMapPWA.で呼び出せるAPI

実験的機能段階 :

以下のAPIは、SVGMapLv0.1_PWA_r*.jsを用いた場合に使える。

- SVGMap.jsをPrpgressiveWebApps(PWA)として動作させ、オフラインでも利用できるウェブアプリを構築することができる。

- Progressive Web Appsが機能するブラウザで有効。Chrome,Edge(PC,Android), Safari(Apple製品)

- iOS SafariのPWAネイティブキャッシュの50MB制限を回避するIndexedDBによる実装がなされており、そのクォータが許す限りの(iOSでも数百MB以上の)オフライン地図コンテンツを利用できる

- 同じく、iOS Safariが持たないsyncの一部を代替する機能(オンラインになったらポストする機能)が利用できる

- zip圧縮されたオフラインコンテンツパッケージ読み込み機構を使う場合はzip.jsおよびそれが利用するArrayBufferReader.js,deflate.js,inflate.jsの読み込みが必要。

- serviceWorkerPathグローバル変数で、専用のサービスワーカープログラムsvgMapServiceWorker_r*.jsのパスを指定する必要がある。

- サービスワーカー～svgMapServiceWorker_r*.jsは、同jsと同じディレクトリにあるbaseResources.jsonを読み込み初期設定を行う

- baseResources.json：　srcにサービスワーカーネイティブのキャッシュに読み込むべきリソースのリストを記載、mapCacheTargetに、SVGMapのコンテンツキャッシュを稼働させるターゲットとなるパスを記載

-baseResources.jsonの例

{
"src": [
"index.html",
"Container_mercator_org.svg",
"SVGMapLv0.1_PWA_r5.js",
"js/SVGMapLv0.1_r16.js",
"js/SVGMapLv0.1_LayerUI2_r3.js",
"js/SVGMapLv0.1_GIS_r2.js",
"js/SVGMapLv0.1_Authoring_r7.js",
"js/jsts.min.js",
"imgs/gps.png",
"imgs/gps_s.png",
"imgs/Xcursor.png",
"imgs/zoomdown.png",
"imgs/zoomdown_s.png",
"imgs/zoomup.png",
"imgs/zoomup_s.png",
"imgs/mappin.png"
],
"mapCacheTarget":"localMaps/"
}

• autoPilotDownloader

  エリアと縮尺を指定し、オートパイロットで地図画面をスクロールさせることで、オフラインキャッシュに地図を保存する動作を自動的に行う機能のオブジェクト。レイヤー固有UIでの利用などを想定しており、以下のメンバー関数を持つ

  • halt()

    オートパイロット動作を中断させる

  • searchAll(initialViewBox, minScale, maxScale)

    - initialViewBoxで指定したエリアを、minScale、maxScaleの間でオートパイロットをかけキャッシュに保存させる

    - minScale, maxScaleは、コンテナsvgコンテンツの座標系におけるscale値(getRootScale()で取れるもの)

  • setProgressCallBack(cbf)

    オートパイロット動作中の進行状況をcbfの第一引数に返却する

• async clearOfflineContents()

  SVGMapのオフラインコンテンツを全消去する。SVGMapのオフラインコンテンツはserviceWorkerのネイティブキャッシュ機構とは別の独自キャッシュ機構(indexedDBを使用した機構)として構築される

• clearCache()

  （未実装）serviceWorkerのネイティブキャッシュを全消去する

• cacheDB

  SVGMapのオフラインコンテンツデータベースのオブジェクト。IndexedDBをpromise化した簡略的APIをメンバ関数として持つ。

  • clear()

    データベースをクリア

  • async connect()

    データベースに接続

  • async delete(path)

    pathで指定したコンテンツを削除

  • async get(path)

    pathで指定したコンテンツ(blob)を取得

  • async getAll()

    全コンテンツを取得

  • async getAllKeys()

    全Key(コンテンツのpath)を取得

  • async put({idCol:path,contentBlob:blobdata})

    コンテンツ(blobdata)をpathをキーにして格納(上書き)

• deleteCachedLayerMeta()
• async disableCache()

  serviceWorkerのネイティブのキャッシュ機構とSVGMapの独自キャッシュ機構を全て無効化する

• async enableCache()

  serviceWorkerのネイティブのキャッシュ機構とSVGMapの独自キャッシュ機構を全て有効化する

• getCachedLayerMeta
• async getPostQueue()

  postMessageWhenConnectedでポストをリクエストし、未完了のリクエストを取得する

• getRootScale()

  svgMapのコンテナsvgコンテンツ座標系における現在の表示のscaleを取得

• getScales()

  読み込み済み文書全てのscaleを連想配列で返す(hashKeyはdocID)

• getVisibleLayers
• getStorageUsage
• async loadOfflineContents(contentUrlList, overwrite, progressCallBack)

  -contentUrlListで指定したコンテンツをオフラインキャッシュに読み込む(自ドメイン内のコンテンツ限定)

  -overwriteをtrueにすると上書きする。progressCallBackは指定した関数の第一引数に進捗状況を返却

• async loadZippedOfflineContents(zip_url,progressCallBack)

  保存してあるディレクトリに対して、そのzipファイルの中のディレクトリ構造で、コンテンツがあるものと見做したURLもつキャッシュを形成する

• async postMessageWhenConnected(URL, postData, postCompleteCBF)

  -postDataデータをURLにポストする　オンライン時は即座にポスト、オフライン時はいったんindexedDBにポストデータを格納後オンラインになったらポストする。

  -postDataは、文字列(この場合form-data決め打ちのリクエスト)、もしくは .bodyメンバー変数を持ったオブジェクト

  -この場合は .bodyはFormDataタイプのインスタンスもしくは任意のデータ、そしてfetchAPIに準じた.headers, .methodをメンバー変数に持たせることができる。(methodでGETを指定すればGETリクエストも可能)またserviceWorkerが管理する

• async setCachedLayerMeta
• setScaleTrim
• async updateCacheIndex()

svgMapCustomLayersManager.で呼び出せるAPI

実験的機能段階 :

基本的なフレームワークで提供されているレジューム機能を更に強化し、レイヤーの表示非表示状態、初期表示エリア(viewPort)等をユースケースなどに応じて複数登録、切り替えを可能とする機能を提供します。更にコンテナsvgコンテンツをさらに積極的に編集し、コンテナsvgコンテンツファイルに無いレイヤーを追加したり、削除したりした、カスタマイズされたコンテナsvgコンテンツを差分情報の形でlocalStorageに保存・利用する機能を提供します。

- 以下のAPIは、SVGMapLv0.1_CustomLayersManager_r*.jsを用いた場合に使用できます。

- SVGMapLv0.1_CustomLayersManager_r*.jsは、svgMapオブジェクトもつwindowで使用するとともに、svgMapオブジェクト用のカスタムレイヤーセットを構築するための別ページのwebAppsにおいても使用することができます。

- 上記svgMapオブジェクト用のカスタムレイヤーセットを構築するためのwebApps用としてSVGMapCustomLayersManagerApp_r*.js、SVGMapCustomLayersManager.htmlが用意されています。

• registCustomLayer(customLayerObject, applyImmediately, customLayerMetadata)
• applyCustomLayers(customLayersObject, baseLayersPropertySet)
• getDetailedLayersPropertySet(rootContainerDoc, ignoreIid)
• getDetailedLayersPropertySetFromPath(rootContainerUrl, ignoreIid)
• getDif( edit, orig )
• originalLayersProperty
• deepCopy(obj)
• deleteAllCustomLayerSettings()
• deleteCustomLayerSetting( key )
• setCustomLayerSettingIndex(key)
• buildCustomLayersSetting(difObj, editedLayersProperty, originalLayersProperty)
• loadCustomLayerSettings()
• storeCustomLayerSettings( settings )
• getElementByAttr( XMLNode , searchId , atName )
• applyCustomLayersSettingsToCurrentMapView(lpEdit, svgMapWin)
• loadCustomGeoViewboxes()
• storeCustomGeoViewboxes(customViewBoxes)
• buildCustomGeoViewboxSettingObject(key, title, geoViewBoxX, geoViewBoxY, geoViewBoxWidth, geoViewBoxHeight)

起動URLによるオプション指定

svgMapフレームワークを導入したhtmlコンテンツは、URLの"#"以降であるフラグメント識別子によってフレームワークにいくつかの起動時オプションを提示することができます。 通常、これらのオプションは、コンテナsvgコンテンツにおける記述で示されています。フラグメント識別子による指示はそれをオーバーライドします。 一般的な"&"による区切りで複数の複数のパラメータを指定できます。

表示範囲の指定

global座標系によって表示範囲を指示することができます。　標準のフラグメント記述に対してそれぞれ"global"文字列の追加が必要です。 なおglobal座標系におけるxは一般的に経度、yは一般的に緯度に対応することに留意してください。

• メディアフラグメントによる指定 : xywh=global:<xmin>,<ymin>,<width>,<height>
• svgViewフラグメントによる指定 : svgView(viewbox(global,<xmin>,<ymin>,<width>,<height>))

表示・非表示レイヤーの指定

• 表示すべきレイヤー: visibleLayer=<layer title>,<layer title>...
• 非表示すべきレイヤー: hiddenLayer=<layer title>,<layer title>...
• 個々のレイヤーに対するフラグメントの提示 : それぞれのレイヤーに対しては、さらにフラグメントを追加することができます。ただし"="は"%3D",&は"%26"でURLエンコードしてください。<layer title>#fragment1=val1&fragment2=val2　⇒<layer title>#fragment1%3Dval1%26fragment2%3Dval2　

レイヤー固有のUI

"Layers as WebApps"(ウェブアプリケーションとしてのレイヤー: webApp Layer)を実現する機構　（レイヤーwebApp、webAppレイヤー、アプリレイヤー、レイヤーアプリなどと呼ぶこともある）

概要

レイヤーsvgコンテンツ(フレームワークが最初に読み込むコンテナsvgコンテンツの中で埋め込まれるsvgコンテンツ)に対して、動的な地図レイヤーの一種として、そのレイヤーに固有の処理ロジックや、可視化・描画ロジック　そしてユーザインターフェースも含むことができる　htmlによるウェブアプリを定義できる機能です。

javascriptを使った独自のロジックによる動的な可視化データの生成が実装可能です。

また、この機能はそのレイヤーの設定やインタラクティブ操作のための表示やユーザインターフェースを地図表現とは別に表示したい場合にも用いることができます。従来のアーキテクチャでは、もしもこのようなレイヤーに固有のUIが必要だった場合でも、地図アプリケーション全体の処理や表示を司るグローバルな空間(ルートhtmlコンテンツのwindowオブジェクト直下)に、サイドエフェクトを考慮しながらコードを組み込む必要があり、結果としてコードのスパゲッティ化が懸念されました。SVGMapのレイヤー固有UIは、レイヤーごとにUIとそのロジックをカプセル化可能にし、これを排除することが可能です。(カプセル化はiframeによって行われます。)さらに、レイヤー固有UIによるウェブアプリは自律分散的な配置にも対応し、UIを備えた地図レイヤーにまでハイパーレイヤリングアーキテクチャを拡張します。

なお、#動的な地図レイヤーは、htmlによるユーザーインターフェースを持つことができませんが、同種のウェブアプリケーションのカプセル化の効果があります。

このＵＩには主に二つの用途が考えられます。

凡例

各レイヤーはその地図表現の意味を示すための固有の凡例を持つことがあります。その凡例を表示するために利用できます。

ウェブアプリケーションによる動的な地図レイヤー

先述のように、ウェブアプリケーションによる動的な地図レイヤーは独自のロジックによってそのレイヤーの地図表現を動的に変化させる機能を備えることができます。この場合、例えばエンドユーザがFORMで入力したフィルター条件ををもとに表現を変更するようなケースも考えられます。

これらケースでは、そのフォームや凡例は、ルートhtml文書に設置することは可能ですが、もしも多くのレイヤーを表示するアプリケーションであり、それらのレイヤーがそれぞれ固有のフィルタ条件を持つような場合、ルートhtml文書は、それぞれのレイヤーをフィルタリングするためのFORMとそのフィルタリングロジックをすべて埋め込む必要があり、画面のデザイン、およびロジックのコーディングの双方がスパゲッティ化する可能性があります。さらに、もしもこのアプリケーションに後日さらにレイヤーが追加される場合、スパゲッティ化の問題はより深刻になるかもしれません。凡例の表示についても同様の問題が考えられます。本レイヤー固有ＵＩはこのような問題に対するソリューションを提供しています。

この機能は、ベースのフレームワークrev12以上　且つLayerUI2フレームワークを読み込み、id="layerSpecificUI"のdiv要素がルートhtml文書に設置されているときに使用できます。

サンプル

開発者向けチュートリアルでいくつかのサンプルを見ることができます。

レイヤーsvgコンテンツでの指定

レイヤー固有UIの設置には、レイヤーsvgコンテンツ(のルート要素(svg要素))に、data-controller属性を与え、そこにそのレイヤー固有のUIのためのhtml文書のリンク(ただしsame origin)を設置します。またサブセットとして、data-controller属性にビットイメージ(.pngもしくは.jpg, .jpeg, .gif拡張子を持つビットイメージ)へのリンクを与えることでレイヤーの凡例情報の提示をすることもできます。

レイヤー固有ＵＩの表示部位には、このように指定されたリソース(ビットイメージもしくはhtml)がレイヤーの選択の状況に応じて、切り替わり表示されます。レイヤーがONになっている間、それに紐付けられたレイヤー固有UI(htmkのwindowオブジェクト)が存在し続け、そのレイヤーのsvgDOMの操作やUIの提供が可能です。

なお、標準のフレームワークでは、表示中のレイヤーの中の選択された一つのUIのみが地図のメインのwindowに配置されたiframeで表示されます。表示中ではあっても選択されていないレイヤーのUI(iframe)は非表示状態で動作しています。

サンプル

<?xml version="1.0" encoding="UTF-8"?>
<svg  xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
  viewBox="9000.0 -9000.0 9000.0 9000.0" go:dataArea="9000.0 -9000.0 9000.0 9000.0"
  data-controller="../Self-GS-POI_controller.html">
.....

レイヤー固有のUIのためのhtml文書(webApp)の構造・作法

レイヤー固有のUIとなるhtml文書は、下記の通り、その初期化等を行うライブラリ svgMapLayerLib.js を読み込む必要があります。（現在のところ通常のjavascriptライブラリのみ提供されます） CDNからライブラリを読む場合は、https://cdn.jsdelivr.net/gh/svgmap/svgmapjs@latest/svgMapLayerLib.jsです。

サンプル

<!doctype html>
<html>
  ...
  <script src="https://cdn.jsdelivr.net/gh/svgmap/svgmapjs@latest/svgMapLayerLib.js"></script>
  ...
</html>

詳細

• レイヤー固有UIは、SVGMapのグローバルなwindowに設置されたiframeの中で動作します。このiframeではデフォルトで組み込まれる下記APIを通して、そのレイヤーのSVG DOMをはじめとしたSVGMapの各種リソースへのアクセスが可能です。
  • アクセスが可能になるのは、"load"イベント・onload段階以降です。
• コンテナsvgコンテンツが設置されたSVGMapのグローバルなwindowと異なるドメインにレイヤーを設置し、そのレイヤーがレイヤー固有UIを持つこともできます。ただし適切なCORS設定が必要であるとともに、一部のAPIの使用に注意が必要になります。(下記cotrollerSrc参照)
• レイヤーsvgコンテンツのドキュメントルート要素へdata-controller属性を設定する代わりに、コンテナsvgコンテンツにおけるレイヤーsvgコンテンツへの参照要素にdata-controller属性を設定することもできます。
• data-controller属性の代わりに、data-controller-src属性の値に、適切にエスケープすることで直接htmlを記述することもできます。
• data-controller属性によって参照されるhtmlコンテンツでは、次節#拡張APIで説明する値や関数が使用できます。
• data-controller属性のURLには以下のオプションをフラグメント識別子として指定することができます。
  • #exec=appearOnLayerLoad||hiddenOnLayerLoad||onClick
    • appearOnLayerLoad : レイヤーを表示状態にすると即座にレイヤ固有UIが出現
    • hiddenOnLayerLoad : レイヤーを表示状態にすると即座にレイヤ固有UIがhidden状態で起動(そのレイヤ固有UIに含まれるscriptが起動)
    • onClick : レイヤー固有UI起動ボタン">"を押したときにレイヤ固有UIが出現(デフォルト)
  • #requiredHeight=hhh&requiredWidth=www
    • id="layerSpecificUI"のdiv要素のcss値に関わらず、requiredHeight、requiredWidthでiframeの表示を指示
• 下記APIはレイヤー固有UIのiframeが生成された直後はアクセスできません。(アクセス可能になるまでタイムラグがあります)　ただし、2021/6/24のリリースから、onload(load)段階でアクセス可能になりました。
  • 初期化時には、addEventListener("load",初期化関数)　もしくは onload=function(){初期化処理}　等として利用してください。

拡張API

レイヤー固有UI(iframeのwindowオブジェクトのjavascriptコード)では以下のAPIが拡張されています。

イベント

• openFrame : そのiframeが、新たに生成された
• closeFrame : 同、消滅した
• hideFrame : 同、隠された
• appearFrame : 同、隠されていたのが再度現れた
• zoomPanMap : SVGMapフレームワークと同じ
• zoomPanMapCompleted : 同上
• refreshScreen : 同上

svgImageProps

このレイヤー固有UIに紐づいたレイヤーSVGの各種プロパティ (参考:#svgImagesProps.5B.5D)

• プロパティのリストはこちらを参照
• svgImageProps.scriptで、動的地図レイヤーのscript要素によって生成されたオブジェクトにもアクセスできます。
• svgMap.getSvgImagesProps(layerID) で得た値と同等。

svgImage

このレイヤー固有UIに紐づいたレイヤーSVG文書(DOM Documentオブジェクト) (参考：#svgImages.5B.5D)

• このドキュメントを操作することで、そのレイヤーの表示を動的に変化させることが可能です。
• 特に、動作の制限に注意して実装してください
• svgMap.getSvgImages(layerID) で得た値と同等。

svgMap

svgMapフレームワークインスタンス

layerID

• svgMapフレームワークが管理しているSVG文書ハッシュリスト(svgMap.getSvgImages())における、このレイヤー固有UIに紐づいたレイヤーSVG文書のハッシュキー
• #getLayerId参照

svgMapGIStool

GIStoolsフレームワークを拡張した時、同インスタンス

• svgMapGIStoolが持つAPI

svgMapAuthoringTool

svgMapAuthoringToolフレームワークを拡張した時、同インスタンス

• svgMapAuthoringToolが持つAPI

controllerSrc

レイヤー固有UIのiframeの起動に使われたsrc属性(レイヤー固有UIのパス・URL)が読み出せます。特にレイヤーが異なるドメインから配信されたものの場合、レイヤー固有UIのwindowのlocation属性(及びそれによるURL解決を行うAPI)からは適切な情報が得られません。これ代えてこの値が使用できるケースがあるでしょう。

putGlobalMessage(messageText)

messageTextを#グローバルメッセージエリアに表示する　レイヤーが消滅したら自動でメッセージも消滅します。

preRenderFunction

この名前の関数を(レイヤー固有UIのwindowに)定義すると、そのレイヤーのSVG文書の再描画(画面更新)シーケンスの直前にこの関数の内容が実行される。詳細はsetPreRenderControllerを参照

customHitTester

この名前の関数を定義すると、そのレイヤーに固有のヒットテスト（マウスやタッチによって地図上をヒットしたときの振る舞い）機能を追加することができます。ヒットテストは通常のクリッカブルオブジェクト（ポイントやライン・ポリゴンなど）のそれと同等に扱われます。

• customHitTester( position )
  • 第一引数に、ヒットされた座標(.screenX,Y:window上の座標、.lat,lng:地理座標、.isMapCenterHitTest:後述)が与えられます。（この値をもとに実際のヒットテスト処理を書く）　この関数の帰り値がnullやundefinedの場合はヒットしなかったこと、trueもしくは文字列もしくはそのレイヤーの任意の図形要素、もしくはそれらの配列の場合はヒットしたことを示します。
    • isMapCenterHitTestがtrueの場合、そのヒットテストは伸縮スクロール時自動発生するケースで発生したものです。（もしこのケースでのテストを除外したいなど特別な処理をしたい場合に利用できます）
  • ヒットテスト後の振る舞いも通常のクリッカブルオブジェクトと同等で、通常はデフォルトで備えるヒットされたグラフィックスオブジェクトのメタデータ表示パネルが呼び出されます。(帰り値が図形要素の場合）　もしこの振る舞いを変更したい場合は、setShowPoiPropertyを用いることが可能です。
  • 帰り値がtrue、文字列、およびそれらの配列を返す場合は、setShowPoiPropertyを使用してカスタマイズされた処理を行う必要があります。この場合setShowPoiPropertyで設定された関数が受け取る引数は、そのSVG文書のドキュメントルート要素であり、その"data-hitTestIndex"属性に選択されたオブジェクトのインデックス(配列の場合。配列でない場合は常に0)が設定されます。

動的な地図レイヤー

svgドキュメントにjavascriptを記述することでも、動的なデータ生成を実装可能としています。 本フレームワークでは、svgドキュメント中に<script>要素を一つだけ記述することができ、その要素の中にjavascriptコードを入れることができます。

DOMを操作し、動的に描画を変化させることが可能です。ただし、動作の制限に注意してください

動的SVGMapコンテンツで利用可能な拡張API

一般のjavascriptAPIに加えて、動的な地図レイヤーを実装するために以下のAPIが提供されます。（既存のものでも注記があるものも列挙）

• document: このsvgMapドキュメント自身
• READ ONLY変数
  • CRS:このドキュメントのCRS : CRS.a....fに、地理座標からこのドキュメントのSVGユーザ座標への変換係数が提供される
  • docId:このSVGドキュメントのdocId
  • scale：倍率：このドキュメントの座標系と、画面の(px座標系)との間の倍率(この値は等倍が1.0だが、svgMapコンテンツのvisibleMin/MaxZoom値は%(等倍は100)なので注意)
  • actualViewBox：このドキュメントの座標系でのviewBox
  • geoViewBox：地理座標におけるviewBox
  • geoViewport
  • viewport
  • this.location:相対パス
  • (this.verIE)
• refreshScreen(): 描画の更新を明示: refreshScreenを用いていない場合、そのレイヤーのDOMを編集してもそれが即座に表示に反映(更新)するとは限りません。文書のロード、ズーム、スクロールのときが表示のDOMの内容を反映した画面の自動更新のタイミングです。それ以外、多くの場合反映されません（性能確保のための本フレームワークの制限）。DOMO編集をそれ以外のタイミングで表示に反映したい場合、この関数の呼び出しを行うひつようがあります。一方不必要にこの関数を呼び出すとシステム全体の性能が低下するかもしれません。
• transform()
• getCanvasSize()
• linkedDocOp()
• isIntersect()
• drawGeoJson()
• childDocOp()
• onload:この関数を設定すると、ロードされると呼ばれる(ドキュメントロード後、描画前のタイミング。)
  • この関数は、DOMトラバース前に同期処理される。
  • したがってonloadで実行される処理はその中が非同期でない限り、refreshScreen()しなくてもonload時のDOM編集は直後の描画に反映される。
• onscroll:この関数を設定すると、スクロールされるとき呼ばれる（ほかにズーム以外で画面更新時も）(スクロール後の描画前のタイミング。)
  • 同上
• onzoom:この関数を設定すると、ズーミングが発生するとき呼ばれる(同上)

拡張イベント

• document -> zoomPanMap イベント addEventHandlerすると、ズームパンが起き(viewPortが変化したとき)地図システム全体の描画が完了(含タイムアウト)後に発行される。SVGMap*.jsが地図をウェブアプリ起動後、最初に描画完了した時にもこのイベントが発生する。（レイヤー追加時には発生しない）
  • これをイベントリスナに設定した関数は、非同期に実行される。onscroll()と異なり、もしその関数でDOM編集を行った場合は、直後の描画にそれが反映される保証がない。refreshScren()による再描画が必要。
• document -> screenRefreshed イベント addEventHandlerすると、ズームパン以外で地図システム全体の描画が完了(含タイムアウト)後に発行される。主にrefreshScreen()など。このイベントをフックにして、SVGMapコンテンツのDOM操作・再描画（refreshScreen()）を行うと無限ループに陥るので使用方法に注意が必要。
• document -> zoomPanMapCompleted イベント SVGMaplayerUIが有効な時に発行される。　zoomPanMapイベントは伸縮スクロール完了時に発行されるが、その直後にレイヤー固有UIにおいて(XHRやfetchを用いた)非同期なデータ取得とレイヤー書き換えが生じるケースでは、その完了を検知しない。zoomPanMapCompleted イベントはこのような非同期通信の完了後に発行される。

SVGMapの埋め込み(SVGMapFrame)

実験的機能段階 :

SVGMapフレームワークはwindow全体に地図コンテンツが占有される形で表示する設計です。ウェブページはwebAppsとしてカプセル化されたレイヤーをsvgMapオブジェクトに差し込む形でアプリケーションが構築されます。すなわち、基本的にグローバル空間windowにはsvgMapオブジェクトだけが単独で存在し、その他のアプリケーションをwindow上に実装する場合は、その開発者がsvgMapオブジェクトとのグローバル空間でのスパゲッティ化に注意を払いながら開発していく必要があります。

それに対して、SVGMapLv0.1_Frame*.jsが提供する機能は、window内の指定した領域にsvgMapによる地図を埋め込むことを可能にします。さらにこの埋め込まれたsvgMapオブジェクトを　外部からより簡単に操作できるようカプセル化されたインターフェースを提供します。

ライブラリ

SVGMapを埋め込むウェブページではSVGMapLv0.1_Frame*.jsを導入します。

<!doctype html>
<html>
 <script type="text/javascript" src="SVGMapLv0.1_Frame_r4.js"></script>
</html>

svg-map要素

svg-mapカスタム要素を使用してsvgMapオブジェクトを任意の場所に埋め込むことができます。

 <!doctype html>
 <html>
  <script type="text/javascript" src="SVGMapLv0.1_Frame_r4.js"></script>
  <body>
   <table>
    <tr>
     <td>
      説明用地図
     </td>
     <td>
      <svg-map svgMapAppPage="SVGMapper_r16_layerUICustom.html" id="svgMapTag" latitude="37" longitude="135" zoom="4" layerui="#layerUIarea">
      </svg-map>
     </td>
    </tr>
   </table>
  </body>
 </html>

属性

svgMapAppPage

必須属性: 起動するSVGMapLv0.1*.jsが組み込まれたhtmlを指定。 svg-map要素はshadow domとなっており、内部はひとつのiframeとして構成されます。このiframe内のwindowで通常のsvgMapオブジェクトが稼働する形となります。svgMapAppPage属性はこのiframe内で起動するsvgMapオブジェクトを持ったhtmlを指定するものです。

latitude, longitude

オプション: 表示領域を下記の属性と組み合わせて指定します。DOMを操作することによって動的に表示領域を変更することが可能です。

zoom

オプション: 表示位置の中心点を上の2属性で、ズームレベルをこの属性で指定します。ズームレベルの定義はwebMercatorタイルピラミッドのレベル番号（ただし小数点指定も可能）

latitude2, longitude2

オプション: latitude, longitudeと組み合わせて対角線を指定し表示領域を設定します。

customjson

オプション: 任意のJSON文字列を(エスケープしたうえで)与えることができます。 SVGMap.jsのあるiframeのwindow.rootMessage.customJsonに、JSON.parseされたうえでその値が反映されます。この値もDOM操作により動的に反映されます。window.rootMessage.customJsonの変化を監視できるようsetterを設けることで動的な変化に対応する実装が可能です。

var rootMessage={
 set customJson(json){
  ...
 }
}

layerui

オプション: レイヤーUIの出力要素をxlinkで指定します。　この値はmutationをobserveしていません（svg-mapオブジェクトが生成された、最初の一回のみ有効です）

<svg-map svgMapAppPage="SVGMapper_r16_layerUICustom.html" id="svgMapTag" latitude="37" longitude="135" zoom="4" layerui="#layerUIarea">

DOM API

setCenter

setCenter( longitude, latitude, zoom ) : 緯度経度ズームレベルで地図を表示させる

addLayer

addLayer(url,title,visibility) : URLで指定したリソースのレイヤーをtitleを付けて追加する

svgMapObject

getter svgMapObject : この要素に紐付いたsvgMapオブジェクトを得る

layer要素

svg-map要素の子要素として、任意の個数のlayer要素を設置できます。

属性

title

iframeで起動されるsvgMapオブジェクトのコンテナsvgコンテンツファイルにある、レイヤー名(title)を指定し、そのレイヤーとlayer要素を紐付ける。該当するレイヤーが無く、且つ下記のsrcが指定されている場合は新しいレイヤーを追加する。なお、任意の属性や子ノードが与えられている場合は、下記の通りレイヤーの読み込み後にそれらの値が該当するレイヤーのdata-controllerの window.rootMessageに設定される。

src

iframeで起動されるsvgMapオブジェクトのコンテナsvgコンテンツファイルにある、レイヤーをURLを使って指定する

visibility [TBD]

visible もしくは hiddenを設定すると、そのレイヤーの表示状態を制御できる。

任意の属性

任意の属性を設定できる。設定した属性名と属性値は、対応するレイヤーのdata-controllerで指定されたレイヤーのコントローラのwindowにおけるwindow.rootMessageの対応するメンバ変数に反映される。setterを設定することで変化に応じて動作させることが可能になる。

rootMessage.update()関数

レイヤーのコントローラのwindow.rootMessage.update()関数(引数なし)が定義されている場合、上記の属性変更(最初の設定も含む)が検知される度にこの関数が呼び出される。

子ノード(TEXT CONTENTやXML要素)

任意のテキスト(textContent)や、XML要素(xmlContent)を子ノードに入れることができる。 入れられた情報は、同様に対応するレイヤーのdata-controllerの window.rootMessage.textContent、もしくはwindow.rootMessage.xmlContentメンバ変数に反映される。 XMLに関しては任意の階層化がされていても良い。DOM操作による変化があれば更新されるので、同様にsetterを用いて変化を反映させることが可能。

DOMAPI

layerId

layerId : このレイヤーのレイヤーIDを得る

svgImage

svgImage : このレイヤーに紐付いたsvgMapコンテンツ(document)を得る

svgImageProps

svgImageProps : このレイヤーに紐づいたsvgMapコンテンツのsvgImagePropsオブジェクト(各種プロパティを格納したオブジェクト)を得る

controllerWindow

controllerWindow : (もしあれば)このレイヤーに紐づいたsvgMapコンテンツのレイヤー固有UIを得る

第四章：内部機構解説

別ページを参照してください。