lib/src/jp/nyatla/nyartoolkit/processor/SingleNyIdMarkerProcesser.java

   1 /* \r
   2  * Capture Test NyARToolkitサンプルプログラム\r
   3  * --------------------------------------------------------------------------------\r
   4  * The NyARToolkit is Java edition ARToolKit class library.\r
   5  * Copyright (C)2008-2009 Ryo Iizuka\r
   6  *\r
   7  * This program is free software: you can redistribute it and/or modify\r
   8  * it under the terms of the GNU General Public License as published by\r
   9  * the Free Software Foundation, either version 3 of the License, or\r
  10  * (at your option) any later version.\r
  11  * \r
  12  * This program is distributed in the hope that it will be useful,\r
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of\r
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\r
  15  * GNU General Public License for more details.\r
  16  *\r
  17  * You should have received a copy of the GNU General Public License\r
  18  * along with this program.  If not, see <http://www.gnu.org/licenses/>.\r
  19  * \r
  20  * For further information please contact.\r
  21  *      http://nyatla.jp/nyatoolkit/\r
  22  *      <airmail(at)ebony.plala.or.jp> or <nyatla(at)nyatla.jp>\r
  23  * \r
  24  */\r
  25 package jp.nyatla.nyartoolkit.processor;\r
  26 \r
  27 import jp.nyatla.nyartoolkit.NyARException;\r
  28 import jp.nyatla.nyartoolkit.core.analyzer.raster.threshold.*;\r
  29 import jp.nyatla.nyartoolkit.core.param.*;\r
  30 import jp.nyatla.nyartoolkit.core.raster.*;\r
  31 import jp.nyatla.nyartoolkit.core.raster.rgb.*;\r
  32 import jp.nyatla.nyartoolkit.core.transmat.*;\r
  33 import jp.nyatla.nyartoolkit.core.rasterfilter.rgb2bin.NyARRasterFilter_ARToolkitThreshold;\r
  34 import jp.nyatla.nyartoolkit.core.types.*;\r
  35 import jp.nyatla.nyartoolkit.nyidmarker.*;\r
  36 import jp.nyatla.nyartoolkit.nyidmarker.data.*;\r
  37 import jp.nyatla.nyartoolkit.core.squaredetect.*;\r
  38 /**\r
  39  * このクラスは、1個のNyARマーカを検出する処理を、イベントドリブンにするシーケンスを定義します。\r
  40  * マーカの出現・移動・消滅を、自己コールバック関数で通知することができます。\r
  41  * クラスにはNyIdマーカのエンコーダを指定できます。エンコーダの種類を変えることで、異なる種類のNyIdマーカを同じクラスで\r
  42  * 取り扱うことができます。（同時に取り扱うことはできません。）\r
  43  * <p>自己コールバック関数の説明-\r
  44  * このクラスには、３個の自己コールバック関数があります。{@link SingleARMarkerProcesser}は、以下のタイミングでこれらを呼び出します。\r
  45  * ユーザは継承クラスでこれらの関数に実装を行い、イベント駆動のアプリケーションを作成できます。\r
  46  * <ul>\r
  47  * <li>　{@link #onEnterHandler} - 登録したマーカが初めて見つかった時に呼び出されます。ここに、発見したマーカに対応した初期処理を書きます。\r
  48  * <li>　{@link #onLeaveHandler} - 検出中のマーカが消失した時に呼び出されます。ここに、マーカの終期処理を書きます。\r
  49  * <li>　{@link #onUpdateHandler}- 検出中のマーカの位置姿勢が更新されたときに呼び出されます。ここに、マーカ位置の更新処理を書きます。\r
  50  * </ul>\r
  51  * </p>\r
  52  * <p>特性-\r
  53  * <ul>\r
  54  * <li>自動敷居値調整を行うため、環境光の変化に耐性があります。\r
  55  * <li>複数のNyIdマーカが画像にある場合は、一番初めに認識したIdのマーカを優先して認識します。\r
  56  * <li>複数の同一IDのNyIdマーカが画像にある場合は、区別できません。\r
  57  * </ul>\r
  58  * </p>\r
  59  */\r
  60 public abstract class SingleNyIdMarkerProcesser\r
  61 {\r
  62         /**\r
  63          * Rle矩形Detectorのブリッジ\r
  64          */\r
  65         private class RleDetector extends NyARSquareContourDetector_Rle\r
  66         {\r
  67                 //公開プロパティ\r
  68                 public final NyARSquare square=new NyARSquare();\r
  69                 public INyIdMarkerData marker_data;\r
  70                 public int threshold;\r
  71 \r
  72                 \r
  73                 //参照\r
  74                 private INyARRgbRaster _ref_raster;\r
  75                 //所有インスタンス\r
  76                 private INyIdMarkerData _current_data;\r
  77                 private final NyIdMarkerPickup _id_pickup = new NyIdMarkerPickup();\r
  78                 private NyARCoord2Linear _coordline;\r
  79                 private INyIdMarkerDataEncoder _encoder;\r
  80 \r
  81                 \r
  82                 private INyIdMarkerData _data_temp;\r
  83                 private INyIdMarkerData _prev_data;\r
  84                 \r
  85                 public RleDetector(NyARParam i_param,INyIdMarkerDataEncoder i_encoder) throws NyARException\r
  86                 {\r
  87                         super(i_param.getScreenSize());\r
  88                         this._coordline=new NyARCoord2Linear(i_param.getScreenSize(),i_param.getDistortionFactor());\r
  89                         this._data_temp=i_encoder.createDataInstance();\r
  90                         this._current_data=i_encoder.createDataInstance();\r
  91                         this._encoder=i_encoder;\r
  92                         return;\r
  93                 }\r
  94                 private NyARIntPoint2d[] __ref_vertex=new NyARIntPoint2d[4];\r
  95                 /**\r
  96                  * Initialize call back handler.\r
  97                  */\r
  98                 public void init(INyARRgbRaster i_raster,INyIdMarkerData i_prev_data)\r
  99                 {\r
 100                         this.marker_data=null;\r
 101                         this._prev_data=i_prev_data;\r
 102                         this._ref_raster=i_raster;\r
 103                 }\r
 104                 private final NyIdMarkerParam _marker_param=new NyIdMarkerParam();\r
 105                 private final NyIdMarkerPattern _marker_data=new NyIdMarkerPattern();\r
 106 \r
 107                 /**\r
 108                  * 矩形が見付かるたびに呼び出されます。\r
 109                  * 発見した矩形のパターンを検査して、方位を考慮した頂点データを確保します。\r
 110                  */\r
 111                 protected void onSquareDetect(NyARIntCoordinates i_coord,int[] i_vertex_index)  throws NyARException\r
 112                 {\r
 113                         //既に発見済なら終了\r
 114                         if(this.marker_data!=null){\r
 115                                 return;\r
 116                         }\r
 117                         //輪郭座標から頂点リストに変換\r
 118                         NyARIntPoint2d[] vertex=this.__ref_vertex;\r
 119                         vertex[0]=i_coord.items[i_vertex_index[0]];\r
 120                         vertex[1]=i_coord.items[i_vertex_index[1]];\r
 121                         vertex[2]=i_coord.items[i_vertex_index[2]];\r
 122                         vertex[3]=i_coord.items[i_vertex_index[3]];\r
 123                 \r
 124                         NyIdMarkerParam param=this._marker_param;\r
 125                         NyIdMarkerPattern patt_data  =this._marker_data;                        \r
 126                         // 評価基準になるパターンをイメージから切り出す\r
 127                         if (!this._id_pickup.pickFromRaster(this._ref_raster,vertex, patt_data, param)){\r
 128                                 return;\r
 129                         }\r
 130                         //エンコード\r
 131                         if(!this._encoder.encode(patt_data,this._data_temp)){\r
 132                                 return;\r
 133                         }\r
 134 \r
 135                         //継続認識要求されている？\r
 136                         if (this._prev_data==null){\r
 137                                 //継続認識要求なし\r
 138                                 this._current_data.copyFrom(this._data_temp);\r
 139                         }else{\r
 140                                 //継続認識要求あり\r
 141                                 if(!this._prev_data.isEqual((this._data_temp))){\r
 142                                         return;//認識請求のあったIDと違う。\r
 143                                 }\r
 144                         }\r
 145                         //新しく認識、または継続認識中に更新があったときだけ、Square情報を更新する。\r
 146                         //ココから先はこの条件でしか実行されない。\r
 147                         NyARSquare sq=this.square;\r
 148                         //directionを考慮して、squareを更新する。\r
 149                         for(int i=0;i<4;i++){\r
 150                                 int idx=(i+4 - param.direction) % 4;\r
 151                                 this._coordline.coord2Line(i_vertex_index[idx],i_vertex_index[(idx+1)%4],i_coord,sq.line[i]);\r
 152                         }\r
 153                         for (int i = 0; i < 4; i++) {\r
 154                                 //直線同士の交点計算\r
 155                                 if(!sq.line[i].crossPos(sq.line[(i + 3) % 4],sq.sqvertex[i])){\r
 156                                         throw new NyARException();//ここのエラー復帰するならダブルバッファにすればOK\r
 157                                 }\r
 158                         }\r
 159                         this.threshold=param.threshold;\r
 160                         this.marker_data=this._current_data;//みつかった。\r
 161                 }       \r
 162         }       \r
 163 \r
 164         \r
 165         /**　ユーザーが自由に使えるタグ変数です。*/\r
 166         public Object tag;\r
 167 \r
 168         /**\r
 169          * ロスト遅延の管理\r
 170          */\r
 171         private int _lost_delay_count = 0;\r
 172         private int _lost_delay = 5;\r
 173 \r
 174         private RleDetector _square_detect;\r
 175         protected INyARTransMat _transmat;\r
 176         private NyARRectOffset _offset; \r
 177         private boolean _is_active;\r
 178         private int _current_threshold=110;\r
 179         // [AR]検出結果の保存用\r
 180         private NyARBinRaster _bin_raster;\r
 181         private NyARRasterFilter_ARToolkitThreshold _tobin_filter;\r
 182         private INyIdMarkerData _data_current;\r
 183 \r
 184 \r
 185         /**\r
 186          * デフォルトコンストラクタ。\r
 187          * クラスを継承するときは、このコンストラクタを呼び出した後に、{@link #initInstance}関数でインスタンスの初期化処理を実装します。\r
 188          */\r
 189         protected SingleNyIdMarkerProcesser()\r
 190         {\r
 191                 return;\r
 192         }\r
 193         private boolean _initialized=false;\r
 194         /**\r
 195          * この関数は、インスタンスを初期化します。\r
 196          * 継承先のクラスから呼び出してください。\r
 197          * @param i_param\r
 198          * カメラパラメータオブジェクト。このサイズは、{@link #detectMarker}に入力する画像と同じサイズである必要があります。\r
 199          * @param i_encoder\r
 200          * IDマーカの値エンコーダを指定します。\r
 201          * @param i_marker_width\r
 202          * マーカの物理縦横サイズをmm単位で指定します。\r
 203          * @param i_raster_format\r
 204          * {@link #detectMarker}関数に入力する画像の画素形式。\r
 205          * この値には、{@link INyARRgbRaster#getBufferType}関数の戻り値を利用します。\r
 206          * @throws NyARException\r
 207          */\r
 208         protected void initInstance(NyARParam i_param,INyIdMarkerDataEncoder i_encoder,double i_marker_width,int i_raster_format) throws NyARException\r
 209         {\r
 210                 //初期化済？\r
 211                 assert(this._initialized==false);\r
 212                 \r
 213                 NyARIntSize scr_size = i_param.getScreenSize();\r
 214                 // 解析オブジェクトを作る\r
 215                 this._square_detect = new RleDetector(i_param,i_encoder);\r
 216                 this._transmat = new NyARTransMat(i_param);\r
 217 \r
 218                 // ２値画像バッファを作る\r
 219                 this._bin_raster = new NyARBinRaster(scr_size.w, scr_size.h);\r
 220                 //ワーク用のデータオブジェクトを２個作る\r
 221                 this._data_current=i_encoder.createDataInstance();\r
 222                 this._tobin_filter =new NyARRasterFilter_ARToolkitThreshold(110,i_raster_format);\r
 223                 this._threshold_detect=new NyARRasterThresholdAnalyzer_SlidePTile(15,i_raster_format,4);\r
 224                 this._initialized=true;\r
 225                 this._is_active=false;\r
 226                 this._offset=new NyARRectOffset();\r
 227                 this._offset.setSquare(i_marker_width);\r
 228                 return;\r
 229                 \r
 230         }\r
 231         /**\r
 232          * この関数は、マーカの物理サイズを変更します。\r
 233          * @param i_width\r
 234          * マーカの物理縦横サイズをmm単位で指定します。\r
 235          */\r
 236         public void setMarkerWidth(int i_width)\r
 237         {\r
 238                 this._offset.setSquare(i_width);\r
 239                 return;\r
 240         }\r
 241         /**\r
 242          * この関数は、インスタンスの状態をリセットします。\r
 243          * 状態をリセットすると、もしマーカを認識している場合には、{@link #onLeaveHandler}イベントハンドラがコールされ、未認識状態になります。\r
 244          * @param i_is_force\r
 245          * 強制フラグ。trueにすると、イベント通知なしにマーカ認識状態をリセットします。\r
 246          */\r
 247         public void reset(boolean i_is_force)\r
 248         {\r
 249                 if (i_is_force == false && this._is_active){\r
 250                         // 強制書き換えでなければイベントコール\r
 251                         this.onLeaveHandler();\r
 252                 }\r
 253                 //マーカ無効\r
 254                 this._is_active=false;\r
 255                 return;\r
 256         }\r
 257         /**\r
 258          * この関数は、画像を処理して、適切なマーカ検出イベントハンドラを呼び出します。\r
 259          * イベントハンドラの呼び出しは、この関数を呼び出したスレッドが、この関数が終了するまでに行います。\r
 260          * @param i_raster\r
 261          * 検出処理をする画像を指定します。\r
 262          * @throws NyARException\r
 263          */\r
 264         public void detectMarker(INyARRgbRaster i_raster) throws NyARException\r
 265         {\r
 266                 // サイズチェック\r
 267                 if (!this._bin_raster.getSize().isEqualSize(i_raster.getSize().w, i_raster.getSize().h)) {\r
 268                         throw new NyARException();\r
 269                 }\r
 270                 // ラスタを２値イメージに変換する.\r
 271                 this._tobin_filter.setThreshold(this._current_threshold);\r
 272                 this._tobin_filter.doFilter(i_raster, this._bin_raster);\r
 273 \r
 274                 // スクエアコードを探す(第二引数に指定したマーカ、もしくは新しいマーカを探す。)\r
 275                 this._square_detect.init(i_raster,this._is_active?this._data_current:null);\r
 276                 this._square_detect.detectMarker(this._bin_raster);\r
 277 \r
 278                 // 認識状態を更新(マーカを発見したなら、current_dataを渡すかんじ)\r
 279                 final boolean is_id_found=updateStatus(this._square_detect.square,this._square_detect.marker_data);\r
 280 \r
 281                 //閾値フィードバック(detectExistMarkerにもあるよ)\r
 282                 if(is_id_found){\r
 283                         //マーカがあれば、マーカの周辺閾値を反映\r
 284                         this._current_threshold=(this._current_threshold+this._square_detect.threshold)/2;\r
 285                 }else{\r
 286                         //マーカがなければ、探索+DualPTailで基準輝度検索\r
 287                         int th=this._threshold_detect.analyzeRaster(i_raster);\r
 288                         this._current_threshold=(this._current_threshold+th)/2;\r
 289                 }               \r
 290                 return;\r
 291         }\r
 292 \r
 293         \r
 294         private NyARRasterThresholdAnalyzer_SlidePTile _threshold_detect;\r
 295         private NyARTransMatResult __NyARSquare_result = new NyARTransMatResult();\r
 296 \r
 297         /**オブジェクトのステータスを更新し、必要に応じて自己コールバック関数を駆動します。\r
 298          */\r
 299         private boolean updateStatus(NyARSquare i_square, INyIdMarkerData i_marker_data)  throws NyARException\r
 300         {\r
 301                 boolean is_id_found=false;\r
 302                 NyARTransMatResult result = this.__NyARSquare_result;\r
 303                 if (!this._is_active) {// 未認識中\r
 304                         if (i_marker_data==null) {// 未認識から未認識の遷移\r
 305                                 // なにもしないよーん。\r
 306                                 this._is_active=false;\r
 307                         } else {// 未認識から認識の遷移\r
 308                                 this._data_current.copyFrom(i_marker_data);\r
 309                                 // イベント生成\r
 310                                 // OnEnter\r
 311                                 this.onEnterHandler(this._data_current);\r
 312                                 // 変換行列を作成\r
 313                                 this._transmat.transMat(i_square, this._offset, result);\r
 314                                 // OnUpdate\r
 315                                 this.onUpdateHandler(i_square, result);\r
 316                                 this._lost_delay_count = 0;\r
 317                                 this._is_active=true;\r
 318                                 is_id_found=true;\r
 319                         }\r
 320                 } else {// 認識中\r
 321                         if (i_marker_data==null) {\r
 322                                 // 認識から未認識の遷移\r
 323                                 this._lost_delay_count++;\r
 324                                 if (this._lost_delay < this._lost_delay_count) {\r
 325                                         // OnLeave\r
 326                                         this.onLeaveHandler();\r
 327                                         this._is_active=false;\r
 328                                 }\r
 329                         } else if(this._data_current.isEqual(i_marker_data)) {\r
 330                                 //同じidの再認識\r
 331                                 this._transmat.transMatContinue(i_square, this._offset, result,result);\r
 332                                 // OnUpdate\r
 333                                 this.onUpdateHandler(i_square, result);\r
 334                                 this._lost_delay_count = 0;\r
 335                                 is_id_found=true;\r
 336                         } else {// 異なるコードの認識→今はサポートしない。\r
 337                                 throw new  NyARException();\r
 338                         }\r
 339                 }\r
 340                 return is_id_found;\r
 341         }       \r
 342         /**\r
 343          * 自己コールバック関数です。\r
 344          * 継承したクラスで、マーカ発見時の処理を実装してください。\r
 345          * @param i_code\r
 346          * 検出したIDマーカの内容をエンコードしたデータです。\r
 347          * 使用したエンコーダに合せて、キャストしてください。\r
 348          * (例えば、{@link NyIdMarkerDataEncoder_RawBit}をエンコーダに用いた時は、{@link NyIdMarkerDataEncoder_RawBit}にキャストできます。)\r
 349          */\r
 350         protected abstract void onEnterHandler(INyIdMarkerData i_code);\r
 351         /**\r
 352          * 自己コールバック関数です。\r
 353          * 継承したクラスで、マーカ消失時の処理を実装してください。\r
 354          */\r
 355         protected abstract void onLeaveHandler();\r
 356         /**\r
 357          * 自己コールバック関数です。\r
 358          * 継承したクラスで、マーカ更新時の処理を実装してください。\r
 359          * 引数の値の有効期間は、関数が終了するまでです。\r
 360          * @param i_square\r
 361          * 現在のマーカ検出位置です。\r
 362          * @param result\r
 363          * 現在の姿勢変換行列です。\r
 364          */\r
 365         protected abstract void onUpdateHandler(NyARSquare i_square, NyARTransMatResult result);\r
 366 }\r