解説書
目次 |
SVGMap.js (Level0.1フレームワーク)解説書
2017年現在のSVGMapのデータ形式、およびそれを実装した初歩的なフレームワーク(SVGMap Level0.1 Revision*)の解説を行います。
第一章:SVGMapの更新部分
この章は、JIS化されたSVGMap (JIS X.7197)に対する近年の開発成果に基づくアップデート部分を解説しています。
地理座標系の扱い方
SVG2では地理空間座標を記述するスペック(metadata geospatial coordinate systems)が削除されました。これは、W3C SVG仕様の範囲では単なるメタデータであり、ユーザエージェントの振る舞いに何ら影響を及ぼさないことが理由です。 また、JIS SVGMapにおいては、coordinateReferenceSystem 要素が定義され、それに基づくユーザエージェントの振る舞いが規定されていますが、これは一方でW3Cのスペックではないという課題を持ちます。
これを受けて、現在提案されているSVGMapのデータ仕様では、SVG1.1の段階ですでに標準化と実装が行われたスペックを注意深く活用することにより、JIS SVGMapで規定された地理座標系に関する機能のいくつか(すべてではない)を実現する方法を用いることとしています。(globalView spec)
なお、JIS SVGMapのcoordinateReferenceSystem要素もサポートしています。
ウェブアプリケーションによる動的な地図レイヤーと、そのハイパーレイヤリング
SVG2(SVG1.1 2nd Edition)では、SVG単独によるのユーザエージェントという実装想定は撤廃され、よく知られているウェブブラウザの機能の一部としてのSVGデータの描画機能、HTMLやCSSと一体化されたデータ・コンテンツ へと変化しました。一方、近代のウェブブラウザにおけるコンテンツでは古典的なhtmlに基づくコンテンツデータに対して、javascriptとDOM APIによるプログラムでコンテンツをブラウザ上で動的に生成する(ウェブアプリケーション)機構を備えます。すなわちSVGを実装する現代のユーザエージェントは例外なくウェブアプリケーションの実行が可能となりました。
そこで、SVGMapでは従来の静的なSVGによる地図コンテンツに加え ウェブアプリケーションをも地図コンテンツとして扱えることとしました。それにもかかわらず SVGMapは依然として複数のウェブ上で分散する地図データを一つの画面上にレイヤリングする機能(ハイパーレイヤリング)を維持しています。したがって、SVGMapは複数の地図ウェブアプリケーションをレイヤリング(マッシュアップ)する機能が拡張されます。すなわち、SVGMapのマッシュアップ・ハイパーレイヤリングの可能性を、単に地図画像データのレイヤリングから、地図上に表現された動的なオブジェクトのマッシュアップ・レイヤリングに広げています。
例
以下に、いくつかのこのような動的な地図コンテンツの例を示しましょう。
- 検索によって表示スタイルを変更する機能を持ったレイヤー
- 例えばコンビニエンスストアのPOIレイヤーを表示したとして、そのメタデータを読み取り、検索条件に基づいて(例えば深夜営業している店舗)の表示スタイルを変更するような検索機能を実装したレイヤー メタデータは書くレイヤーごとに独特の値を持つため、その検索ロジックはレイヤーに固有のものとなることがあります。このケースではそのような機能をレイヤーに組み込むことを可能にします。
- CSVデータなどのレガシーな非SVGデータをHXRで取得し、ブラウザ上でSVG DOMツリーを生成するようなSVG地図コンテンツ。
- このケースでは、サーバからクライアントに送信されるデータの実体はSVG形式の地図データではなく、CSVなどのレガシーなデータです。SVG地図コンテンツには、CSVデータをSVGとして描画するためのデータ読み込み・解読・SVG DOMツリー生成機構を備えたjavascriptコードが含まれます。
- OpenStreepMapのTile Serverや、Tile Map Serviceのような、特定のロジックによる数列のような法則性を持った地図タイルリソースをタイリングする地図コンテンツ。
- 更新されたSVGMapでは、地図コンテンツに内蔵されたアプリケーションロジックとしてそれを取り扱うことができます。タイリング規則をそのままウェブアプリケーションとしてで書き下し、スケールやビューポートに応じて適切なタイリング(配置)を行うSVG DOMツリーを生成するSVG地図コンテンツが構築できます。
従来の地図フレームワークでは、このようなタイリング機能は特定のタイリングロジックとパラメータを伴った専用の機能として地図フレームワーク本体に作りこまれたうえでしばしば提供されてきました。一方、これらのロジックにはさまざまなバリエーションや最適化のための調整パラメータが存在し、これまで長らくその互換性や相互運用に問題を抱えてきました。TMSspecs@osgeowiki, tiling@osgeowiki
一方、これらのロジックはその多様なバリエーションを含め、javascriptによるプログラムコードとしては容易に記述可能です。多くの場合わずか数十行のロジックで記述できるでしょう。
レイヤー固有ユーザインターフェース
Rev.12で拡張
SVGMapLevel0.1 Revision 12以降では、個々の地図レイヤーがそのレイヤーに特化したそれぞれ固有のユーザーインターフェースを備えることができる機能が拡張されました。ユーザーインターフェースはhtmlによる任意のウェブアプリとして構築でき、それは新たに設計されたレイヤー選択UIを通してiframe中に呼び出されます。 この機能を用いるにはSVGMapLevel0.1フレームワークに加えて、拡張フレームワーク(SVGMapLv0.1_LayerUI2_r*.js)をロードする必要があります。
このフレームワークでは、拡張されたAPIが利用可能です。
たとえば気象情報のレイヤーに対して気象情報の時間変化を表示するアニメーションのコントローラ などのようなUIを任意に構築できます。
トポロジースイート(地理空間情報処理)
Rev.13で拡張
SVGMapLevel0.1 Revision 13以降では、SVGMapコンテンツに対してトポロジー演算機能(地理空間情報処理機能)を適用する拡張フレームワークが提供されます。この機能を用いるにはSVGMapLevel0.1フレームワークに加えて、拡張フレームワーク(SVGMapLv0.1_GIS_r*.js)をロードする必要があります。 このフレームワークでは、拡張されたAPI(TBD)が利用可能です。 フレームワークに内蔵された基本的な演算機能に加え、geoJSONと整合するインターフェースを備え、jstsを組み込み、より高度な機能を実装するための機構も持ちます。
この機能を用いると、特定のレイヤーに登録されているポリゴンの範囲に入っている、特定のレイヤーのポイントをフィルタリングして表示の色を変更する。といったことが可能です。ただし、これらはすべてすでにブラウザ上にロードされている限られた量のコンテンツの中での演算に限定されます。もしもサーバ上にしかないデータに対してこれらの演算を試みたい場合、従来通りサーバサイド技術によってそれは実現すべきです。
オーサリングシステム
Rev.14で拡張
(TBD)SVGMapLevel0.1 Revision 14以降では、SVGMapコンテンツを編集するツール機能が実装された拡張フレームワークが提供されます。(Rev11以前にはPOIに限って基本フレームワークに内蔵していた)なお編集したオブジェクトを保存したり登録するためには別のサービスやアプリケーションの開発が必要です。
第二章:SVGMap Revsion 0.1フレームワーク
SVGMapは究極的には既存のすべてのウェブブラウザがネイティブの機能としてそれを備えることを目標とし、既存のHTML,CSS,SVGなどのウェブブラウザの標準規格との整合性を備え、且つ既存のWeb Mappingの規格との整合性をも備えた仕様として検討と標準化を進めています。しかし今のところまだその標準化は完遂されていないため、その完全な実装がなされたウェブブラウザは存在しません。一方、既存のウェブブザでSVGMapの機能が実行可能となるような拡張をJavascriptによるフレームワークとして構築することが可能です。SVGMap Revision 0.1フレームワークは、このようなJavascriptによるSVGMapの仕様に基づいた初歩的な制限と拡張がされた実装です。
そのアーキテクチャの特徴は、ブラウザネイティブのSVGレンダラーを使用せず、HTML,CSS,HTMLCanvas2DAPIを用いてSVGMapが実装されている点です。この特徴は主にこのフレームワークの開発が開始された時期に起因しています。当時のウェブブラウザの多くはSVGが実装されていませんでした。また実装されていたとしても、大規模なベクトルデータのレンダリング、および伸縮スクロール・インタラクティブな操作に対する性能面での処理制御に問題がありました。これらの問題のいくつかは現在のブラウザで解消されているものがあるかもしれません。またこれらの問題の解決とともに、SVGMapフレームワークはLevel番号を上げつつよりネイティブの機能に基づいた実装に移行するかもしれません。参考までに、実験的なネイティブのレンダラを用いた実装(2010年)があります。
SVGのベクトル描画機能はcanvgのpathパーサなどを引用することで実装されています。一方、地図としてあまり用いられないと想定された 多くの要素やプロパティ、アトリビュートの実装が省略されています。
追加・拡張された機能:
フレームワークの呼び出し
本フレームワークを用いる場合、SVGMapコンテンツをブラウザに直接読み込ませることはできません。フレームワークを動作させるhtmlコンテンツ(WebApps)を準備し、そこからSVGMapコンテンツを呼び出します。利用者には、このhtmlコンテンツのURLを告知します。このhtmlコンテンツを以降ルートhtml文書と呼ぶことにします。
htmlコンテンツの<body>要素直下に以下の要素を配置します。
- フレームワークを実装したjavascriptコードを読み込むscript要素
<script type="text/javascript" src="SVGMapLv0.1_r*.js"></script> 注記:r*は、フレームワークのリビジョンによって変化する
- レイヤーリストを実装した拡張フレームワークのjavascriptコードを読み込むscript要素(必要に応じて)
<script type="text/javascript" src="SVGMapLv0.1_LayerUI2_r*.js"></script> 注記:r*は、フレームワークのリビジョンによって変化する
- その他、各種の拡張フレームワークのjavascriptコードを読み込むscript要素(必要に応じて) SVGMapLv0.1_Authoring_r*.js、SVGMapLv0.1_GIS_r*.js他がある。
<script type="text/javascript" src="拡張フレームワークファイル.js"></script> 注記:拡張フレームワークファイル.jsは用いる拡張によって変化する
- SVGMapコンテンツを配置するためのdiv要素。
- id属性に"mapcanvas"を設定し、title属性(もしくはdata-src属性(>rev14))にはルートとなるSVGコンテンツ(以降ルートSVGコンテンツと呼びます)のパスを指定したdiv要素を設置します。(要確認:地図のサイズ・配置はこのdiv要素のサイズとなります。無指定の場合は全ウィンドサイズ)
<div id="mapcanvas" title="Container.svg"></div>
<div id="mapcanvas" data-src="Container.svg"></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が上記の値である必要があります。ボタン押下で測位し、測位点を中心にして地図を表示する機能。表示の範囲は測位制度に応じて適当に設置されます。
- 地図中心の緯度経度値表示
<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要素
<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が上記の通りである必要があります。レジューム機能とは、cookieを用いて、前回最後に表示された状態(レイヤーの表示非表示状態、表示領域(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コンテンツを埋め込むことがあります。これらのコンテンツはよくサブレイヤーもしくは単にレイヤーと呼ばれることもあります。そこで、"ルート"をあえて付記することにします。
なお、Rev12以降のSVGMapLv0.1フレームワークではレイヤーフレームワークは本体と独立した実装となり、拡張や切り離しが可能となりました。以下は、標準で提供されるレイヤーフレームワークのVer2 (SVGMapLv0.1_LayerUI2_r*.js)に関して解説します。
レイヤーUIフレームワークが提供するUIは、先述のレイヤーリストUIを設置するdiv要素によって提供されます。このUIは以下の機能を持ちます。
- 折り畳み可能なレイヤーの一覧を表示する機能
- 各レイヤーの表示非表示を切り替える機能
- グルーピングされたレイヤー(後述)をグループとして表現、折り畳み、一括表示非表示する機能。
- そのレイヤーに紐づけられたレイヤー固有UIを出現させる機能。
- 表示されているレイヤーの個数などの情報を表示する機能
レイヤー固有UI
レイヤーに固有の情報やユーザインターフェースを地図表現とは別に表示したい場合に用いることができる機能です。(先述の通りこの機能はSVGMapLv0.1_LayerUI2*.jsを読み込んだ場合に機能します。) レイヤー固有UIを設けるには、レイヤールートSVGコンテンツのドキュメントルートsvg要素にdata-controller属性を設置、そこにレイヤー固有UIのためのリソースを参照するパスを記述します。参照先はpngもしくはjpg,jpeg,gif拡張子を持つビットイメージもしくは、それ以外の拡張子を持つHTML文書である必要があります。
レイヤー固有UIの表示部位に、このように指定されたリソース(ビットイメージもしくはhtml)がレイヤーの選択の状況に応じて、切り替わり表示されます。htmlの場合iframeとして埋め込まれ、ウェブアプリケーションを持つことも可能です。レイヤー固有UIとして起動されたウェブアプリケーションが持つ拡張された関数および変数については、ウェブアプリケーションの開発の章で解説します。
このUIには主に二つの用途が考えられます。
- 凡例
- 各レイヤーはその地図表現の意味を示すための固有の凡例を持つことがあります。その凡例を表示するために利用できます。
- ウェブアプリケーションによる動的な地図レイヤー
- 先述のように、ウェブアプリケーションによる動的な地図レイヤーは独自のロジックによってそのレイヤーの地図表現を動的に変化させる機能を備えることができます。この場合、例えばエンドユーザがFORMで入力したフィルター条件ををもとに表現を変更するようなケースも考えられます。
これらケースでは、そのフォームや凡例は、ルートhtml文書に設置することは可能ですが、もしも多くのレイヤーを表示するアプリケーションであり、それらのレイヤーがそれぞれ固有のフィルタ条件を持つような場合、ルートhtml文書は、それぞれのレイヤーをフィルタリングするためのFORMとそのフィルタリングロジックをすべて埋め込む必要があり、画面のデザイン、およびロジックのコーディングの双方がスパゲッティ化する可能性があります。さらに、もしもこのアプリケーションに後日さらにレイヤーが追加される場合、スパゲッティ化の問題はより深刻になるかもしれません。凡例の表示についても同様の問題が考えられます。本レイヤー固有UIはこのような問題に対するソリューションを提供しています。
詳細
- レイヤールートsvgコンテンツのドキュメントルート要素へdata-controller属性を設定する代わりに、ルートsvgコンテンツにおけるレイヤールートsvgコンテンツへの参照要素に設定することもできます。
- data-controller属性の代わりに、data-controller-src属性によって、直接htmlを記述することができます。
- data-controller属性によって参照されるhtmlコンテンツでは、以下の値が設定されます。
- layerID, svgImageProps, svgImage, svgMap, svgMapGIStool, svgMapAuthoringTool
- 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の表示を指示
- #exec=appearOnLayerLoad||hiddenOnLayerLoad||onClick
クリッカブルオブジェクト
グラフィックスオブジェクトをクリック(タブレットの場合は、タップもしくは照準アイコンに合わせたうえでタップ)することでそれに紐づけられたインタラクティブ動作を実行する。インタラクティブ動作はフレームワークが独自に提供する、metadataフレームワークに基づく、メタデータの表示機能を対象とします。
なお、image要素(useによって間接的に設置されたimage要素を含む)は、a要素によるハイパーリンクが加えて実装されています。metadaとa要素の双方が設定されているimage要素では、どちらのインタラクティビティを発動させるかをモーダルダイアログによるユーザへの問い合わせが行われます。
class属性によるレイヤーのグルーピング・クリッカブル機能の提供
ルートsvgコンテンツが参照するレイヤー(レイヤールートsvgコンテンツ)へのリンクを記述する要素(animationもしくはiframe要素)は、class属性によって、各レイヤーに特性を与えることができます。classはスペース区切りで複数指定することができますが、グループ名は一つしか認識されません。
- グルーピング
- グループ名として、以下の属性値以外の値をしていることで、同じグループ名を持ったレイヤーたちをグルーピングすることができます。グルーピングの効果はレイヤーUIにおけるグループ表現と、下記のbatch,switch特性です。
- batch
- グルーピングとともに使用します。そのグループに属するレイヤーを一括で表示非表示するための機能がレイヤーUIに付加されます。
- switch
- グルーピングとともに使用します。そのグループに属するレイヤーは、どれか一つしか表示されません。batchとの併存はできません。(無視されます(要確認))
- clickable
- Pathなどのベクトル図形要素はデフォルトではインタラクティビティが提供されません。クラス値にclickableを指定することでこのレイヤー(子供のsvgコンテンツを含む)の図形要素においてのみ、インタラクティビティが提供されます。提供されるインタラクティビティは、マウスによって図形をクリックしたとき、そのグラフィックス要素がクリッカブルな要因を備えているかどうかを検索し、備えている場合それに対応するアクションを起こします。
なお、image要素(useによって間接的に設置されたimage要素を含む)は、このクラスの設定に依らず、a要素によるハイパーリンク、およびmetadataフレームワークを用いたクリッカブルオブジェクトとして機能します。
- editable(一時的廃止)
- Rev11までのフレームワークにはPOI(defsで定義されたビットイメージをuseで貼り付ける機能)が内蔵されていました。その機能を発動するためのクラスです。なおRev12からはその実装は外されており、今後編集機能は機能拡充されたうえで周辺ライブラリとして提供される予定です。
metadataフレームワーク
データ格納効率に優れたメタデータのフレームワークが提供されます。このメタデータは先述のクリッカブルオブジェクトとしてインタラクティビティの実装に用いられます。 svgドキュメントルート要素のproperty属性に、メタデータの属性名をカンマ区切りで記述。そのファイルの図形要素にメタデータをproopertyに列挙した順に、メタデータの値を記述していきます。
ひとつの文書に対して一つのスキーマ(メタデータの属性名とその順番)しか与えられないという制約を持ちます。metadataはデフォルトの状態ではブラウザが備えるalertダイアログに属性名と属性値がそれぞれ列挙された形で表示されます。metadata表示機能の拡張については、ウェブアプリケーションの開発の章で別途解説します。
例:
<svg property="Name,Brand,Address,test3" ... > <path content="セルフニュー小原SS / 木村商店,ENEOS,宮城県白石市小原字中北前田13,37.9551373" ... />
実装されている機能
多くの機能が実装されていないため、実装されている機能をここでは列挙することとします。
要素
TBD
- path
- image
- spatial fragment (xywhによっ参照されるimageの部分を埋め込む)。もしもアスペクト比が異なった場合(TBD)
- circle
- text
- defs
- animation
- iframe
- globalCoordinateSystem
- view
属性
TBD
- ref(svg,
- fill,stroke
- arrow
- dasharray
- viewvox
第三章:ウェブアプリケーションの開発
本章はSVGMap Revsion 0.1フレームワークを用いたウェブアプリケーションの開発について解説します。 本フレームワークによる開発部分は以下に分類されます。
- ルートhtml文書によるウェブアプリケーション(SVGMapフレームワーク)
- ウェブアプリケーションによる動的な地図レイヤー
- レイヤー固有iframe
SVGMapフレームワーク
ルートhtml文書によるウェブアプリケーションはSVGMapLv0.1フレームワークを用いたウェブアプリケーションの基本であり、そのhtml文書が持つ'svgMap'という名前のインスタンスを用いてフレームワークのための拡張機能を利用することができます。
SVGMapが持つ基幹オブジェクト
SVGMapLv0.1フレームワークのインスタンス'svgMap'が持つ基幹のオブジェクトを解説します。これらの基幹オブジェクトはそれぞれゲッター(getSvgImages, getSvgImagesProps)によって取得できます。
svgImages[]
svgImages[hashID]は、 現在ローディングされているSVGドキュメント(“XML” DOMツリー(SVG DOMツリーというよりむしろ))が蓄積されているハッシュテーブル
- ハッシュID:フレームワークが任意に付番した文書ID。ただし、最初にロードされるルートのドキュメントのハッシュキーは、”root”
svgImagesProps[]
同、個々のSVGドキュメントが持つ、各種プロパティが蓄積されているハッシュテーブル
- ハッシュID: svgImages同様
プロパティリスト
- .Path コンテンツのパス(webAppsのdocument(html) rootに対する相対パス。Originが違う場合は絶対パス
- .CRS 地理座標からSVG座標に変換するための変換パラメータ
- .script SVG文書がscript要素を持つとき、そのscriptへのインターフェースが登録される。同script要素で生成されるオブジェクトに暗黙に登録されるメンバー変数については、動的SVGMapレイヤーを参照
- .editable 編集可能レイヤーを示す レイヤーのclass = editableに対応
- .editing 編集可能レイヤーを編集中
- .isClickable クリッカブルなレイヤーを示す レイヤーのclass = clickableに対応
- .parentDocId このSVG文書を埋め込んでいる、親のSVG文書のハッシュID
- .childImages[hashID] このSVG文書が読み込んでいる、子のSVG文書(複数)
- .refresh
- .loadScript
- .timeout
- .start
- .controller レイヤー固有のUIへの(web appsのdoc rootに対する)相対パス
- .isSVG2 その文書がSVG2タイプの文書であるかどうか(CRSとembedの仕方がちがう)
- .rootLayer そのSVG文書が属する「レイヤー」を示す文書
利用可能API
【TBD】 APIのリストは下記の通りです。
SVGMap.で呼び出せるAPI
- Geo2SVG( lat , lng , crs ) : 指定された緯度(lat)・経度(lng)・CRSより、SVG座標を計算する
- POIviewSelection( poi ) : 指定されたPOIの属性・リンクの表示選択画面を表示する。また、選択したイベントに従い、属性の表示または、リンク先のページを表示する。
- SVG2Geo ( svgX , svgY , crs , inv ) : 指定されたSVG座標(svgX , svgY)をCRSにより、GEO座標に変換する。または、invにより逆変換する
- addEvent(elm,listener,fn) : 指定された要素(elm)にイベント属性(listener)時の呼び出す関数(fn)を設定する (addEventListenerが実装されていなかったブラウザサポートの名残です)
- callFunction( fname ,p1,p2,p3,p4,p5) : 指定した関数(fname)を引数(p1,p2,p3,p4,p5)を渡してフレームワーク内の任意の関数を実行する。(フレームワークの内部関数も呼び出すことができる)
- captureGISgeometries( cbFunc , prop1 , prop2 , prop3 , prop4 , prop5 , prop6 , prop7 ): 現在表示中の地図コンテンツに対応した、GeoJsonのGeometryデータ構造に準拠のGISgeomerry情報をがレイヤ単位でまとまった連想配列の形で取り出す。非同期処理で、cbFuncの最初の引数に返却される。
- 連想配列のハッシュ値:レイヤID
- geomeryには、src(そのジオメトリのもととなっているSVGの図形要素), href(ビットイメージの場合のリンク)が付加される
- captureGISgeometriesOption(BitImageGeometriesCaptureFlg,TreatRectAsPolygonFlg): captureGISgeometriesでキャプチャするデータの取得条件を設定する。
- BitImageGeometriesCaptureFlg: ビットイメージタイルを取得するか(Default:false)。captureGISgeometriesを呼び出す前に使用する。
- TreatRectAsPolygonFlg: rect要素をポリゴンとして扱う(デフォルトは円もrectもPointとして扱われる)
- checkSmartphone() : タッチに対応したスマホブラウザなのかどうかを判別
- childDocOp(func , docHash , param1, param2 , param3 , param4 , param5) : 指定した文書をルートにして、DOM操作をその子文書に対して実行する。なおこれはlinkedDocOpの直系の子供のみ適用版(自身も適用しない)
- dynamicLoad( docId , parentElem ) : 指定した文書ID(docId)以下の表示に必要な文書を読み込み、指定したdiv要素(parentElem)に表示する
- escape(str) : 以下の文字をHTMLエスケープする(&:&,":",':',<:<,>:>)
- geo2Screen( lat ,lng ) : 地理座標を指定すると、その画面上のキャンバスの座標(px)を返す
- getBBox( x , y , width , height ) : 指定された値でviewBoxを作成する
- getCentralGeoCoorinates() : グローバル変数 rootViewBox,rootCrsから画面中心地理座標を得る
- getConversionMatrixViaGCS( fromCrs , toCrs ) : 元座標変換行列(fromCrs)から先座標変換行列(toCrs)への変換行列を作成する
- getElementByImageId( XMLNode , searchId ) : 指定されたSVG文書群ノード(XMLNode)以下の属性iidが指定されたID(searchId)と等しいノードを返す
- getGeoViewBox() : ルートSVGのviewBoxをgeo変換したgeoのviewBoxを取得
- getHashByDocPath ( docPath ) : ターゲットのレイヤーのハッシュをPath名(docPath)から探し出す
- getHyperLink( svgNode ) : 指定されたsvg文書(svgNode)から、親文書をたどり最初に取得できたハイパーリンクを取得
- getInverseMatrix(matrix) : 逆行列を求める(matrix.a..f)
- getLayer(layerID_Numb_Title) : レイヤーのID,title,番号,href(URI)のいずれかで、ルートコンテナSVGDOMにおけるレイヤーの(svg:animation or svg:iframe)要素を取得する。getLayersと似ているが、getLayersのほうは任意のsvg文書(オプションなしではroot container)に対して、内包されるレイヤーのリストを返却。こちらはrootコンテナに対して検索キーに基づいてレイヤーを返却する
- getLayerId( layerKey ) : ルートコンテナにおける"レイヤ"概念のレイヤidを検索する。検索に用いることができるのは、getLayerと同じtitle,url,もしくはルートレイヤの要素
- getLayers( id ) : オプションなしの場合、ルートSVGコンテナのレイヤーに該当する要素をリストアップし、返却する。 オプションアリの場合、そのidを持つ要素を返却
- getMapCanvas() : 地図キャンバスとなる、おおもとのdiv要素の取得
- getMapCanvasSize() : 地図キャンバスのサイズ(画面サイズ)を取得
- getMouseXY( evt ) : 指定されたイベント時のマウスの画面上の座標(px)を返す
- getNonScalingOffset(svgPoiNode) : 拡大縮小しても伸縮しない図形要素のオフセット値を取得する
- getObject( oname ) : 指定されたオブジェクト(oname)を取得
- getPoiPos( svgPoiNode ) : =getNonScalingOffset
- getRoot2Geo() : ルートSVGのCRSの逆変換CRS( rootのsvg - > geo )を取得
- getRootCrs() : ルートSVGのCRS ( geo->rootのsvg )を取得
- getRootLayersProps() : ルートコンテナの(animetion||iframeで構成される)レイヤー情報を取得する。Arrayが返却、並び順はsvgのルートコンテナと同じ(最初のレイヤーが一番下。selectメニュー創るときはひっくり返して使うこと)レイヤー情報:名称、表示非常時状態、レイヤーグループ、グループのフィーチャ(バッチ||スイッチ||ふつう)、編集可、編集中、対応SVGドキュメント、個別ユーザインターフェース、個別凡例
- getRootViewBox() : aspectを加味し実際に開いているルートSVGのviewBoxを取得
- getSvgImages() : svg文書群(XML)(arrayのハッシュキーはimageId("root"以外は"i"+連番))を取得
- getSvgImagesProps() : svg文書群のプロパティ( .Path,.CRS,.script,.editable,.editing,.isClickable,.parentDocId,.childImages,.controller)を取得
- getSvgTarget( htmlImg ) : html文書中のimg要素(POI)を入力すると、対応するSVG文書の文書番号とその要素(use)が出力される。対応するuse要素を持つsvg文書自体を取得したい場合は.ownerDocumentする。idからhtml文書のimg要素を取得するには、Document.gelElementById(id)
- getSwLayers ( cat ) : swLayers[クラス名]に、クラス名ごとのレイヤー(のSVG要素)の全リストを構築する。catがある場合は、catの名称を持つもののリストのみを構築する
- getSymbols(svgDoc) : POI編集のsymbol選択を可能にするとともに、defsは、useより前に無いといけないという制約を払った
- getTickerMetadata() : 現在Tickerが表示されているグラフィックスオブジェクトのメタデータを取得する
- getTransformedBox ( inBox , matrix ) : 指定されたviewBox(inBox)を変換行列にてサイズ変更と移動のみでの座標変換する。b=0、c=0の場合のみ利用可能
- getUaProp() : ブラウザの種類(isIE:IEかどうか、isSP:スマートフォンかどうか)を取得する
- getVerticalScreenScale(screenLength) : 垂直(緯度)方向のscreenLengthに対する長さを取得する(input: px, return : Km)
- getViewBox( svgDoc ) : 指定したSVG文書のviewBoxを取得
- gps() : ブラウザの測位APIによって測位しその点を中心に表示、表示縮尺は測位精度を元に適当に決定
- gpsCallback(position) : GPS測位が成功した後に実行されるコールバック関数で、positionを中心とした場所を表示させる
- handleResult( docId , docPath , parentElem , httpRes , parentSvgDocId ) : SVG文書を(docPathから)svg文書群とそのプロパティをHTTPXMLRequest(httpRes)から親文書(parentSvgDocId)の子文書(docId)として読込み、指定されたHTML要素(parentElem)に貼り付ける
- ignoreMapAspect() : 地図のアスペクト比を、rootSVGのviewBox( or hashのviewBox)そのものに設定する
- initLoad() : load時に"一回だけ"呼ばれる初期化関数
- isIntersect( rect1, rect2 ): rect1(x,y,width,height)とrect2が交差(包含も含む)しているかどうかを返却
- linkedDocOp( func , docHash , param1, param2 , param3 , param4 , param5 ) : 再帰実行のルートになる文書のハッシュ(docHash)以下の子・孫・・・文書に対して、同じ処理(func( docHash , param1, param2 , param3 , param4 , param5 ))を再帰実行する関数
- loadSVG( path , id , parentElem , parentSvgDocId) : SVG文書を(pathから)svg文書群とそのプロパティを親文書(parentSvgDocId)の子文書(id)として読込み、指定されたHTML要素(parentElem)に貼り付ける
- numberFormat( number , digits ) : 指定された数値(number)を小数点以下第digit+1位を四捨五入した値を取得
- override( mname , mval ) : グローバルオブジェクトの関数プロパティでmnameという変数にmvalの値を代入する
- parseEscapedCsvLine(csv) : CSV 1行分文字列データ(csv)をエスケープを考慮して配列にパースする。
- refreshScreen() : 画面の再描画を実行する
- registLayerUiSetter( layerUIinitFunc, layerUIupdateFunc ) : レイヤー選択UI初期化関数と更新用関数を設定する
- reLoadLayer(layerID_Numb_Title) : 指定したレイヤー(ルートコンテナのレイヤーのみ。小孫レイヤーはNG)をリロードする
- resumeToggle(evt) : 引数のイベント(evt)ターゲットのチェックボックスのチェック状態により、setResumeを実行する
- screen2Geo( screenX , screenY ) : 画面上の座標(px)を指定すると、その地理座標を返す
- setCustomModal( messageHTML , buttonMessages , callback,callbackParam) : モーダル画面を表示し、指定されたメッセージ(messageHTML)、指定されたボタン(buttonMessages(Array))を表示する。ボタンが押された場合、コールバック関数(callback)を引数(クリックしたボタンのインデックス, callbackParam)を渡し呼び出す
- setDevicePixelRatio( dpr ) : zoom計算時のみに用いる(たとえば2にするとzoom値が本来の2分の1になる)変数を指定値(dpr)に設定する
- setGeoCenter( lat , lng , radius) : 中心地理座標を指定して地図を移動 (radiusは緯度方向の度1≒110Km) lat,lng:必須 radius:オプション(今の縮尺のまま移動)
- setGeoViewPort( lat, lng, latSpan , lngSpan , norefresh) : 地理(グローバル)座標系で指定したエリアを包含する最小のviewportを設定する
- setLayerVisibility(layerID_Numb_Title) : 指定したルートコンテナのレイヤーの表示非表示を設定し、layerListUIのアップデートも行う
- setMapCanvas : ( mc ) : 地図キャンバスとなる、おおもとのdiv要素を指定した要素(mc)に設定
- setMapCanvasCSS(mc) : マップキャンバスのCSS(postion、overflow、top、left、width、height)を設定
- setMapCanvasSize( mcs ) : 地図キャンバスのサイズを指定したサイズ(mcs)に設定
- setSmoothZoomInterval(zoomInterval) : ズームアニメーションの設定(ズームイン/アウト後のタイル読み込み開始タイマー(ms))(Default:20ms)
- setSmoothZoomTransitionTime(zoomTransitionTime) : ズームイン/アウト時の遷移時間(Default:300ms)
- setResume( stat ) : レジュームを実行するかどうかを引数(stat)によって設定し、cookieにレイヤー情報を保存する
- setRootLayersProps(layerID_Numb_Title, visible , editing ) : ルートコンテナの(animetion||iframeで構成される)レイヤー情報を設定する。layerID_Numb_Titleは、レイヤー番号(root svg container内での順番)、レイヤーID(svg文書のiid = htmlのid = selectのvalue)、タイトル名(不確実-同じ名前があるかもしれない。最初に当たったものを選択)。変化があるとtrueが返却される。visible , editingはtrue,false,nullのいずれか。nullの場合、その値を変化させないという意味。もしくは不合理の場合はfalseが返却される。この時classで設定されているレイヤーグループの特性(switch)に基づいた制御がかかる ただしlayerListUIのアップデート(updateLayerListUI())は別途行う必要がある
- setRootViewBox ( rvb ) : aspectを加味し実際に開いているルートSVGのviewBoxを指定したルートSVGのviewBox(rvg)に設定*setShowPoiProperty( func , docId ) : 特定のレイヤー・svg文書(docId)もしくは、全体に対して別のprop.表示関数(func)を指定する。funcが未指定の場合、設定された関数をクリアする。指定した関数は、帰り値がfalseだった場合、デフォルトprop.表示関数を再度呼び出す
- setShowPoiProperty(func , docId ): 特定のレイヤー・svg文書(いずれもdocIDで指定)もしくは、全体に対してPOIをクリックした時の表示関数をセットする
- セットされていないときは内蔵のデフォルト関数が使用される
- docId: セットされていないときはすべてのレイヤの docIdがルートレイヤに対応するものの場合はそのレイヤー下の子孫文書に対しても
- func: セットされいていないときはクリアする
- setSummarizeCanvas( val ) : 2Dベクトル図形描画用に統合キャンバス(レイヤー単位でのキャンバス統合)の使用有無を設定する。デフォルトは統合する
- setUpdateCenterPos(func) : 中心座標書き換え関数を指定した関数に設定(デフォルト:id="centerPos"要素の文字列を適当に書き換える)
- setZoomRatio ( ratio ) : zoomUp、zoomDownボタン押下時のズームレシオを指定した値(ratio)に設定する
- showModal( htm , maxW, maxH) : モーダル表示フレームワークを呼び出し、指定したhtm文字列を最大maxW,H値の中で表示する。closeボタンはフレームワークで設置される
- showPage( hyperLink ) : 指定されたハイパーリンク先のページを表示する。ハッシュだけの場合は viewPort変化をさせる
- showUseProperty( target ) : 指定されたPOI( target )の属性情報を表示する
- transform ( x , y , mat , calcSize , nonScaling) : 指定された座標を変換する。
- updateLayerListUI() : レイヤーリストのUIの表示を更新させる
- zoomup() : 地図をズームアップ:倍率は1.732倍固定
- zoomdown() : 同ズームダウン
svgMapAuthoringTool.で呼び出せるAPI
以下のAPIは、SVGMapLv0.1_Authoring_r*.jsを用いた場合に使える
- initPOItools(targetDiv,poiDocId,cbFunc,cbFuncParam,getPointOnly) : 複数のPOIを編集するツールを初期化する (このツールは一個しか設置できない)
- targetDiv: 編集ツールを設置するDIV要素
- poiDocId : 対象とするDocId 文書にはuse要素でPointを設置するため、defs要素によって少なくとも一個以上のアイコンがあらかじめ定義されている必要がある
- cbFunc : 編集完了時に呼び出すコールバック関数(Optional) 第一引数にはツールの完了状態が文字列で返却される
- cbFuncParam : 同コールバック関数に渡す引数(Optional)
- getPointOnly : ポイントを取得するのみで、その点にuse要素を設置することはしない
- initPOIregistTool(targetDiv,poiDocId,poiId,iconId,title,metaData,cbFunc,cbFuncParam,getPointOnly): 一個のPOINTオブジェクトの登録ツール・座標入力ツールを初期化する
- targetDiv: 編集ツールを設置するDIV要素
- poiDocId : 対象とするDocId 文書にはuse要素でPointを設置するため、defs要素によって少なくとも一個以上のアイコンがあらかじめ定義されている必要がある
- poiId : 登録するPOIのIDを指定
- iconId : 対象文書内のアイコンのIDを指定
- title : アイコンのタイトルを指定
- metaData : アイコンのメタデータ文字列を指定
- cbFunc : 編集完了時に呼び出すコールバック関数(Optional)
- cbFuncParam : 同コールバック関数に渡す引数(Optional)
- getPointOnly : ポイントを取得するのみで、その点にuse要素を設置することはしない
- initPolygonTools(targetDiv,poiDocId,cbFunc,cbFuncParam,isPolylineMode): POLYGONオブジェクトの"編集"ツール 新規追加、削除、変更などが可能 ただし一個しか設置できない
- targetDiv: 編集ツールを設置するDIV要素
- poiDocId : 対象とするDocId 文書にはuse要素でPointを設置するため、defs要素によって少なくとも一個以上のアイコンがあらかじめ定義されている必要がある
- cbFunc : 編集完了時に呼び出すコールバック関数(Optional) 第一引数にはツールの完了状態が文字列で返却される
- cbFuncParam : 同コールバック関数に渡す引数(Optional)
- isPolylineMode : ポリゴンではなくポリラインの編集ツールとする
- setTargetObject: TBD
- isEditingGraphicsElement: TBD
svgMapGIStool.で呼び出せるAPI
以下のAPIは、SVGMapLv0.1_GIS_r*.jsを用いた場合に使える。なお本機能拡張はjsts.min.jsの読み込みがさらに必要。
- captureGeometries( cbFunc , opt ) : svgMap.captureGISgeometriesの引用
- getIncludedPoints(poiID, polyID, cbFunc, param , progrssCallback , inverse , pointOnly ) : TBD
- getExcludedPoints : TBD
- buildIntersection : TBD
- haltComputing : TBD
- drawGeoJson : TBD
- getInRangePoints
- setImageProxy
- latLng2GeoJsonPoint :
svgMapLayerUI.で呼び出せるAPI
以下のAPIは、SVGMapLv0.1_LayerUI2_r*.jsを用いた場合に使える。
- layerSpecificUIhide : TBD
- setLayerListmessage : TBD
起動URLによるオプション指定(内容チェック前)
svgMapフレームワークを導入したhtmlコンテンツは、URLの"#"以降であるフラグメント識別子によってフレームワークにいくつかの起動時オプションを提示することができます。 通常、これらのオプションは、ルートコンテナにおける記述で示されています。フラグメント識別子による指示はそれをオーバーライドします。 一般的な"&"による区切りで複数の複数のパラメータを指定できます。
表示範囲の指定
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
動的な地図レイヤー
svgドキュメントにjavascriptを記述することにより動的なデータ生成を実装可能としています。 本フレームワークでは、ドキュメント中に<script>要素を一つだけ記述することができ、その要素の中にjavascriptコードを入れることができます。
動的SVGMapコンテンツで利用可能な拡張API
一般のjavascriptAPIに加えて、動的な地図レイヤーを実装するために以下のAPIが提供されます。(既存のものでも注記があるものも列挙)
- document: このsvgMapドキュメント自身
- READ ONLY変数
- this.CRS:このドキュメントのCRS : CRS.a....fに、地理座標からこのドキュメントのSVGユーザ座標への変換係数が提供される
- this.scale:倍率:このドキュメントの座標系と、画面の(px座標系)との間の倍率
- this.actualViewBox:このドキュメントの座標系でのviewBox
- this.geoViewBox:地理座標におけるviewBox
- this.location:
- (this.verIE)
- refreshScreen(): 描画の更新を明示: refreshScreenを用いていない場合、そのレイヤーのDOMを編集してもそれが即座に表示に反映(更新)するとは限りません。文書のロード、ズーム、スクロールのときが表示のDOMの内容を反映した画面の自動更新のタイミングです。それ以外、多くの場合反映されません(性能確保のための本フレームワークの制限)。DOMO編集をそれ以外のタイミングで表示に反映したい場合、この関数の呼び出しを行うひつようがあります。一方不必要にこの関数を呼び出すとシステム全体の性能が低下するかもしれません。
- onload:この関数を設定すると、ロードされると呼ばれる(ドキュメントロード後、描画前のタイミング。)
- したがってonloadで実行される処理はその中が非同期でない限り、refreshScreen()しなくてもonload時のDOM編集は描画に反映される。
- onscroll:この関数を設定すると、スクロールされるとき呼ばれる(ほかにズーム以外で画面更新時も)(スクロール後の描画前のタイミング。)
- 同上
- onzoom:この関数を設定すると、ズーミングが発生するとき呼ばれる(同上)
拡張イベント
- document -> zoomPanMap イベント addEventHandlerすると、ズームパンが起き(viewPortが変化したとき)地図システム全体の描画が完了(含タイムアウト)後に発行される
- document -> screenRefreshed イベント addEventHandlerすると、ズームパン以外で地図システム全体の描画が完了(含タイムアウト)後に発行される。主にrefreshScreen()など。このイベントをフックにして、SVGMapコンテンツのDOM操作・再描画(refreshScreen())を行うと無限ループに陥るので使用方法に注意が必要。
レイヤー固有iframe (ベースのフレームワークrev12以上 且つLayerUI2フレームワークを拡張した時)
レイヤーコンテンツ(フレームワークが最初に読み込むルートsvgコンテンツの中で埋め込まれるsvgコンテンツ)に対して、そのレイヤーに固有のユーザインターフェースをhtmlによるウェブアプリとして持たせる機能が提供されます。 レイヤーのsvgコンテンツのルート要素(svg要素)に、data-controller属性を与え、そこにそのレイヤー固有のUIのためのhtml文書のリンク(ただしsame origin)を設置します。またサブセットとして、data-controller属性にビットイメージ(png or jpg)へのリンクを与えることでレイヤーの凡例情報の提示をすることもできます。
サンプル
<?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"> .....
拡張API
レイヤー固有iframeでは以下のAPIが拡張されています。
- イベント
- openFrame : そのiframeが、新たに生成された
- closeFrame : 同、消滅した
- hideFrame : 同、隠された
- appearFrame : 同、隠されていたのが再度現れた
- zoomPanMap : SVGMapフレームワークと同じ
- refreshScreen : 同上
- svgImageProps : このレイヤー固有UIに紐づいたレイヤーSVGの各種プロパティ
- svgImage : このレイヤー固有UIに紐づいたレイヤーSVG文書(DOM)
- svgMap : svgMapフレームワークインスタンス
- layerID : svgMapフレームワークが管理しているSVG文書ハッシュリスト(svgMap.getSvgImages())における、このレイヤー固有UIに紐づいたレイヤーSVG文書のハッシュキー
- svgMapGIStool : GIStoolsフレームワークを拡張した時、同インスタンス
- svgMapAuthoringTool : svgMapAuthoringToolフレームワークを拡張した時、同インスタンス