パタン操作
[FPM(特徴点応用マッチング)]


関数
FHANDLE FVALGAPI	fnFIE_fpm_alloc (FHANDLE himage, FHANDLE hmask, DPNT_T offset, enum f_fpm_mode matching_mode, enum f_fpm_featedge method, const F_FPM_FEATURE pfeature_param, INT perr_code)
	FPM オブジェクト生成
FHANDLE FVALGAPI	fnFIE_fpm_import_alloc (F_DEDGE ptn_edges, INT num_ptn_edges, FHANDLE himage_ptn, DPNT_T offset, enum f_fpm_mode matching_mode, INT perr_code)
	点情報から FPM オブジェクト生成
FHANDLE FVALGAPI	fnFIE_fpm_alloc_shape_ellipse (DOUBLE a, DOUBLE b, BOOL is_white, enum f_fpm_mode matching_mode, INT *perr_code)
	形状指定 FPM オブジェクト生成(楕円or円)
FHANDLE FVALGAPI	fnFIE_fpm_alloc_shape_rectangle (DOUBLE width, DOUBLE height, BOOL is_white, enum f_fpm_mode matching_mode, INT *perr_code)
	形状指定 FPM オブジェクト生成(矩形)
FHANDLE FVALGAPI	fnFIE_fpm_alloc_shape_cross (DOUBLE a, DOUBLE b, BOOL is_close, BOOL is_white, enum f_fpm_mode matching_mode, INT *perr_code)
	形状指定 FPM オブジェクト生成(十字)
INT FVALGAPI	fnFIE_fpm_set_pattern_mask (FHANDLE hfpm, FHANDLE hmask)
	マスクの設定
INT FVALGAPI	fnFIE_fpm_clear_pattern_mask (FHANDLE hfpm)
	マスク情報のクリア
INT FVALGAPI	fnFIE_fpm_set_pattern_offset (FHANDLE hfpm, DPNT_T offset)
	マッチング回答オフセット値の設定
INT FVALGAPI	fnFIE_fpm_set_pattern_offset_gravity (FHANDLE hfpm)
	マッチング回答オフセット値の自動設定（特徴量重心）
INT FVALGAPI	fnFIE_fpm_get_pattern_mask (FHANDLE hfpm, FHANDLE *phmask)
	マスク情報の取得
INT FVALGAPI	fnFIE_fpm_get_pattern_offset (FHANDLE hfpm, DPNT_T *poffset)
	マスターパタンマッチング回答オフセット値の取得
INT FVALGAPI	fnFIE_fpm_get_pattern_size (FHANDLE hfpm, INT ptn_width, INT ptn_height)
	マスターパタン画像サイズ取得
INT FVALGAPI	fnFIE_fpm_get_pattern_feature_param (FHANDLE hfpm, enum f_fpm_featedge pmethod, F_FPM_FEATURE pfeature_param)
	特徴量パラメータ取得
INT FVALGAPI	fnFIE_fpm_get_matching_mode (FHANDLE hfpm, enum f_fpm_mode *pmatching_mode)
	FPMオブジェクト生成時のマッチングモードの取得
INT FVALGAPI	fnFIE_fpm_get_pattern_image (FHANDLE hfpm, FHANDLE *phimage)
	マスターパタン画像の取得
INT FVALGAPI	fnFIE_fpm_get_pattern_feature_num (FHANDLE hfpm, INT *pfeature_num)
	マスターパタン特徴量数の取得
INT FVALGAPI	fnFIE_fpm_get_pattern_feature_edges (FHANDLE hfpm, F_DEDGE *pedges)
	マスターパタン特徴量を取得（勾配方向付きエッジ型）
INT FVALGAPI	fnFIE_fpm_get_matching_feature_num (FHANDLE hfpm, INT *pmatching_feature_num)
	サーチ対象画像の特徴量数の取得
INT FVALGAPI	fnFIE_fpm_get_matching_feature_edges (FHANDLE hfpm, F_DEDGE *pmatching_edges)
	マッチングで使用した特徴量を取得（勾配方向付きエッジ型）
INT FVALGAPI	fnFIE_fpm_clear_result (FHANDLE hfpm)
	FPMオブジェクト結果データのクリア
INT FVALGAPI	fnFIE_fpm_get_relative_edge (FHANDLE hfpm, INT no, INT err_wide, F_DEDGE edges, INT edge_num)
	指定ポーズ下の対応点取得
INT FVALGAPI	fnFIE_fpm_set_pattern_essential (FHANDLE hfpm, FHANDLE hesse)
	不可欠領域の設定
INT FVALGAPI	fnFIE_fpm_get_pattern_essential (FHANDLE hfpm, FHANDLE *phesse)
	不可欠領域情報の取得
INT FVALGAPI	fnFIE_fpm_set_pattern_edgeless_mask (FHANDLE hfpm, FHANDLE hedgeless)
	エッジ減点領域の設定
INT FVALGAPI	fnFIE_fpm_get_pattern_edgeless_mask (FHANDLE hfpm, FHANDLE *phedgeless)
	エッジ減点領域情報の取得
INT FVALGAPI	fnFIE_fpm_set_refine_mode (FHANDLE hfpm, INT refine_mode)
	高精度ポーズ推定モードの設定
INT FVALGAPI	fnFIE_fpm_get_refine_mode (FHANDLE hfpm, INT *refine_mode)
	高精度ポーズ推定モードの取得
INT FVALGAPI	fnFIE_fpm_set_pitch (FHANDLE hfpm, INT pitch_x, INT pitch_y)
	最小検出間隔の設定
INT FVALGAPI	fnFIE_fpm_get_pitch (FHANDLE hfpm, INT pitch_x, INT pitch_y)
	最小検出間隔の取得
INT FVALGAPI	fnFIE_fpm_set_refine_pose_boundary_mode (FHANDLE hfpm, enum f_fpm_pose_boundary_mode boundary_mode)
	高精度ポーズ推定における姿勢の範囲境界モードの設定
INT FVALGAPI	fnFIE_fpm_get_refine_pose_boundary_mode (FHANDLE hfpm, enum f_fpm_pose_boundary_mode *boundary_mode)
	高精度ポーズ推定における姿勢の範囲境界モードの取得

関数

FHANDLE FVALGAPI fnFIE_fpm_alloc	(	FHANDLE	himage,
		FHANDLE	hmask,
		DPNT_T	offset,
		enum f_fpm_mode	matching_mode,
		enum f_fpm_featedge	method,
		const F_FPM_FEATURE *	pfeature_param,
		INT *	perr_code
	)

FPM オブジェクト生成

マスターパタンとして使用する画像オブジェクトから、FPMオブジェクト(F_OBJID_FPM)を生成します。

引数:

`[in]`	himage	FPMで使用するための特徴量を取得する対象となる画像オブジェクト(画像タイプ：uc8 のみ対応) チャネル数は 1 でなければいけません。
`[in]`	hmask	マスターパタン特徴量取得時のマスク指定用画像オブジェクト(画像タイプ：uc8 のみ対応) チャネル数は 1 でなければいけません。 NULLを指定するとマスクなしのパターンになります。
`[in]`	offset	マッチング回答オフセット値(マスターパタン画像の左上位置からの相対値)
`[in]`	matching_mode	FPMを行う際のマッチングモード F_FPM_NORMAL_MODE 通常モード F_FPM_SPEED_MODE 高速モード
`[in]`	method	特徴量抽出手法 F_FPM_SOBEL_EDGE ソーベルによる特徴量抽出 F_FPM_CORR_EDGE 相関エッジによる特徴量抽出 F_FPM_SOBEL_MAX_EDGE 強度上限付ソーベルによる特徴量抽出 F_FPM_CORR_MAX_EDGE 強度上限付相関エッジによる特徴量抽出 F_FPM_GROOVE_EDGE 細線エッジによる特徴量抽出
`[in]`	pfeature_param	FPMオブジェクトを生成する際に使用する特徴量計測パラメータ
`[out]`	perr_code	正常終了、またはエラーコードが入力されます。エラーコードを受け取る必要の無い場合は、NULLを指定します。 F_ERR_NONE 正常終了 F_ERR_INVALID_IMAGE 引数画像オブジェクトが異常 F_ERR_INVALID_PARAM 引数異常 F_ERR_NOMEMORY メモリ不足 F_ERR_FPM_NOFEATURE 特徴量が見つかりません。 F_ERR_NO_LICENCE ライセンスエラー、または未初期化エラー

戻り値:: 正常終了した場合は、生成したFPMオブジェクトのハンドルを返します。異常終了により生成できなかったときはNULLを返します。

注意:

画像オブジェクトからマスターパタンの特徴量を取得する際には、指定した画像に対してボーダー拡張処理を行っています。
FPMオブジェクトが不要になったら、必ず fnFIE_free_object() で解放してください。

FHANDLE FVALGAPI fnFIE_fpm_import_alloc	(	F_DEDGE *	ptn_edges,
		INT	num_ptn_edges,
		FHANDLE	himage_ptn,
		DPNT_T	offset,
		enum f_fpm_mode	matching_mode,
		INT *	perr_code
	)

点情報から FPM オブジェクト生成

マスターパタン画像のエッジ情報(F_DEDGE 型)をインポートして、FPMオブジェクト(F_OBJID_FPM)を生成します。自身で作成した処理によって計測したエッジ情報や、既知の幾何情報から生成した情報等を用いてFPMオブジェクトを生成することが可能です。

fig．画像オブジェクトを用いたFPMの処理(左)と、F_DEDGE型の情報を用いたFPMの処理(右)

引数:

`[in]`	ptn_edges	F_DEDGE 型エッジデータ
`[in]`	num_ptn_edges	ptn_edges に格納されているエッジデータ数(1≦ num_ptn_edges)
`[in]`	himage_ptn	ptn_edges を取得した画像（type:uc8,ch:1, マスターパタン画像がない、または FPMオブジェクトが保持する必要が無ければNULLを指定することも可能です）
`[in]`	offset	マッチング回答オフセット値(マスターパタン画像の左上位置からの相対値)
`[in]`	matching_mode	FPMを行う際のマッチングモード F_FPM_NORMAL_MODE 通常モード F_FPM_SPEED_MODE 高速モード
`[out]`	perr_code	正常終了、またはエラーコードが入力されます。エラーコードを受け取る必要の無い場合は、NULLを指定することも可能です。 F_ERR_NONE 正常終了 F_ERR_INVALID_IMAGE 画像オブジェクト異常 F_ERR_INVALID_PARAM 引数異常 F_ERR_NOMEMORY メモリ不足 F_ERR_NO_LICENCE ライセンスエラー、または未初期化エラー

戻り値:: 正常終了した場合は、生成したFPMオブジェクトのハンドルを返します。異常終了により生成できなかったときはNULLを返します。

注意:

入力情報 ptn_edges のメンバである強度 mag は使用しません。値が未知であっても値を計算する必要はありません。(未知の場合には 0で初期化しておいてください)
FPMオブジェクトが不要になったら、必ず fnFIE_free_object() で解放してください。
本ライブラリではエッジ計測パラメータは使用しません。本ライブラリを使用して作成したFPMオブジェクトに対して fnFIE_fpm_get_pattern_feature_param() 関数を実行してもパラメータを取得することができません。
本ライブラリは必ずしもマスターパタン画像を必要とするものではありません。マスターパタンの画像を指定せずに作成したFPMオブジェクトに対して fnFIE_fpm_get_pattern_image() 関数を実行してもマスターパタン画像を取得することができません。
ptn_edges の入力エッジ情報は、画像処理で取得したエッジを想定しています。そのため ptn_edges のＸＹの入力値として、四捨五入して負になるような値を入力した場合には、戻り値に F_ERR_INVALID_PARAM が返ります。(同様に、 himage_ptn にパタン画像を指定した場合には、パタン画像サイズよりも小さい値のエッジ情報を指定しなければなりません。)

FHANDLE FVALGAPI fnFIE_fpm_alloc_shape_ellipse	(	DOUBLE	a,
		DOUBLE	b,
		BOOL	is_white,
		enum f_fpm_mode	matching_mode,
		INT *	perr_code
	)

形状指定 FPM オブジェクト生成(楕円or円)

楕円(or円)の形状情報を指定して、FPMオブジェクト(F_OBJID_FPM)を生成します。

楕円は次の式で表されます。

$\frac {x^{2}}{a^{2}} + \frac{y^{2}}{b^{2}} = 1$

0 < b < a の時には、2a は長軸の長さ、2b は短軸の長さを表します。xy 平面上にグラフを書くと、下図のように横長の楕円となります。本式からは、a と b が等しければ、半径が a (= b)の円を表すこともわかります。

fig．楕円パタンと指定パラメータの関係

また、登録時の回答基準位置は、図の原点位置 $o$ (=図形の中心位置)に設定されます。

引数:

`[in]`	a	楕円の方程式パラメータ a (3.0<=a, 単位:画素)
`[in]`	b	楕円の方程式パラメータ b (3.0<=b, 単位:画素)、円を指定する場合には a と b の値を等しい値にします。
`[in]`	is_white	楕円パタンの色 TRUE 指定楕円は白(背景よりも明るい) FALSE 指定楕円は黒(背景よりも暗い)
`[in]`	matching_mode	FPMを行う際のマッチングモード F_FPM_NORMAL_MODE 通常モード F_FPM_SPEED_MODE 高速モード
`[out]`	perr_code	正常終了、またはエラーコードを格納します。エラーコードを受け取る必要の無い場合は、NULLを指定することも可能です。 F_ERR_NONE 正常終了 F_ERR_INVALID_PARAM 引数異常 F_ERR_NOMEMORY メモリ不足 F_ERR_BUFFER_OVERFLOW バッファ不足エラー F_ERR_NO_LICENCE ライセンスエラー、または未初期化エラー

戻り値:: 正常終了した場合は、生成したFPMオブジェクトのハンドルを返します。異常終了により生成できなかったときはNULLを返します。

注意:

FPMオブジェクトが不要になったら、必ず fnFIE_free_object() で解放してください。
本ライブラリではエッジ計測パラメータは使用しません。本ライブラリを使用して作成したFPMオブジェクトに対して fnFIE_fpm_get_pattern_feature_param() 関数を実行してもパラメータを取得することができません。
本ライブラリは必ずしもマスターパタンを使用しません。本ライブラリを使用して作成したFPMオブジェクトに対して fnFIE_fpm_get_pattern_image() 関数を実行してもマスターパタン画像を取得することができません。
内部で生成される楕円状の点情報 $\left(x_i,y_i\right)$ がもつエッジの勾配方向は、楕円接線の傾斜に対して垂直な方向とし、式 $q_i=\tan^{-1}{ \left(\frac{{\it a}^2y_i}{{\it b}^2x_i} \right)}$ によって得られます。(is_white の値によっては180度反転します)
ここでは説明の図と式に原点を中心とした楕円を用いていますが、実際には xyのシフト移動を行い、楕円が第１象限(0<x,0<y)に収まるような状態です。

FHANDLE FVALGAPI fnFIE_fpm_alloc_shape_rectangle	(	DOUBLE	width,
		DOUBLE	height,
		BOOL	is_white,
		enum f_fpm_mode	matching_mode,
		INT *	perr_code
	)

形状指定 FPM オブジェクト生成(矩形)

矩形の形状情報を指定して、FPMオブジェクト(F_OBJID_FPM)を生成します。

fig．矩形パタンと指定パラメータの関係

登録時の回答基準位置は、図の点 $P_c$ (=図形の中心位置)に設定されます。

引数:

`[in]`	width	矩形のX方向幅(3.0<=width, 単位:画素)
`[in]`	height	矩形のY方向高さ(3.0<=height, 単位:画素)
`[in]`	is_white	矩形パタンの色 TRUE 指定矩形は白(背景よりも明るい) FALSE 指定矩形は黒(背景よりも暗い)
`[in]`	matching_mode	FPMを行う際のマッチングモード F_FPM_NORMAL_MODE 通常モード F_FPM_SPEED_MODE 高速モード
`[out]`	perr_code	正常終了、またはエラーコードを格納します。エラーコードを受け取る必要の無い場合は、NULLを指定することも可能です。 F_ERR_NONE 正常終了 F_ERR_INVALID_PARAM 引数異常 F_ERR_NOMEMORY メモリ不足 F_ERR_BUFFER_OVERFLOW バッファ不足エラー F_ERR_NO_LICENCE ライセンスエラー、または未初期化エラー

戻り値:: 正常終了した場合は、生成したFPMオブジェクトのハンドルを返します。異常終了により生成できなかったときはNULLを返します。

注意:

FPMオブジェクトが不要になったら、必ず fnFIE_free_object() で解放してください。
本ライブラリではエッジ計測パラメータは使用しません。本ライブラリを使用して作成したFPMオブジェクトに対して fnFIE_fpm_get_pattern_feature_param() 関数を実行してもパラメータを取得することができません。
本ライブラリは必ずしもマスターパタンを使用しません。本ライブラリを使用して作成したFPMオブジェクトに対して fnFIE_fpm_get_pattern_image() 関数を実行してもマスターパタン画像を取得することができません。

FHANDLE FVALGAPI fnFIE_fpm_alloc_shape_cross	(	DOUBLE	a,
		DOUBLE	b,
		BOOL	is_close,
		BOOL	is_white,
		enum f_fpm_mode	matching_mode,
		INT *	perr_code
	)

形状指定 FPM オブジェクト生成(十字)

十字パタンの形状情報を指定して、FPMオブジェクト(F_OBJID_FPM)を生成します。

fig．十字パタンと指定パラメータの関係

登録時の回答基準位置は、図の点 $P_c$ (=図形の中心位置)に設定されます。

引数:

`[in]`	a	十字パタンのパラメータ a (3.0<=a, 単位:画素)
`[in]`	b	十字パタンのパラメータ b (1.0<=b, b<a,単位:画素)
`[in]`	is_close	十字パタン開閉状態 TRUE 指定十字マークは閉じている FALSE 指定十字マークは開いている(パラメータ b の位置のエッジが無い) *fig．is_close* に TRUE を指定(左)、もしくは FALSE を指定(右)した際の生成エッジ情報の違い**
`[in]`	is_white	十字パタンの色 TRUE 指定矩形は白(背景よりも明るい) FALSE 指定矩形は黒(背景よりも暗い)
`[in]`	matching_mode	FPMを行う際のマッチングモード F_FPM_NORMAL_MODE 通常モード F_FPM_SPEED_MODE 高速モード
`[out]`	perr_code	正常終了、またはエラーコードを格納します。エラーコードを受け取る必要の無い場合は、NULLを指定することも可能です。 F_ERR_NONE 正常終了 F_ERR_INVALID_PARAM 引数異常 F_ERR_NOMEMORY メモリ不足 F_ERR_BUFFER_OVERFLOW バッファ不足エラー F_ERR_NO_LICENCE ライセンスエラー、または未初期化エラー

戻り値:: 正常終了した場合は、生成したFPMオブジェクトのハンドルを返します。異常終了により生成できなかったときはNULLを返します。

注意:

FPMオブジェクトが不要になったら、必ず fnFIE_free_object() で解放してください。
本ライブラリではエッジ計測パラメータは使用しません。本ライブラリを使用して作成したFPMオブジェクトに対して fnFIE_fpm_get_pattern_feature_param() 関数を実行してもパラメータを取得することができません。
本ライブラリは必ずしもマスターパタンを使用しません。本ライブラリを使用して作成したFPMオブジェクトに対して fnFIE_fpm_get_pattern_image() 関数を実行してもマスターパタン画像を取得することができません。

INT FVALGAPI fnFIE_fpm_set_pattern_mask	(	FHANDLE	hfpm,
		FHANDLE	hmask
	)

マスクの設定

FPMオブジェクトのマスターパタンに対するマスク情報を更新します。マスクの設定を行うと、マスクの指定されていないエリアにある情報だけを使用してマッチングを行います。

引数:

`[in,out]`	hfpm	FPMオブジェクト
`[in]`	hmask	マスク指定用画像オブジェクト(画像タイプ：uc8 のみ対応) 画像オブジェクトのサイズは、FPMオブジェクトで管理されるマスターパタンのサイズと合わせてください。マスクを指定する場合には1を、マスクを指定しない場合には0を設定してください。それ以外の値が設定されていた場合にはF_ERR_INVALID_PARAMが戻ります。

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_OBJECT	引数オブジェクトの種別が異常
	F_ERR_NOMEMORY	メモリ不足
	F_ERR_INVALID_IMAGE	対応していない画像が渡された
	F_ERR_FPM_NOFEATURE	特徴量が見つかりません
	F_ERR_INVALID_PARAM	引数異常
	F_ERR_UNSUPPORTED	未サポートエラー
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

INT FVALGAPI fnFIE_fpm_clear_pattern_mask ( FHANDLE hfpm )

マスク情報のクリア

FPMオブジェクト内のマスターパタンへのマスク情報をクリアします。

引数:

[in,out] hfpm FPMオブジェクト

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_NOMEMORY	メモリ不足
	F_ERR_INVALID_OBJECT	引数オブジェクトの種別が異常
	F_ERR_UNSUPPORTED	未サポートエラー
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

INT FVALGAPI fnFIE_fpm_set_pattern_offset	(	FHANDLE	hfpm,
		DPNT_T	offset
	)

マッチング回答オフセット値の設定

FPMオブジェクトのマッチング回答オフセット値を更新します。

引数:

`[in,out]`	hfpm	FPMオブジェクト
`[in]`	offset	マッチング回答オフセット値(マスターパタン画像の左上位置からの値)

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_OBJECT	引数オブジェクトの種別が異常
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

INT FVALGAPI fnFIE_fpm_set_pattern_offset_gravity ( FHANDLE hfpm )

マッチング回答オフセット値の自動設定（特徴量重心）

FPMオブジェクトの回答オフセット値を、取得した特徴量重心位置に更新します。

引数:

[in,out] hfpm FPMオブジェクト

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_OBJECT	引数オブジェクトの種別が異常
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

INT FVALGAPI fnFIE_fpm_get_pattern_mask	(	FHANDLE	hfpm,
		FHANDLE *	phmask
	)

マスク情報の取得

FPMオブジェクトで管理しているマスターパタンへのマスク情報を取得します。

引数:

`[in]`	hfpm	FPMオブジェクト
`[out]`	phmask	マスターパタンのマスク情報 ( type: uc8 ) 画像オブジェクトを生成し、FPMオブジェクトで管理されるマスターパタンのマスク情報の複製を取得します。　*phmask はNULLで初期化してから引数に渡してください。

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_OBJECT	引数オブジェクトの種別が異常
	F_ERR_INVALID_PARAM	引数異常
	F_ERR_NOMEMORY	メモリ不足
	F_ERR_INVALID_IMAGE	対応していない画像が渡された
	F_ERR_UNSUPPORTED	未サポートエラー
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

注意:

マスク画像が不要になったら必ず fnFIE_free_object() で解放してください。

INT FVALGAPI fnFIE_fpm_get_pattern_offset	(	FHANDLE	hfpm,
		DPNT_T *	poffset
	)

マスターパタンマッチング回答オフセット値の取得

FPMオブジェクトの回答オフセット値を取得します。

引数:

`[in]`	hfpm	FPMオブジェクト
`[out]`	poffset	FPMオブジェクトが管理しているマッチング回答オフセット値(マスターパタン画像の左上位置からの値)

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_OBJECT	引数オブジェクトの種別が異常
	F_ERR_INVALID_PARAM	引数異常
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

INT FVALGAPI fnFIE_fpm_get_pattern_size	(	FHANDLE	hfpm,
		INT *	ptn_width,
		INT *	ptn_height
	)

マスターパタン画像サイズ取得

FPMオブジェクトに保存されているマスターパタンの画像の縦横サイズを取得します。

引数:

`[in]`	hfpm	FPMオブジェクト
`[out]`	ptn_width	マスターパタン画像Ｘサイズ
`[out]`	ptn_height	マスターパタン画像Ｙサイズ

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_OBJECT	引数オブジェクトの種別が異常
	F_ERR_INVALID_PARAM	引数異常
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

INT FVALGAPI fnFIE_fpm_get_pattern_feature_param	(	FHANDLE	hfpm,
		enum f_fpm_featedge *	pmethod,
		F_FPM_FEATURE *	pfeature_param
	)

特徴量パラメータ取得

FPMオブジェクト生成時に使用した特徴量パラメータの値を取得します。

引数:

`[in]`	hfpm	FPMオブジェクト
`[out]`	pmethod	特徴量取得方法
`[out]`	pfeature_param	特徴量パラメータ

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_OBJECT	引数オブジェクトの種別が異常
	F_ERR_INVALID_PARAM	引数異常
	F_ERR_NODATA	パラメータは存在しません( FPMオブジェクトは fnFIE_fpm_import_alloc() によって生成されました )
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

INT FVALGAPI fnFIE_fpm_get_matching_mode	(	FHANDLE	hfpm,
		enum f_fpm_mode *	pmatching_mode
	)

FPMオブジェクト生成時のマッチングモードの取得

FPMオブジェクトを生成した際のマッチングモードを取得します。

引数:

`[in]`	hfpm	FPMオブジェクト
`[out]`	pmatching_mode	FPMマッチング実行モード

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_OBJECT	引数オブジェクトの種別が異常
	F_ERR_INVALID_PARAM	引数異常
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

INT FVALGAPI fnFIE_fpm_get_pattern_image	(	FHANDLE	hfpm,
		FHANDLE *	phimage
	)

マスターパタン画像の取得

FPMオブジェクトを生成した際に指定した画像を取得します。

引数:

`[in]`	hfpm	FPMオブジェクト
`[out]`	phimage	マスターパタンの画像 ( type: uc8 ) 画像オブジェクトを生成し、FPMオブジェクトで管理されるマスターパタンの複製を取得します。　*phimage はNULLで初期化してから引数に渡してください。

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_OBJECT	引数オブジェクトの種別が異常
	F_ERR_NOMEMORY	メモリ不足
	F_ERR_INVALID_IMAGE	対応していない画像が渡された
	F_ERR_INVALID_PARAM	引数異常
	F_ERR_NODATA	画像が登録されていません( FPMオブジェクトは fnFIE_fpm_import_alloc() によって生成する際に画像が指定されませんでした )
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

注意:

マスターパタン画像が不要になったら必ず fnFIE_free_object() で解放してください。

INT FVALGAPI fnFIE_fpm_get_pattern_feature_num	(	FHANDLE	hfpm,
		INT *	pfeature_num
	)

マスターパタン特徴量数の取得

FPMオブジェクトを生成した際のマスターパタンの特徴量の数を取得します。

引数:

`[in]`	hfpm	FPMオブジェクト
`[out]`	pfeature_num	FPMオブジェクトにある特徴量の数

戻り値:

	F_ERR_NONE	正常終了。
	F_ERR_INVALID_OBJECT	引数オブジェクトの種別が異常
	F_ERR_INVALID_PARAM	引数異常
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

INT FVALGAPI fnFIE_fpm_get_pattern_feature_edges	(	FHANDLE	hfpm,
		F_DEDGE *	pedges
	)

マスターパタン特徴量を取得（勾配方向付きエッジ型）

FPMオブジェクトに格納されているマスターパタンの特徴量を勾配方向付きエッジデータ型で取得します。

引数:

`[in]`	hfpm	FPMオブジェクト
`[out]`	pedges	勾配付きエッジ情報(格納エリアは予め確保する必要があります) 予め fnFIE_fpm_get_pattern_feature_num() によって特徴量の数を取得し、必要な領域を確保する必要があります。

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_OBJECT	引数オブジェクトの種別が異常
	F_ERR_INVALID_PARAM	引数異常
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

注意:

強度の出力値は0が入ります。

参照:: fnFIE_fpm_get_pattern_feature_num()

INT FVALGAPI fnFIE_fpm_get_matching_feature_num	(	FHANDLE	hfpm,
		INT *	pmatching_feature_num
	)

サーチ対象画像の特徴量数の取得

マッチングの際に使用した特徴量の数を取得します。

引数:

`[in]`	hfpm	FPMオブジェクト
`[out]`	pmatching_feature_num	FPMオブジェクトにある特徴量の数

戻り値:

	F_ERR_NONE	正常終了。
	F_ERR_INVALID_OBJECT	引数オブジェクトの種別が異常
	F_ERR_INVALID_PARAM	引数異常
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

注意:

本関数をコールする場合、マッチング処理(fnFIE_fpm_matching_image() or fnFIE_fpm_matching_feature() or fnFIE_fpm_matching())を行い、FPMオブジェクト内部で特徴量オブジェクトを確保しておく必要があります。

INT FVALGAPI fnFIE_fpm_get_matching_feature_edges	(	FHANDLE	hfpm,
		F_DEDGE *	pmatching_edges
	)

マッチングで使用した特徴量を取得（勾配方向付きエッジ型）

FPMオブジェクトに格納されている特徴量を勾配方向付きエッジデータ型で取得します。

引数:

`[in]`	hfpm	FPMオブジェクト
`[out]`	pmatching_edges	勾配付きエッジ情報予め fnFIE_fpm_get_matching_feature_num() によって特徴量の数を取得し、必要な領域を確保する必要があります。

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_OBJECT	引数オブジェクトの種別が異常
	F_ERR_INVALID_PARAM	引数異常
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

注意:

本関数をコールする場合、マッチング処理(fnFIE_fpm_matching_image() or fnFIE_fpm_matching_feature() or fnFIE_fpm_matching())を行い、FPMオブジェクト内部で特徴量オブジェクトを確保しておく必要があります。
強度の出力値は0が入ります。

参照:: fnFIE_fpm_get_matching_feature_num()

INT FVALGAPI fnFIE_fpm_clear_result ( FHANDLE hfpm )

FPMオブジェクト結果データのクリア

FPMオブジェクトに格納されている結果情報(マッチング回答、マッチングに使用した特徴量)を削除します。

引数:

[in,out] hfpm FPMオブジェクト

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_OBJECT	引数オブジェクトの種別が異常
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

INT FVALGAPI fnFIE_fpm_get_relative_edge	(	FHANDLE	hfpm,
		INT	no,
		INT	err_wide,
		F_DEDGE *	edges,
		INT *	edge_num
	)

指定ポーズ下の対応点取得

サーチ回答として格納された番号を指定し、その回答に使用された対応エッジ情報の取得します。

fig．指定ポーズ下の対応点を取得し表示

引数:

`[in]`	hfpm	FPMオブジェクト(サーチを実行済み)
`[in]`	no	対応するエッジを取得するサーチ回答番号(0～)
`[in]`	err_wide	誤差範囲　±err_wide (0以上)
`[out]`	edges	対応点情報
`[out]`	edge_num	取得した対応点数

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_NOMEMORY	メモリ不足
	F_ERR_INVALID_OBJECT	不正なオブジェクトが入力されました
	F_ERR_INVALID_PARAM	不正なパラメータが入力されました
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

注意:

対応点を格納する edge のメモリは、最大数であるマスターパタンの特徴量数の分( fnFIE_fpm_get_pattern_feature_num() によって取得 )だけ予め確保しておいてください。
取得した edge 内で格納された対応点情報は、マッチングの状況によっては同じ対応点を複数回出力することがあります。

INT FVALGAPI fnFIE_fpm_set_pattern_essential	(	FHANDLE	hfpm,
		FHANDLE	hesse
	)

不可欠領域の設定

マスターパタンに対する不可欠領域情報を設定します。

不可欠領域の設定を行うと、通常のサーチ処理を行った後、不可欠領域エリアにある情報だけを使用してスコアを再計算します。特に、下図のように大きなパタンの中に含まれる小さな領域に対してのスコアに差をつけたい場合に有効な処理です。

fig．不可欠領域設定によるスコア

引数:

`[in,out]`	hfpm	FPMオブジェクト
`[in]`	hesse	不可欠領域指定用画像オブジェクト(画像タイプ：uc8 のみ対応) 画像オブジェクトのサイズは、FPMオブジェクトで管理されるマスターパタンのサイズと合わせてください。不可欠領域を指定する画素には1を、不可欠領域を指定しない画素には0を設定してください。それ以外の値が設定されていた場合にはF_ERR_INVALID_PARAMが戻ります。

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_OBJECT	引数オブジェクトの種別が異常
	F_ERR_NOMEMORY	メモリ不足
	F_ERR_INVALID_IMAGE	対応していない画像が渡された
	F_ERR_FPM_NOFEATURE	特徴量が見つかりません
	F_ERR_INVALID_PARAM	引数異常
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

参照:: fnFIE_fpm_get_pattern_essential(), fnFIE_fpm_matching_essential()

INT FVALGAPI fnFIE_fpm_get_pattern_essential	(	FHANDLE	hfpm,
		FHANDLE *	phesse
	)

不可欠領域情報の取得

マスターパタンへの不可欠領域情報を取得します。

引数:

`[in]`	hfpm	FPMオブジェクト
`[out]`	phesse	マスターパタンの不可欠領域情報画像オブジェクト( type: uc8 )を生成し、FPMオブジェクトで管理されるマスターパタンの不可欠領域情報の複製を取得します。不可欠領域として指定された画素には1を、指定されていない画素には0が設定されます。　*phesse はNULLで初期化してから引数に渡してください。

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_OBJECT	引数オブジェクトの種別が異常
	F_ERR_INVALID_PARAM	引数異常
	F_ERR_NOMEMORY	メモリ不足
	F_ERR_UNKNOWN	原因不明なエラー
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

注意:

不可欠領域画像が不要になったら必ず fnFIE_free_object() で解放してください。

参照:: fnFIE_fpm_set_pattern_essential(), fnFIE_fpm_matching_essential()

INT FVALGAPI fnFIE_fpm_set_pattern_edgeless_mask	(	FHANDLE	hfpm,
		FHANDLE	hedgeless
	)

エッジ減点領域の設定

マスターパタンに対するエッジ減点領域情報を設定します。

エッジ減点領域を使用すると、通常のサーチ処理を行った後、エッジ減点領域情報にあるエッジの分だけ減点処理を行いスコアを再計算します。下図のように、大きなパタンの内側に含まれる余計なエッジを減点しつつ、パタンの外側にあるエッジは減点しない場合に有効な処理です。

fig．エッジ減点領域設定によるスコア

設定されたエッジ減点領域は fnFIE_fpm_matching_recalc_with_edgeless_mask() で使用されます。 fnFIE_fpm_matching() などで実行される通常のマッチング処理では使用されません。

引数:

`[in,out]`	hfpm	FPMオブジェクト
`[in]`	hedgeless	エッジ減点領域指定用画像オブジェクト(type：bin, uc8) 画像オブジェクトのサイズは、FPMオブジェクトで管理されるマスターパタンのサイズと合わせてください。エッジ減点領域を指定する画素には1を、エッジ減点領域を指定しない画素には0を設定してください。それ以外の値が設定されていた場合には F_ERR_INVALID_IMAGE が戻ります。

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_OBJECT	引数オブジェクトの種別が異常
	F_ERR_NOMEMORY	メモリ不足
	F_ERR_INVALID_IMAGE	不正な画像が渡された
	F_ERR_INVALID_PARAM	引数異常
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

参照:: fnFIE_fpm_get_pattern_edgeless_mask(), fnFIE_fpm_matching_recalc_with_edgeless_mask()

INT FVALGAPI fnFIE_fpm_get_pattern_edgeless_mask	(	FHANDLE	hfpm,
		FHANDLE *	phedgeless
	)

エッジ減点領域情報の取得

マスターパタンへのエッジ減点領域情報を取得します。

引数:

`[in]`	hfpm	FPMオブジェクト
`[out]`	phedgeless	マスターパタンのエッジ減点領域情報画像オブジェクト( type: uc8 )を生成し、FPMオブジェクトで管理されるマスターパタンのエッジ減点領域情報の複製を取得します。エッジ減点領域として指定された画素には1を、指定されていない画素には0が設定されます。　*phedgeless はNULLで初期化してから引数に渡してください。

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_OBJECT	引数オブジェクトの種別が異常
	F_ERR_INVALID_PARAM	引数異常
	F_ERR_NOMEMORY	メモリ不足
	F_ERR_UNKNOWN	原因不明なエラー
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

注意:

エッジ減点領域画像が不要になったら必ず fnFIE_free_object() で解放してください。

参照:: fnFIE_fpm_set_pattern_edgeless_mask(), fnFIE_fpm_matching_recalc_with_edgeless_mask()

INT FVALGAPI fnFIE_fpm_set_refine_mode	(	FHANDLE	hfpm,
		INT	refine_mode
	)

高精度ポーズ推定モードの設定

高精度ポーズ推定が収束せずに適当な回答が見つからなかった際の動作を指定します。

引数:

`[in]`	hfpm	FPMオブジェクト
`[in]`	refine_mode	指定する高精度ポーズ推定の動作モード 0：粗サーチの位置姿勢情報を使用し、スコア計算まで行います(初期値) 1：その候補位置での回答を返しません

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_OBJECT	不正なオブジェクトが入力されました
	F_ERR_INVALID_PARAM	不正なパラメータが入力されました
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

参照:: fnFIE_fpm_get_refine_mode()

INT FVALGAPI fnFIE_fpm_get_refine_mode	(	FHANDLE	hfpm,
		INT *	refine_mode
	)

高精度ポーズ推定モードの取得

現在設定されている高精度ポーズ推定モードを取得します。

引数:

`[in]`	hfpm	FPMオブジェクト
`[out]`	refine_mode	設定されている高精度ポーズ推定の動作モード 0：粗サーチの位置姿勢情報を使用し、スコア計算まで行います(初期値) 1：その候補位置での回答を返しません

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_OBJECT	不正なオブジェクトが入力されました
	F_ERR_INVALID_PARAM	不正なパラメータが入力されました
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

参照:: fnFIE_fpm_set_refine_mode()

INT FVALGAPI fnFIE_fpm_set_pitch	(	FHANDLE	hfpm,
		INT	pitch_x,
		INT	pitch_y
	)

最小検出間隔の設定

最小検出間隔を設定します。最小検出間隔はサーチの回答が同一の解であるとみなす範囲で、回答候補の周辺で最小検出間隔以内にある別の候補の出現を抑制します。単位はピクセルです。初期値はゼロで、その場合パタンのもつ特徴量から自動決定した数値が使われます。パタンの大きさより小さい間隔で複数の回答を出現させたい場合に、その間隔よりすこし小さい数値を当関数で設定します。

水平方向、垂直方向個別に設定できますが、直感的ではない挙動変化をするため同一の数値を推奨します。
XY方向はパタンの座標系によります。
検出ピッチを小さくしすぎると処理時間が増大します。
検出ピッチを大きくしすぎると検出抜けが発生します。

引数:

`[out]`	hfpm	FPMオブジェクト
`[in]`	pitch_x	同一の解であるとみなす範囲で、単位はピクセルです。0の場合パタンの情報から自動決定します。
`[in]`	pitch_y	同一の解であるとみなす範囲で、単位はピクセルです。0の場合パタンの情報から自動決定します。

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_OBJECT	不正なオブジェクトが入力されました
	F_ERR_INVALID_PARAM	不正なパラメータが入力されました
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

参照:: fnFIE_fpm_get_pitch()

INT FVALGAPI fnFIE_fpm_get_pitch	(	FHANDLE	hfpm,
		INT *	pitch_x,
		INT *	pitch_y
	)

最小検出間隔の取得

現在設定されている最小検出間隔を取得します。

引数:

`[in]`	hfpm	FPMオブジェクト
`[out]`	pitch_x	同一の解であるとみなす範囲で、単位はピクセルです。0の場合パタンの情報から自動決定します。
`[out]`	pitch_y	同一の解であるとみなす範囲で、単位はピクセルです。0の場合パタンの情報から自動決定します。

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_OBJECT	不正なオブジェクトが入力されました
	F_ERR_INVALID_PARAM	不正なパラメータが入力されました
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

参照:: fnFIE_fpm_set_pitch()

INT FVALGAPI fnFIE_fpm_set_refine_pose_boundary_mode	(	FHANDLE	hfpm,
		enum f_fpm_pose_boundary_mode	boundary_mode
	)

高精度ポーズ推定における姿勢の範囲境界モードの設定

高精度ポーズ推定における、姿勢（傾きとスケール）の範囲境界に対する処理モードを設定します。
傾きの範囲は F_FPM_MATCH::min_angle と F_FPM_MATCH::max_angle 、スケールの範囲は F_FPM_MATCH::min_scale と F_FPM_MATCH::max_scale により設定されます。
下記の3種類のモードがあります。

F_FPM_POSE_UNBOUNDED
範囲制限のないモードです。設定された傾きやスケールの範囲外となるマッチング回答が得られる場合があります。

F_FPM_POSE_BOUNDED
範囲制限のあるモードです。マッチング回答は必ず設定された傾きやスケールの範囲内となります。サーチ対象物の真の姿勢がわずかに設定された傾きやスケールの範囲外となる場合、真の姿勢とマッチング回答にずれが生じる場合があります。

F_FPM_POSE_DELETE_OUT_OF_BOUND
範囲外の回答を削除するモードです。モードを F_FPM_POSE_UNBOUNDED とした場合と同様に高精度ポーズ推定を行い、マッチング回答が設定された傾きやスケールの範囲外であれば、その回答を削除します。

初期モードは F_FPM_POSE_UNBOUNDED です。最初はこのモードでマッチングを行い、範囲外のマッチング回答により不都合を生じる場合に他のモードを検討することを推奨します。

引数:

`[in,out]`	hfpm	FPMオブジェクト
`[in]`	boundary_mode	姿勢の範囲境界モード F_FPM_POSE_UNBOUNDED 姿勢の範囲制限なし（初期値） F_FPM_POSE_BOUNDED 姿勢の範囲制限あり F_FPM_POSE_DELETE_OUT_OF_BOUND 姿勢が範囲外となる回答を削除

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_OBJECT	不正なオブジェクトが入力されました
	F_ERR_INVALID_PARAM	不正なパラメータが入力されました
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

参照:: fnFIE_fpm_get_refine_pose_boundary_mode()

INT FVALGAPI fnFIE_fpm_get_refine_pose_boundary_mode	(	FHANDLE	hfpm,
		enum f_fpm_pose_boundary_mode *	boundary_mode
	)

高精度ポーズ推定における姿勢の範囲境界モードの取得

現在の高精度ポーズ推定における姿勢の範囲境界モードを取得します。

引数:

`[in]`	hfpm	FPMオブジェクト
`[out]`	boundary_mode	姿勢の範囲境界モード F_FPM_POSE_UNBOUNDED 姿勢の範囲制限なし（初期値） F_FPM_POSE_BOUNDED 姿勢の範囲制限あり F_FPM_POSE_DELETE_OUT_OF_BOUND 姿勢が範囲外となる回答を削除

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_OBJECT	不正なオブジェクトが入力されました
	F_ERR_INVALID_PARAM	不正なパラメータが入力されました
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

参照:: fnFIE_fpm_set_refine_pose_boundary_mode()

パタン操作 [FPM(特徴点応用マッチング)]

関数

関数

パタン操作
[FPM(特徴点応用マッチング)]