フィルターテンプレート
[低レベル処理関数]


型定義
typedef VOID(FVALGAPI *	F_TEMPLATE_FUNC_1x1 )(VOID src_pixel, VOID src_opt_pixel, VOID dst_pixel, VOID param)
	コールバック関数のポインタ型（1画素単位フィルターテンプレート）
typedef VOID(FVALGAPI *	F_TEMPLATE_FUNC_MxN )(VOID src_pixel, INT_PTR src_step, VOID dst_pixel, VOID *param)
	コールバック関数のポインタ型（カーネルフィルターテンプレート）
typedef INT(FVALGAPI *	F_TEMPLATE_FUNC_P )(FHANDLE src, FHANDLE src_opt1, FHANDLE src_opt2, FHANDLE dst, VOID *param)
	コールバック関数のポインタ型（既存画像処理関数並列化テンプレート）
typedef VOID(FVALGAPI *	F_TEMPLATE_FUNC_CHANNELS )(VOID src_pixels, VOID dst_pixels, VOID *param)
	コールバック関数のポインタ型（複数チャネル対応　1画素単位フィルターテンプレート）
関数
INT FVALGAPI	fnFIE_img_filter_template_1x1 (FHANDLE hsrc, FHANDLE hsrc_optional, FHANDLE hdst, F_TEMPLATE_FUNC_1x1 pixel_func, VOID *func_param)
	1画素単位フィルターテンプレート
INT FVALGAPI	fnFIE_img_filter_template_mxn (FHANDLE hsrc, FHANDLE hdst, F_TEMPLATE_FUNC_MxN pixel_func, VOID *func_param, INT border_left, INT border_top, INT border_right, INT border_bottom, INT border_mode, DOUBLE border_value)
	カーネルフィルターテンプレート
INT FVALGAPI	fnFIE_img_filter_template_parallel (FHANDLE hsrc, FHANDLE hsrc_optional1, FHANDLE hsrc_optional2, FHANDLE hdst, F_TEMPLATE_FUNC_P block_func, VOID *func_param, INT block_width, INT block_height, INT border_left, INT border_top, INT border_right, INT border_bottom, INT border_mode, DOUBLE border_value)
	既存画像処理関数並列化テンプレート
INT FVALGAPI	fnFIE_filter_template_channels (FHANDLE hsrc, FHANDLE hdst, F_TEMPLATE_FUNC_CHANNELS pixels_func, VOID *func_param)
	複数チャネル対応　1画素単位フィルターテンプレート

関数

INT FVALGAPI fnFIE_img_filter_template_1x1	(	FHANDLE	hsrc,
		FHANDLE	hsrc_optional,
		FHANDLE	hdst,
		F_TEMPLATE_FUNC_1x1	pixel_func,
		VOID *	func_param
	)

1画素単位フィルターテンプレート

入出力画像の同じ座標の画素だけを参照した1画素単位の空間フィルタを実施します。フィルタの内容はユーザーが引数 pixel_func で自由に指定できます。

入出力画像は下記の条件を満たしていなければなりません。

幅、高さ、チャネル数が等しい
いずれの画像も二値画像ではない

単一ピクセル処理関数 pixel_func

単一ピクセル処理関数 pixel_func は、出力画像の各画素で呼び出されて処理をする関数で、ユーザーが指定します。
この関数 pixel_func は次の型で定義します。

     VOID (FVALGAPI *pixel_func)( VOID *src_pixel, VOID *src_opt_pixel, VOID *dst_pixel, VOID *param );

本関数は出力画像の全てのピクセルにおいて、入力画像で対応する座標にあるピクセルのポインタを pixel_func に渡して呼び出します。 hsrc の画素は src_pixel, hsrc_optional の画素は src_opt_pixel, hdst の画素は dst_pixel に渡されます。また func_param は param にそのまま渡されます。

引数 pixel_func に与える単一ピクセル処理関数の実装例

     VOID myfunc( VOID *src, VOID *src_opt, VOID *dst, VOID *param ){
         UCHAR *ps = (UCHAR*)src;
         INT *ps_opt = (INT*)src_opt;
         DOUBLE *pd = (DOUBLE*)dst;
         MYSTRUCT *pstruct = (MYSTRUCT*)param;
         *pd = ( *ps_opt - *ps / pstruct->alpha ) + pstruct->beta;
     }

引数:

`[in]`	hsrc	入力画像ハンドル
`[in]`	hsrc_optional	入力画像ハンドル　必要なければNULLを渡してください。その際は pixel_func の第2引数にアクセスしないでください。
`[out]`	hdst	出力画像ハンドル
`[in]`	pixel_func	1ピクセルだけ処理する内容を記述した関数の関数ポインタ
`[in,out]`	func_param	オプションパラメータ各画素で pixel_func が実行される際に参照できます。必要がなければNULLを渡してください

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_IMAGE	入力画像異常
	F_ERR_INVALID_PARAM	パラメータ異常
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

覚え書き:

pixel_func の記述内容によっては入力画像への書き込みや画像外へのメモリアクセスが可能なので注意してください。
pixel_func で想定した画像型と与えた画像型が異なる場合でも検知してエラー終了することができずに実行してしまい、異常な結果出力や領域外アクセスが発生しますので注意してください。
param 内に値を書き込む場合、スレッドセーフになるような pixel_func でなければ正しい値になりませんので注意してください。

INT FVALGAPI fnFIE_img_filter_template_mxn	(	FHANDLE	hsrc,
		FHANDLE	hdst,
		F_TEMPLATE_FUNC_MxN	pixel_func,
		VOID *	func_param,
		INT	border_left,
		INT	border_top,
		INT	border_right,
		INT	border_bottom,
		INT	border_mode,
		DOUBLE	border_value
	)

カーネルフィルターテンプレート

出力画像の各ピクセルに対し、入力画像で上下左右に範囲を持ったアクセスを行うカーネルフィルタに類似した空間フィルタを実施します。フィルタの内容はユーザーが引数 pixel_func で自由に指定できます。

入出力画像は下記の条件を満たしていなければなりません。

幅、高さ、チャネル数が等しい
いずれの画像も二値画像ではない
hsrc が fnFIE_copy_border() で処理可能な画像型である

pixel_func は出力画像の各画素と同一座標を持つ入力画像の画素から上下左右へアクセスするため、ボーダー処理モードが F_BORDER_NONE の時、出力画像の周囲における該当範囲は処理されず元の値を維持します。それ以外のボーダー処理モードの時、入力画像を指定のモードでボーダー拡張しフィルタ処理を施します。この時、出力画像の領域全面でフィルタ処理結果が得られます。ボーダー拡張の詳細な仕様は fnFIE_copy_border() を参照して下さい。

フィルタカーネル関数 pixel_func

フィルタカーネル関数 pixel_func は、出力画像の各画素で呼び出されて処理をする関数で、ユーザーが指定します。
この関数 pixel_func は次の型で定義します。

    VOID (FVALGAPI *pixel_func)( VOID *src_pixel, INT_PTR step, VOID *dst_pixel, VOID *param );

本関数は出力画像の全てのピクセルにおいて、入力画像で対応する座標にあるピクセルのポインタを pixel_func に渡して呼び出します。 hsrc の画素は src_pixel, hdst の画素は dst_pixel に渡されます。入力画像のステップサイズは画素単位で引数 step に渡されます。また、 func_param は param にそのまま渡されます。

引数 pixel_func に与えるフィルタカーネル関数の例

    VOID myfunc( VOID *src, INT_PTR step_src, VOID *dst, VOID *param ){
        INT x, y;
        DOUBLE sum = 0;
        UCHAR *ps = (UCHAR*)src;
        DOUBLE *pd = (DOUBLE*)dst;
        MYSTRUCT *pstruct = (MYSTRUCT*)param;

        for( y = -1; y <= 1; y++ ){
            for( x = -2; x <= 2; x++ ){
                sum += *( ps + y * step_src + x );
            }
        }
        *pd = ( sum * pstruct->alpha ) + pstruct->beta;
    }

フィルタカーネル関数内で上下左右にアクセスした範囲によって、実質的なフィルタのアンカー位置が決まります。またアクセス範囲を border_left などに反映することで、領域外アクセスすることなく上記フィルタカーネル関数を適用できます。

引数:

`[in]`	hsrc	入力画像ハンドル
`[out]`	hdst	出力画像ハンドル
`[in]`	pixel_func	1ピクセルだけ処理する内容を記述した関数の関数ポインタ
`[in,out]`	func_param	オプションパラメータ各画素で pixel_func が実行される際に参照できます。必要がなければNULLを渡してください
`[in]`	border_left	pixel_func が左方向にアクセスするサイズ。ゼロ以上を指定してください。
`[in]`	border_top	pixel_func が上方向にアクセスするサイズ。ゼロ以上を指定してください。
`[in]`	border_right	pixel_func が右方向にアクセスするサイズ。ゼロ以上を指定してください。
`[in]`	border_bottom	pixel_func が下方向にアクセスするサイズ。ゼロ以上を指定してください。
`[in]`	border_mode	ボーダー処理モード F_BORDER_NONE ボーダー拡張しない F_BORDER_ZERO ０埋めモード F_BORDER_VALUE 一定値モード F_BORDER_CONTINUOUS 端延長モード F_BORDER_REPEAT 繰り返しモード F_BORDER_MIRROR1 反転モード１ F_BORDER_MIRROR2 反転モード２
`[in]`	border_value	ボーダー濃度値。 border_mode が F_BORDER_VALUE の場合のみ使用されます。その他のモードの場合は、この値は無視されます。

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_IMAGE	入力画像異常
	F_ERR_INVALID_PARAM	パラメータ異常
	F_ERR_NOMEMORY	メモリ不足
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

覚え書き:

pixel_func の記述内容によっては入力画像への書き込みや画像外へのメモリアクセスが可能なので注意してください。
pixel_func で想定した画像型と与えた画像型が異なる場合でも検知してエラー終了することができずに実行してしまい、異常な結果出力や領域外アクセスが発生しますので注意してください。
param 内に値を書き込む場合、スレッドセーフになるような pixel_func でなければ正しい値になりませんので注意してください。

INT FVALGAPI fnFIE_img_filter_template_parallel	(	FHANDLE	hsrc,
		FHANDLE	hsrc_optional1,
		FHANDLE	hsrc_optional2,
		FHANDLE	hdst,
		F_TEMPLATE_FUNC_P	block_func,
		VOID *	func_param,
		INT	block_width,
		INT	block_height,
		INT	border_left,
		INT	border_top,
		INT	border_right,
		INT	border_bottom,
		INT	border_mode,
		DOUBLE	border_value
	)

既存画像処理関数並列化テンプレート

既存のFIE画像オブジェクトを扱うシングルスレッドの空間フィルタを利用して並列処理するテンプレートです。入出力画像を指定したサイズのブロックに分割し、フィルタを各ブロックごとに並列に適応します。フィルタの内容はユーザーが引数 block_func で自由に指定できます。

入出力画像は下記の条件を満たしていなければなりません。

block_func で処理できる組み合わせである
入力画像が fnFIE_copy_border() で処理可能な画像型である
全ての画像で縦横サイズが同じ
入力画像と出力画像は重なっていない

当関数に与えるボーダー処理モードが F_BORDER_NONE の時、出力画像の周囲(上側 border_top, 下側 border_bottom, 左側 border_left, 右側 border_right の範囲)は処理されず元の値を維持します。それ以外のボーダー処理モードの時、入力画像を指定のモードでボーダー拡張しフィルタ処理を施します。この時、出力画像の領域全面でフィルタ処理結果が得られます。ボーダー拡張の詳細な仕様は fnFIE_copy_border() を参照して下さい。

ユーザー定義フィルタ関数 block_func

block_func は、出力画像を block_width × block_height のサイズに区切った少さな画像領域ごとに呼び出されて処理をする関数で、ユーザーが指定します。
この関数 block_func は次の型で定義します。

    INT (FVALGAPI *block_func)( FHANDLE src_image, FHANDLE src_image_optional_1, FHANDLE src_image_optional_2, FHANDLE dst_image, VOID *param );

全てのブロックが F_ERR_NONE を回答した場合にのみ当関数は F_ERR_NONE を返し、ひとつでも F_ERR_NONE でなければその戻り値を返します。複数のブロックがそれぞれ異なる値を返した場合でも、いずれかひとつだけを返します。

block_func の注意点

block_func は当関数を通さず直接入出力画像を渡した際に正常に処理できる必要があります。
block_func の記述内容によっては入力画像への書き込みや画像外へのメモリアクセスが可能なので注意してください。
block_func がスレッドセーフでないと、正常な結果が得られず出力画像が異常になるなどの可能性があります。
block_func 内部で並列化を行っていると、当関数で並列化した場合パフォーマンスが充分に向上しなかったり悪化したりします。
block_func の画像出力範囲が当関数のborder関連引数と異なる場合、出力画像が異常になったり画像外へメモリアクセスしたりするので注意してください。 block_func 内部が F_BORDER_NONE 相当の処理でなければ出力画像が異常になる可能性があります。つまり、出力画像の周囲(上側 border_top, 下側 border_bottom, 左側 border_left, 右側 border_right の範囲)は処理せず元の値を維持しなければなりません。また、入出力画像で全て同じ位置の画素のみ参照するならborder関連引数は全てゼロでなければなりません。

引数 block_func に与えるフィルタ関数の例

    INT FVALGAPI myfunc( FHANDLE src, FHANDLE opt1, FHANDLE opt2, FHANDLE dst, VOID *param ){
        INT *p  = (INT*)param;
        return fnFIE_averageMxN( src, dst, p[0], p[1], F_BORDER_NONE, 0 );
    }

    INT FVALGAPI myfunc2( FHANDLE src, FHANDLE opt1, FHANDLE opt2, FHANDLE dst, VOID *param ){
        return  fnFIE_img_atan2( src, opt1, dst );
    }

引数:

`[in]`	hsrc	入力画像ハンドル
`[in]`	hsrc_optional1	入力画像ハンドル必要なければNULLを渡してください
`[in]`	hsrc_optional2	入力画像ハンドル必要なければNULLを渡してください
`[out]`	hdst	出力画像ハンドル
`[in]`	block_func	並列化したい画像フィルタを記述したユーザー定義フィルタ関数の関数ポインタ
`[in,out]`	func_param	オプションパラメータ各画素で block_func が実行される際に参照できます。必要がなければNULLを渡してください
`[in]`	block_width	並列化する際、各々のスレッドが処理する幅(pixel) 1以上を指定してください。
`[in]`	block_height	並列化する際、各々のスレッドが処理する高さ(pixel) 1以上を指定してください。
`[in]`	border_left	block_func が左方向にアクセスするサイズ。ゼロ以上を指定してください。
`[in]`	border_top	block_func が上方向にアクセスするサイズ。ゼロ以上を指定してください。
`[in]`	border_right	block_func が右方向にアクセスするサイズ。ゼロ以上を指定してください。
`[in]`	border_bottom	block_func が下方向にアクセスするサイズ。ゼロ以上を指定してください。
`[in]`	border_mode	ボーダー処理モード F_BORDER_NONE ボーダー拡張しない F_BORDER_ZERO ０埋めモード F_BORDER_VALUE 一定値モード F_BORDER_CONTINUOUS 端延長モード F_BORDER_REPEAT 繰り返しモード F_BORDER_MIRROR1 反転モード１ F_BORDER_MIRROR2 反転モード２
`[in]`	border_value	ボーダー濃度値。 border_mode が F_BORDER_VALUE の場合のみ使用されます。その他のモードの場合は、この値は無視されます。

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_IMAGE	入力画像異常
	F_ERR_INVALID_PARAM	パラメータ異常
	F_ERR_NOMEMORY	メモリ不足
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

INT FVALGAPI fnFIE_filter_template_channels	(	FHANDLE	hsrc,
		FHANDLE	hdst,
		F_TEMPLATE_FUNC_CHANNELS	pixels_func,
		VOID *	func_param
	)

複数チャネル対応　1画素単位フィルターテンプレート

入出力画像の同じ座標で各チャネル1画素を参照した、1座標単位の画像変換を行います。
変換内容はユーザーが引数pixels_func で自由に指定できます。

入力画像と出力画像は下記の条件を満たしている必要があります。

幅、高さが等しい (※チャネル数は異なっても可)
いずれの画像も二値画像ではない

1座標処理関数 pixels_func

1座標処理関数 pixels_func は、入出力画像の各画素で呼び出されて処理をする関数で、ユーザーが指定します。
この関数 pixels_func は次の型で定義します。

    VOID( FVALGAPI * pixels_func )(VOID **src_pixels, VOID **dst_pixels, VOID *param);

本関数は出力画像の画素において、入力画像で対応する画素のポインタを pixels_func に渡して呼び出します。
hsrc の画素は src_pixels, hdst の画素は dst_pixels に渡され、 func_param は param に渡されます。また、src_pixelsとdst_pixelsに渡されるポインタは、入出力画像それぞれ、チャネル0のポインタから順にリストされています。(チャネル：0,1,2...)

引数 pixels_func に与える処理関数の実装例

    VOID FVALGAPI myfunc( VOID **src, VOID **dst, VOID *param )
    {
        UCHAR **ps = (UCHAR**)src;
        DOUBLE **pd = (DOUBLE**)dst;
        MYSTRUCT *pstruct = (MYSTRUCT*)param;
        *pd[0] = *ps[0] * pstruct->a  + *ps[1] * pstruct->b   + *ps[2] * pstruct->c;
        *pd[1] = *ps[0] * pstruct->a*2+ *ps[1] * pstruct->b*2 + *ps[2] * pstruct->c*2;
        *pd[2] = *ps[0] * pstruct->a*3+ *ps[1] * pstruct->b*3 + *ps[2] * pstruct->c*3;
    }

引数:

`[in]`	hsrc	入力画像のハンドル
`[out]`	hdst	出力画像のハンドル
`[in]`	pixels_func	1ピクセルだけ処理する内容を記述した関数の関数ポインタ
`[in]`	func_param	オプションパラメータ各画素で pixels_func が実行される際に参照できます。必要がなければNULLを渡してください

戻り値:

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

覚え書き:

pixels_func の記述内容によっては入力画像への書き込みや画像外へのメモリアクセスが可能なので注意してください。
pixels_func で想定した画像型と与えた画像型が異なる場合でも検知してエラー終了することができずに実行してしまい、異常な結果出力や領域外アクセスが発生しますので注意してください。
param 内に値を書き込む場合、スレッドセーフになるような pixels_func でなければ正しい値になりませんので注意してください。

フィルターテンプレート [低レベル処理関数]

型定義

関数

関数

フィルターテンプレート
[低レベル処理関数]