PLEASE NOTE : This is the documentation for the avs module executable info, which contains the following modules: dpeakpick dstats varviff vfileinfo vprdata vstats Any mention of xvimage is actually a "field 2D". Also, the INPUTs and OUTPUTs, which are mapped to avs parameters, inputs, and outputs, are for the khoros library routine. ********************************************************************************* Documentation for avs module dpeakpick 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 aver- age 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 com- plex, 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 .... DESCRIPTION dpeakpick 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 indi- vidually. 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 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 warn- ing 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 monotoni- cally 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 maxim- izes 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 ques- tion 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 orien- tation ( process_dir parameter). Vector processing means that data stored in multiband format will be pro- cessed 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 com- plex, 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 con- tains 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 dpeakpick 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. ********************************************************************************* Documentation for avs module dstats INPUT OUTPUT DESCRIPTION dstats computes the mean, variance, standard deviation, RMS level, peaks with locations, integral, skew, kurtosis, entropy, and contrast for and input filed. Descriptions of how these statistics are calculated are given in the lvstats man page. A masking file can be specified (-m option) which will allow specified vectors to NOT be included in the statistics calculations. Statistics for any vector that has a corresponding mask value of 0 will not be calculated. SEE ALSO intro(1), verror(3), vgparms(3), vutils(3) RESTRICTIONS dstats cannot work on VFF_TYP_BIT If the -o (output VIFF file) option is specified, at least one statistic must be specified to be put in the output file If -all is true for the output VIFF file, but any other of the statistics flags is set, the -all flag is ignored Entropy and contrast are calculated only on VFF_TYP_BYTE files. For all other valid data types, entropy and contrast values are not computed and 0.0 is returned COPYRIGHT Copyright 1991, University of New Mexico. All rights reserved. ********************************************************************************* Documentation for avs module varviff INPUT image xvimage structure x value location in x direction (column index) y value location in y direction (row index) band band number of value Note that indexing begins at zero (0). OUTPUT value single data element of pixel value. Return Value: 1 on success, 0 on failure. DESCRIPTION varviff takes as input a viff data structure and extracts a single data value (image pixel or vector element) based upon the user indicated location (X, Y, and band number). The extracted data value is returned to the calling routine. When varviff is used with varviff(1), the data extracted can be referenced in any valid Cantata expression. Note that band and location numbering begins at zero (0). SEE ALSO varviff(1), intro(3), vipl(3), verror(3), vutils(3) RESTRICTIONS varviff currently only extreacts single values extract information from the viff header or from color map or loca- tion data. varviff Does not work on data types: VFF_TYP_BIT, VFF_TYP_COMPLEX. AUTHOR John Rasure and Carla Williams COPYRIGHT Copyright 1991, University of New Mexico. All rights reserved. ********************************************************************************* Documentation for avs module vfileinfo INPUT struct xvimage *image: VIFF image char *input_file: Name of the VIFF image FILE *printdev: Output File to output informations OUTPUT FILE *printdev: Holds the result. DESCRIPTION vfileinfo prints out the header information that describes the input image file. The output can be sent to stderr, stdout or a filename according to printdev. input_file is the name of the image that you want to know about. SEE ALSO vfileinfo(1), intro(3), vipl(3), verror(3), vutils(3) AUTHOR Argiro, Young, Neher, Rasure COPYRIGHT Copyright 1991, University of New Mexico. All rights reserved. ********************************************************************************* Dcoumentation for avs module vprdata INPUT img - input xvimage structure matflg - print image as a matrix (if set to one) else print image as a single column. input_file - name of file getting data on. OUTPUT printdev - data is printed in ascii format to the screen or a file according to printdev. DESCRIPTION vprdata prints image file data (viff) data to the screen or a file in ascii format. The image data can be printed as a matrix if the matflg flag is set to 1. The output device or file is specified with printdev, a filename of # will send the output to stderr. SEE ALSO vprdata(1), intro(3), vipl(3), verror(3), vutils(3) RESTRICTIONS vprdata will not print COMPLEX images in matrix format (just single column format). AUTHOR Mark Young, Tom Sauer, John Rasure COPYRIGHT Copyright 1991, University of New Mexico. All rights reserved. ********************************************************************************* Documentation for avs module vstats INPUT img1 (struct xvimage) - input xvimage structure img2 (struct xvimage) - gating or masking image mflag (int) - a flag set (equal 1) if gating image mask available process_dir (int) - 0 = vector processing, 1 = band, and 2 = calculate one set of stats for entire file. OUTPUT stats structure loaded with the values computed from the image. DESCRIPTION vstats calculates the mean, variance, standard deviation, rms, integral, positive and negative parts of the integral, skewness, kurtosis, entropy and contrast of img1. It also finds the minimum and maximum values and the positions of these values in the data, and gives the total number and the number of positive and negative contributing points. This statistics data is passed back through the array of vstat structures, stat. vstats returns a zero upon failure and a one upon success. img1 img1 is a pointer to the input xvimage struc- ture. vstats will reject images of type VFF_TYP_BIT. img2 img2 is a pointer to a masking image. This image must be of the same type, size, and have the same number of bands as img1. Pix- els in img1 corresponding to pixels in img2 which have a value of zero are masked out, and are not included in calculating the statistics. mflag mflag is a flag passed in which is TRUE if a masking image is being passed in. stats stats is a pointer to an array of struct vstat. All stat data is stored here and passed back to the calling routine through this structure. The number of vstat struc- tures in stats should correspond to the number of vectors in the input image if process_dir = 0, and the number of bands in the input file if process_dir = 1. process_dir Data can be processed in vector or band orientation, or the entire file can be pro- cessesed as a single raster. If process_dir = DSP_VECTOR = 0, the data stored in multi- band 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 changed so that each band is processed (instead of each vector) by setting process_dir = DSP_BAND = 1. If process_dir is set to 2, the entire data set, regardless of number of bands, is processed as a single raster of data. Calculation of Mean: mean = (1/N) * SUM xi Where N is the number of samples, SUM is the sum from i=0 to i=N-1, and xi is the sample value of x at i. Calculation of Variance: variance = (1/(N-1)) * (SUM (xi - mean)^2) Where N is the number of samples, SUM is the sum from i=0 to i=N-1, and xi is the sample value of x at i. Calculation of Standard Deviation: standard deviation = sqrt(variance) Calculation of RMS: RMS = sqrt ( (SUM xi^2)/N ) Where N is the number of samples, SUM is the sum from i=0 to i=N-1, and xi is the sample value of x at i. Calculation of Integral Values: total integral = SUM xi positive part of integral = SUM xi, for all xi >= 0 negative part of integral = SUM xi, for all xi < 0 Where N is the number of samples, SUM is the sum from i=0 to i=N-1, and xi is the sample value of x at i. Calculation of Skewness: Skewness is a measure of the tendency of the deviations from the mean to be larger in one direction than in the other, or, in other words, the asymmetry of a distribu- tion about its mean. A positive skew value signifies a distribution whose tail extends out towards more posi- tive x, and a negative tail signifies a distribution whose tail extends out towards more negative x. Popu- lation skewness is unitless and is defined as: E[((x-mean)/(stdev))^3], where stdev is the standard deviation of the data. vstats computes the sample skewness as: skew = 1/(stdev^3 * N) * { SUM (xi - mean)^3 } Where N is the number of samples, SUM is the sum from i=0 to i=N-1, and xi is the sample value of x at i. Calculation of Kurtosis: Kurtosis is a unitless measure of the tail heaviness of a distribution and is defined as: E[((x-mean)/(stdev))^4] - 3, where stdev is the standard deviation of the data. vstats computes the sample kurtosis as: kurtosis = ( 1/(stdev^4 * N) * { SUM (xi - mean)^4} ) - 3 Where N is the number of samples, SUM is the sum from i=0 to i=N-1, and xi is the sample value of x at i. Calculation of Entropy: entropy = - ( SUM (norm_hist * log2(norm_hist) ) ) where norm_hist = (num pixels with gray level x)/(total number pixels), SUM is the sum from i=0 to i=N-1, and N is the number of gray levels. Calculation of Contrast: contrast = SUM( (pixel_value^2) * norm_hist ) where norm_hist = (num pixels with gray level x)/(total number pixels), SUM is the sum from i=0 to i=N-1, and N is the number of gray levels. SEE ALSO vstats(1), intro(3), vipl(3), verror(3), vutils(3) RESTRICTIONS vstats cannot work on VFF_TYP_BIT. Entropy and contrast are calculated only on VFF_TYP_1_BYTE files. For all other valid data types, entropy and contrast values are returned as 0.0. AUTHOR Donna Koechner, John Rasure COPYRIGHT Copyright 1991, University of New Mexico. All rights reserved. *********************************************************************************