From: nyatla Date: Wed, 26 Jan 2011 03:46:48 +0000 (+0000) Subject: git-svn-id: http://svn.sourceforge.jp/svnroot/nyartoolkit/NyARToolkit/trunk@806 7cac0... X-Git-Url: http://git.sourceforge.jp/view?p=nyartoolkit-and%2Fnyartoolkit-and.git;a=commitdiff_plain;h=971bb2642ca5ebc906315b84aadc992c61653b4c;hp=ab6d8ed8b7a764d8509bdf954b7c2aa66344d76f git-svn-id: svn.sourceforge.jp/svnroot/nyartoolkit/NyARToolkit/trunk@806 7cac0a50-4618-4814-88d0-24b83990f816 --- diff --git a/lib/src.rpf/jp/nyatla/nyartoolkit/rpf/tracker/nyartk/INyARVectorReader.java b/lib/src.rpf/jp/nyatla/nyartoolkit/rpf/tracker/nyartk/INyARVectorReader.java index 0a76617..39cb0c9 100644 --- a/lib/src.rpf/jp/nyatla/nyartoolkit/rpf/tracker/nyartk/INyARVectorReader.java +++ b/lib/src.rpf/jp/nyatla/nyartoolkit/rpf/tracker/nyartk/INyARVectorReader.java @@ -29,71 +29,139 @@ import jp.nyatla.nyartoolkit.core.types.*; import jp.nyatla.nyartoolkit.rpf.utils.VecLinearCoordinates; /** - * グレイスケールラスタに対する、特殊な画素アクセス手段を提供します。 + * このインタフェイスは、グレイスケールラスタから画像のベクトルを読みだす関数を定義します。 + * 画像のベクトルは、n*mの領域にある画素を集計して計算する二次元のベクトルです。 + *

+ * このクラスは、輪郭のヒント画像(1/2^nサイズのエッジ画像)と、グレースケールの元画像を使って、 + * 画像の輪郭ベクトルを求めます。ヒント画像は、元画像を1/2^n倍したエッジ画像、又はグレースケール画像です。 + * ヒント画像のポイントに対応する元画像の領域を調査することで、その周辺のエッジ座標と、ベクトルを求めます。 + *

* */ public interface INyARVectorReader { /** - * RECT範囲内の画素ベクトルの合計値と、ベクトルのエッジ中心を取得します。 320*240の場合、 - * RECTの範囲は(x>=0 && x<319 x+w>=0 && x+w<319),(y>=0 && y<239 x+w>=0 && x+w<319)となります。 + * この関数は、元画像の矩形領域を集計して、その領域内のエッジ中心と、エッジの方位ベクトルを返します。 + * 画素の集計には、3x3のカーネルを使います。 + * 矩形領域は、例えば取得元の画像が320*240の場合、(x>=0 && x<=320 x+w>=0 && x+w<=320),(y>=0 && y<=240 y+h>=0 && y+h<=240)です。 + * 実装クラスでは、3x3カーネルを使って、入力された矩形内の画素から、エッジ中心とベクトルを得る処理を実装します。 * @param ix * ピクセル取得を行う位置を設定します。 * @param iy * ピクセル取得を行う位置を設定します。 * @param iw * ピクセル取得を行う範囲を設定します。 + * 3以上でなければなりません。 * @param ih * ピクセル取得を行う範囲を設定します。 + * 3以上でなければなりません。 * @param o_posvec * エッジ中心とベクトルを返します。 * @return * ベクトルの強度を返します。強度値は、差分値の二乗の合計です。 */ public int getAreaVector33(int ix, int iy, int iw, int ih,NyARVecLinear2d o_posvec); + /** + * この関数は、{@link #getAreaVector33}のカーネルサイズ違いの関数です。 + * 画素の集計には、2x2のカーネルを使います。 + * この関数は実験的な関数です。実装しなくともかまいません。(その場合、0を返却ます。) + * 実装クラスでは、2x2カーネルを使って、入力された矩形内の画素から、エッジ中心とベクトルを得る処理を実装します。 + * @param ix + * ピクセル取得を行う位置を設定します。 + * @param iy + * ピクセル取得を行う位置を設定します。 + * @param iw + * ピクセル取得を行う範囲を設定します。 + * 3以上でなければなりません。 + * @param ih + * ピクセル取得を行う範囲を設定します。 + * 3以上でなければなりません。 + * @param o_posvec + * エッジ中心とベクトルを返します。 + * @return + * ベクトルの強度を返します。強度値は、差分値の二乗の合計です。 + */ public int getAreaVector22(int ix, int iy, int iw, int ih,NyARVecLinear2d o_posvec); - + /** + * この関数は、ヒント画像の基点から輪郭点をトレースして、元画像の輪郭ベクトルを配列に返します。 + * 実装クラスでは、輪郭線の輪郭点毎のエッジ中心とベクトルを得る処理を実装します。 + * @param i_th + * 輪郭を判定するための敷居値。0から255の範囲です。 + * @param i_entry + * 輪郭点のエントリポイントです。輪郭を構成する点の一部を指定します。 + * @param o_coord + * 輪郭点を出力する配列です。 + * @return + * 輪郭点の抽出に成功すると、trueを返します。 + * @throws NyARException + */ public boolean traceConture(int i_th, NyARIntPoint2d i_entry, VecLinearCoordinates o_coord) throws NyARException; /** - * 点1と点2の間に線分を定義して、その線分上のベクトルを得ます。点は、画像の内側でなければなりません。 320*240の場合、(x>=0 && - * x<320 x+w>0 && x+w<320),(y>0 && y<240 y+h>=0 && y+h<=319)となります。 - * + * この関数は、元画像の点1と点2の間に線分を定義して、その線分上のベクトルを配列に得ます。 + * 点は、画像の内側でなければなりません。 + * この関数はクリッピング処理を行いません。クリッピングが必要な時には、{@link #traceLineWithClip}を使います。 * @param i_pos1 - * 点1の座標です。 + * 点1の座標です。 * @param i_pos2 - * 点2の座標です。 - * @param i_area - * ベクトルを検出するカーネルサイズです。1の場合(n*2-1)^2のカーネルになります。 点2の座標です。 + * 点2の座標です。 + * @param i_edge + * ベクトルを検出するカーネルサイズです。(n*2+1)*(n*2+1)のカーネルになります。 * @param o_coord - * 結果を受け取るオブジェクトです。 + * 結果を受け取るオブジェクトです。 * @return + * 抽出に成功すると、trueを返します。 * @throws NyARException */ public boolean traceLine(NyARIntPoint2d i_pos1, NyARIntPoint2d i_pos2,int i_edge, VecLinearCoordinates o_coord); - + /** + * この関数は、元画像の点1と点2の間に線分を定義して、その線分上のベクトルを配列に得ます。 + * 点は、画像の内側でなければなりません。 + * この関数はクリッピング処理を行いません。クリッピングが必要な時には、{@link #traceLineWithClip}を使います。 + * @param i_pos1 + * 点1の座標です。 + * @param i_pos2 + * 点2の座標です。 + * @param i_edge + * ベクトルを検出するカーネルサイズです。(n*2+1)*(n*2+1)のカーネルになります。 + * @param o_coord + * 結果を受け取るオブジェクトです。 + * @return + * 抽出に成功すると、trueを返します。 + * @throws NyARException + */ public boolean traceLine(NyARDoublePoint2d i_pos1,NyARDoublePoint2d i_pos2, int i_edge, VecLinearCoordinates o_coord); /** - * 輪郭線を取得します。 - * 取得アルゴリズムは、以下の通りです。 - * 1.輪郭座標(n)の画素周辺の画素ベクトルを取得。 - * 2.輪郭座標(n+1)周辺の画素ベクトルと比較。 - * 3.差分が一定以下なら、座標と強度を保存 - * 4.3点以上の集合になったら、最小二乗法で直線を計算。 - * 5.直線の加重値を個々の画素ベクトルの和として返却。 + * この関数は、カーネルサイズを指定して、ヒント画像の輪郭座標から、元画像の輪郭線のベクトルを得ます。 + * @param i_coord + * ヒント画像の輪郭点 + * @param i_pos_mag + * ヒント画像と元画像の倍率(1/2なら2) + * @param i_cell_size + * ベクトルの領域サイズ + * @param o_coord + * 画素ベクトルを返却するオブジェクト。 + * @return + * 処理に成功するとtrue */ public boolean traceConture(NyARIntCoordinates i_coord, int i_pos_mag,int i_cell_size, VecLinearCoordinates o_coord); /** - * クリッピング付きのライントレーサです。 - * + * この関数は、クリッピング付きのライントレーサです。 + * 元画像の点1と点2の間に線分を定義して、その線分上のベクトルを配列に得ます。 + * 座標は、適切に画像内にクリッピングします。 * @param i_pos1 + * 点1の座標です。 * @param i_pos2 + * 点2の座標です。 * @param i_edge + * ベクトルを検出するカーネルサイズです。(n*2+1)*(n*2+1)のカーネルになります。 * @param o_coord + * 結果を受け取るオブジェクトです。 * @return + * 処理に成功するとtrue * @throws NyARException */ public boolean traceLineWithClip(NyARDoublePoint2d i_pos1, diff --git a/lib/src.rpf/jp/nyatla/nyartoolkit/rpf/tracker/nyartk/NegativeSqRoberts.java b/lib/src.rpf/jp/nyatla/nyartoolkit/rpf/tracker/nyartk/NegativeSqRoberts.java index 3ba303e..7c6445f 100644 --- a/lib/src.rpf/jp/nyatla/nyartoolkit/rpf/tracker/nyartk/NegativeSqRoberts.java +++ b/lib/src.rpf/jp/nyatla/nyartoolkit/rpf/tracker/nyartk/NegativeSqRoberts.java @@ -31,21 +31,40 @@ import jp.nyatla.nyartoolkit.core.types.NyARBufferType; import jp.nyatla.nyartoolkit.core.types.NyARIntSize; /** - * NyARReality用のエッジ検出フィルタ。 - * Roberts勾配の2乗値16倍に最大値制限をかけ、反転した値です。 - * 右端と左端の1ピクセルは、常に0が入ります。 + * この関数は、{@link NyARTracker}用のエッジ検出フィルターです。 + * {@link NyARTrackerSource_Reference}から、ヒント画像を作るために使います。通常、ユーザが使うことはありません。 + *

フィルタの構造 - + * このフィルタは、Roberts勾配の値の2乗値を16倍して、範囲を0から255に制限して反転した値を出力します。 + * 右端と左端の1ピクセルは、常に0が入ります。
+ * Roberts勾配のカーネルとは、以下の形式です。 + * 

  * X=|-1, 0|  Y=|0,-1|
  *   | 0, 1|    |1, 0|
- * V=sqrt(X^2+Y+2)/2
+ * V=(sqrt(X^2+Y+2)>>4);V=V>255?255:V;
+ *
*/ public class NegativeSqRoberts implements INyARRasterFilter { private IdoFilterImpl _do_filter_impl; + /** + * コンストラクタです。 + * 入力ラスタの画素形式を指定して、インスタンスを作成します。 + * @param i_raster_type + * 入力するラスタの画素形式です。{@link NyARBufferType#INT1D_GRAY_8}のみ対応します。 + * @throws NyARException + */ public NegativeSqRoberts(int i_raster_type) throws NyARException { this.initInstance(i_raster_type); } - public void initInstance(int i_raster_type)throws NyARException + /** + * この関数は、インスタンスを初期化します。 + * コンストラクタから呼び出します。 + * @param i_raster_type + * 入力するラスタの画素形式です。 + * @throws NyARException + */ + protected void initInstance(int i_raster_type)throws NyARException { switch (i_raster_type) { case NyARBufferType.INT1D_GRAY_8: @@ -55,17 +74,35 @@ public class NegativeSqRoberts implements INyARRasterFilter throw new NyARException(); } } + /** + * この関数は、入力画像にフィルタ処理をして、出力画像に書き込みます。 + */ public void doFilter(INyARRaster i_input, INyARRaster i_output) throws NyARException { this._do_filter_impl.doFilter(i_input,i_output,i_input.getSize()); } - - interface IdoFilterImpl + /** + * このインタフェイスは、フィルタ処理関数を定義します。 + * {@link NegativeSqRoberts#doFilter}から使います。 + * + */ + protected interface IdoFilterImpl { + /** + * この関数は、i_sizeのサイズを持つ入力画像をフィルタ処理して、同じくi_sizeのサイズを持つ出力画像へ書込みます。 + * 実装クラスでは、{@link NegativeSqRoberts}のアルゴリズムでフィルタ処理を行う処理を書きます。 + * @param i_input + * 入力画像 + * @param i_output + * 出力画像 + * @param i_size + * 入力、出力画像のサイズ + * @throws NyARException + */ public void doFilter(INyARRaster i_input, INyARRaster i_output,NyARIntSize i_size) throws NyARException; } private final static int SH=4; - class IdoFilterImpl_GRAY_8 implements IdoFilterImpl + private class IdoFilterImpl_GRAY_8 implements IdoFilterImpl { public void doFilter(INyARRaster i_input, INyARRaster i_output,NyARIntSize i_size) throws NyARException { diff --git a/lib/src.rpf/jp/nyatla/nyartoolkit/rpf/tracker/nyartk/NyARRectTargetList.java b/lib/src.rpf/jp/nyatla/nyartoolkit/rpf/tracker/nyartk/NyARRectTargetList.java index 963660f..2adf0d5 100644 --- a/lib/src.rpf/jp/nyatla/nyartoolkit/rpf/tracker/nyartk/NyARRectTargetList.java +++ b/lib/src.rpf/jp/nyatla/nyartoolkit/rpf/tracker/nyartk/NyARRectTargetList.java @@ -4,14 +4,27 @@ import jp.nyatla.nyartoolkit.NyARException; import jp.nyatla.nyartoolkit.rpf.sampler.lrlabel.*; import jp.nyatla.nyartoolkit.rpf.tracker.nyartk.status.*; +/** + * このクラスは、RECTトラックターゲットのリストです。 + * {@link NyARTargetList}クラスの矩形検索関数を置き換えます。 + * + */ public class NyARRectTargetList extends NyARTargetList { + /** + * コンストラクタです。 + * リストの最大サイズを指定して、インスタンスを生成します。 + * @param iMaxTarget + * リストの最大サイズ + * @throws NyARException + */ public NyARRectTargetList(int iMaxTarget) throws NyARException { super(iMaxTarget); } /** - * super classの機能に、予測位置からの探索を追加します。 + * この関数は、サンプルアイテムに最も近いアイテムのリストインデクスを検索します。 + * ベースクラスの関数との違いは、予想矩形位置も探索範囲に含む事です。 */ public int getMatchTargetIndex(LowResolutionLabelingSamplerOut.Item i_item) { diff --git a/lib/src.rpf/jp/nyatla/nyartoolkit/rpf/tracker/nyartk/NyARTarget.java b/lib/src.rpf/jp/nyatla/nyartoolkit/rpf/tracker/nyartk/NyARTarget.java index 1ef5cd2..6e42d8a 100644 --- a/lib/src.rpf/jp/nyatla/nyartoolkit/rpf/tracker/nyartk/NyARTarget.java +++ b/lib/src.rpf/jp/nyatla/nyartoolkit/rpf/tracker/nyartk/NyARTarget.java @@ -4,26 +4,30 @@ import jp.nyatla.nyartoolkit.core.types.NyARDoublePoint2d; import jp.nyatla.nyartoolkit.core.types.NyARIntRect; import jp.nyatla.nyartoolkit.core.utils.NyARManagedObject; import jp.nyatla.nyartoolkit.rpf.sampler.lrlabel.LowResolutionLabelingSamplerOut; -import jp.nyatla.nyartoolkit.rpf.tracker.nyartk.status.NyARTargetStatus; +import jp.nyatla.nyartoolkit.rpf.tracker.nyartk.status.*; /** - * トラッキングターゲットのクラスです。 + * このクラスは、トラッキングデータ1個のデータを格納します。 + * 単体での使用は想定していません。 + * トラッキングデータは２層構造です。１層目は２次元画像上のラベルデータを元にした情報群をメンバ変数に格納します。 + * ２層目は、{@link NyARTargetStatus}型のメンバ変数{@link #_ref_status}に格納します。 + * {@link #_ref_status}の内容は、認識の進行具合（ステータス）に合せて、{@link NyARTracker}が再割り当てします。 + * 現在割り当てられているステータスオブジェクトの型を知るには、{@link #_st_type}をチェックします。 + *

* {@link #tag}以外の要素については、ユーザからの直接アクセスを推奨しません。 - * + *

*/ public class NyARTarget extends NyARManagedObject { - /** - * シリアルID生成時に使うロックオブジェクト。 - */ + /**　シリアルID生成時に使うロックオブジェクト。*/ private static Object _serial_lock=new Object(); - /** - * システム動作中に一意なシリアル番号 - */ + /** シリアルIDカウンタ*/ private static long _serial_counter=0; /** - * 新しいシリアルIDを返します。この値は、NyARTargetを新規に作成したときに、Poolクラスがserialプロパティに設定します。 + * この関数は、クラスのドメインで一意なシリアルID（トラックターゲットID）を返します。 + * この関数は、{@link NyARTargetPool}が呼び出します。通常ユーザは使いません。 * @return + * トラックターゲットID */ public static long createSerialId() { @@ -33,50 +37,51 @@ public class NyARTarget extends NyARManagedObject } //////////////////////// //targetの基本情報 - /** - * ステータスのタイプを表します。この値はref_statusの型と同期しています。 - */ + /** {@link #_ref_status}に格納しているオブジェクトのタイプを表します。ユーザに対しては、[read only]です。*/ public int _st_type; - /** - * Targetを識別するID値 - */ + /**　トラックターゲットIDです。ユーザに対しては、[read only]です。*/ public long _serial; - /** - * 認識サイクルの遅延値。更新ミスの回数と同じ。 - */ + /**　認識の遅延サイクル数です。認識ミスが発生するとインクリメントされ、成功すると0にリセットされます。ユーザに対しては、[read only]です。*/ public int _delay_tick; - - /** - * 現在のステータスの最大寿命。 - */ + /** 現在のステータスの最大寿命値です。この値は、{@link NyARTracker}がトラックターゲットの寿命管理に使います。ユーザに対しては、[read only]です。*/ public int _status_life; //////////////////////// //targetの情報 - public NyARTargetStatus _ref_status; - /** - * ユーザオブジェクトを配置するポインタータグです。リリース時にNULL初期化されます。 + * ステータスオブジェクトです。ステータスオブジェクトは、トラックターゲットのステータス{@link #_ref_status}により、その内容が変わります。 + * */ + public NyARTargetStatus _ref_status; + + /** ユーザオブジェクトを配置するポインタータグです。*/ public Object tag; // //Samplerからの基本情報 - /** - * サンプリングエリアを格納する変数です。 - */ + /** トラックターゲットのクリップ領域を格納する変数です。クリップ領域は、画像上の矩形で表現します。*/ public NyARIntRect _sample_area=new NyARIntRect(); - //アクセス用関数 + /** - * Constructor + * コンストラクタです。 + * 親poolの操作インタフェイスを指定してインスタンスを生成します。 + * @param iRefPoolOperator + * 親poolの操作インタフェイス */ public NyARTarget(INyARManagedObjectPoolOperater iRefPoolOperator) { super(iRefPoolOperator); this.tag=null; } + /** - * この関数は、ref_statusの内容を安全に削除します。 + * この関数は、オブジェクトの参照カウンタを1減算します。 + * 参照カウンタが0になった時のみ、所有する参照オブジェクトの参照カウンタも操作します。 */ public int releaseObject() { @@ -89,8 +94,9 @@ public class NyARTarget extends NyARManagedObject } /** - * 頂点情報を元に、sampleAreaにRECTを設定します。 + * この関数は、４頂点から包括矩形を計算して{@link #_sample_area}に設定します。 * @param i_vertex + * 4頂点を格納した配列。 */ public void setSampleArea(NyARDoublePoint2d[] i_vertex) { @@ -98,7 +104,7 @@ public class NyARTarget extends NyARManagedObject } /** - * LowResolutionLabelingSamplerOut.Itemの値をを元に、sample_areaにRECTを設定します。 + * この関数は、LowResolutionLabelingSamplerOut.Itemから{@link #_sample_area}に設定します。 * @param i_item * 設定する値です。 */ diff --git a/lib/src/jp/nyatla/nyartoolkit/detector/NyARCustomSingleDetectMarker.java b/lib/src/jp/nyatla/nyartoolkit/detector/NyARCustomSingleDetectMarker.java index 722b334..f4d5dbb 100644 --- a/lib/src/jp/nyatla/nyartoolkit/detector/NyARCustomSingleDetectMarker.java +++ b/lib/src/jp/nyatla/nyartoolkit/detector/NyARCustomSingleDetectMarker.java @@ -269,6 +269,7 @@ public abstract class NyARCustomSingleDetectMarker * デバック関数。 * privateメンバにアクセスするためのトンネルです。 * @return + * デバック用オブジェクトを格納した配列。 */ public Object[] _getProbe() { diff --git a/lib/src/jp/nyatla/nyartoolkit/detector/NyARDetectMarker.java b/lib/src/jp/nyatla/nyartoolkit/detector/NyARDetectMarker.java index 407a869..14cf12e 100644 --- a/lib/src/jp/nyatla/nyartoolkit/detector/NyARDetectMarker.java +++ b/lib/src/jp/nyatla/nyartoolkit/detector/NyARDetectMarker.java @@ -247,7 +247,7 @@ public class NyARDetectMarker * 関数は、登録されているマーカパターンそれぞれに対し、検出したマーカから最も一致した物を探し、その一致率と位置を計算します。 * @param i_raster * マーカーを検出するイメージを指定します。 - * @param i_thresh + * @param i_threshold * 検出閾値を指定します。0～255の範囲で指定してください。 通常は100～130くらいを指定します。 * @return * 検出したマーカーの数を返します。 マーカーが見つからない場合は0を返します。 diff --git a/lib/src/jp/nyatla/nyartoolkit/detector/NyARSingleDetectMarker.java b/lib/src/jp/nyatla/nyartoolkit/detector/NyARSingleDetectMarker.java index 49b076d..d9fca83 100644 --- a/lib/src/jp/nyatla/nyartoolkit/detector/NyARSingleDetectMarker.java +++ b/lib/src/jp/nyatla/nyartoolkit/detector/NyARSingleDetectMarker.java @@ -102,20 +102,20 @@ public class NyARSingleDetectMarker extends NyARCustomSingleDetectMarker * コンストラクタです。 * 指定した1種のマーカを1個検出するインスタンスを作ります。 * @param i_param - * カメラパラメータを指定します。このサイズは、{@link #detectMarker}に入力する画像と同じである必要があります。 + * カメラパラメータを指定します。このサイズは、{@link #detectMarkerLite}に入力する画像と同じである必要があります。 * @param i_code * 検出するマーカパターンを指定します。 * @param i_marker_width * 正方形マーカの物理サイズをmm単位で指定します。 * @param i_input_raster_type - * {@link #detectMarker}に入力するラスタの画素形式を指定します。 + * {@link #detectMarkerLite}に入力するラスタの画素形式を指定します。 * この値は、{@link INyARRgbRaster#getBufferType}関数の戻り値を利用します。 * @param i_profile_id * 計算アルゴリズムの選択値です。以下の定数のいずれかを指定します。 * * @throws NyARException */ @@ -128,8 +128,8 @@ public class NyARSingleDetectMarker extends NyARCustomSingleDetectMarker /** * コンストラクタです。 * 指定した1種のマーカを1個検出するインスタンスを作ります。 - * i_profile_idに{@link NyARSingleDetectMarker#PF_NYARTOOLKIT}を選択した{@link NyARSingleDetectMarker#NyARSingleDetectMarker(NyARParam, NyARCode, double, int, int)と同じです。 - * @see NyARSingleDetectMarker#NyARSingleDetectMarker(NyARParam, NyARCode, double, int, int) + * i_profile_idに{@link #PF_NYARTOOLKIT}を選択した{@link #NyARSingleDetectMarker(NyARParam, NyARCode, double, int, int)}と同じです。 + * @see #NyARSingleDetectMarker(NyARParam, NyARCode, double, int, int) * @param i_param * Check see also * @param i_code @@ -148,8 +148,8 @@ public class NyARSingleDetectMarker extends NyARCustomSingleDetectMarker } /** * この関数は、インスタンスを初期化します。 - * 引数は、{@link NyARSingleDetectMarker#NyARSingleDetectMarker}の対応する引数と同じです。 - * @see NyARSingleDetectMarker#NyARSingleDetectMarker(NyARParam, NyARCode, double, int, int) + * 引数は、{@link #NyARSingleDetectMarker}の対応する引数と同じです。 + * @see #NyARSingleDetectMarker(NyARParam, NyARCode, double, int, int) * @param i_ref_param * Check see also * @param i_ref_code