// -*- coding: utf-8 mode:html-helper -*-

/*!
  @mainpage 大経路RTコンポーネント機能仕様

<h2>はじめに</h2>

本コンポーネントは，自律移動ロボットの大経路計画モジュール群の一部であ
り，Windows上で動作するRGISコンポーネントである，RgisOperatorとの通信，
データフォーマットの変換を行う。他の大経路コンポーネントや，小経路コン
ポーネントから見た場合，RGISとのインターフェースとなる。

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

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


<h2>概要</h2>

環境GIS研究所様作成によるRgisOperatorコンポーネントに接続し，以下の機能を提供する。
<ul>
  <li>Linux側で動作するコンポーネントとしてRgisOperatorへのインターフェースとなる </li>
  <li>共通のデータ通信形式としてXMLをサポート </li>
  <li> 目的地の入力</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> MapServicePort </td>
    <td> サービスポート(Consumer) </td>
    <td> @see RgisOperator_simple.idl </td>
    <td> RgisOperatorのMapServiceを受けるためのポート </td>
  </tr>
  <tr>
    <td> RouteServicePort </td>
    <td> サービスポート(Consumer) </td>
    <td> @see RgisOperator_simple.idl </td>
    <td> RgisOperatorのRouteServiceを受けるためのポート </td>
  </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>

MapServiePortおよび，RouteServicePortの通信仕様はRgisOperatorの通信仕様
(@a RgisOperator_simple.idl)に従う。

入力ポート(@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 GridMap.h
@see Localization.h

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

<pre>

data = header, object-data;

header = @a baseRTC::Header;

object-data = @a NavData::PotentialGrid

            | @a NavData::PathNodes

            | @a NavData::CommandString

            | @a NavData::TaggedPoint

            | @a Localization

            | @a GridMap

            ;
</pre>


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

<h3> GlobalNavigationモジュール内の構成 </h3>
<pre>
.
├── bin                         バイナリ
│   ├── GlobalNavigation.xml     コンポーネント設定ファイル
│   ├── GlobalNavigationComp     コンポーネントバイナリ
│   └── rtc.conf                 コンポーネント設定ファイル
├── doc                         ドキュメント
│   ├── html                      HTMLファイル群
│   ├── images                    画像ディレクトリ
│   └── latex                     latexファイル群
└── src                         コンポーネントのソースディレクトリ
    ├── Doxyfile
    ├── GlobalNavigation.xml
    ├── GlobalNavigation.yaml
    ├── GlobalNavigationComp.cpp
    ├── GlobalNavigationRTC.cpp
    ├── GlobalNavigationRTC.h
    ├── Makefile
    ├── RgisOperator_simple.idl
    ├── RgisOperator_simpleDynSK.cc
    ├── RgisOperator_simpleSK.cc
    ├── RgisOperator_simpleStub.cpp
    ├── config_data.cpp
    ├── config_data.h
    ├── cur_pos.h
    ├── debug_utils.cpp
    ├── debug_utils.h
    ├── gnav.cpp
    ├── gnav.h
    ├── rtc.conf
    ├── service_if.cpp
    ├── service_if.h
    └── mainpage.txt
</pre>
  
<h2>使用方法 </h2>  

<h3> 開発／動作環境 </h3>

開発／動作チェックは<a href="http://www.ubuntu.com/">Ubuntu</a> 8.04.3 にて行った。

<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>$ ./GlobalNavigationComp </li>
  </ul>
  </li>
  <li>ポートを接続する。
  @image html  connection2.png "ポート接続の例"
  @image latex connection2.eps "ポート接続の例"
  <br>
  <ul>
    <li>MapServicePortをRGISOperatorのMapServicePortへ接続</li>
    <li>RouteServicePortをRGISOperatorのRouteServicePortへ接続</li>
    <li>入力ポートをXMLを生成するコンポーネントへ接続</li>
    <li>出力ポートをXMLを受信するコンポーネントへ接続</li>
  </ul>
  </li>
  <li>コンポーネントをアクティベートする。 </li>
</ol>

<p>
上記の接続図では，入力ポートの一つをgenxml(テスト用，xml生成コンポーネ
ント) 出力ポートの一つをMapViewRTC(地図表示用GUIコンポーネント)に接続している。
入力ポートからは，現在値，目的地などのデータを受信する。出力ポートには，
ポテンシャルマップや経路データなどが送信される。
</p>


<h3> 終了 </h3>

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

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

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

<ul>
  <li>
  input_number: 入力ポートの数を指定する。
  </li>
  <li>
  destination: 起動時に送信する目的位置の設定(終了時に持っていた値が保存される)
  </li>
  <li>
  current_pos: 起動時に送信する現在位置の設定(終了時に持っていた値が保存される)
  </li>
  <li>
  pgrid_depth: 出力ポートへ送信するポテンシャルグリッドの階調を設定する。
  2から65536でなくてはならない。RgisOperatorとの通信は64bitのbinaryデータ
  で行われるが，送信ポートへはXML化した形でデータを送信する。このため。
  データ量が膨大になることを防ぐために，階調を制限することが可能である。
  </li>
  <li>
  use_saved_curpos: この値を零にすると，起動時に設定ファイルに
  保存された現在位置を送信しない。
  </li>
</ul>



<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>
</ul>

<h3> 構築方法</h3>

<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>$ make </tt>
    </li>
  </ol>

  </li>  
</ol>

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

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

本コンポーネントと通信に必要なデータ形式は，以下のヘッダファイルに定義
されている。
@see baseRTC.h
@see xml_serdes.h
@see navigation_data.h
@see GridMap.h
@see Localization.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>


 */





