ldpeakpick(3)

LIBRARY ROUTINE
ldpeakpick - Find peaks or troughs in 1D data set

LIBRARY CALL
#include "vinclude.h"
int
ldpeakpick(image, peak_flg, all_flg, num_peaks, max_flg, end_flg, w_size,
           hwr, process_dir, peak_info, vect_info)
struct xvimage  *image;         /* input image structure */
int             peak_flg,       /* flg = 1 for peaks, 0 for troughs */
                all_flg,        /* flg = 1 find all peaks */
                num_peaks,      /* number of peaks or troughs to detect */
                max_flg,        /* flag = 0 -> find first n peaks,
                                   flag = 1 -> find max/min n peaks/troughs */
                end_flg,        /* if TRUE, end points can be peaks */
                w_size,         /* window size to each side of point */
                process_dir;    /* 0 = DSP_VECTOR, 1 = DSP_BAND */
double          hwr;            /* minimum height to width ratio */
struct p_info   ***peak_info;    /* 2D array of peak/trough values & positions */
struct v_info   **vect_info;     /* 1D array of vector peak statistics */

INPUT

image
    (struct xvimage) - input data structure

peak_flg
    (int) - flag set to 1 if peaks are to be detected. Set to 0 if troughs are to be detected

all_flg
    (int) - flag set to 1 if all peaks are to be detected. Set to 0 if user specifies the number of peaks to be detected.

num_peaks
    (int) - number of peaks/troughs to detect (only valid if all_flg = 0)

max_flg
    (int) - if flag = 0 -> find first n peaks, if flag = 1 -> find max/min n peaks/troughs (only valid if all_flg = 0)

end_flg
    (int) - flag which signals whether the first and last points in a data sequence should be considered for peak or trough designation. If end_flg is 1, endpoints will be considered for peak or trough designation, if 0, they will not.

w_size
    (int) - number of steps on both sides of a point that must be monotonically increasing/decreasing before the point will be counted as a peak or trough.

hwr (double) - minimum height to width ratio. Point of interest is a peak only if absolute value of the average slope over window size is greater than hwr.

process_dir
    (int) - Direction of data processing: down vectors = 0 = DSP_VECTOR, across bands = 1 = DSP_BAND

OUTPUT

image
    (struct xvimage) - output peak/trough implicit VIFF file. All values are zero except peak/trough values.

peak_info
    (struct p_info) - 2D array containing peak/trough values and positions. If the data is complex, the number of vectors in this array will be 2 times the actual number of vectors. They will be arranged in the following order vect0:r,i vect1:r,i ....

vect_info
    (struct v_info) - 1D array containing number of peaks, and mean and variance of the distance between peaks/troughs, for each vector. If the data is complex, the number of vectors represented in this array will be 2 times the actual number of vectors. The statistics will be arranged in the following order vect0:r,i vect1:r,i ....

MODIFICATIONS

DESCRIPTION
ldpeakpick finds peaks or troughs in 1D data vectors by doing an estimate of the first derivative. Peaks are detected by watching for sign changes in the slope of the line:
    slope = f(x) - f(x-1)
Two parameters, the window size (w_size) and the height to width ratio (hwr), can be varied to "smooth" the data. Increasing the values of these parameters will tend to reduce the number of peaks found in the data set. If flat peaks are encountered, the last point of the flat area will be assigned as the peak position. When dealing with complex data, the real and imaginary components are processed individually.

image (input/output)
    image is the xvimage structure which contains the input data, and will ultimately contain the output VIFF data passed back to the calling routine. This output file is an implicit file in which the peak or trough values are preserved, and all other values are set to zero. Note that if data has peaks with amplitude = 0.0, these peaks will not show up in the VIFF output file.

peak_flg (input)
    peak_flg is an integer flag to signal whether peaks or troughs are to be detected in the input sequence. If peak_flg is TRUE (1), peaks are detected, and if peak_flg is FALSE (0), troughs are detected. Troughs are detected by inverting the input data, performing peak detection, and then inverting the results before returning to the calling routine.

all_flg (input)
    all_flg is an integer flag, which if TRUE (1), will cause all peaks in the sequence to be detected. If all_flg is FALSE (0), the parameter num_peaks will be used to determine how many peaks will be detected. When all_flg is TRUE, the num_peaks parameter is ignored.

num_peaks (input)
    num_peaks is an interger value which, if all_flg is FALSE, is used to determine how many peaks will be recorded. (If fewer peaks are found than num_peaks, then that number of peaks will be recorded and a warning statement printed. The values allowed for this parameter are
    0 < num_peaks < (signal length - 1)/2.

max_flg (input)
    This is an integer flag which, if all_flg is FALSE, indicates whether the num_peaks recorded peaks should be the first encountered, or the maximum valued in the data set. If max_flg is TRUE (1), the maximum N peaks will be found; if max_flg is FALSE (0), the first num_peaks peaks are recorded.

end_flg (input)
    This is an integer flag which signals whether the first and last points in a data sequence should be considered for peak or trough designation. If this option is set to TRUE, endpoints will be considered for peak or trough designation, if FALSE, they will not.

w_size (input)
    w_size is an integer which describes the number of steps on both sides of a point that must be monotonically increasing/decreasing before the point will be counted as a peak. A window size of 1 will provides for exact realization of the equation above, and maximizes the number of peaks detected. Two special cases exist at the beginning and ending of a data sequence, where the window size on one side of the point in question will not be satisfied by the number of points available. In such cases, the decision of whether the point is an extreme will be based on the available points. The upper limit on w_size is (signal length - 1)/2.

hwr (input)
    hwr is a double value which can be adjusted to decrease the number of peaks detected by requiring that the absolute value of the average slope over w_size be above the hwr value specified. Setting hwr to 0.0 will effectively "disable" this parameter.

process_dir (input)
    Data can be processed with either band or vector orientation ( process_dir parameter). Vector processing means that data stored in multiband format will be processed as a set of data sequences, where each sequence corresponds to a pixel location, and the points of each sequence are defined by the bands corresponding to that pixel location. The direction of processing can be set so that each band is processed as a signal (instead of each vector being a signal) by setting process_dir to 1.

peak_info (output)
    peak_info is a 2D array of p_info structures containing peak/trough values and positions. If the data is complex, the number of vectors in this array will be 2 times the actual number of vectors, and they will be arranged in the following order vect0:r,i vect1:r,i .... The length of each vector will be num_peaks if all_flg is FALSE, and the maximum number of peaks found if all_flg is TRUE.

vect_info (output)
    vect_info is a 1D array of v_info structures which contains the number of peaks, and the mean and variance of the distance between peaks/troughs, for each vector. If the data is complex, the number of vectors represented in this array will be 2 times the actual number of vectors, and the statistics will be arranged in the following order vect0:r,i vect1:r,i ....

SEE ALSO
dpeakpick(1), intro(3), vipl(3), verror(3), vutils(3)

RESTRICTIONS
ldpeakpick assumes that the input image structure is VFF_LOC_IMPLICIT. Only works on VFF_TYP_FLOAT and VFF_TYP_COMPLEX data.

AUTHOR
Donna Koechner

COPYRIGHT
Copyright 1991, University of New Mexico. All rights reserved.