// -*- coding: utf-8 mode:html-helper -*-
/*!
  @mainpage MapViewerコンポーネント機能仕様

<h2>はじめに</h2>

本コンポーネントは，自律移動ロボットの大経路計画モジュール群の一部であり，
経路計画に使用される地図データや経路の表示を行う。

大経路のモジュール郡は以下から構成されている。RGISOperator以外はubuntu
linux 8.04上で動作する。

<ul>
  <li>
  RGISOperator: RGISの地図データから移動ポテンシャルグリッド，最短経路を生成する。Windows上で動作する。
  </li>
  <li>
  GlobalNavigation: RGISOperatorとの通信，データ形式の変換を行う。
  </li>
  <li>
  MapViewer: 上記のコンポーネントが生成したデータの表示や保存，GUIによる目的地や現在地の設定をおこなう。
  </li>
</ul>
  
<h2>概要</h2>

本コンポーネントの提供する機能は以下の通りである。

<ul>
  <li>表示する地図レイヤの登録</li>
  <li>登録されたレイヤの表示／非表示切替</li>
  <li>レイヤ表示順序入れ替え</li>
  <li>レイヤ不透明度の制御</li>
  <li>レイヤ情報の表示</li>
  <li>座標線の表示</li>
  <li>地図の拡大，縮小，スクロール</li>
  <li>任意文字列の表示</li>
  <li>目的地の登録</li>
  <li>現在地の登録</li>
  <li>地図のAutoScroll</li>
  <li>マウス位置の座標(実際の位置)を画面上に表示</li>
  <li>縮尺情報の表示</li>
  <li>表示地図のスナップショット画像保存</li>
  <li>レイヤデータの保存</li>
  <li>レイヤデータの削除</li>
</ul>

<h2>入出力</h2>

<h3>ポート構成</h3>

本コンポーネントのポート構成は以下の通り

<table align="center" cellpadding="0" border=1>
  <tr>
    <th bgcolor="#aaaaff" colspan=4><div align="center">ポートの構成</div></th>
  </tr>
  <tr>
    <th> 名称</th>
    <th> ポートの種類</th>
    <th> データの型</th>
    <th> 説明</th>
  </tr>
  <tr>
    <td> in<em>n</em> (nは数字) </td>
    <td> 入力ポート </td>
    <td> TimedString</td>
    <td>
      XMLにシリアライズされたオブジェクトを受信するポート。
      設定ファイルにて個数を変更可能。デフォルトのポート数は1
    </td>
  </tr>
    <tr>
    <td> out </td>
    <td> 出力ポート </td>
    <td> TimedString</td>
    <td>
      このコンポーネントの処理結果を出力するポート。
      出力データはXMLにシリアライズされて送信されるため，テキスト型である。
    </td>
  </tr> 
</table>

<h3>入出力データ仕様</h3>


入力ポート(@a in) および出力ポート(@a out)では，データはXMLにシリアライ
ズされて送信される。シリアライズ／デシリアライズには<a
href="http://www.boost.org/">Boostライブラリ</a>1.34.1を使用している。
送受信のデータフォーマットについては以下のファイル内のデータ定義を参照
のこと。

@see baseRTC.h
@see xml_serdes.h
@see navigation_data.h
@see Localization.h
@see GridMap.h

本コンポーネントが入出力するデータ形式は以下の通りである。ただし，構造
体名の部分はそれぞれXMLにシリアライズされた文字列とする。

<pre>

data = header, object-data;

header = @a baseRTC::Header;

object-data = @a NavData::PotentialGrid

            | @a NavData::CommandString

            | @a NavData::TaggedPoint

            | @a Path
			
            | @a GridMap

            | @a Localization

            ;
</pre>


<h2>ディレクトリ構成</h2>

本モジュールのファイル／ディレクトリ構成は以下の通りである。

<h3> RTCモジュール群の中での位置 </h3>
<pre>
[RTC2009トップディレクトリ]
├── common
│   ├── include
│   ├── lib
│   └── src
│       ├── baseRTC
│       └── serdes
├── human_interface
│   └── mapviewer
│       ├── bin
│       ├── doc
│       │   └── images
│       └── src
│           ├── doxydoc
│           │   └── images
│           ├── images
│           └── init
(以下略)
</pre>

<h3> mapviewerモジュール内の構成 </h3>
<pre>
mapviewer
├── bin                         バイナリ
│   ├── MapViewer                コンポーネントバイナリ
│   ├── MapViewer.xml            コンポーネント設定ファイル
│   └── rtc.conf                 コンポーネント設定ファイル
├── doc                         ドキュメント
│   ├── html                      HTMLファイル群
│   ├── images                    画像ディレクトリ
│   └── latex                     latexファイル群
└── src                         コンポーネントのソースディレクトリ
    ├── mapviewer.pro           Qtのqmake用プロジェクトファイル
    ├── Doxyfile
    ├── common_defs.h
    ├── config_data.cpp
    ├── config_data.h
    ├── debug_utils.cpp
    ├── debug_utils.h
    ├── gui_main.cpp
    ├── gui_main.h
    ├── gui_settings.cpp
    ├── gui_settings.h
    ├── images
    │   ├── 24-em-check.png
    │   ├── 24-em-cross.png
    │   ├── camera.png
    │   ├── camera_win.png
    │   ├── down_arrow.png
    │   ├── floppy.png
    │   ├── map.png
    │   ├── pos_set.png
    │   ├── trashcan_full.png
    │   ├── up_arrow.png
    │   ├── zoomin.png
    │   └── zoomout.png
    ├── images.qrc
    ├── layer_archive.cpp
    ├── layer_archive.h
    ├── layer_view.cpp
    ├── layer_view.h
    ├── main.cpp
    ├── map_grid.cpp
    ├── map_grid.h
    ├── map_layer.cpp
    ├── map_layer.h
    ├── map_layer_delegate.cpp
    ├── map_layer_delegate.h
    ├── map_layer_list_model.cpp
    ├── map_layer_list_model.h
    ├── map_layer_table_view.h
    ├── map_manager.cpp
    ├── map_manager.h
    ├── map_view.cpp
    ├── map_view.h
    ├── mapview_rtc.cpp
    ├── mapview_rtc.h
    ├── rtc.conf
    ├── shared_queue.h
    ├── widget_observer.cpp
    ├── widget_observer.h
    └── mainpage.txt

</pre>  
<h2>使用方法 </h2>

<h3> 起動 </h3>

起動の順序は以下の通り。

以下の方法はEclipse上のRTCLinkで行うことを想定している。
<ol>
  <li>事前準備
  <ul>
    <li>OmniORBネームサービスの設定が適切に行われていること</li>
    <li>WindowsPC上でRGISOperatorコンポーネントを起動する</li>
    <li>RGISOperatorの設定を行う(Eclipse上のRTCLinkから行っても，あらかじめデフォルトの設定ファイルを書き換えておいても良い)</li>
  </ul>
  </li>
  <li>コンポーネントのバイナリを実行する
  <ul>
    <li>バイナリの置き場所に移動</li>
    <li>$ ./MapViewer </li>
  </ul>
  </li>
  <li>ポートを接続する。
  @image html connection4.png
  @image latex connection4.eps
  <br>
  <ul>
    <li>入力ポートをXMLを生成するコンポーネントへ接続</li>
    <li>出力ポートをXMLを受信するコンポーネントへ接続</li>
  </ul>
  </li>
  <li>コンポーネントをアクティベートする。 </li>
</ol>
<p>
上記の接続図においては，入力ポートをGlobalNavigation(大経路計画)コンポーネント
に接続し，出力ポートをGlobalNavigation(大経路計画)コンポーネントとstrinコンポーネントに接続している。(strinは，テストに使用したポート内容をダンプするコンポーネントである)
</p>
<p>
この接続では，大経路からの
<ul>
  <li>ポテンシャルグリッドマップ</li>
  <li>経路情報</li>
</ul>
を受信する。またMapViewerの出力はstrinとGlobalNavigationに分配される。
MapViewerの送信出力は下記のように処理される。現在のところ出力は
GUIで指定した目的地と現在地である。
<ul>
  <li> GlobalNavigationは，目的地／現在地を受信する</li>
  <li> strinは全てを受信し標準出力にダンプする </li>
</ul>

</p>


<h3>ユーザインターフェース </h3>

ユーザインターフェースは下記二つのウィンドウからなる。
<ol>
  <li>MapViewウィンドウ
  </li>
  <li>LayerViewウィンドウ</li>
</ol>
それぞれについて以下で説明する。

<h4>MapViewウィンドウ</h4>

@image html  mapview_win_usage.png
@image latex mapview_win_usage.eps

このウィンドウは，地図の情報を実際に表示するウィンドウである。マウス／
ボタンの操作により，地図のスクロールやズームイン，ズームアウトが可能で
ある。

<table align="center" cellpadding="0" bgcolor="#ffffff" border=1>
  <tr>
    <th bgcolor="#aaaaff" colspan=2><div align="center">各部の使用方法 </div></th>
  </tr>
  <tr>
    <th align="center"> 名称 </th><th>機能</th>
  </tr>
  <tr>
    <td>ズームインボタン</td>
    <td>クリックすることにより地図が拡大する</td>
  </tr>
  <tr>
    <td>ズームアウトボタン</td>
    <td>クリックすることにより地図が縮小する</td>
  </tr>
  <tr>
    <td>ズーム調整スライダ</td>
    <td>スライドすることで地図が拡大／縮小する。カーソルがこの上にあるときにマウスホイールを操作することでも拡大，縮小ができる</td>
  </tr>
  <tr>
    <td>座標グリッド表示／非表示切替えチェックボックス</td>
  <td>座標線グリッドの表示／非表示を切り替える</td>
  </tr>
  <tr>
    <td>autoscroll on/off切替えチェックボックス</td>
    <td>地図のオートスクロールをon/offする</td>
  </tr>
  <tr>
    <td>カーソル位置座標，縮尺の表示</td>
    <td>マウス位置に対応する実際の位置，グリッド間隔を表示する</td>
  </tr>
  <tr>
    <td>地図スナップショットの保存</td>
    <td>表示中の地図を画像として保存することが出来る</td>
  </tr>
  <tr>
    <td>その他</td>
    <td>地図画面上で右クリックすることにより，目的地を設定することができる</td>
  </tr>
</table>


<h4>LayerViewウィンドウ</h4>

@image html  layer_win_usage.png
@image latex layer_win_usage.eps

このウィンドウは，地図レイヤーの情報の表示する。また描画順，不透明度等
の設定，レイヤーの保存，新規レイヤーの読み込みが可能である。

<table align="center" cellpadding="0" bgcolor="#ffffff" border=1>
  <tr>
    <th bgcolor="#aaaaff" colspan=2><div align="center">各部の使用方法 </div></th>
  </tr>
  <tr>
    <th align="center"> 名称 </th><th>機能</th>
  </tr>
  <tr>
    <td>可視／不可視表示</td>
    <td>レイヤがMapViewウィンドウに表示されるかどうかを設定する</td>
  </tr>
  <tr>
    <td>不透明度表示</td>
    <td>レイヤの不透明度をパーセント表示する</td>
  </tr>
  <tr>
    <td>レイヤ名称表示</td>
    <td>レイヤの名称を文字列で表示する</td>
  </tr>
  <tr>
    <td>レイヤの表示順序設定ボタン</td>
    <td>クリックすることで選択したレイヤの表示順を変更する</td>
  </tr>
  <tr>
    <td>その他</td>
    <td>地図画面上で右クリックすることにより，以下が可能である。
      <ul>
	<li>
	新規レイヤーの読み込み
	</li>
	<li>
	レイヤーの削除
	</li>
      </ul>
    </td>
  </tr>
</table>






<h3> 終了 </h3>

終了順序は以下の通り
<ol>
  <li>本コンポーネントをディアクティベートする</li>
  <li>コンポーネントを終了する</li>
</ol>

<h2>ビルド方法 </h2>  

<h3> 要求するライブラリ</h3>

ビルドに必要となるライブラリは以下の通り。BoostおよびXerces-C++は
ubuntu8.04から<tt>apt-get</tt>でインストールしたものである。
<ul>
  <li><a href="http://www.is.aist.go.jp/rt/OpenRTM-aist/html/">
  OpenRTM-aist-0.4.2</a>及び関連パッケージ一式</li>
  <li><a href="http://www.boost.org/">Boost</a> 1.34.1</li>
  <li><a href="http://xerces.apache.org/xerces-c/">Xerces-C++ XML Parser</a>
   2.8.0
  </li>
  <li><a href="http://qt.nokia.com/">Qt</a>4.5.3
  開発開始時点での最新版:  qt-sdk-linux-x86-opensource-2009.04.1.bin
  </li>
</ul>

<h4> Qtのinstall手順 </h4>

<ol>
  <li> 上記Nokiaのサイトより，最新バージョンのQtをダウンロードする。</li>
  <li>
  実行属性を付与する <tt> $ chmod 755 ./qt-sdk-linux-x86-opensource-2009.04.1.bin </tt>
  </li>
  <li>
  root 権限により，当該ファイルを実行する。インストーラが起動する。
  いくつか質問に答えることでインストールが終了する。
  <tt>
  $ sudo ./qt-sdk-linux-x86-opensource-2009.04.1.bin 
  </tt>
  特に設定を変更しなければ，<tt>/opt/qtsdk-2009.04</tt>以下にインストールされる。
  </li>

  <li> (optional) 使用するユーザのパスを設定する。ubuntuには，あらかじ
  め<tt>/usr/</tt>以下に やや古いバージョンのqtがインストールされている。
  以下で，qmakeなどのコマンドを実行するが，こうしたコマンドも<tt>/usr/bin/qmake </tt>および<tt>/opt/qtsdk-2009.04/qt/bin </tt>に重複して存在することになり，
  実際に使用するコマンドを間違い易い。

  こうした曖昧さを避けるには，以下のいずれかを行う必要がある。
  <ul>
    <li> qtのコマンドはフルパスで指定する 例:<tt>/opt/qtsdk-2009.04/qt/bin/qmake</tt></li>

    <li>ユーザのPATH環境変数の<em>先頭</em>にqtのpathを追加する</li>
  </ul>
  後者を選択した場合，追加すべきパスは
  <ul>
    <li>/opt/qtsdk-2009.04/qt/bin</li>
    <li>/opt/qtsdk-2009.04/qt/qt/bin</li>
  </ul>
  の二つである。前者には，qtcreatorなどの開発ツール，後者にはassistant, qmake
  など様々なツール群が含まれている。

  </li>
</ol>
  <strong>Qtの異なるバージョンをインストールした場合，上記の <tt>qtsdk-2009.04</tt>などはインストールしたバージョンに読み替えること。</strong>

また，<tt> sudo ln -sf /opt/qtsdk-2009.04 /opt/qt </tt> などのように，シンボリックリンクを活用する方法もある。
  




<h3>Qtのプロジェクトファイル </h3>

本プロジェクトのビルドにはQtのqmakeを使用する。プロジェクトファイル(mapviewer.pro)の内容は以下の通り

@verbinclude mapviewer.pro


<ol>
  <li>
  共通ライブラリの構築を行う。
  <ol>
    <li>ライブラリのあるディレクトリに移動: <tt>$ cd common/src </tt></li>
    <li>ライブラリの構築: <tt>$ make && make install </tt></li>
  </ol>
  </li>
  <li>コンポーネントの構築を行う
    <ol>
    <li>
      コンポーネントのあるディレクトリに移動:
      <tt>$ cd src</tt>
    </li>
    <li>
      コンポーネントの構築:
      <tt>$ qmake && make && make install</tt>
    </li>
  </ol>

  </li>  
</ol>

<h2> 設定用XMLファイルについて </h2>

本コンポーネントは，初期化時に設定ファイルを読み込む。
RTCのコンフィグで読み込むファイルを設定可能である。
デフォルトでは，バイナリが起動されたディレクトリにあるMapViewer.xmlであ
る。現在設定可能な項目は下記の通りである。それ以外のタグを指定しても無
視される。

<ul>
  <li>
  input_number: 入力ポートの数を指定する。
  </li>
  <li>
  startup_dir: 起動時にレイヤー等のデータを読み込むディレクトリ名
  </li>
  <li>
  potential_min: ポテンシャルマップを偽色表示する際に，これ以下の値は最低値と見なす
  </li>
  <li>
  potential_max: ポテンシャルマップを偽色表示する際に，これ以上の値は最高値と見なす
  </li>

</ul>


<h2> バイナリ配布の場合の使用方法について </h2>

本コンポーネントのバイナリ配布を使用し，ビューワー等に使用する場合，自
律移動ロボットコンポーネント群（大経路計画，小経路計画，各種センサ／制
御用コンポーネント）が使用する通信データフォーマットに従う必要がある。
通信データの詳細は，入出力データ仕様の項目を参照のこと。

本コンポーネントと通信に必要なデータ形式は，RTC2009/common以下にある，下記
ヘッダに定義されている。

@see baseRTC.h
@see xml_serdes.h
@see navigation_data.h
@see Localization.h
@see GridMap.h

ただし，上記のヘッダファイルが間接的に必要とするファイル，ライブラリと
して，RTC2009/common以下のファイル一式(ヘッダ／ライブラリ)と，下記のラ
イブラリも必要となる。

<ul>
  <li><a href="http://www.is.aist.go.jp/rt/OpenRTM-aist/html/">
  OpenRTM-aist-0.4.2</a>及び関連パッケージ一式</li>
  <li><a href="http://www.boost.org/">Boost</a> 1.34.1</li>
  <li><a href="http://xerces.apache.org/xerces-c/">Xerces-C++ XML Parser</a>
   2.8.0
  </li>
</ul>





 */


