ピーク探索
[ビジョンツール]

ピーク探索

入力された配列を走査し、ピーク点 (データの極大点) を探索します。
例えば、濃度プロファイルから配列を作成し、局所的に濃度値が高くなっている位置を検出するといったことが可能です。

この関数は、データ点とデータ点の間隔を 1 とし、データ点とデータ点の間を補間して浮動小数点精度でピーク値とその位置を出力します。
各種パラメータによって出力するピークを抑制することができます。

参照が配列外となるときの挙動

ピーク値とその位置の補間、出力するピークの抑制の処理では、ピークそのものだけでなく、その付近も参照します。
その参照が配列外となるときは、配列外となった側の参照範囲を配列の端まで縮小させます。

相対的ピーク高

相対的ピーク高とは、データ点によって作成される曲線を山や谷と見立てたとき、注目するピークを囲む極小値の等高線の中で、そのピークより高い地点を包括して囲わない最も低い等高線からピークまでの高さを示します。
図1-1 の入力の例では、極小値 a の等高線は、ピーク A のみのグループと ピーク B, C, D のグループに分割するようにピークを囲みます。 極小値 b の等高線は、すべてのピークを包括するようにピークを囲みます。このような関係を 図1-2 に示します。
例えば、すべての極小値の等高線は ピーク B を囲います。そして、ピーク B よりも高いピークは存在しないので、ピーク B の相対的ピーク高は、最小値 b の位置から測定されます。 一方、極小値 c 以下の等高線は ピーク C とそれよりも高いピークである ピーク B を囲みます。このとき、ピーク C の相対的ピーク高は、極小値 c 以下の等高線のうちピーク B と ピーク C を分割するように囲む、極小値 c の位置から測定されます。
このようにして計算すると、図1-1 における相対的ピーク高は、a から A までの高さ、b から B までの高さ、… となります。
相対的ピーク高が小さなピークを無視することで、細かい振動によるピークの出現を抑制できます。
同値のピークが計算範囲内に出現したときには、先に出現したピークのほうが高いときと同様な挙動をします ( 図2 )。

図1-1	図1-2
図2

引数:

[in]	src_val	入力配列
[in]	src_num	入力配列の要素数 ( 1 ≦ src_num )
[in]	neighbor	近傍範囲 ( 0 ≦ neighbor ) 極大のデータ点から 前後それぞれ neighbor 個までの範囲を近傍とし、補間に利用します。 0が指定された場合、補間なしとなります。
[in]	nms_length	非極大抑制のフィルタ片幅 ( 0 ≦ nms_length ) 極大のデータ点の前後 nms_length の範囲に複数のピークが出現したとき、 そのうちの最もピーク値の大きいものを採用し、他は無視します。 同値の場合は、先に出現したピークが優先されます。 nms_length = 0 のときには、制限なしとなります。
[in]	rel_length	相対的ピーク高の計算片幅 ( 0 ≦ rel_length ) 極大のデータ点の前後 rel_length の範囲内で相対的ピーク高を計算します。 rel_length = 0 のときには、入力配列全体が計算範囲となります。
[in]	val_thresh	ピーク値の閾値 入力値が val_thresh 未満のピークは出力されません。 val_thresh ≦ ( 入力値の最低値 ) の場合、制限なしとなります。
[in]	rel_thresh	相対的ピーク高の閾値 ( 0 ≦ rel_thresh ) 相対的ピーク高が rel_thresh 未満のピークは出力されません。 rel_thresh = 0 の場合、制限なしとなります。
[in]	max_abs_diff	差分絶対値の上限 ( 0 ≦ max_abs_diff ) 極大のデータ点と前後の隣接しているデータ点との差がどちらも max_abs_diff より大きいときには、ごましおノイズ等によって出現したピークとみなして無視します。 max_abs_diff の値が小さいほど、ノイズを抑制しやすくピークが出現しにくい傾向があり、 max_abs_diff の値が大きいほど、ノイズを抑制しにくくピークが出現しやすい傾向があります。 入力値の最大値と最小値の差の1/4程度を推奨します。 特に制限しない場合は、0 を指定してください。
[in]	sort_mode	peaks_val と peaks_pos のソートモード 0 : 位置基準昇順 1 : 位置基準降順 2 : ピーク値基準昇順 3 : ピーク値基準降順
[out]	peaks_val	取得ピーク値保存用のバッファ sort_mode で指定された順にピーク値を格納します。 peaks_num 個以上の配列を確保したうえで、その配列を渡してください。
[out]	peaks_pos	取得ピーク位置保存用のバッファ sort_mode で指定された順にピーク位置を格納します。 つまり、peaks_val[idx] と peaks_pos[idx] は対応しています。 peaks_num 個以上の配列を確保したうえで、その配列を渡してください。
[in,out]	peaks_num	ピークの個数 入力のときには、ピークを最大で何個出力するか ( 1以上 ) を指定します。 出力のときには、以下の数値となります。 検出されたピークの個数が peaks_num 以内の場合 : 検出されたピークの個数 検出されたピークの個数が peaks_num を超えた場合 : 入力時の peaks_num このとき、ソートモードに従い、順に peaks_num 個のピークを出力します。

戻り値:

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