= BarCodeReaderコンポーネント v0.2.1.3

== 概要

* BarCodeReaderは、入力ポートからの入力画像(Img::TimedCameraImage型)
  からバーコードを読み取り、その位置姿勢(6DOF)を出力するRTコンポーネントです。
  * ZBarライブラリがサポートする各種1次元バーコードを読み取ることができます。

* ARMarkerReaderは、入力ポートからの入力画像(Img::TimedCameraImage型)
  から拡張現実感(AR)マーカを読み取り、その位置姿勢(6DOF)を出力するRTコン
  ポーネントです。
  * ARToolKitPlusライブラリがサポートするマーカを読み取ることができます。

* Imagerコンポーネントは、BarCodeReader/ARMarkerReader の動作確認のための
  サンプルプログラムです。
  USBカメラや動画ファイル、静止画像列などから画像データを読み取り、
  出力ポートから画像(Img::TimedCameraImage型)を出力します。

* ObjectIdProviderコンポーネントは、BarCodeReader/ARMarkerReader の動
  作確認のためのサンプルプログラムです。

* ライセンスは OpenRTM-aist-1.0 に準じます。

* 実行環境は Ubuntu10.04LTS です。

* コンパイルに必要なソフトウェアは以下のとおりです。
  * OpenRTM-aist-1.0
  * ZBar-0.10
  * ARToolKitPlus-2.1.5
  * OpenCV-2.0
  * その他開発用パッケージ&ライブラリ

=== スクリーンショット

* BarCodeReader実行のスクリーンショット

  ((<BarCodeReader実行のスクリーンショット|"IMG:BarCodeReader_Screenshot2.JPG">))
* ARMarkerReader実行のスクリーンショット

  ((<ARMarkerReader実行のスクリーンショット|"IMG:ARMarkerReader_Screenshot.JPG">))

== ZBarについて
バーコードを読み取るソフトウェアライブラリ。
* EAN-13/UPC-A, UPC-E, EAN-8, Code 128, Code 39, Interleaved 2 of 5,
  および QR Code に対応
* ライセンスは、GNU LGPL 2.1
* Link: ((<ZBar|URL:http://zbar.sourceforge.net/>))

== ARToolKitPlusについて
2次元マーカからカメラの位置姿勢を検出するためのソフトウェアライブラリ。
* ARToolKitの拡張。
* ライセンスは、GPL
* オリジナルは ARToolKitPlus2.1.1 でアップデート停止。
* 現在は別プロジェクトとして開発が進んでいる。ただしLinuxのみ。
* Link
  * ((<オリジナルARToolKitPlus|URL:http://studierstube.icg.tugraz.at/handheld_ar/artoolkitplus.php>))
  * ((<新ARToolKitPlus|URL:https://launchpad.net/artoolkitplus>))

== 入出力

=== 入力データポート

* ポート名:  "Image"
* データ型:  Img::TimedCameraImage
* Img.idlの定義
   module Img {
      /* vector and matrix type */
     typedef double Vec3[3];
     typedef double Mat44[4][4];
     
     /* image */
     enum ColorFormat
     {
       CF_UNKNOWN, CF_GRAY, CF_RGB
     };
     
     struct ImageData
     {
       long width;
       long height;
     
       ColorFormat format;
       sequence<octet> raw_data;
     };
     
     /* camera image */
     struct CameraIntrinsicParameter
     {
       double matrix_element[5];
       sequence<double> distortion_coefficient;
     };
     
     struct CameraImage
     {
       RTC::Time captured_time;
       ImageData image;
       CameraIntrinsicParameter intrinsic;
       Mat44 extrinsic;
     };
     
     struct TimedCameraImage
     {
       RTC::Time tm;
       CameraImage data;
       long error_code;
     };
   }

=== 出力データポート

* ポート名: "RecognitionResult"
* データ型:  RTC::TimedDoubelSeq
* 要素数: 20
* 配列内容
   カメラID, 物体ID, 認識候補No, 座標系No,
   認識確度, エラーNo, 予備１, 予備２,
   r000，r001，r002，t0x，
   r010，r011，r012，t0y.
   r020，r021，r022，t0z,

=== サービスコンシューマポート

* ポート名: "objectId"
* インタフェース名: recognitionService
* データ型: RecognitionService
* RecognitionService.idlの定義

  interface RecognitionService
  {
    long getModelID();
    void setModelID(in long ModelID);
  };


== パッケージのディレクトリ構成
 TOP.
    |-- UFV                        --- ライブラリソースコード
    |   |-- CLUEReaderImpl
    |   |-- DetectorImpl
    |   `-- ImagerImpl
    |-- doc                        --- ドキュメントなど
    |-- include                    --- ヘッダファイル
    |-- lib                        --- サードパーティのライブラリファイル
    `-- rtc
         |-- ARMarkerReader        --- ARMarkerリーダコンポーネント
         |-- BarCodeReader         --- 1次元バーコードリーダコンポーネント
         |-- Imager                --- 画像コンポーネント(サンプル)
         |   `-- share
         |       `-- CameraParam
         `-- ObjectIdProvider      --- オブジェクトIDコンポーネント (サンプル)


== インストール

=== 必要ソフトウェアのインストール
(0) PCにOSとして Ubuntu10.04LTS をインストール

(1) OpenRTM-aist-1.0.0 を一括インストールスクリプトでインストール
    * 一括インストールスクリプトについては OpenRTM-aist のWebサイト
      http://www.openrtm.org/ をご覧ください。
    * インストール後、OSを再起動し、ネームサーバを起動してください。

(2) RTSystemEditor をインストール
    * インストール方法は OpenRTM-aist のWebサイトをご覧ください。

(3) 以下の開発パッケージとライブラリを apt-get でインストール
    * autoconf
    * automake
    * libtool
    * libjpeg62-dev
    * freeglut3-dev
    * libdc1394-22-dev
    * libcv-dev
    * libcv4
    * libcvaux-dev
    * libcvaux4
    * libhighgui-dev
    * libhighgui4

(4) ZBar-0.10 をコンパイルしてインストール
    * 必要パッケージを apt-get でインストール
      * libmagickwand-dev
      * libgtk2.0-dev
      * python-gtk2-dev
      * libqt4-dev, libqt4-gui
    * コンパイル&インストール
        $ ./configure ; make ; sudo make install
        $ sudo ldconfig

(5) ARtoolkitPlus2.1.5 をコンパイルしてインストール
    * 必要パッケージを apt-get でインストール
      * scons
    * ARToolkitPlus-2.1.5/SConstruct を修正
        $ diff ../ARToolkitPlus-2.1.5/SConstruct SConstruct
        2c2
        < vrs.Add("prefix", "installation directory", "/usr")
        ---
        > vrs.Add("prefix", "installation directory", "/usr/local")
        14c14
        < arlib = env.SharedLibrary("ARToolkitPlus", sources)
        ---
        > arlib = env.SharedLibrary("ARToolKitPlus", sources)
    * コンパイル&インストール
        $ scons
        $ sudo scons install
    * リンク作成
        $ cd /usr/local/lib
        $ sudo ln -s libARToolKitPlus.so libARToolKitPlus.so.2
        $ sudo ldconfig

=== パッケージのコンパイル
(1) UFVライブラリのコンパイル
    * コンパイル
        $ cd $(TOP)/UFV
        $ ./configure
        $ make

(2) BarCodeReaderのコンパイル
    * コンパイル
        $ cd $(TOP)/rtc/BarCodeReader
        $ make -f Makefile.BarCodeReader

(3) ARMarkerReaderのコンパイル
    * コンパイル
        $ cd $(TOP)/rtc/ARMarkerReader
        $ make -f Makefile.ARMarkerReader

(4) ObjectIdProviderのコンパイル
    * コンパイル
        $ cd $(TOP)/rtc/ObiectIdProvider
        $ make -f Makefile.ObiectIdProvider

(5) Imagerのコンパイル
    * コンパイル
        $ cd $(TOP)/rtc/Imager
        $ make -f Makefile.Imager


== BarCodeReader/ARMarkerReaderコンポーネントの使用法

=== 接続イメージ

   +----------+
   |  Imager  |=>--+
   +----------+    |
          <Img::TimedCameraImage>
                   |      +------------------+
                   +----<=|                  |=> --- <RTC::TimedDoubleSeq> ---
                          |  BarCodeReader   |
                          |       or         |
                          |  ARMarkerReader  |
                     +--#=|                  |
                     |    +------------------+
           <RecognitionService>
                     |    +------------------+
                     +--#=| ObjectIdProvider |
                          +------------------+

=== 使用手順

(1) ハードウェアを準備する。
    * PC (Ubuntu10.04LTS)を起動する。
    * USBカメラをPCに接続し、以下を確認する。
      * 毎秒15フレーム以上で画像入力ができること
      * 入力画像の解像度が640x480であること
      * フォーカス、コントラスト、明度などが適切に設定されていること
      注): カメラの設定方法は機種や接続方法によって異なります。

(2) $(TOP)/rtc/*/rtc.conf ファイルを環境に合わせて書き換える。
    * corba.nameservers と corba.endpoint の値を書き換えます。
    * OSのIPアドレスは ifconfig -a コマンドで取得できます。
 
(3) RTSystemEditorを起動し、ネームサーバ localhost:2809 または
    IPアドレス:2809 を追加する。
    * ネームサーバは、RTSystemEditorの"Name Service View"のコンセント
      形アイコンをクリックすれば追加することができます。

(4) "端末"からBarCodeReaderコンポーネントを起動する。
      $ cd $(TOP)/rtc/BarCodeReader
      $ ./BarCodeReaderComp

(5) 別の"端末"からImagerコンポーネントを起動する。
      $ cd $(TOP)/rtc/Imager
      $ ./ImagerComp

(6) 別の"端末"からObjectIdProviderコンポーネントを起動します。
      $ cd $(TOP)/rtc/ObjectIdProvider
      $ ./ObjectIdProviderComp

(7) RTSystemEditorの"Name Service View"の localhost:2809ツリーから、各コン
    ポーネントを"System Diabram"にドラッグ&ドロップします。
 
(8) Imagerコンポーネントの出力ポートと、BarCodeReaderコンポーネントの
    入力ポートとを接続します。
 
(9) ObjectIdProviderのサービスポートと、BarCodeReaderコンポーネントの
    サービスポートとを接続します。
 
(10) ImagerコンポーネントをActivateし、以下を確認する。
     * 画像表示用のWindowが開くこと
     * そのWindowにUSBカメラからの画像が連続的に表示されること。
 
(11) ObjectIdProviderをActivateする。
 
(12) BarCodeReaderコンポーネントを Activate し、以下を確認する。
     * バーコードの特徴点検出結果を表示するWindow が開くこと
     * バーコードの位置姿勢認識結果を表示するWindow が開くこと
 
(13) USBカメラを適当なバーコードに近づけ、バーコード認識結果が表示され
     ることを確認する。
     * バーコードとカメラの距離はスクリーンショットを参考にしてください。
     * ただし、バーコードの認識精度等は照明条件などに左右されます。
 
(14) 終了時には、各コンポーネントを Deactivate する。

* ARMarkerReader コンポーネントも同様の手順で利用できます。
  * ARMarkerReader コンポーネントを Activate すると、位置姿勢認識結果
    を表示するWindowがひとつだけ開きます。
  * マーカはARToolKitPlusパッケージに含まれている画像 
        ARToolkitPlus-2.1.5/id-markers/bch/BchThin_????.png
    を拡大印刷してご利用ください。

=== 使用上の注意

==== 実行環境について

* BarCodeReader/ARMarkerReaderコンポーネントへの入力画像は、以下を想定しています。
  * コンポーネントへの入力画像の解像度は、640x480ピクセルであること
  * コンポーネントへの画像入力サイクルは、毎秒30フレーム以下であること
  * カメラの内部パラメタが、入力画像のすべてのフレームに含まれていること。
  * カメラのフォーカス、コントラスト、明度等が適切に設定されていること。

* 認識するバーコードのデフォルトのサイズは以下のとおりです。
  * バーコード: 幅31mm, 高さ11mm
  * ARToolKitPlusマーカ: 一辺 20mm
  * これらの値は、RTSystemEditorのコンフィギュレーションビューで
    変更できます。

* Imagerコンポーネントは、PCに接続したUSBカメラ等から画像を取り込む
  サンプルプログラムです。
  * OpenCV2.0でサポートされているUSBカメラが必要です。

==== カメラ内部パラメタについて
* Imagerコンポーネントが出力する画像データに含まれるカメラ内部パラメタは、
  デフォルトでは以下の値が用いられます。
    レンズ歪み:
      [  0.0521901,  -0.137511, -0.00118309, 0.00110536 ]
    カメラパラメタ:
       - [    533.679,          0,    322.334 ]
       - [          0,    532.424,    244.238 ]
       - [          0,          0,          1 ]

* 実際に接続したカメラの内部パラメタが不明でも、上記デフォルト値のまま
  で動作確認は可能です。
  カメラの設定もオートフォーカスにしておけばよいでしょう。

* ただし、バーコードの正しい位置姿勢を計測するには、
  カメラの設定を固定フォーカスにした上で、
  別途カメラキャリブレーションをしておく必要があります。
  * カメラキャリブレーションは、本パッケージには含まれません。
    実行にあたっては OpenCVのドキュメント等を参考にしてください。

* Imagerコンポーネントは、デフォルトでは
      $(TOP)/rtc/Imager/share/CameraParam/Qcam200V.yml
  からカメラ内部パラメタを読み取ります。パラメタ値を変更するには、
  上記ファイルを書き換えるか、
  別のファイルをRTSystemEditorのコンフィギュレーションで指定してください。

==== コンポーネントの実行順序について
* 本コンポーネントは、onActivate()実行時に、入力データポートから
  Img::TimedCameraImageデータを１フレームだけ取得し、そこからカメラの
  内部パラメタを読み取ります。
  * したがって、本コンポーネントを Activate する前に、出力ポートのデー
    タ型が Img::TimedCameraImage であるコンポーネントを Activate し、入
    出力ポートを接続しておく必要があります。

* 本コンポーネントは、onExecute()実行時に、サービスコンシューマポートの
  RecognitionService::getModelID() インタフェースから、検出対象の
  ObjectIdを取得します。
  * BarCodeReaderコンポーネントを Activate する際には、サービスコンシュー
    マポートに RecognitionService::getModelID() インタフェースを提供す
    るサービスプロバイダポートを接続しておいてください。
  * ObjectIDが負値のときは、任意の対象(マーカ)を検出します。

