From 7d7f725b9a7395a890c4576075cfad47906bfdca Mon Sep 17 00:00:00 2001 From: nyatla Date: Mon, 24 Jan 2011 09:27:41 +0000 Subject: [PATCH] [NyARToolKit for java]update document git-svn-id: http://svn.sourceforge.jp/svnroot/nyartoolkit/NyARToolkit/trunk@804 7cac0a50-4618-4814-88d0-24b83990f816 --- .../nyatla/nyartoolkit/rpf/mklib/CardDetect.java | 12 - .../nyartoolkit/core/raster/rgb/NyARRgbRaster.java | 2 + .../rgb2gs/NyARRasterFilter_Rgb2Gs_RgbAve192.java | 4 +- .../rgb2gs/NyARRasterFilter_Rgb2Gs_RgbCube.java | 6 +- .../rgb2gs/NyARRasterFilter_Rgb2Gs_YCbCr.java | 4 +- .../rasterreader/NyARPerspectiveRasterReader.java | 2 +- .../core/types/stack/NyARIntPointStack.java | 13 +- .../core/types/stack/NyARIntRectStack.java | 14 +- .../core/types/stack/NyARObjectStack.java | 79 +++-- .../core/types/stack/NyARPointerStack.java | 66 ++-- .../nyatla/nyartoolkit/core/utils/NyARDistMap.java | 68 +++- .../nyartoolkit/core/utils/NyAREquationSolver.java | 74 +++-- .../nyartoolkit/core/utils/NyARManagedObject.java | 48 ++- .../core/utils/NyARManagedObjectPool.java | 77 ++++- .../jp/nyatla/nyartoolkit/core/utils/NyARMath.java | 63 +++- .../nyartoolkit/core/utils/NyARObjectPool.java | 33 +- .../core/utils/NyARPerspectiveParamGenerator.java | 37 ++- .../utils/NyARPerspectiveParamGenerator_O1.java | 6 +- .../NyARPerspectiveParamGenerator_Reference.java | 10 +- .../NyARSystemOfLinearEquationsProcessor.java | 37 ++- .../nyartoolkit/nyidmarker/NyIdMarkerParam.java | 10 +- .../nyartoolkit/nyidmarker/NyIdMarkerPattern.java | 9 +- .../nyartoolkit/nyidmarker/NyIdMarkerPickup.java | 350 ++++++++++++++------- .../nyidmarker/data/INyIdMarkerData.java | 11 +- .../nyidmarker/data/INyIdMarkerDataEncoder.java | 21 +- .../data/NyIdMarkerDataEncoder_RawBit.java | 12 +- .../nyidmarker/data/NyIdMarkerData_RawBit.java | 14 +- .../nyartoolkit/utils/TransformedBitmapPickup.java | 32 +- 28 files changed, 787 insertions(+), 327 deletions(-) diff --git a/lib/src.rpf/jp/nyatla/nyartoolkit/rpf/mklib/CardDetect.java b/lib/src.rpf/jp/nyatla/nyartoolkit/rpf/mklib/CardDetect.java index 26ca833..85d3512 100644 --- a/lib/src.rpf/jp/nyatla/nyartoolkit/rpf/mklib/CardDetect.java +++ b/lib/src.rpf/jp/nyatla/nyartoolkit/rpf/mklib/CardDetect.java @@ -63,18 +63,6 @@ public class CardDetect /** {@link #UnknownRectInfo}のステータス値。推定に失敗しました。入力値が間違っている？*/ public final static int FAILED_TARGET_MISSMATCH=4; /** - * i_targetの大きさを推定して、{@link UnknownRectInfo}に結果を保存します。この関数は{@link UnknownRectInfo}の状態を変化させるだけです。 - * @param i_target - * 大きさを推定するターゲット。 - * @param io_result - * 入出力パラメータ。前段までの推定結果と現在の推定値をマージして返します。 - * はじめてターゲットの推定をするときは、リセットした{@link UnknownRectInfo}を入力してください。 - * @return - * 認識状況を返します。 - * @throws NyARException - */ - - /** * この関数は、i_targetの矩形比率を推定します。 * 推定結果は、io_resultに返却します。 *

関数の使い方- diff --git a/lib/src/jp/nyatla/nyartoolkit/core/raster/rgb/NyARRgbRaster.java b/lib/src/jp/nyatla/nyartoolkit/core/raster/rgb/NyARRgbRaster.java index d25df13..6179a8a 100644 --- a/lib/src/jp/nyatla/nyartoolkit/core/raster/rgb/NyARRgbRaster.java +++ b/lib/src/jp/nyatla/nyartoolkit/core/raster/rgb/NyARRgbRaster.java @@ -81,6 +81,7 @@ public class NyARRgbRaster extends NyARRgbRaster_BasicClass * @param i_is_alloc * 外部参照/内部バッファのフラグ * @return + * 初期化が成功すると、trueです。 */ protected boolean initInstance(NyARIntSize i_size,int i_raster_type,boolean i_is_alloc) { @@ -139,6 +140,7 @@ public class NyARRgbRaster extends NyARRgbRaster_BasicClass * コンストラクタでi_is_allocをfalseにしてラスタを作成した場合、 * バッファにアクセスするまえに、バッファの有無をこの関数でチェックしてください。 * @return + * インスタンスがバッファを所有すれば、trueです。 */ public boolean hasBuffer() { diff --git a/lib/src/jp/nyatla/nyartoolkit/core/rasterfilter/rgb2gs/NyARRasterFilter_Rgb2Gs_RgbAve192.java b/lib/src/jp/nyatla/nyartoolkit/core/rasterfilter/rgb2gs/NyARRasterFilter_Rgb2Gs_RgbAve192.java index e256f57..f8584f0 100644 --- a/lib/src/jp/nyatla/nyartoolkit/core/rasterfilter/rgb2gs/NyARRasterFilter_Rgb2Gs_RgbAve192.java +++ b/lib/src/jp/nyatla/nyartoolkit/core/rasterfilter/rgb2gs/NyARRasterFilter_Rgb2Gs_RgbAve192.java @@ -66,8 +66,6 @@ public class NyARRasterFilter_Rgb2Gs_RgbAve192 implements INyARRasterFilter_Rgb2 /** * コンストラクタです。 * 入力、出力ラスタの画素形式を指定して、フィルタを作成します。 - * @param i_threshold - * 敷居値の初期値です。0<n<256の値を指定します。 * @param i_in_raster_type * 入力ラスタの形式です。 * @param i_out_raster_type @@ -146,7 +144,7 @@ public class NyARRasterFilter_Rgb2Gs_RgbAve192 implements INyARRasterFilter_Rgb2 * 入力画像と出力画像のサイズは同じである必要があります。 * @param i_input * 入力画像 - * @param i_area + * @param i_rect * ２値化する矩形範囲。入力画像の範囲内である必要があります。 * @param i_output * 出力画像 diff --git a/lib/src/jp/nyatla/nyartoolkit/core/rasterfilter/rgb2gs/NyARRasterFilter_Rgb2Gs_RgbCube.java b/lib/src/jp/nyatla/nyartoolkit/core/rasterfilter/rgb2gs/NyARRasterFilter_Rgb2Gs_RgbCube.java index 927f49e..d1a1eb1 100644 --- a/lib/src/jp/nyatla/nyartoolkit/core/rasterfilter/rgb2gs/NyARRasterFilter_Rgb2Gs_RgbCube.java +++ b/lib/src/jp/nyatla/nyartoolkit/core/rasterfilter/rgb2gs/NyARRasterFilter_Rgb2Gs_RgbCube.java @@ -78,17 +78,15 @@ public class NyARRasterFilter_Rgb2Gs_RgbCube implements INyARRasterFilter_Rgb2Gs /** * コンストラクタです。 * 入力、出力ラスタの画素形式を指定して、フィルタを作成します。 - * @param i_threshold - * 敷居値の初期値です。0<n<256の値を指定します。 * @param i_in_raster_type * 入力ラスタの形式です。 * @param i_out_raster_type * 出力ラスタの形式です。 * @throws NyARException */ - public NyARRasterFilter_Rgb2Gs_RgbCube(int i_in_raster_type,int i_out_raster) throws NyARException + public NyARRasterFilter_Rgb2Gs_RgbCube(int i_in_raster_type,int i_out_raster_type) throws NyARException { - if(!initInstance(i_in_raster_type,i_out_raster)) + if(!initInstance(i_in_raster_type,i_out_raster_type)) { throw new NyARException(); } diff --git a/lib/src/jp/nyatla/nyartoolkit/core/rasterfilter/rgb2gs/NyARRasterFilter_Rgb2Gs_YCbCr.java b/lib/src/jp/nyatla/nyartoolkit/core/rasterfilter/rgb2gs/NyARRasterFilter_Rgb2Gs_YCbCr.java index bc3dbfa..e45b666 100644 --- a/lib/src/jp/nyatla/nyartoolkit/core/rasterfilter/rgb2gs/NyARRasterFilter_Rgb2Gs_YCbCr.java +++ b/lib/src/jp/nyatla/nyartoolkit/core/rasterfilter/rgb2gs/NyARRasterFilter_Rgb2Gs_YCbCr.java @@ -77,9 +77,9 @@ public class NyARRasterFilter_Rgb2Gs_YCbCr implements INyARRasterFilter_Rgb2Gs * 出力ラスタの形式です。 * @throws NyARException */ - public NyARRasterFilter_Rgb2Gs_YCbCr(int i_in_raster_type,int i_out_raster) throws NyARException + public NyARRasterFilter_Rgb2Gs_YCbCr(int i_in_raster_type,int i_out_raster_type) throws NyARException { - if(!initInstance(i_in_raster_type,i_out_raster)) + if(!initInstance(i_in_raster_type,i_out_raster_type)) { throw new NyARException(); } diff --git a/lib/src/jp/nyatla/nyartoolkit/core/rasterreader/NyARPerspectiveRasterReader.java b/lib/src/jp/nyatla/nyartoolkit/core/rasterreader/NyARPerspectiveRasterReader.java index 20a0849..bfb44a5 100644 --- a/lib/src/jp/nyatla/nyartoolkit/core/rasterreader/NyARPerspectiveRasterReader.java +++ b/lib/src/jp/nyatla/nyartoolkit/core/rasterreader/NyARPerspectiveRasterReader.java @@ -52,7 +52,7 @@ import jp.nyatla.nyartoolkit.core.utils.*; * 他の形式でも動作しますが、低速な場合があります。 *

*

高速化について - - * 入力ラスタ形式が、{@link NyARBufferType#INT1D_X8R8G8B8_32},{@link NyARBufferType#BYTE1D_B8G8R8_24) + * 入力ラスタ形式が、{@link NyARBufferType#INT1D_X8R8G8B8_32},{@link NyARBufferType#BYTE1D_B8G8R8_24} * ,{@link NyARBufferType#BYTE1D_R8G8B8_24}のものについては、他の形式よりも高速に動作します。 * また、出力ラスタ形式が、{@link NyARBufferType#INT1D_X8R8G8B8_32}の物については、単体サンプリングモードの時のみ、さらに高速に動作します。 * 他の形式のラスタでは、以上のものよりも低速転送で対応します。 diff --git a/lib/src/jp/nyatla/nyartoolkit/core/types/stack/NyARIntPointStack.java b/lib/src/jp/nyatla/nyartoolkit/core/types/stack/NyARIntPointStack.java index a6c799f..e0cb402 100644 --- a/lib/src/jp/nyatla/nyartoolkit/core/types/stack/NyARIntPointStack.java +++ b/lib/src/jp/nyatla/nyartoolkit/core/types/stack/NyARIntPointStack.java @@ -35,16 +35,25 @@ import jp.nyatla.nyartoolkit.NyARException; import jp.nyatla.nyartoolkit.core.types.*; /** - * NyARIntPoint2d型の可変長配列です。 - * + * このクラスは、{@link NyARIntPoint2d}型の可変長配列です。 */ public class NyARIntPointStack extends NyARObjectStack { + /** + * コンストラクタです。 + * 配列の最大長さを指定して、インスタンスを生成します。 + * @param i_length + * 配列の最大長さ + * @throws NyARException + */ public NyARIntPointStack(int i_length) throws NyARException { super.initInstance(i_length,NyARIntPoint2d.class); return; } + /** + * この関数は、配列要素を作成します。 + */ protected NyARIntPoint2d createElement() { return new NyARIntPoint2d(); diff --git a/lib/src/jp/nyatla/nyartoolkit/core/types/stack/NyARIntRectStack.java b/lib/src/jp/nyatla/nyartoolkit/core/types/stack/NyARIntRectStack.java index 449d9f9..12382f4 100644 --- a/lib/src/jp/nyatla/nyartoolkit/core/types/stack/NyARIntRectStack.java +++ b/lib/src/jp/nyatla/nyartoolkit/core/types/stack/NyARIntRectStack.java @@ -33,13 +33,25 @@ package jp.nyatla.nyartoolkit.core.types.stack; import jp.nyatla.nyartoolkit.NyARException; import jp.nyatla.nyartoolkit.core.types.NyARIntRect; - +/** + * このクラスは、{@link NyARIntRect}型の可変長配列です。 + */ public class NyARIntRectStack extends NyARObjectStack { + /** + * コンストラクタです。 + * 配列の最大長さを指定して、インスタンスを生成します。 + * @param i_length + * 配列の最大長さ + * @throws NyARException + */ public NyARIntRectStack(int i_length) throws NyARException { super.initInstance(i_length,NyARIntRect.class); } + /** + * この関数は、配列要素を作成します。 + */ protected NyARIntRect createElement() { return new NyARIntRect(); diff --git a/lib/src/jp/nyatla/nyartoolkit/core/types/stack/NyARObjectStack.java b/lib/src/jp/nyatla/nyartoolkit/core/types/stack/NyARObjectStack.java index 84f0fe6..614337c 100644 --- a/lib/src/jp/nyatla/nyartoolkit/core/types/stack/NyARObjectStack.java +++ b/lib/src/jp/nyatla/nyartoolkit/core/types/stack/NyARObjectStack.java @@ -28,22 +28,38 @@ import jp.nyatla.nyartoolkit.NyARException; /** - * 可変長なオブジェクト配列です。 - * 型Tのオブジェクト配列を所有し、アクセス方法を提供します。 + * このクラスは、オブジェクトを格納する可変長配列です。 + * 配列に、オブジェクトの実態を所有します。 + * このクラスの実体化は禁止しています。継承して使ってください。 + *

継承クラスの実装方法 - + * 配列要素の生成シーケンスを実装するには、{@link #createElement}をオーバライドして、 + * コンストラクタから{@link #initInstance}を呼び出します。 + * {@link #initInstance}には２種類の関数があります。要素生成パラメータの有無で、どちらかを選択して呼び出してください。 + *

+ * @param + * 配列型を指定します。 */ public class NyARObjectStack extends NyARPointerStack { - + /** + * コンストラクタです。 + * クラスの実体化を禁止するために宣言しています。 + * 継承クラスから呼び出してください。 + * @throws NyARException + */ protected NyARObjectStack() throws NyARException { return; } /** - * パラメータが不要なインスタンスを作るためのinitInstance - * コンストラクタから呼び出します。この関数を使うときには、 createElement()をオーバライドしてください。 + * この関数は、インスタンスを初期化します。 + * 継承クラスのコンストラクタから呼び出します。 + * {@link #initInstance(int, Class, Object)}との違いは、オブジェクトの生成に引数を渡すかどうかです。 + * 引数が必要な時は、こちらの関数を使って、{@link #createElement()}をオーバライドします。 * @param i_length + * 配列の最大長さ * @param i_element_type - * @param i_param + * 配列型を示すクラスタイプ * @throws NyARException */ protected void initInstance(int i_length,Class i_element_type) throws NyARException @@ -56,11 +72,16 @@ public class NyARObjectStack extends NyARPointerStack return; } /** - * パラメータが必要なインスタンスを作るためのinitInstance - * コンストラクタから呼び出します。この関数を使うときには、 createElement(Object i_param)をオーバライドしてください。 + * この関数は、インスタンスを初期化します。 + * 継承クラスのコンストラクタから呼び出します。 + * {@link #initInstance(int, Class)}との違いは、オブジェクトの生成に引数を渡すかどうかです。 + * 引数が必要な時は、こちらの関数を使って、{@link #createElement(Object)}をオーバライドします。 * @param i_length + * 配列の最大長さ * @param i_element_type + * 配列型を示すクラスタイプ * @param i_param + * 配列要素を生成するときに渡すパラメータ * @throws NyARException */ protected void initInstance(int i_length,Class i_element_type,Object i_param) throws NyARException @@ -72,18 +93,36 @@ public class NyARObjectStack extends NyARPointerStack } return; } + /** + * この関数は、配列要素のオブジェクトを１個作ります。 + * {@link #initInstance(int, Class)}から呼び出されます。 + * 継承クラスでオーバライドして、要素オブジェクトを１個生成して返す処理を実装してください。 + * @return + * 新しいオブジェクトを返してください。 + * @throws NyARException + */ protected T createElement() throws NyARException { throw new NyARException(); } + /** + * この関数は、配列要素のオブジェクトを(引数付きで)１個作ります。 + * {@link #initInstance(int, Class, Object)}から呼び出されます。 + * 継承クラスでオーバライドして、要素オブジェクトを１個生成して返す処理を実装してください。 + * @return + * 新しいオブジェクトを返してください。 + * @throws NyARException + */ protected T createElement(Object i_param) throws NyARException { throw new NyARException(); } /** - * 新しい領域を予約します。 + * この関数は、配列から新しい要素を１個わりあてて返します。 + * 関数が成功すると、有効な配列長が+1されます。 * @return + * 成功すると、新しい配列要素。 * 失敗するとnull * @throws NyARException */ @@ -99,18 +138,16 @@ public class NyARObjectStack extends NyARPointerStack return ret; } /** - * このクラスは、オブジェクトをpushすることはできません。 - * prePush()を使用してください。 + * この関数は機能しません。{@link #prePush}を使って下さい。 */ public T push(T i_object) { return null; } /** - * スタックを初期化します。 + * この関数は、配列の有効長を設定します。 * @param i_reserv_length - * 使用済みにするサイズ - * @return + * 設定するサイズ */ public final void init(int i_reserv_length) throws NyARException { @@ -119,11 +156,8 @@ public class NyARObjectStack extends NyARPointerStack throw new NyARException(); } this._length=i_reserv_length; - } - /** - * 指定した要素を削除します。 - * 削除した要素は前方詰めで詰められます。 - */ + } + //override public final void remove(int i_index) { if(i_index!=this._length-1){ @@ -135,12 +169,7 @@ public class NyARObjectStack extends NyARPointerStack } this._length--; } - /** - * 指定した要素を順序を無視して削除します。 - * 削除後のスタックの順序は保証されません。 - * このAPIは、最後尾の有効要素と、削除対象の要素を交換することで、削除を実現します。 - * @param i_index - */ + //override public final void removeIgnoreOrder(int i_index) { assert(this._length>i_index && i_index>=0); diff --git a/lib/src/jp/nyatla/nyartoolkit/core/types/stack/NyARPointerStack.java b/lib/src/jp/nyatla/nyartoolkit/core/types/stack/NyARPointerStack.java index 36fcf29..9b52ef1 100644 --- a/lib/src/jp/nyatla/nyartoolkit/core/types/stack/NyARPointerStack.java +++ b/lib/src/jp/nyatla/nyartoolkit/core/types/stack/NyARPointerStack.java @@ -5,18 +5,22 @@ import java.lang.reflect.Array; import jp.nyatla.nyartoolkit.NyARException; /** - * 実体をもたない可変長配列です。 - * このクラスは実体化できません。継承して使います。 - * + * このクラスは、オブジェクトの参照値を格納する可変長配列です。 + * このクラスの実体化は禁止しています。継承して使ってください。 * @param + * 配列型を指定します。 */ public class NyARPointerStack { + /** オブジェクトの参照値を格納するバッファ*/ protected T[] _items; + /** 配列の長さ。({@link #_items#length)とは異なることに注意してください。*/ protected int _length; /** - * このクラスは実体化できません。 + * コンストラクタです。 + * クラスの実体化を禁止するために宣言しています。 + * 継承クラスから呼び出してください。 * @throws NyARException */ protected NyARPointerStack() throws NyARException @@ -24,9 +28,12 @@ public class NyARPointerStack } /** - * スタックのメンバ変数を初期化します。この関数は、このクラスを継承したクラスを公開するときに、コンストラクタから呼び出します。 + * この関数は、インスタンスを初期化します。 + * この関数は、このクラスを継承したクラスのコンストラクタから呼び出します。 * @param i_length + * 配列の最大長さ * @param i_element_type + * 配列型を示すクラスタイプ * @throws NyARException */ @SuppressWarnings("unchecked") @@ -40,9 +47,11 @@ public class NyARPointerStack } /** - * スタックに参照を積みます。 + * この関数は、配列の最後尾にオブジェクトを追加します。 + * @param i_object + * 追加するオブジェクト * @return - * 失敗するとnull + * 追加したオブジェクト。失敗するとnullを返します。 */ public T push(T i_object) { @@ -56,9 +65,13 @@ public class NyARPointerStack return i_object; } /** - * スタックに参照を積みます。pushとの違いは、失敗した場合にassertすることです。 + * この関数は、配列の最後尾にオブジェクトを追加します。 + * {@link #push}との違いは、失敗したときにASSERT、または例外を発生することです。 + * 確実に成功することがわっかっていない場合は、{@link #push}を使ってください。 * @param i_object + * 追加するオブジェクト * @return + * 追加したオブジェクト。 */ public T pushAssert(T i_object) { @@ -71,8 +84,9 @@ public class NyARPointerStack } /** - * 見かけ上の要素数を1減らして、そのオブジェクトを返します。 + * この関数は、配列の最後尾の要素を取り除いて返します。 * @return + * 最後尾のオブジェクト。 */ public T pop() { @@ -81,9 +95,9 @@ public class NyARPointerStack return this._items[this._length]; } /** - * 見かけ上の要素数をi_count個減らします。 + * この関数は、配列の最後尾から指定個数の要素を取り除きます。 * @param i_count - * @return + * 取り除く個数 */ public final void pops(int i_count) { @@ -92,29 +106,41 @@ public class NyARPointerStack return; } /** - * 配列を返します。 - * + * この関数は、配列全体を返します。 + * 有効な要素の数は、先頭から{@link #getLength}個です。 * @return + * 配列の参照ポインタ */ public final T[] getArray() { return this._items; } + /** + * この関数は、指定したインデクスの配列要素を返します。 + * @param i_index + * 要素のインデクス番号。 + * 有効な値は、0から{@link #getLength}-1です。 + * @return + * 配列要素の参照値 + */ public final T getItem(int i_index) { return this._items[i_index]; } /** - * 配列の見かけ上の要素数を返却します。 + * この関数は、配列の有効な要素数返します。 * @return + * 有効な要素数 */ public final int getLength() { return this._length; } /** - * 指定した要素を削除します。 - * 削除した要素は前方詰めで詰められます。 + * この関数は、指定したインデクスの要素を配列から取り除きます。 + * 要素は、前方詰めで詰められます。 + * @param i_index + * 削除する要素のインデクス */ public void remove(int i_index) { @@ -132,8 +158,12 @@ public class NyARPointerStack this._length--; } /** - * 指定した要素を順序を無視して削除します。 + * この関数は、指定したインデクスの要素を配列から取り除きます。 + * 要素の順番は、削除したインデクス以降が不定になります。 + * このAPIは、最後尾の有効要素と、削除対象の要素を交換することで、削除を実現します。 + * {@link #remove}より高速ですが、要素の順序が重要な処理では注意して使ってください。 * @param i_index + * 削除する要素のインデクス */ public void removeIgnoreOrder(int i_index) { @@ -145,7 +175,7 @@ public class NyARPointerStack this._length--; } /** - * 見かけ上の要素数をリセットします。 + * この関数は、配列の長さを0にリセットします。 */ public void clear() { diff --git a/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARDistMap.java b/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARDistMap.java index a1ba3dd..4576062 100644 --- a/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARDistMap.java +++ b/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARDistMap.java @@ -27,25 +27,50 @@ package jp.nyatla.nyartoolkit.core.utils; import jp.nyatla.nyartoolkit.core.types.NyARIntPoint2d; /** - * 2つの点集合同士を比較して、集合の各点同士の距離が最も近くになる組み合わせを計算 - * するためのクラスです。 - * 点集合の2次元距離マップを作成して、そこから最適な組み合わせを計算します。 + * このクラスは、距離マップを利用した、頂点集合同士のマッチング処理機能を提供します。 + * 2つの点集合同士を比較して、集合の各点同士の距離が最も近くになる組み合わせを計算します。 + *

アルゴリズム - + * 2つの点集合の総当たりの距離マップを作り、その距離が小さいのものから順に抽出することで、 + * 其々の点の移動距離が最小になる組み合わせを計算します。 + *

+ *

使い方　- + * このクラスは、まず距離マップを作るために距離値をセットして、次に組み合わせを得る手順で使います。 + * 距離マップには行と列があります。列を基準値、行を比較値として、その距離値を格納します。 + * 行と列の距離マップを作り終えたら、組合せを計算します。 + *

    + *
  1. {@link setMapSize}関数で、マップサイズ（比較する頂点数）を設定する。 + *
  2. {@link #setDist},または{@link #setPointDists}で、距離マップに全ての値を書き込む。 + *
  3. + *
+ *

*/ public class NyARDistMap { + /** 処理用のデータ型*/ protected class DistItem { public int row; public int col; public int dist; } + /**　距離マップ用の配列*/ protected DistItem[] _map; - + /**　ワーク変数*/ protected int _min_dist; + /**　ワーク変数*/ protected int _min_dist_index; + /**　ワーク変数*/ protected int _size_row; + /**　ワーク変数*/ protected int _size_col; - + /** + * コンストラクタです。 + * マップの最大サイズを指定して、インスタンスを作成します。 + * @param i_max_col + * マップの最大列数 + * @param i_max_row + * マップの最大行数 + */ public NyARDistMap(int i_max_col,int i_max_row) { this._min_dist=Integer.MAX_VALUE; @@ -58,10 +83,12 @@ public class NyARDistMap } } /** - * マップのサイズを再設定します。内容は不定になり、距離マップの再設定が必要です。 + * この関数は、マップのサイズを指定します。 + * 値は初期化されません。 * @param i_col - * 列数 + * 新しい列数。 * @param i_row + * 新しい行数。 */ public void setMapSize(int i_col,int i_row) { @@ -69,11 +96,16 @@ public class NyARDistMap this._size_col=i_col; } /** - * 列と行を指定して、距離値をマップに値をセットします。 - * このAPIは低速です。setPointsDistsを参考に、マップに直接距離値を置く関数を検討してください。 + * この関数は、列と行を指定して、距離値1個をマップにセットします。 + *

注意 - + * このAPIは低速です。性能が必要な時は、{@link #setPointsDists}を参考に、一括書込みする関数を検討してください。 + *

* @param i_col + * 列のインデクスを指定します。 * @param i_row + * 行のインデクスを指定します。 * @param i_dist + * その行と列の距離値を指定します。 */ public void setDist(int i_col,int i_row,int i_dist) { @@ -89,13 +121,19 @@ public class NyARDistMap return; } /** - * 2つの点集合同士の距離を計算して、距離マップに値をセットします。 - * 点の座標が他の表現で実装されている場合は、この関数をオーバーロードして実装してください。 + * この関数は、２つの座標点配列同士の距離値を一括してマップにセットします。 + *

+ * 実装メモ - + * 点のフォーマットが合わない実装されている場合は、この関数参考にオーバーロードしてください。 + *

* @param i_vertex_r + * 比較する頂点群を格納した配列。 * @param i_row_len + * i_vertex_rの有効な要素数 * @param i_vertex_c + * 基準となる頂点群を格納した配列 * @param i_col_len - * @param o_rowindex + * i_vertex_cの有効な要素数 */ public void setPointDists(NyARIntPoint2d[] i_vertex_r,int i_row_len,NyARIntPoint2d[] i_vertex_c,int i_col_len) { @@ -124,10 +162,12 @@ public class NyARDistMap return; } /** - * 現在の距離マップから、colに対するrowの組み合わせを計算します。 - * colに対して最適なものが無い場合は、o_rowindexの値に-1がセットされます。 + * この関数は、現在の距離マップから、col要素に対するrow要素の組合せを計算します。 + * colに対して適したrow要素が見つからない場合は、o_rowindexの該当要素に-1を設定します。 * この関数は内部データを不可逆に変更します。計算後は、距離マップの再セットが必要です。 * @param o_rowindex + * 組合せを受け取る配列です。 + * col[n]に対するrow[m]のインデクス番号mを、o_rowindex[n]に返します。 */ public void getMinimumPair(int[] o_rowindex) { diff --git a/lib/src/jp/nyatla/nyartoolkit/core/utils/NyAREquationSolver.java b/lib/src/jp/nyatla/nyartoolkit/core/utils/NyAREquationSolver.java index 6e8c111..e89ff38 100644 --- a/lib/src/jp/nyatla/nyartoolkit/core/utils/NyAREquationSolver.java +++ b/lib/src/jp/nyatla/nyartoolkit/core/utils/NyAREquationSolver.java @@ -25,23 +25,58 @@ package jp.nyatla.nyartoolkit.core.utils; import jp.nyatla.nyartoolkit.*; + /** - * 方程式を解く関数を定義します。 - * + * このクラスには、方程式を解く関数を定義します。 */ public class NyAREquationSolver { + /** + * この関数は、 二次方程式(ax^2+bx+c=0)を解いて、実根のみを返します。 + * @param i_a + * 係数aの値 + * @param i_b + * 係数bの値 + * @param i_c + * 係数cの値 + * @param o_result + * 解を受け取る配列。2要素以上である事。 + * @return + * o_resultに格納した実根の数。 + */ public static int solve2Equation(double i_a, double i_b, double i_c,double[] o_result) { assert i_a!=0; return solve2Equation(i_b/i_a,i_c/i_a,o_result,0); } - + /** + * この関数は、 二次方程式(x^2+bx+c=0)を解いて、実根のみを返します。 + * @param i_b + * 係数bの値 + * @param i_c + * 係数cの値 + * @param o_result + * 解を受け取る配列。2要素以上である事。 + * @return + * o_resultに格納した実根の数。 + */ public static int solve2Equation(double i_b, double i_c,double[] o_result) { return solve2Equation(i_b,i_c,o_result,0); } - + /** + * この関数は、 二次方程式(x^2+bx+c=0)を解いて、実根のみを返します。 + * @param i_b + * 係数bの値 + * @param i_c + * 係数cの値 + * @param o_result + * 解を受け取る配列。 + * @param i_result_st + * o_resultの格納を開始するインデクス番号 + * @return + * o_resultに格納した実根の数。 + */ public static int solve2Equation(double i_b, double i_c,double[] o_result,int i_result_st) { double t=i_b*i_b-4*i_c; @@ -62,9 +97,8 @@ public class NyAREquationSolver } /** - * ３次方程式 a*x^3+b*x^2+c*x+d=0の実根を求める。 - * http://aoki2.si.gunma-u.ac.jp/JavaScript/src/3jisiki.html - * のコードを基にしてます。 + * この関数は、３次方程式(a*x^3+b*x^2+c*x+d=0)の実根を計算します。 + * このコードは、http://aoki2.si.gunma-u.ac.jp/JavaScript/src/3jisiki.htmlを元にしています。 * @param i_a * X^3の係数 * @param i_b @@ -76,18 +110,16 @@ public class NyAREquationSolver * @param o_result * 実根。double[3]を指定すること。 * @return + * 返却した実根の数。 */ public static int solve3Equation(double i_a, double i_b, double i_c, double i_d,double[] o_result) { assert (i_a != 0); return solve3Equation(i_b/i_a,i_c/i_a,i_d/i_a,o_result); } - /** - * ３次方程式 x^3+b*x^2+c*x+d=0の実根を求める。 - * だけを求める。 - * http://aoki2.si.gunma-u.ac.jp/JavaScript/src/3jisiki.html - * のコードを基にしてます。 + * この関数は、３次方程式(x^3+b*x^2+c*x+d=0)の実根を計算します。 + * このコードは、http://aoki2.si.gunma-u.ac.jp/JavaScript/src/3jisiki.htmlを元にしています。 * @param i_b * X^2の係数 * @param i_c @@ -95,9 +127,10 @@ public class NyAREquationSolver * @param i_d * X^0の係数 * @param o_result - * 実根。double[1]以上を指定すること。 + * 実根。double[3]を指定すること。 * @return - */ + * 返却した実根の数。 + */ public static int solve3Equation(double i_b, double i_c, double i_d,double[] o_result) { double tmp,b, p, q; @@ -131,18 +164,21 @@ public class NyAREquationSolver /** - * ４次方程式の実根だけを求める。 + * この関数は、4次方程式(ax^4+bx^3+b*cx^2+d*x+e=0)の実根を計算します。 * @param i_a - * X^3の係数 + * X^4の係数 * @param i_b - * X^2の係数 + * X^3の係数 * @param i_c - * X^1の係数 + * X^2の係数 * @param i_d + * X^1の係数 + * @param i_e * X^0の係数 * @param o_result - * 実根。double[3]を指定すること。 + * 実根。double[4]を指定すること。 * @return + * 返却した実根の数。 */ public static int solve4Equation(double i_a, double i_b, double i_c, double i_d,double i_e,double[] o_result) throws NyARException { diff --git a/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARManagedObject.java b/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARManagedObject.java index 6308a5d..946ca74 100644 --- a/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARManagedObject.java +++ b/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARManagedObject.java @@ -25,36 +25,50 @@ package jp.nyatla.nyartoolkit.core.utils; /** - * NyARManagedObjectPoolの要素クラスです。 - * + * このクラスは、{@link NyARManagedObjectPool}の要素の基本クラスです。 + * オブジェクトの有効性を判断するための、参照カウンタをもちます。 + * {@link NyARManagedObjectPool}に対して、オブジェクトの操作インタフェイスを提供します。 */ public class NyARManagedObject { /** - * このインタフェイスは、NyARManagedObjectがPoolを操作するために使います。 - */ + * このインタフェイスは、{@link NyARManagedObject}が{@link NyARManagedObjectPool}を + * 所有される操作する関数を定義します。 + */ public interface INyARManagedObjectPoolOperater { + /** + * この関数は、指定したオブジェクトを、割り当て済みから未割り当てにします。 + * @param i_object + * 未割当にするオブジェクト。 + */ public void deleteObject(NyARManagedObject i_object); } - /** - * オブジェクトの参照カウンタ - */ + + /** オブジェクトの参照カウンタ*/ private int _count; - /** - * オブジェクトの解放関数へのポインタ - */ + + /** 所有されるオブジェクトプールの操作インタフェイスのポインタ*/ private INyARManagedObjectPoolOperater _pool_operater; + /** - * NyARManagedObjectPoolのcreateElement関数が呼び出すコンストラクタです。 + * コンストラクタです。 + * 所有される{@link NyARManagedObjectPool}を指定して、インスタンスを作成します。 + * この関数は、{@link NyARManagedObjectPool#createElement}関数が呼び出します。ユーザが使うことはありません。 * @param i_ref_pool_operator - * Pool操作の為のインタフェイス + * このオブジェクトの所有者の持つ、操作インタフェイス */ protected NyARManagedObject(INyARManagedObjectPoolOperater i_ref_pool_operator) { this._count=0; this._pool_operater=i_ref_pool_operator; } + /** + * この関数は、オブジェクトを初期状態にします。 + * この関数は、{@link NyARManagedObjectPool}が呼び出します。ユーザが呼び出すことはありません。 + * @return + * このオブジェクトを初期化したオブジェクト。 + */ public final NyARManagedObject initObject() { assert(this._count==0); @@ -62,8 +76,9 @@ public class NyARManagedObject return this; } /** - * このオブジェクトに対する、新しい参照オブジェクトを返します。 + * この関数は、オブジェクトの参照カウンタを1加算します。 * @return + * このオブジェクトの参照値。 */ public final NyARManagedObject refObject() { @@ -72,8 +87,10 @@ public class NyARManagedObject return this; } /** - * 参照オブジェクトを開放します。 + * この関数は、オブジェクトの参照カウンタを1減算します。 + * 参照カウンタが0になると、オブジェクトは未参照状態となり、自動的に{@link NyARManagedObjectPool}へ返却されます。 * @return + * 減算後の参照カウンタ */ public int releaseObject() { @@ -85,8 +102,9 @@ public class NyARManagedObject return this._count; } /** - * 現在の参照カウンタを返します。 + * この関数は、現在のインスタンスの参照カウンタ値を返します。 * @return + * 参照カウンタ値 */ public final int getCount() { diff --git a/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARManagedObjectPool.java b/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARManagedObjectPool.java index 19314e8..91b66d1 100644 --- a/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARManagedObjectPool.java +++ b/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARManagedObjectPool.java @@ -6,24 +6,42 @@ import jp.nyatla.nyartoolkit.NyARException; - - /** - * 参照カウンタ付きのobjectPoolです。NyARManagedObjectから派生したオブジェクトを管理します。 - * このクラスは、参照カウンタ付きのオブジェクト型Tのオブジェクトプールを実現します。 + * このクラスは、参照カウンタ付きのObjectPoolの基本クラスです。 + * {@link NyARManagedObject}から派生したオブジェクト型Tのオブジェクトプールを実現します。 + * + * オブジェクトプールは、未割当リストを使って、オブジェクト要素を管理します。 + * はじめ、全てのオブジェクト要素は未割当リストにあります。オブジェクト要素の生成要求があると、オブジェクトプール + * は未割当リストにあるオブジェクト要素の参照カウンタを1加算して、未割当リストから削除します。 + * 逆に、オブジェクト要素の解放を要求があると、オブジェクト要素の参照カウンタを1減算して、その数が　0になったら、 + * オブジェクト要素を未割当リストへ加えます。 + *
+ * このクラスは、NyARManagedObjectと密接に関係して動作することに注意してください。 + * 割り当て関数はオブジェクトプールの{@link NyARManagedObjectPool#newObject}、解放関数にはオブジェクト要素の + * {@link NyARManagedObject#releaseObject()}を使います。 + *
+ * また、このクラスは{@link NyARManagedObject}に対して、特殊な関数を持つインタフェイスを提供します。 + * このインタフェイスは、{@link NyARManagedObject}が{@link NyARManagedObjectPool}のリストを操作するために使います。 + *

継承クラスの実装について - + * このクラスは、そのまま実体化できません。継承クラスを実装する必要があります。 + * 実装するには、{@link #createElement}をオーバライドして、コンストラクタから{@link #initInstance}を呼び出します。 + * {@link #initInstance}には２種類の関数があります。要素生成パラメータの有無で、どちらかを選択して呼び出してください。 + *

* - * このクラスは、NyARManagedObjectと密接に関連して動作することに注意してください。 - * 要素の作成関数はこのクラスで公開しますが、要素の解放関数は要素側に公開します。 * @param */ public class NyARManagedObjectPool { /** + * このクラスは、{@link NyARManagedObject}へ提供する操作インタフェイスの実体です。 + * 未割当リストを操作する関数を定義します。 * Javaの都合でバッファを所有させていますが、別にこの形で実装しなくてもかまいません。 */ public class Operator implements NyARManagedObject.INyARManagedObjectPoolOperater { + /** 要素の実体の保管用リスト*/ public NyARManagedObject[] _buffer; + /** 未割当オブジェクトのリスト*/ public NyARManagedObject[] _pool; public int _pool_stock; public void deleteObject(NyARManagedObject i_object) @@ -35,15 +53,15 @@ public class NyARManagedObjectPool } } /** - * 公開するオペレータオブジェクトです。 - * このプールに所属する要素以外からは参照しないでください。 + * オブジェクト要素から参照する操作インタフェイス。ユーザが使用することはありません。 + * @bug このスコープはprotectedではないか？ */ public Operator _op_interface=new Operator(); /** - * プールから型Tのオブジェクトを割り当てて返します。 + * この関数は、新しいオブジェクトを１個割り当てて返します。 * @return - * 新しいオブジェクト + * 新しいオブジェクト。失敗した場合はnull */ @SuppressWarnings("unchecked") public T newObject() throws NyARException @@ -57,16 +75,22 @@ public class NyARManagedObjectPool return (T)(pool._pool[pool._pool_stock].initObject()); } /** - * 実体化の拒否の為に、コンストラクタを隠蔽します。 - * 継承クラスを作成して、初期化処理を実装してください。 + * コンストラクタです。 + * 生成拒否の為に、コンストラクタを隠蔽します。 + * 継承クラスを作成してください。 */ protected NyARManagedObjectPool() { } /** - * オブジェクトを初期化します。この関数は、このクラスを継承したクラスを公開するときに、コンストラクタから呼び出します。 + * この関数は、インスタンスを初期化します。 + * 継承クラスのコンストラクタから呼び出します。 + * {@link #initInstance(int, Class, Object)}との違いは、オブジェクトの生成に引数を渡すかどうかです。 + * 引数が必要な時は、こちらの関数を使って、{@link #createElement()}をオーバライドします。 * @param i_length + * 配列の最大長さ * @param i_element_type + * 配列型を示すクラスタイプ * @throws NyARException */ @SuppressWarnings("unchecked") @@ -85,7 +109,19 @@ public class NyARManagedObjectPool } return; } - + /** + * この関数は、インスタンスを初期化します。 + * 継承クラスのコンストラクタから呼び出します。 + * {@link #initInstance(int, Class)}との違いは、オブジェクトの生成に引数を渡すかどうかです。 + * 引数が必要な時は、こちらの関数を使って、{@link #createElement(Object)}をオーバライドします。 + * @param i_length + * 配列の最大長さ + * @param i_element_type + * 配列型を示すクラスタイプ + * @param i_param + * 配列要素を生成するときに渡すパラメータ + * @throws NyARException + */ @SuppressWarnings("unchecked") protected void initInstance(int i_length,Class i_element_type,Object i_param) throws NyARException { @@ -103,14 +139,25 @@ public class NyARManagedObjectPool return; } /** - * オブジェクトを作成します。継承クラス内で、型Tのオブジェクトを作成して下さい。 + * この関数は、配列要素のオブジェクトを１個作ります。 + * {@link #initInstance(int, Class)}から呼び出されます。 + * 継承クラスでオーバライドして、要素オブジェクトを１個生成して返す処理を実装してください。 * @return + * 新しいオブジェクトを返してください。 * @throws NyARException */ protected T createElement() throws NyARException { throw new NyARException(); } + /** + * この関数は、配列要素のオブジェクトを(引数付きで)１個作ります。 + * {@link #initInstance(int, Class, Object)}から呼び出されます。 + * 継承クラスでオーバライドして、要素オブジェクトを１個生成して返す処理を実装してください。 + * @return + * 新しいオブジェクトを返してください。 + * @throws NyARException + */ protected T createElement(Object i_param) throws NyARException { throw new NyARException(); diff --git a/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARMath.java b/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARMath.java index 7d70b83..f63f54b 100644 --- a/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARMath.java +++ b/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARMath.java @@ -2,26 +2,50 @@ package jp.nyatla.nyartoolkit.core.utils; /** - * 数学関数を定義します。 - * + * このクラスには、数学関数、数学定数を定義します。 */ public class NyARMath { + /** 定数値。40^2*/ public final static int SQ_40=40*40; + /** 定数値。20^2*/ public final static int SQ_20=20*20; + /** 定数値。10^2*/ public final static int SQ_10=10*10; + /** 定数値。8^2*/ public final static int SQ_8=8*8; + /** 定数値。5^2*/ public final static int SQ_5=5*5; + /** 定数値。2^2*/ public final static int SQ_2=2*2; - + /** 定数値。cos(30)の近似値*/ public final static double COS_DEG_30=0.8660; + /** 定数値。cos(25)の近似値*/ public final static double COS_DEG_25=0.9063; + /** 定数値。cos(20)の近似値*/ public final static double COS_DEG_20=0.9396; + /** 定数値。cos(15)の近似値*/ public final static double COS_DEG_15=0.9395; + /** 定数値。cos(10)の近似値*/ public final static double COS_DEG_10=0.9848; + /** 定数値。cos(8)の近似値*/ public final static double COS_DEG_8 =0.9902; + /** 定数値。cos(5)の近似値*/ public final static double COS_DEG_5 =0.9961; + /** + * この関数は、点p1と点p2の距離の二乗値を返します。 + * @param i_p1x + * 点1のX座標 + * @param i_p1y + * 点1のY座標 + * @param i_p2x + * 点2のX座標 + * @param i_p2y + * 点2のY座標 + * @return + * 二乗距離値 + */ public static final double sqNorm(double i_p1x,double i_p1y,double i_p2x,double i_p2y) { double x,y; @@ -29,22 +53,30 @@ public class NyARMath y=i_p2y-i_p1y; return x*x+y*y; } - - - + /** + * この関数は、点1と点2の距離値を返します。 + * @param i_x1 + * 点1のX座標 + * @param i_y1 + * 点1のY座標 + * @param i_x2 + * 点2のX座標 + * @param i_y2 + * 点2のY座標 + * @return + * 距離値 + */ public static final double dist(double i_x1,double i_y1,double i_x2,double i_y2) { return Math.sqrt(i_x1*i_y1+i_x2+i_y2); } - - - - /** - * 3乗根を求められないシステムで、３乗根を求めます。 - * http://aoki2.si.gunma-u.ac.jp/JavaScript/src/3jisiki.html + * この関数は、3乗根を求めます。 + * 出典 http://aoki2.si.gunma-u.ac.jp/JavaScript/src/3jisiki.html * @param i_in + * 3乗根を求める数値 * @return + * 三乗根の値 */ public static double cubeRoot(double i_in) { @@ -52,11 +84,14 @@ public class NyARMath return (i_in >= 0) ? res : -res; } /** - * ユークリッドの互除法により、2変数の最大公約数を求める。 - * http://ja.wikipedia.org/wiki/%E3%83%A6%E3%83%BC%E3%82%AF%E3%83%AA%E3%83%83%E3%83%89%E3%81%AE%E4%BA%92%E9%99%A4%E6%B3%95 + * この関数は、ユークリッドの互除法により、最大公約数を求めます。 + * 出典 http://ja.wikipedia.org/wiki/%E3%83%A6%E3%83%BC%E3%82%AF%E3%83%AA%E3%83%83%E3%83%89%E3%81%AE%E4%BA%92%E9%99%A4%E6%B3%95 * @param i_x + * 最大公約数を求める数1 * @param i_y + * 最大公約数を求める数2 * @return + * 最大公約数 */ public static int gcd(int i_x,int i_y) { diff --git a/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARObjectPool.java b/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARObjectPool.java index 0e53a4a..da54cb1 100644 --- a/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARObjectPool.java +++ b/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARObjectPool.java @@ -31,19 +31,25 @@ import jp.nyatla.nyartoolkit.NyARException; /** - * このクラスは、型Tのオブジェクトプールを提供します。 - * + * このクラスは、シンプルなオブジェクトプールの基本クラスです。 + * 生成済のオブジェクトを複数所有して、他のオブジェクトに貸付る機能を提供します。 + * 参照カウンタを持つ管理されたオブジェクトプールが必要な時には、{@link NyARManagedObjectPool}クラスを使用します。 * @param + * 要素のオブジェクト型 */ public class NyARObjectPool { + /**　要素の保管リスト*/ protected T[] _buffer; + /**　未割当の要素トリスト*/ protected T[] _pool; + /** 未割当の要素の数*/ protected int _pool_stock; /** - * オブジェクトプールからオブジェクトを取り出します。 + * この関数は、新しいオブジェクトを１個割り当てて返します。 * @return + * 新しいオブジェクト。失敗した場合はnull */ public T newObject() { @@ -55,8 +61,10 @@ public class NyARObjectPool } /** - * オブジェクトプールへオブジェクトを返却します。 - * @return + * この関数は、オブジェクトプールへオブジェクトを返却します。 + * @param　i_object + * {@link #newObject}で割り当てたオブジェクトを指定します。 + * 必ず同じインスタンスで割り当てたオブジェクトを指定してください。 */ public void deleteObject(T i_object) { @@ -68,16 +76,20 @@ public class NyARObjectPool } /** - * このクラスは実体化できません。 - * @throws NyARException + * コンストラクタです。 + * 生成拒否の為に、コンストラクタを隠蔽します。 + * 継承クラスを作成してください。 */ public NyARObjectPool() throws NyARException { } /** - * オブジェクトを初期化します。この関数は、このクラスを継承したクラスを公開するときに、コンストラクタから呼び出します。 + * この関数は、インスタンスを初期化します。 + * 継承クラスのコンストラクタから呼び出します。 * @param i_length + * 配列の最大長さ * @param i_element_type + * 配列型を示すクラスタイプ * @throws NyARException */ @SuppressWarnings("unchecked") @@ -96,8 +108,11 @@ public class NyARObjectPool return; } /** - * オブジェクトを作成します。 + * この関数は、配列要素のオブジェクトを１個作ります。 + * {@link #initInstance(int, Class)}から呼び出されます。 + * 継承クラスでオーバライドして、要素オブジェクトを１個生成して返す処理を実装してください。 * @return + * 新しいオブジェクトを返してください。 * @throws NyARException */ protected T createElement() throws NyARException diff --git a/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARPerspectiveParamGenerator.java b/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARPerspectiveParamGenerator.java index 6909f03..2a545f4 100644 --- a/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARPerspectiveParamGenerator.java +++ b/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARPerspectiveParamGenerator.java @@ -28,20 +28,24 @@ import jp.nyatla.nyartoolkit.NyARException; import jp.nyatla.nyartoolkit.core.types.*; /** - * 遠近法を用いたPerspectiveパラメータを計算するクラスのテンプレートです。 - * 任意頂点四角系と矩形から、遠近法の変形パラメータを計算します。 - * このクラスはリファレンス実装のため、パフォーマンスが良くありません。実際にはNyARPerspectiveParamGenerator_O1を使ってください。 + * このクラスは、遠近法を用いたPerspectiveパラメータを計算する抽象クラスです。 + * 任意頂点の四角形と矩形から、遠近法の変形パラメータを計算します。 + * パラメータは、8個の定数値です。配列に返却します。 + * 継承クラスで、{@link #getParam}関数を実装してください。 */ public abstract class NyARPerspectiveParamGenerator { + /** 射影の基点(X)*/ protected int _local_x; + /** 射影の基点(Y)*/ protected int _local_y; /** * コンストラクタです。 + * 変換先の基準点を設定してインスタンスを作成します。 * @param i_local_x - * パラメータ計算の基準点を指定します。 + * パラメータ計算の基準点を指定します。デフォルト値は1です。 * @param i_local_y - * パラメータ計算の基準点を指定します。 + * パラメータ計算の基準点を指定します。デフォルト値は1です。 */ public NyARPerspectiveParamGenerator(int i_local_x,int i_local_y) { @@ -50,7 +54,7 @@ public abstract class NyARPerspectiveParamGenerator return; } /** - * 遠近法のパラメータを計算します。 + * この関数は、遠近法のパラメータを計算して、返却します。 * @param i_size * 変換先の矩形のサイズを指定します。 * @param i_vertex @@ -67,7 +71,7 @@ public abstract class NyARPerspectiveParamGenerator return this.getParam(i_size.w,i_size.h,i_vertex[0].x,i_vertex[0].y,i_vertex[1].x,i_vertex[1].y,i_vertex[2].x,i_vertex[2].y,i_vertex[3].x,i_vertex[3].y, o_param); } /** - * 遠近法のパラメータを計算します。 + * この関数は、遠近法のパラメータを計算して、返却します。 * @param i_size * 変換先の矩形のサイズを指定します。 * @param i_vertex @@ -83,7 +87,7 @@ public abstract class NyARPerspectiveParamGenerator return this.getParam(i_size.w,i_size.h,i_vertex[0].x,i_vertex[0].y,i_vertex[1].x,i_vertex[1].y,i_vertex[2].x,i_vertex[2].y,i_vertex[3].x,i_vertex[3].y, o_param); } /** - * 遠近法のパラメータを計算します。 + * この関数は、遠近法のパラメータを計算して、返却します。 * @param i_width * 変換先の矩形のサイズを指定します。 * @param i_height @@ -101,7 +105,7 @@ public abstract class NyARPerspectiveParamGenerator return this.getParam(i_width,i_height,i_vertex[0].x,i_vertex[0].y,i_vertex[1].x,i_vertex[1].y,i_vertex[2].x,i_vertex[2].y,i_vertex[3].x,i_vertex[3].y, o_param); } /** - * 遠近法のパラメータを計算します。 + * この関数は、遠近法のパラメータを計算して、返却します。 * @param i_width * 変換先の矩形のサイズを指定します。 * @param i_height @@ -119,19 +123,32 @@ public abstract class NyARPerspectiveParamGenerator return this.getParam(i_width,i_height,i_vertex[0].x,i_vertex[0].y,i_vertex[1].x,i_vertex[1].y,i_vertex[2].x,i_vertex[2].y,i_vertex[3].x,i_vertex[3].y, o_param); } /** - * 遠近法のパラメータを計算します。継承クラスで実装してください。 + * この関数は、遠近法のパラメータを計算して、返却します。 + * 実装クラスでは、遠近法のパラメータを計算する処理を実装してください。 * @param i_dest_w + * 出力先矩形の幅を指定します。 * @param i_dest_h + * 出力先矩形の高さを指定します。 * @param x1 + * 変換元四角形の頂点1のX座標です。 * @param y1 + * 変換元四角形の頂点1のY座標です。 * @param x2 + * 変換元四角形の頂点2のX座標です。 * @param y2 + * 変換元四角形の頂点2のY座標です。 * @param x3 + * 変換元四角形の頂点3のX座標です。 * @param y3 + * 変換元四角形の頂点3のY座標です。 * @param x4 + * 変換元四角形の頂点4のX座標です。 * @param y4 + * 変換元四角形の頂点4のY座標です。 * @param o_param + *　結果を受け取る配列を指定します。 * @return + * 計算に成功するとtrueを返します。 * @throws NyARException */ public abstract boolean getParam(int i_dest_w,int i_dest_h,double x1,double y1,double x2,double y2,double x3,double y3,double x4,double y4,double[] o_param)throws NyARException; diff --git a/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARPerspectiveParamGenerator_O1.java b/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARPerspectiveParamGenerator_O1.java index f3dd52f..94cae4a 100644 --- a/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARPerspectiveParamGenerator_O1.java +++ b/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARPerspectiveParamGenerator_O1.java @@ -28,7 +28,7 @@ import jp.nyatla.nyartoolkit.NyARException; /** - * NyARPerspectiveParamGeneratorを最適化したクラスです。 + * このクラスは、{@link NyARPerspectiveParamGenerator_Reference}を高速化したクラスです。 */ public class NyARPerspectiveParamGenerator_O1 extends NyARPerspectiveParamGenerator { @@ -45,7 +45,9 @@ public class NyARPerspectiveParamGenerator_O1 extends NyARPerspectiveParamGenera return; } - + /** + * この関数は、遠近法のパラメータを計算して、返却します。 + */ public final boolean getParam(int i_dest_w,int i_dest_h,double x1,double y1,double x2,double y2,double x3,double y3,double x4,double y4,double[] o_param)throws NyARException { double ltx=this._local_x; diff --git a/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARPerspectiveParamGenerator_Reference.java b/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARPerspectiveParamGenerator_Reference.java index 6943028..87cc812 100644 --- a/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARPerspectiveParamGenerator_Reference.java +++ b/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARPerspectiveParamGenerator_Reference.java @@ -28,9 +28,9 @@ import jp.nyatla.nyartoolkit.NyARException; import jp.nyatla.nyartoolkit.core.types.matrix.*; /** - * 遠近法を用いたPerspectiveパラメータを計算するクラスです。 - * 任意頂点四角系と矩形から、遠近法の変形パラメータを計算します。 - * このクラスはリファレンス実装のため、パフォーマンスが良くありません。NyARPerspectiveParamGenerator_O1を使ってください。 + * このクラスは、遠近法を用いてPerspectiveパラメータを計算します。 + * 遠近法を可読性を重視して実装している為、若干低速です。 + * 高速化をした{@link NyARPerspectiveParamGenerator_O1}関数を使用してください。 */ public class NyARPerspectiveParamGenerator_Reference extends NyARPerspectiveParamGenerator { @@ -47,7 +47,9 @@ public class NyARPerspectiveParamGenerator_Reference extends NyARPerspectivePara return; } - + /** + * この関数は、遠近法のパラメータを計算して、返却します。 + */ public final boolean getParam(int i_dest_w,int i_dest_h,double x1,double y1,double x2,double y2,double x3,double y3,double x4,double y4,double[] o_param)throws NyARException { double ltx=this._local_x; diff --git a/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARSystemOfLinearEquationsProcessor.java b/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARSystemOfLinearEquationsProcessor.java index a4d840d..3a669a9 100644 --- a/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARSystemOfLinearEquationsProcessor.java +++ b/lib/src/jp/nyatla/nyartoolkit/core/utils/NyARSystemOfLinearEquationsProcessor.java @@ -25,8 +25,7 @@ package jp.nyatla.nyartoolkit.core.utils; /** - * 連立方程式を解くためのプロセッサクラスです。 - * + * このクラスは、連立方程式を解く関数を実装します。 */ public class NyARSystemOfLinearEquationsProcessor { @@ -54,12 +53,31 @@ public class NyARSystemOfLinearEquationsProcessor return true; } /** - * [i_left_src]=[i_right_src]の式にガウスの消去法を実行して、[x][x]の要素が1になるように基本変形します。 - * i_mとi_nが等しくない時は、最終行までの[x][x]要素までを1になるように変形します。 + * この関数は、方程式の係数配列にガウスの消去法を実行します。 + * [i_left_src]=[i_right_src]の式にガウスの消去法を実行して、i_leftの要素を1になるように基本変形します。 + * i_mとi_nが等しくない場合は、最終行の要素が1になるまで基本変形を実行して、終了します。 + *

+ * 方程式の係数は、次のように入力します。 + * 

+	 * 
+	 * 
+	 * 
+	 * 
+	 * 
i_left[0][0]*X+i_left[0][1]*Y+i_left[0][2]*Z=i_right[0]
i_left[1][0]*X+i_left[1][1]*Y+i_left[1][2]*Z=i_right[1]
i_left[2][0]*X+i_left[2][1]*Y+i_left[2][2]*Z=i_right[2]

+	 *
+ * 関数を実行すると、配列は次のようになります。 + * 
+	 * 
+	 * 
+	 * 
+	 * 
+	 * 
100=A
010=B
001=C

+	 *
+ *

* @param i_left * 連立方程式の左辺値を指定します。[i_m][i_n]の配列を指定してください。 * @param i_right - * 連立方程式の右辺値を指定します。[i_m][i_n]の配列を指定してください。 + * 連立方程式の右辺値を指定します。[i_m]の配列を指定してください。 * @param i_n * 連立方程式の係数の数を指定します。 * @param i_m @@ -131,8 +149,15 @@ public class NyARSystemOfLinearEquationsProcessor return true; } /** - * i_leftとi_rightの連立方程式を解いて、i_left,i_right内容を更新します。 + * この関数は、i_leftとi_rightで表現された連立方程式を解いて、i_left,i_right内容を更新します。 * i_right[n]の内容が、i_left[x][n]番目の係数の解になります。 + * 配列の表現については、{@link #doGaussianElimination}を参照してください。 + * @param i_left + * 連立方程式の左辺値を指定します。[i_m][i_n]の配列を指定してください。 + * @param i_right + * 連立方程式の右辺値を指定します。[i_m]の配列を指定してください。 + * @param i_number_of_system + * 方程式の数を指定します。 * @return * 方程式が解ければtrueを返します。 */ diff --git a/lib/src/jp/nyatla/nyartoolkit/nyidmarker/NyIdMarkerParam.java b/lib/src/jp/nyatla/nyartoolkit/nyidmarker/NyIdMarkerParam.java index 8fd48d8..023cd4e 100644 --- a/lib/src/jp/nyatla/nyartoolkit/nyidmarker/NyIdMarkerParam.java +++ b/lib/src/jp/nyatla/nyartoolkit/nyidmarker/NyIdMarkerParam.java @@ -25,19 +25,17 @@ package jp.nyatla.nyartoolkit.nyidmarker; /** - * [[Strage class]] - * マーカを抽出した時のパラメータを格納するクラスです。 - * + * このクラスは、NyIdマーカを抽出した時の画像処理パラメータを格納します。 + * {@link NyIdMarkerPickup#pickFromRaster}関数の返却値を受け取るために使います。 */ public class NyIdMarkerParam { /** - * マーカの方位値です。 + * ARToolKit準拠のマーカの方位値です。 */ public int direction; /** - * マーカ周辺のパターン閾値です。 + * マーカから求められたラべリング用閾値です。 */ public int threshold; - } diff --git a/lib/src/jp/nyatla/nyartoolkit/nyidmarker/NyIdMarkerPattern.java b/lib/src/jp/nyatla/nyartoolkit/nyidmarker/NyIdMarkerPattern.java index 3316a8f..6218426 100644 --- a/lib/src/jp/nyatla/nyartoolkit/nyidmarker/NyIdMarkerPattern.java +++ b/lib/src/jp/nyatla/nyartoolkit/nyidmarker/NyIdMarkerPattern.java @@ -23,10 +23,11 @@ * */ package jp.nyatla.nyartoolkit.nyidmarker; + /** - * [[Strage class]] - * IDマーカパターン値を格納するクラスです。 - * クラスは、未整形のマーカデータを格納しています。 + * このクラスは、Idマーカのデータ部の値を格納します。 + * Idマーカのデータ仕様については、以下のURLを参照してください。 + * http://sourceforge.jp/projects/nyartoolkit/docs/standards_document0001/ja/2/standards_document0001.pdf * */ public class NyIdMarkerPattern @@ -48,7 +49,7 @@ public class NyIdMarkerPattern */ public int check; /** - * データパケットの値 + * データパケットの配列。有効長はモデルによって異なります。 */ public final int[] data=new int[32]; } \ No newline at end of file diff --git a/lib/src/jp/nyatla/nyartoolkit/nyidmarker/NyIdMarkerPickup.java b/lib/src/jp/nyatla/nyartoolkit/nyidmarker/NyIdMarkerPickup.java index aec8562..b0e9fed 100644 --- a/lib/src/jp/nyatla/nyartoolkit/nyidmarker/NyIdMarkerPickup.java +++ b/lib/src/jp/nyatla/nyartoolkit/nyidmarker/NyIdMarkerPickup.java @@ -31,13 +31,111 @@ import jp.nyatla.nyartoolkit.core.types.*; import jp.nyatla.nyartoolkit.core.utils.*; +/** + * このクラスは、ラスタ画像に定義したの任意矩形から、NyIdパターンのデータを読み取ります。 + * 読み取り結果は、{@link NyARIdMarkerData}クラスのオブジェクト出力します。 + * + */ +public class NyIdMarkerPickup +{ + private PerspectivePixelReader _perspective_reader; + private final PerspectivePixelReader.TThreshold __pickFromRaster_th=new PerspectivePixelReader.TThreshold(); + private final MarkerPattEncoder __pickFromRaster_encoder=new MarkerPattEncoder(); + + /** + * コンストラクタです。インスタンスを生成します。 + */ + public NyIdMarkerPickup() + { + this._perspective_reader=new PerspectivePixelReader(); + return; + } + /** + * この関数は、ラスタからNyIdマーカの情報を読み出します。 + * @param image + * NyIdマーカが撮影されている（見込みのある）ラスタ + * @param i_vertex + * マーカの頂点位置を示す配列。4要素である事。 + * @param o_data + * 抽出したパターンデータを格納するオブジェクト。 + * @param o_param + * 抽出したパターンパラメータを格納するオブジェクト。 + * @return + * 抽出に成功するとtrue.失敗するとfalseです。 + * @throws NyARException + */ + public final boolean pickFromRaster(INyARRgbRaster image, NyARDoublePoint2d[] i_vertex,NyIdMarkerPattern o_data,NyIdMarkerParam o_param)throws NyARException + { + //遠近法のパラメータを計算 + if(!this._perspective_reader.setSourceSquare(i_vertex)){ + return false; + } + return this._pickFromRaster(image,o_data,o_param); + } + /** + * この関数は、ラスタからNyIdマーカの情報を読み出します。 + * @param image + * NyIdマーカが撮影されている（見込みのある）ラスタ + * @param i_vertex + * マーカの頂点位置を示す配列。4要素である事。 + * @param o_data + * 抽出したパターンデータを格納するオブジェクト。 + * @param o_param + * 抽出したパターンパラメータを格納するオブジェクト。 + * @return + * 抽出に成功するとtrue.失敗するとfalseです。 + * @throws NyARException + */ + public final boolean pickFromRaster(INyARRgbRaster image, NyARIntPoint2d[] i_vertex,NyIdMarkerPattern o_data,NyIdMarkerParam o_param)throws NyARException + { + if(!this._perspective_reader.setSourceSquare(i_vertex)){ + return false; + } + return this._pickFromRaster(image,o_data,o_param); + } + + /** + * i_imageから、idマーカを読みだします。 + * o_dataにはマーカデータ、o_paramにはマーカのパラメータを返却します。 + * @param image + * @param i_vertex + * @param o_data + * @param o_param + * @return + * @throws NyARException + */ + private final boolean _pickFromRaster(INyARRgbRaster image, NyIdMarkerPattern o_data,NyIdMarkerParam o_param)throws NyARException + { + INyARRgbPixelReader reader=image.getRgbPixelReader(); + NyARIntSize raster_size=image.getSize(); + + final PerspectivePixelReader.TThreshold th=this.__pickFromRaster_th; + final MarkerPattEncoder encoder=this.__pickFromRaster_encoder; + //マーカパラメータを取得 + this._perspective_reader.detectThresholdValue(reader,raster_size,th); + + if(!this._perspective_reader.readDataBits(reader,raster_size,th, encoder)){ + return false; + } + final int d=encoder.encode(o_data); + if(d<0){ + return false; + } + o_param.direction=d; + o_param.threshold=th.th; + + return true; + } +} /** - * NyARColorPatt_NyIdMarkerがラスタからPerspective変換して読みだすためのクラス + * {@link NyARColorPatt_NyIdMarker}がラスタからPerspective変換して読みだすためのクラス + * 画像処理全般を担当します。 + * ユーザがこのクラスを使うことはありません。 * */ final class PerspectivePixelReader @@ -46,22 +144,40 @@ final class PerspectivePixelReader private NyARPerspectiveParamGenerator _param_gen=new NyARPerspectiveParamGenerator_O1(1,1); private double[] _cparam=new double[8]; - + /** + * コンストラクタです。 + */ public PerspectivePixelReader() { return; } - + /** + * この関数は、マーカ四角形をインスタンスにセットします。 + * @param i_vertex + * セットする四角形頂点座標。4要素である必要があります。 + * @return + * 成功するとtrueです。 + * @throws NyARException + */ public boolean setSourceSquare(NyARIntPoint2d[] i_vertex)throws NyARException { return this._param_gen.getParam(READ_RESOLUTION,READ_RESOLUTION,i_vertex, this._cparam); } + /** + * この関数は、マーカ四角形をインスタンスにセットします。 + * @param i_vertex + * セットする四角形頂点座標。4要素である必要があります。 + * @return + * 成功するとtrueです。 + * @throws NyARException + */ public boolean setSourceSquare(NyARDoublePoint2d[] i_vertex)throws NyARException { return this._param_gen.getParam(READ_RESOLUTION,READ_RESOLUTION,i_vertex, this._cparam); } + /** - * 矩形からピクセルを切り出します + * ラスタから射影変換したピクセルを得ます。 * @param i_lt_x * @param i_lt_y * @param i_step_x @@ -69,7 +185,7 @@ final class PerspectivePixelReader * @param i_width * @param i_height * @param i_out_st - * o_pixelへの格納場所の先頭インデクス + * 格納バッファo_pixelの先頭のインデクス。 * @param o_pixel * @throws NyARException */ @@ -120,6 +236,7 @@ final class PerspectivePixelReader return true; } /** + * パターン分析関数。 * i_freqにあるゼロクロス点の周期が、等間隔か調べます。 * 次段半周期が、前段の80%より大きく、120%未満であるものを、等間隔周期であるとみなします。 * @param i_freq @@ -140,6 +257,7 @@ final class PerspectivePixelReader return true; } /** + * パターン分析関数。 * i_freq_count_tableとi_freq_tableの内容を調査し、最も大きな周波数成分を返します。 * @param i_freq_count_table * @param i_freq_table @@ -191,18 +309,20 @@ final class PerspectivePixelReader private final int[] _freq_table=new int[(MAX_FREQ*2-1)*MAX_FREQ*2/2]; /** - * i_y1行目とi_y2行目を平均して、タイミングパターンの周波数を得ます。 - * LHLを1周期として、たとえばLHLHLの場合は2を返します。LHLHやHLHL等の始端と終端のレベルが異なるパターンを + * この関数は、マーカ画像のi_y1行目とi_y2行目を平均して、タイミングパターンの周波数を得ます。 + * L=暗点、H=明点、LHL=1周期として、たとえばLHLHLの場合は2を返します。LHLHやHLHL等の始端と終端のレベルが異なるパターンを * 検出した場合、関数は失敗します。 - * * @param i_y1 - * @param i_y2 + * ライン1のインデクス * @param i_th_h + * 明点の敷居値 * @param i_th_l + * 暗点の敷居値 * @param o_edge_index - * 検出したエッジ位置(H->L,L->H)のインデクスを受け取る配列です。 - * [FRQ_POINTS]以上の配列を指定してください。 + * 検出したエッジ位置(H->L,L->H)のインデクスを受け取る配列。 + * [FRQ_POINTS]以上の配列を指定すること。 * @return + * 周波数の値。失敗すると-1 * @throws NyARException */ public int getRowFrequency(INyARRgbPixelReader i_reader,NyARIntSize i_raster_size,int i_y1,int i_th_h,int i_th_l,int[] o_edge_index)throws NyARException @@ -276,11 +396,26 @@ final class PerspectivePixelReader } return getMaxFreq(freq_count_table,freq_table,o_edge_index); } - + /** + * この関数は、マーカ画像のi_x1列目とi_x2列目を平均して、タイミングパターンの周波数を得ます。 + * L=暗点、H=明点、LHL=1周期として、たとえばLHLHLの場合は2を返します。LHLHやHLHL等の始端と終端のレベルが異なるパターンを + * 検出した場合、関数は失敗します。 + * @param i_x1 + * ライン1のインデクス + * @param i_th_h + * 明点の敷居値 + * @param i_th_l + * 暗点の敷居値 + * @param o_edge_index + * 検出したエッジ位置(H->L,L->H)のインデクスを受け取る配列。 + * [FRQ_POINTS]以上の配列を指定すること。 + * @return + * 周波数の値。失敗すると-1 + * @throws NyARException + */ public int getColFrequency(INyARRgbPixelReader i_reader,NyARIntSize i_raster_size,int i_x1,int i_th_h,int i_th_l,int[] o_edge_index)throws NyARException { final double[] cpara=this._cparam; -// final INyARRgbPixelReader reader=this._raster.getRgbPixelReader(); final int[] ref_x=this._ref_x; final int[] ref_y=this._ref_y; final int[] pixcel_temp=this._pixcel_temp; @@ -400,7 +535,9 @@ final class PerspectivePixelReader private static final int THRESHOLD_SAMPLE=THRESHOLD_PIXEL*THRESHOLD_PIXEL; private static final int THRESHOLD_SAMPLE_LT=THRESHOLD_EDGE; private static final int THRESHOLD_SAMPLE_RB=100-THRESHOLD_WIDTH-THRESHOLD_EDGE; - + /** + * 敷居値の保持型 + */ public static class TThreshold{ public int th_h; public int th_l; @@ -410,8 +547,11 @@ final class PerspectivePixelReader public int rb_x; public int rb_y; } - - class THighAndLow{ + /** + * H/Lの保持型 + */ + class THighAndLow + { public int h; public int l; } @@ -480,11 +620,13 @@ final class PerspectivePixelReader private NyARIntPoint2d __detectThresholdValue_tpt=new NyARIntPoint2d(); private int[] _th_pixels=new int[THRESHOLD_SAMPLE*4]; /** - * 指定した場所のピクセル値を調査して、閾値を計算して返します。 + * この関数はマーカパターンから、敷居値を決定します。 * @param i_reader - * @param i_x - * @param i_y - * @return + * ラスタリーダオブジェクト + * @param i_raster_size + * ラスのタのサイズ + * @param o_threshold + * 敷居値を受け取るオブジェクト * @throws NyARException */ public void detectThresholdValue(INyARRgbPixelReader i_reader,NyARIntSize i_raster_size,TThreshold o_threshold)throws NyARException @@ -650,7 +792,20 @@ final class PerspectivePixelReader } private double[] __readDataBits_index_bit_x=new double[MAX_DATA_BITS*2]; private double[] __readDataBits_index_bit_y=new double[MAX_DATA_BITS*2]; - + /** + * この関数は、マーカパターンからデータを読み取ります。 + * @param i_reader + * ラスタリーダ + * @param i_raster_size + * ラスタのサイズ + * @param i_th + * 敷居値情報 + * @param o_bitbuffer + * データビットの出力先 + * @return + * 成功するとtrue + * @throws NyARException + */ public boolean readDataBits(INyARRgbPixelReader i_reader,NyARIntSize i_raster_size,PerspectivePixelReader.TThreshold i_th,MarkerPattEncoder o_bitbuffer)throws NyARException { final int raster_width=i_raster_size.w; @@ -766,15 +921,10 @@ final class PerspectivePixelReader } return true; } - public boolean setSquare(NyARIntPoint2d[] i_vertex) throws NyARException - { - if (!this._param_gen.getParam(READ_RESOLUTION,READ_RESOLUTION,i_vertex,this._cparam)) { - return false; - } - return true; - } + } + class MarkerPattDecoder { public void decode(int model,int domain,int mask) @@ -783,8 +933,9 @@ class MarkerPattDecoder } } /** - * マーカパターンのエンコーダです。 - * + * このクラスは、マーカパターンのエンコーダです。{@link PerspectivePixelReader}から使います。 + * ピクセルセットから、マーカーデータへエンコードする処理を定義します。 + * 暫定として、5x5と、7x7のマーカについて定義します。 */ class MarkerPattEncoder { @@ -816,6 +967,11 @@ class MarkerPattEncoder private int[] _bits=new int[16]; private int[] _work=new int[16]; private int _model; + /** + * この関数は、 + * @param i_index_no + * @param i_value + */ public void setBitByBitIndex(int i_index_no,int i_value) { assert i_value==0 || i_value==1; @@ -829,7 +985,13 @@ class MarkerPattEncoder } return; } - + /** + * この関数は、ビットイメージ{@link #_bits}のnビット目に、値をセットします。 + * @param i_bit_no + * ビットイメージのインデクス + * @param i_value + * セットする値。 + */ public void setBit(int i_bit_no,int i_value) { assert i_value==0 || i_value==1; @@ -842,6 +1004,13 @@ class MarkerPattEncoder } return; } + /** + * この関数は、ビットイメージ{@link #_bits}のnビット目から、値を得ます。 + * @param i_bit_no + * ビットイメージのインデクス + * @return + * ビット値 + */ public int getBit(int i_bit_no) { if(i_bit_no==0){ @@ -852,6 +1021,11 @@ class MarkerPattEncoder return (this._bits[bidx]>>(sidx))&(0x01); } } + /** + * この関数は、現在セットされているモデル番号を返します。 + * @return + * 現在のモデル番号 + */ public int getModel() { return this._model; @@ -875,7 +1049,15 @@ class MarkerPattEncoder } return -1; } - public static int getCheckValue(int i_model,int[] i_data) + /** + * この関数は、チェックドットの値を返します。 + * @param i_model + * モデル番号 + * @param i_data + * データ配列 + * @return + */ + private static int getCheckValue(int i_model,int[] i_data) { int v; switch(i_model){ @@ -894,6 +1076,13 @@ class MarkerPattEncoder } return -1; } + /** + * この関数は、インスタンスの状態を、指定モデル向けにセットします。 + * @param i_model + * モデル番号 + * @return + * 成功するとtrueを返します。 + */ public boolean initEncoder(int i_model) { if(i_model>3 || i_model<2){ @@ -946,10 +1135,10 @@ class MarkerPattEncoder /** * 格納しているマーカパターンをエンコードして、マーカデータを返します。 * @param o_out + * マーカデータを受け取るオブジェクト。 * @return * 成功すればマーカの方位を返却します。失敗すると-1を返します。 */ - public int encode(NyIdMarkerPattern o_out) { final int d=getDirection(); @@ -1013,6 +1202,18 @@ class MarkerPattEncoder // } return; } + /** + * この関数は、ビットパックi_packを指定ビットだけ左シフトします。 + * 現在未使用です。 + * @param i_pack + * 操作する配列 + * @param i_start + * シフトの開始アドレス + * @param i_length + * シフトする配列の長さ + * @param i_ls + * シフト量 + */ public void shiftLeft(int[] i_pack,int i_start,int i_length,int i_ls) { int[] work=this._work; @@ -1030,86 +1231,3 @@ class MarkerPattEncoder return; } } -/** - * ラスタ画像の任意矩形から、NyARIdMarkerDataを抽出します。 - * - */ -public class NyIdMarkerPickup -{ - private PerspectivePixelReader _perspective_reader; - private final PerspectivePixelReader.TThreshold __pickFromRaster_th=new PerspectivePixelReader.TThreshold(); - private final MarkerPattEncoder __pickFromRaster_encoder=new MarkerPattEncoder(); - - - public NyIdMarkerPickup() - { - this._perspective_reader=new PerspectivePixelReader(); - return; - } - /** - * imageの4頂点で囲まれた矩形からidマーカを読みだします。 - * @param image - * @param i_vertex - * @param o_data - * @param o_param - * @return - * @throws NyARException - */ - public final boolean pickFromRaster(INyARRgbRaster image, NyARDoublePoint2d[] i_vertex,NyIdMarkerPattern o_data,NyIdMarkerParam o_param)throws NyARException - { - //遠近法のパラメータを計算 - if(!this._perspective_reader.setSourceSquare(i_vertex)){ - return false; - } - return this._pickFromRaster(image,o_data,o_param); - } - /** - * imageの4頂点で囲まれた矩形からidマーカを読みだします。 - * @param image - * @param i_vertex - * @param o_data - * @param o_param - * @return - * @throws NyARException - */ - public final boolean pickFromRaster(INyARRgbRaster image, NyARIntPoint2d[] i_vertex,NyIdMarkerPattern o_data,NyIdMarkerParam o_param)throws NyARException - { - if(!this._perspective_reader.setSourceSquare(i_vertex)){ - return false; - } - return this._pickFromRaster(image,o_data,o_param); - } - - /** - * i_imageから、idマーカを読みだします。 - * o_dataにはマーカデータ、o_paramにはマーカのパラメータを返却します。 - * @param image - * @param i_vertex - * @param o_data - * @param o_param - * @return - * @throws NyARException - */ - private final boolean _pickFromRaster(INyARRgbRaster image, NyIdMarkerPattern o_data,NyIdMarkerParam o_param)throws NyARException - { - INyARRgbPixelReader reader=image.getRgbPixelReader(); - NyARIntSize raster_size=image.getSize(); - - final PerspectivePixelReader.TThreshold th=this.__pickFromRaster_th; - final MarkerPattEncoder encoder=this.__pickFromRaster_encoder; - //マーカパラメータを取得 - this._perspective_reader.detectThresholdValue(reader,raster_size,th); - - if(!this._perspective_reader.readDataBits(reader,raster_size,th, encoder)){ - return false; - } - final int d=encoder.encode(o_data); - if(d<0){ - return false; - } - o_param.direction=d; - o_param.threshold=th.th; - - return true; - } -} diff --git a/lib/src/jp/nyatla/nyartoolkit/nyidmarker/data/INyIdMarkerData.java b/lib/src/jp/nyatla/nyartoolkit/nyidmarker/data/INyIdMarkerData.java index 1e6edd2..088ca3e 100644 --- a/lib/src/jp/nyatla/nyartoolkit/nyidmarker/data/INyIdMarkerData.java +++ b/lib/src/jp/nyatla/nyartoolkit/nyidmarker/data/INyIdMarkerData.java @@ -25,23 +25,22 @@ package jp.nyatla.nyartoolkit.nyidmarker.data; /** - * - * [[Strage class]] - * + * このインタフェイスは、エンコード済みマーカデータ格納クラスの共通関数を定義します。 */ public interface INyIdMarkerData { /** - * i_targetのマーカデータと自身のデータが等しいかを返します。 + * この関数は、i_targetのマーカデータとインスタンスのデータを比較します。 * @param i_target * 比較するマーカオブジェクト * @return - * 等しいかの真偽値 + * 内容が等しいかの真偽値。等しければtrue */ public boolean isEqual(INyIdMarkerData i_target); /** - * i_sourceからマーカデータをコピーします。 + * この関数は、i_sourceからインスタンスにマーカデータをコピーします。 * @param i_source + * コピー元のオブジェクト。 */ public void copyFrom(INyIdMarkerData i_source); } diff --git a/lib/src/jp/nyatla/nyartoolkit/nyidmarker/data/INyIdMarkerDataEncoder.java b/lib/src/jp/nyatla/nyartoolkit/nyidmarker/data/INyIdMarkerDataEncoder.java index 329ea1b..1c4da96 100644 --- a/lib/src/jp/nyatla/nyartoolkit/nyidmarker/data/INyIdMarkerDataEncoder.java +++ b/lib/src/jp/nyatla/nyartoolkit/nyidmarker/data/INyIdMarkerDataEncoder.java @@ -26,9 +26,28 @@ package jp.nyatla.nyartoolkit.nyidmarker.data; import jp.nyatla.nyartoolkit.nyidmarker.NyIdMarkerPattern; - +/** + * このインタフェイスは、マーカパターンデータのエンコーダに共通な関数を定義します。 + * NyIdのマーカデータを、利用可能な他形式のデータに変換します。 + */ public interface INyIdMarkerDataEncoder { + /** + * この関数は、マーカパターンデータを他形式のデータに変換します。 + * 実装クラスでは、{@link NyIdMarkerPattern}に格納されるデータを変換する処理を実装してください。 + * @param i_data + * 変換元のデータ + * @param o_dest + * 変換先のデータ + * @return + * 変換に成功するとtrueを返します。 + */ public boolean encode(NyIdMarkerPattern i_data,INyIdMarkerData o_dest); + /** + * この関数は、このエンコーダの出力形式のオブジェクトを生成して返します。 + * 実装クラスでは、そのクラスの{@link #encode}に入力できるオブジェクトを生成してください。 + * @return + * 新しいオブジェクト + */ public INyIdMarkerData createDataInstance(); } diff --git a/lib/src/jp/nyatla/nyartoolkit/nyidmarker/data/NyIdMarkerDataEncoder_RawBit.java b/lib/src/jp/nyatla/nyartoolkit/nyidmarker/data/NyIdMarkerDataEncoder_RawBit.java index 5f851b9..abb0385 100644 --- a/lib/src/jp/nyatla/nyartoolkit/nyidmarker/data/NyIdMarkerDataEncoder_RawBit.java +++ b/lib/src/jp/nyatla/nyartoolkit/nyidmarker/data/NyIdMarkerDataEncoder_RawBit.java @@ -25,12 +25,17 @@ package jp.nyatla.nyartoolkit.nyidmarker.data; import jp.nyatla.nyartoolkit.nyidmarker.*; - - +/** + * このクラスは、マーカパターンを{@link NyIdMarkerData_RawBit}型のデータに変換します。 + */ public class NyIdMarkerDataEncoder_RawBit implements INyIdMarkerDataEncoder { private final static int _DOMAIN_ID=0; private final static int[] _mod_data={7,31,127,511,2047,4095}; + /** + * この関数は、マーカパターンデータを{@link NyIdMarkerData_RawBit}型のデータに変換します。 + * o_destには、{@link NyIdMarkerData_RawBit}型のオブジェクトを指定してください。 + */ public boolean encode(NyIdMarkerPattern i_data,INyIdMarkerData o_dest) { final NyIdMarkerData_RawBit dest=(NyIdMarkerData_RawBit)o_dest; @@ -54,6 +59,9 @@ public class NyIdMarkerDataEncoder_RawBit implements INyIdMarkerDataEncoder dest.length=packet_length; return true; } + /** + * この関数は、{@link NyIdMarkerData_RawBit}型のオブジェクトを生成して返します。 + */ public INyIdMarkerData createDataInstance() { return new NyIdMarkerData_RawBit(); diff --git a/lib/src/jp/nyatla/nyartoolkit/nyidmarker/data/NyIdMarkerData_RawBit.java b/lib/src/jp/nyatla/nyartoolkit/nyidmarker/data/NyIdMarkerData_RawBit.java index 832b432..73c9a29 100644 --- a/lib/src/jp/nyatla/nyartoolkit/nyidmarker/data/NyIdMarkerData_RawBit.java +++ b/lib/src/jp/nyatla/nyartoolkit/nyidmarker/data/NyIdMarkerData_RawBit.java @@ -25,13 +25,19 @@ package jp.nyatla.nyartoolkit.nyidmarker.data; /** - * [[Strage class]] - * + * このクラスは、RawBitタイプのデータを格納します。 + * RawBitタイプのデータは、NyIdマーカのデータパケットをそのまま配列にするだけです。 */ public class NyIdMarkerData_RawBit implements INyIdMarkerData { + /** パケットデータを格納した配列です。0から{@link #length}-1番目までの要素が有効です。*/ public final int[] packet=new int[22]; + /** 有効なデータ長です。*/ public int length; + /** + * この関数は、i_targetのマーカデータとインスタンスのデータを比較します。 + * 引数には、{@link NyIdMarkerData_RawBit}型のオブジェクトを指定してください。 + */ public boolean isEqual(INyIdMarkerData i_target) { NyIdMarkerData_RawBit s=(NyIdMarkerData_RawBit)i_target; @@ -45,6 +51,10 @@ public class NyIdMarkerData_RawBit implements INyIdMarkerData } return true; } + /** + * この関数は、i_sourceからインスタンスにマーカデータをコピーします。 + * 引数には、{@link NyIdMarkerData_RawBit}型のオブジェクトを指定してください。 + */ public void copyFrom(INyIdMarkerData i_source) { final NyIdMarkerData_RawBit s=(NyIdMarkerData_RawBit)i_source; diff --git a/lib/src/jp/nyatla/nyartoolkit/utils/TransformedBitmapPickup.java b/lib/src/jp/nyatla/nyartoolkit/utils/TransformedBitmapPickup.java index feb8478..f1e3d81 100644 --- a/lib/src/jp/nyatla/nyartoolkit/utils/TransformedBitmapPickup.java +++ b/lib/src/jp/nyatla/nyartoolkit/utils/TransformedBitmapPickup.java @@ -9,24 +9,27 @@ import jp.nyatla.nyartoolkit.core.types.NyARBufferType; import jp.nyatla.nyartoolkit.core.types.NyARIntPoint2d; /** - * マーカの周辺領域からビットマップを取得する方法を提供します。 - * 比較的負荷が大きいので、連続してパターンを取得し続ける用途には向いていません。 - * + * このクラスは、姿勢変換行列を使用してマーカの周辺領域からパターンを取得する機能を持つラスタです。 + * 画像の画素フォーマットは、{@link NyARBufferType#INT1D_X8R8G8B8_32}形式のです。 + * このクラスは試験的であり、異なる解像度のパターンを取得することや、異なる画素フォーマットへ画像を出力する事ができません。 + * {@link NyARPerspectiveRasterReader}クラスの使用を検討してください。 */ class TransformedBitmapPickup extends NyARColorPatt_Perspective_O2 { private NyARIntPoint2d[] _work_points = NyARIntPoint2d.createArray(4); - private NyARPerspectiveProjectionMatrix _ref_perspective; - /** - * + * コンストラクタです。 + * 射影変換パラメータ、ラスタサイズ、サンプリング解像度からインスタンスを生成します。 + * @param i_ref_cparam + * 射影変換パラメータの参照値 * @param i_width - * 取得するビットマップの幅 + * ラスタの幅 * @param i_height - * 取得するビットマップの解像度 + * ラスタの高さ * @param i_resolution - * resolution of reading pixel per point. ---- 取得時の解像度。高解像度のときは1を指定してください。低解像度のときは2以上を指定します。 + * ピクセルあたりのサンプリング解像度。1なら出力1ピクセルにつき1ピクセル、2なら1ピクセルにつき4ピクセル(2x2)をサンプリングします。 + * 小さい画像では数値が大きいほど良い結果が得られますが、時間がかかります。 */ public TransformedBitmapPickup(NyARPerspectiveProjectionMatrix i_ref_cparam, int i_width, int i_height, int i_resolution) { @@ -36,12 +39,11 @@ class TransformedBitmapPickup extends NyARColorPatt_Perspective_O2 } /** - * This function retrieves bitmap from the area defined by RECT(i_l,i_t,i_r,i_b) above transform matrix i_base_mat. - * ---- - * この関数は、basementで示される平面のAで定義される領域から、ビットマップを読み出します。 + * この関数は、姿勢変換行列i_base_matで示される平面の矩形(i_l,i_t,i_r,i_b)から、ビットマップを読み出します。 * 例えば、8cmマーカでRECT(i_l,i_t,i_r,i_b)に-40,0,0,-40.0を指定すると、マーカの左下部分の画像を抽出します。 - * * マーカから離れた場所になるほど、また、マーカの鉛直方向から外れるほど誤差が大きくなります。 + * ---- + * This function gets bitmap from the area defined by RECT(i_l,i_t,i_r,i_b) above transform matrix i_base_mat. * @param i_src_imege * 詠み出し元の画像を指定します。 * @param i_l @@ -53,7 +55,9 @@ class TransformedBitmapPickup extends NyARColorPatt_Perspective_O2 * @param i_b * 基準点からの右下の相対座標（y）を指定します。 * @param i_base_mat - * @return 画像の取得の成否を返す。 + * 平面の姿勢を示す行列です。マーカ姿勢を指定することで、マーカの表面を指定することができます。 + * @return + * 画像の取得に成功するとtrueを返します。 */ public boolean pickupImage2d(INyARRgbRaster i_src_imege, double i_l, double i_t, double i_r, double i_b, NyARTransMatResult i_base_mat) throws NyARException { -- 2.11.0