エンハンス処理
[画像フィルタ]


関数
INT FVALGAPI	fnFIE_lut_convert (const FHANDLE hSrc, FHANDLE hDst, const INT *iaConvertTable, const UINT uiTableSize)
	ルックアップテーブルによる濃度変換フィルタ
INT FVALGAPI	fnFIE_lut_convert_ch (const FHANDLE hSrc, FHANDLE hDst, const INT **ppiConvertTable, const UINT uiTableSize)
	ルックアップテーブルによる濃度変換フィルタ（チャネル別）
INT FVALGAPI	fnFIE_lut_set_gamma (const UINT uiInImageType, const UINT uiOutImageType, const DOUBLE dGamma, INT *ppiConvertTable, UINT puiTableSize)
	ガンマ変換用ルックアップテーブルの作成
INT FVALGAPI	fnFIE_gamma_convert (const FHANDLE hSrc, FHANDLE hDst, const DOUBLE dGamma)
	ガンマ変換フィルタ
INT FVALGAPI	fnFIE_histogram_equalization (const FHANDLE hsrc, UINT src_bpp, FHANDLE hdst, UINT dst_bpp)
	ヒストグラムの平坦化
INT FVALGAPI	fnFIE_histogram_normalization (const FHANDLE hsrc, UINT src_bpp, FHANDLE hdst, UINT dst_bpp, INT min_thr, INT min_den, INT max_den)
	ヒストグラムの正規化

関数

INT FVALGAPI fnFIE_lut_convert	(	const FHANDLE	hSrc,
		FHANDLE	hDst,
		const INT *	iaConvertTable,
		const UINT	uiTableSize
	)

ルックアップテーブルによる濃度変換フィルタ

与えられたルックアップテーブルに基づいて濃度変換を施します。被処理画像と処理後画像は同一サイズ、かつ同一チャネル数でなければなりません。ただし画素タイプは、被処理画像と処理後画像で異なっていても構いません。すべての画素タイプ間で変換が可能です。

この関数は、入力画素の濃度値を $D_{in}$ 、出力画素の濃度値を $D_{out}$ とすると、 $D_{out} = table[ D_{in} ]$ という処理を行います。複数のチャネルがあった場合、全てのチャネルにおいて、同じテーブルを用いて濃度変換を行います。入力画像がF_IMG_S16形式のときは $D_{in}=-32768$ が $table[0]$ の値を参照するように内部でオフセットを追加しています。このときの変換式は $D_{out} = table[ D_{in} + 32768 ]$ となっています。

この関数は、与えられたテーブルに従って濃度変換をするだけで、サチュレーションやスケーリングは行っていません。なお濃度テーブルのサイズ（ uiTableSize ）は、入力画像 hSrc の画素タイプにより決定されます。下記の条件を満たさない場合は、F_ERR_INVALID_PARAM が返されます。

F_IMG_UC8 : 256(UC_MAX+1)
F_IMG_US16 : 65536(US16_MAX+1)
F_IMG_S16 : 65536(S16_MAX-S16_MIN+1)

チャネル毎に異なるルックアップテーブルで処理したい場合は、 fnFIE_lut_convert_ch() を使用してください。

引数:

`[in]`	hSrc	被処理画像ハンドル(type: uc8, us16, s16)
`[out]`	hDst	処理後画像ハンドル(type: uc8, us16, s16)
`[in]`	iaConvertTable	濃度テーブル
`[in]`	uiTableSize	濃度テーブルサイズ

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_IMAGE	不正な画像が渡されたもしくは、入出力の画像サイズが違う、など
	F_ERR_INVALID_PARAM	不正なパラメータが渡された
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

参照:: fnFIE_lut_convert_ch()

INT FVALGAPI fnFIE_lut_convert_ch	(	const FHANDLE	hSrc,
		FHANDLE	hDst,
		const INT **	ppiConvertTable,
		const UINT	uiTableSize
	)

ルックアップテーブルによる濃度変換フィルタ（チャネル別）

与えられたルックアップテーブルに基づいて濃度変換を施します。 fnFIE_lut_convert() と本関数の違いは複数チャネルの画像を処理する際に、 fnFIE_lut_convert() では単一のルックアップテーブルしか指定できないのに対し、本関数ではチャネル毎に指定することが可能な点です。また、画素タイプが F_IMG_RGBQUAD の画像も処理することが可能です。処理対象画像が F_IMG_RGBQUAD の場合と、その他の場合で処理可能な条件が異なるため、それぞれに分けて説明します。

F_IMG_RGBQUAD 以外の画素タイプの場合: 本関数はチャネル毎にルックアップテーブルを指定することができます。そのため、ルックアップテーブルは M×N の２次元テーブルとなります。 N はパラメータ uiTableSize にて指定します。 M は $M={M_{0},M_{1},M_{2},...}$ とおくと、チャネル番号と M の番号が対応します。そのため、M は画像オブジェクトのチャネル数分のサイズが必要です。

なお、被処理画像と処理後画像は同一サイズ、かつ同一チャネル数でなければなりません。ただし画素タイプは、被処理画像と処理後画像で異なっていても構いません。対応するすべての画素タイプ間で変換が可能です。

F_IMG_RGBQUAD の場合

被処理画像と処理後画像のいずれか、もしくは両方の画素タイプが F_IMG_RGBQUAD である場合下記の条件が守られていなければなりません。

被処理画像 hSrc, 処理後画像 hDst が共に F_IMG_RGBQUAD である場合
チャネル数は共に１でなければなりません。
被処理画像 hSrc が F_IMG_RGBQUAD 、処理後画像 hDst がその他画素タイプである場合
チャネル数は被処理画像が１、処理後画像は３でなければなりません。
処理後画像 hDst が F_IMG_RGBQUAD である場合
被処理画像 hSrc に F_IMG_RGBQUAD 以外を指定することはできません。

: ルックアップテーブルは、R,G,Bの成分毎に指定することができます。そのため、ルックアップテーブルは MxN の２次元テーブルとなります。 N はパラメータ uiTableSize にて指定します。 M はR,G,Bの各色成分に対応し、M=3となります。

共通条件: 本関数は、入力画素の濃度値を $D_{in}$ 、出力画素の濃度値を $D_{out}$ とすると、 $D_{out} = table[ D_{in} ]$ という処理を行います。入力画像がF_IMG_S16形式では、 $D_{in}=-32768$ がの値を参照するように内部でオフセットを追加しています。このときの変換式は $D_{out} = table[ D_{in} + 32768 ]$ となります。

この関数は、与えられたテーブルに従って濃度変換をするだけで、サチュレーションやスケーリングは行っていません。なお、濃度テーブルのサイズ（ uiTableSize ）は、入力画像 hSrc の画素タイプにより決定されます。下記の条件を満たさない場合は、　F_ERR_INVALID_PARAM が返されます。

F_IMG_UC8 : 256(UC8_MAX+1)
F_IMG_US16 : 65536(US16_MAX+1)
F_IMG_S16 : 65536(S16_MAX-S16_MIN+1)
F_IMG_RGBQUAD : 256(UC8_MAX+1)

: また被処理画像と処理後画像は同一サイズでなければなりません。

引数:

`[in]`	hSrc	被処理画像ハンドル(type: uc8, us16, s16, rgbq)
`[out]`	hDst	処理後画像ハンドル(type: uc8, us16, s16, rgbq)
`[in]`	ppiConvertTable	濃度テーブル
`[in]`	uiTableSize	濃度テーブルサイズ

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_IMAGE	不正な画像が渡されたもしくは、入出力の画像サイズが違う、など
	F_ERR_INVALID_PARAM	不正なパラメータが渡された
	F_ERR_NOMEMOY	メモリ不足
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

参照:: fnFIE_lut_convert()

example

// エラー処理は省略しているので注意して下さい。
#include "oal_aloc.h"
#include "fie.h"

INT main()
{
    FHANDLE hsrc, hdst;
    INT width = 100, height = 100, channel = 3;
    INT **table, *tred, *tgreen, *tblue;

    // FIEライブラリの使用前に必ずコールする必要があります。
    fnFIE_setup();

    // 画像を確保します
    hsrc = fnFIE_img_root_alloc( F_IMG_UC8, channel, width, height );
    hdst = fnFIE_img_root_alloc( F_IMG_UC8, channel, width, height );

    // ここでhsrcに処理したい画像を読み込みます。

    // ルックアップテーブルを確保します。
    tred = ( INT * )fnOAL_calloc( UC8_MAX + 1, sizeof( INT ) );
    tgreen = ( INT * )fnOAL_calloc( UC8_MAX + 1, sizeof( INT ) );
    tblue = ( INT * )fnOAL_calloc( UC8_MAX + 1, sizeof( INT ) );
    table = ( INT ** )fnOAL_calloc( channel, sizeof( INT * ) );
    table[0] = tred;
    table[1] = tgreen;
    table[2] = tblue;

    // ここでtr, tg, tbにテーブルの値を書き込みます。

    // 濃度変換を実施します。
    fnFIE_lut_convert_ch( hsrc, hdst, table, UC8_MAX + 1 );

    fnFIE_free_object( hsrc );
    fnFIE_free_object( hdst );
    fnOAL_free( tred );
    fnOAL_free( tgreen );
    fnOAL_free( tblue );
    fnOAL_free( table );

    // 終了処理
    fnFIE_teardown();

    return 0;
}

INT FVALGAPI fnFIE_lut_set_gamma	(	const UINT	uiInImageType,
		const UINT	uiOutImageType,
		const DOUBLE	dGamma,
		INT **	ppiConvertTable,
		UINT *	puiTableSize
	)

ガンマ変換用ルックアップテーブルの作成

ユーザが任意に設定したガンマ値で、ルックアップテーブルを生成します。

関数エントリー時、ルックアップテーブルのポインタ *ppiConvertTable は NULL でなければなりません。本関数は必要なテーブルに必要なメモリを内部で確保し、そのポインタを *ppiConvertTable に代入して返します。ユーザーはテーブルが不要になった時点で fnOAL_free() にて解放する必要があります。

確保されるテーブルのサイズは uiInImageType にて指定される入力画像タイプに依存し、下記の通りになります。

F_IMG_UC8の場合256
F_IMG_US16またはF_IMG_S16の場合65536

生成されたルックアップテーブルの使い方は fnFIE_lut_convert() を参照してください。

変換式

ルックアップテーブルの各値は下記変換式により計算されます。
入力タイプがF_IMG_UC8またはF_IMG_US16の場合：

$table[ index ] = ( \frac{ index }{ InTypeMax } )^{ \frac{1}{\gamma{} } } * OutTypeMax$

入力画像タイプがF_IMG_S16の場合：
・indexが0以上32787以下の場合は

$table[ index ] = 0$

・indexが32768以上65535以下の場合は

$table[ index ] = ( \frac{ index - 32768 }{ InTypeMax } )^{ \frac{ 1 }{ \gamma{} } } * OutTypeMax$

上式の通り、ガンマ変換をした後に、出力画像型の最大値でスケーリングし、四捨五入しています。

引数:

`[in]`	uiInImageType	入力画像タイプ(入力値：F_IMG_UC8, F_IMG_US16, F_IMG_S16)
`[in]`	uiOutImageType	出力画像タイプ(入力値：F_IMG_UC8, F_IMG_US16, F_IMG_S16)
`[in]`	dGamma	ガンマ値(0 < dGamma)
`[out]`	ppiConvertTable	濃度値テーブル先頭アドレスへのポインタ関数エントリー時 *ppiConvertTable はNULLでなければなりません。
`[out]`	puiTableSize	濃度値テーブルサイズ

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_PARAM	不正なパラメータが渡された
	F_ERR_NOMEMORY	メモリ確保に失敗した
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

参照:: fnFIE_lut_convert()

INT FVALGAPI fnFIE_gamma_convert	(	const FHANDLE	hSrc,
		FHANDLE	hDst,
		const DOUBLE	dGamma
	)

ガンマ変換フィルタ

与えられたガンマ値を基に被処理画像を濃度値変換し、処理画像へ書き込みます。

$f(x) = x^{ \frac{ 1 }{ \gamma{} } }$

上式をガンマ関数と呼び、これで濃度値を変換することをガンマ変換といいます。入力の濃度値を $ (0, 1) $ に正規化して、ガンマ関数で変換し、出力側に合わせてスケーリングし、四捨五入します。

以下に、変換例を挙げます。

グラフに記入してあるように、それぞれ左上がF_IMG_UC8からF_IMG_UC8、右上がF_IMG_UC8からF_IMG_S16、左下がF_IMG_S16からF_IMG_S16、右下がF_IMG_S16からF_IMG_US16への変換です。

また、入力の濃度値がマイナスの場合は出力は0に固定されます。被処理画像 hSrc と処理後画像 hDst は同一サイズ、かつ同一チャネル数でなければなりません。ガンマ値 dGamma は0よりも大きい値を設定する必要があります。

引数:

`[in]`	hSrc	被処理画像（type: uc8, us16, s16）
`[out]`	hDst	処理後画像（type: uc8, us16, s16）
`[in]`	dGamma	ガンマ値（dGamma > 0）

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_IMAGE	不正な画像が渡されたもしくは、入出力の画像サイズが違う、など
	F_ERR_INVALID_PARAM	不正なパラメータが渡された
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

参照:: fnFIE_lut_set_gamma(), fnFIE_lut_convert()

INT FVALGAPI fnFIE_histogram_equalization	(	const FHANDLE	hsrc,
		UINT	src_bpp,
		FHANDLE	hdst,
		UINT	dst_bpp
	)

ヒストグラムの平坦化

本関数は内部で処理対象画像のヒストグラムを作成し、このヒストグラムが平坦化されるように濃度値を変換します。なお、濃度値の変換には fnFIE_lut_convert() が利用されています。処理はチャネル毎に実行されます。

入力画像と出力画像は同じサイズ、チャネル数である必要があります。画像型は、色深度が条件を満たしていれば、どの組合せでも許可されます。

注意:

総画素数が I32_MAX(2147483647)を超える場合は、内部計算にてオーバーフローが発生する場合があり、正しい結果が得られない可能性があります。
入力画像の実際の濃度値が指定した色深度の範囲を超えている場合、色深度の最大値でサチュレーション処理が行われます。

引数:

`[in]`	hsrc	入力画像( type : uc8, us16 )
`[in]`	src_bpp	入力画像の色深度（BPP） 2<= src_bpp <= 8（type : uc8） 2<= src_bpp <= 16（type : us16）
`[out]`	hdst	出力画像( type : uc8, us16 )
`[in]`	dst_bpp	出力画像の色深度（BPP） 2<= dst_bpp <= 8（type : uc8） 2<= dst_bpp <= 16（type : us16）

戻り値:

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

処理結果例：

INT FVALGAPI fnFIE_histogram_normalization	(	const FHANDLE	hsrc,
		UINT	src_bpp,
		FHANDLE	hdst,
		UINT	dst_bpp,
		INT	min_thr,
		INT	min_den,
		INT	max_den
	)

ヒストグラムの正規化

本関数は内部で処理対象画像のヒストグラムを作成し、このヒストグラムが正規化されるように濃度値を変換します。なお、濃度値の変換には fnFIE_lut_convert() が利用されています。処理はチャネル毎に実行されます。

ヒストグラムを作成したら、下記の処理を行い、最大濃度値と最小濃度値を決定します。

ヒストグラムの最小濃度値側から最大濃度値側へ、順に頻度値を調べていき、始めに最小ヒストグラム頻度値( min_thr )を超えた濃度を最小濃度値とする。
ヒストグラムの最大濃度値側から最小濃度値側へ、順に頻度値を調べていき、始めに最小ヒストグラム頻度値を超えた濃度を最大濃度値とする。

そして、この最小～最大濃度値が変換後の画像のヒストグラムで正規化されるように変換を行います。ただし、濃度値の変換は、ルックアップテーブルによって行いますので、処理前の画像で濃度値が同じだった画素は、変換後でも必ず同じ濃度値になります。言い換えると、変換後の画像のヒストグラムは、歯抜けの状態になります。

下図のヒストグラム例では、 min_thr に 200、 min_den に 0、 max_den に 255 を指定して処理を行うと、入力濃度値 87～199 が出力濃度値にて最小～最大となるよう正規化されます。

ただし、 min_thr 、 min_den 、 max_den は、以下の条件を満たす必要があります。

min_thr >= 0
画素タイプの最小値 <= min_den, max_den <= 画素タイプの最大値
min_den <= max_den

min_den 、 max_den を指定すると、その濃度値から頻度値のスキャンを行います。下図のヒストグラム例では、 min_thr に200、 min_den に150、 max_den に250 を指定すれば、入力濃度値 150～199 が正規化されます。

注意:

入力画像と出力画像は同じサイズ、チャネル数である必要があります。画像型は、色深度が条件を満たしていれば、どの組合せでも許可されます。
総画素数が I32_MAX(2147483647)を超える場合は、内部計算にてオーバーフローが発生する場合があり、正しい結果が得られない可能性があります。
入力画像の実際の濃度値が指定した色深度の範囲を超えている場合、色深度の最大値でサチュレーション処理が行われます。

引数:

`[in]`	hsrc	入力画像( type : uc8, us16 )
`[in]`	src_bpp	入力画像の色深度（BPP） 2<= src_bpp <= 8（type : uc8） 2<= src_bpp <= 16（type : us16）
`[out]`	hdst	出力画像( type : uc8, us16 )
`[in]`	dst_bpp	出力画像の色深度（BPP） 2<= dst_bpp <= 8（type : uc8） 2<= dst_bpp <= 16（type : us16）
`[in]`	min_thr	入力画像の最小ヒストグラム頻度値( 0以上 )
`[in]`	min_den	入力画像の最小濃度値
`[in]`	max_den	入力画像の最大濃度値

戻り値:

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

処理結果例：

エンハンス処理 [画像フィルタ]

関数

関数

エンハンス処理
[画像フィルタ]