ヒストグラム
[画像統計量]

画像ヒストグラム作成

画像のヒストグラムを作ります。

作成されたヒストグラムは unppHist に出力されますが、 外部でヒストグラム用に確保したメモリのアドレスを *unppHist に指定した場合は、そのメモリに出力します。 逆に、メモリを確保せず *unppHist にNULLを渡した場合は、 関数内部で必要なメモリを確保して、そのアドレスを *unppHist に返します。 この場合は *unppHist に返されたメモリはユーザーが fnOAL_free() で解放しなければいけません。

ヒストグラム *unppHist に必要なメモリ量は、入力画像型によって異なり、それぞれ下記のようになります。

• 入力画像のタイプが F_IMG_UC8 の場合 256 x sizeof(UINT) byte以上
• 入力画像のタイプが F_IMG_US16及びF_IMG_S16 の場合 65536 x sizeof(UINT) byte以上
• それ以外の画像タイプには対応しません。

入力画像の型が F_IMG_S16 の場合、Histogramの最初の位置（(*unppHist)[0]）は 濃度値S16_MIN に対応し、 最後の位置（(*unppHist)[65535]）は 濃度値S16_MAX に対応しています。

入力画像のチャネル数が１以上の場合は、指定チャネルのヒストグラムのみを作成します。 また、ヒストグラムはUINT型にて作成されるため、入力画像サイズが2^32画素以上の場合には オーバーフローの可能性があります。

引数:

[in]	hImg	入力画像のハンドル (type: uc8, s16, us16)
[in]	iChaNo	処理したいチャネルの番号
[out]	unppHist	ヒストグラムのメモリ
[in,out]	ipHistLen	メモリ確保した場合はそのメモリの量を入力（UINT数単位） メモリ確保しなかった場合は関数内部確保のメモリの量を出力（UINT数単位）

戻り値:

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

example

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

INT main()
{
    FHANDLE himg;
    UINT *hist;
    INT len;

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

    // 適当な画像を用意
    himg = fnFIE_img_root_alloc( F_IMG_UC8, 3, 256, 256 );
    fnFIE_jaehne_testimg( himg );

    /* 外部でメモリ確保をして、ヒストグラムを作成する例 */
    len = 256;
    hist = (UINT*)fnOAL_malloc( sizeof(UINT)*len );
    fnFIE_make_histogram( himg, 1, &hist, &len );   // チャネル１のヒストグラムを作成
    // ここでヒストグラムを利用します
    fnOAL_free( hist );


    /* fnFIE_make_histogram 内で自動的にメモリ確保をする場合 */
    hist = NULL;
    fnFIE_make_histogram( himg, 0, &hist, &len );   // チャネル０のヒストグラムを作成
    // ここでヒストグラムを利用します
    fnOAL_free( hist );

    // 終了処理
    fnFIE_teardown();
}

ヒストグラムからの多値化閾値決定

画像のヒストグラムから多値化するための閾値を算出します。 fnFIE_discrimination_multithreshold() や fnFIE_kittler_multithreshold() と同様の閾値を算出可能です。
num_discrimination 個のクラスに多値化し、各クラスに0から num_discrimination-1 の番号を振るとしたとき、ヒストグラムの配列番号をXとすれば

• クラス0 には の部分が含まれます。
• クラスn には の部分が含まれます。
• クラスnum_discrimination-1 には の部分が含まれます。

入力するヒストグラムの仕様は fnFIE_make_histogram() や fnFIE_img_histogram() で生成されるものに準じています。

• F_IMG_UC8 や F_IMG_US16 の画像型を持つ画像に対応するヒストグラムは data_hist[n] に 濃度nを持つ画素の個数が入っています。
• F_IMG_S16 の場合、data_hist[0] は濃度値S16_MIN に対応し、 data_hist[65535] は濃度値S16_MAXに対応しています。

当関数で算出した閾値を fnFIE_band_threshold() に入力すると特定のクラスに属する画素を白色、それ以外を黒色として出力することができます。 クラスnに該当する画素を白色に出力したい場合、引数 tlow に threshold[n-1] を、引数 thigh に threshold[n]-1 を入力します。 閾値はヒストグラムの先頭からの位置で出力するため、ヒストグラムの生成元になった画像の型がF_IMG_S16の場合、 fnFIE_band_threshold() の入力として使うためには当関数の回答にS16_MINを加算する必要があります。

引数:

[in]	data_hist	ヒストグラムへのポインタ
[in]	size_hist	data_hist の配列の長さ　( size_hist ≧ num_discrimination )
[in]	mode	閾値決定手法 0 大津の方法 1 kittlerの方法
[in]	num_discrimination	多値化の分割数(2 ≦ num_discrimination ≦ size_hist)
[out]	threshold	多値化しきい値結果格納バッファ。しきい値の格納用に num_discrimination -1 個のメモリを確保しておいてください。

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_NOMEMORY	メモリ不足
	F_ERR_INVALID_PARAM	パラメータ異常
	F_ERR_CALC_IMPOSSIBLE	計算不可能
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

参照:

fnFIE_img_histogram(), fnFIE_make_histogram(), fnFIE_calc_binarize_threshold()

ヒストグラムからの二値化閾値決定

入力したヒストグラムを mode で指定したアルゴリズムに従って 2つのクラスに分割する二値化閾値を算出し、 threshold に出力します。
ヒストグラムの配列番号をXとしたとき、クラス0には の部分が、 クラス1には の部分が含まれます。

• mode に0を指定した場合、大津の方法による閾値決定を行います。 クラス間分散が最大になる方法です。 詳細は fnFIE_discrimination_threshold2() のドキュメントをご覧ください。
• mode に1を指定した場合、キトラー(kittler)法による閾値決定を行います。 各クラスの濃度値が正規分布に従う場合に平均誤識別率が最小になる方法です。 詳細は fnFIE_kittler_threshold() のドキュメントをご覧ください。

入力するヒストグラムの仕様は fnFIE_make_histogram() や fnFIE_img_histogram() で生成されるものに準じています。

• F_IMG_UC8 や F_IMG_US16 の画像型を持つ画像に対応するヒストグラムは data_hist[n] に 濃度nを持つ画素の個数が入っています。
• F_IMG_S16 の場合、data_hist[0] は濃度値S16_MIN に対応し、 data_hist[65535] は濃度値S16_MAXに対応しています。

当関数で算出した threshold を fnFIE_binarize() に入力すると クラス0に属する画素を黒色、クラス1に属する画素を白色として出力することができます。 閾値はヒストグラムの先頭からの位置で出力するため、 ヒストグラムの生成元になった画像の型がF_IMG_S16の場合、 fnFIE_binarize() の入力として使うためには当関数の回答にS16_MINを加算する必要があります。

引数:

[in]	data_hist	ヒストグラムへのポインタ
[in]	size_hist	data_hist の配列の長さ 3以上でなければなりません
[in]	mode	閾値決定手法 0 大津の方法 1 kittlerの方法
[out]	threshold	算出した閾値

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_PARAM	パラメータ不正
	F_ERR_CALC_IMPOSSIBLE	計算不能エラー
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

参照:

fnFIE_img_histogram(), fnFIE_make_histogram(), fnFIE_calc_multi_threshold()