lvstats(3)

LIBRARY ROUTINE
lvstats - lvstats computes the mean, variance, standard deviation, RMS level, peaks with locations, integral, skew, kurtosis, entropy, and contrast for an input xviff image.

LIBRARY CALL
#include "vinclude.h"
int
lvstats(img1,img2,mflag,stats,process_dir)
struct xvimage  *img1,*img2;
int             mflag, process_dir;
struct lvstat   **stats;

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.

MODIFICATIONS
Audit Done 05-OCT-90 Donna Koechner

06-OCT-90: Fixed fmin,fmax initialization bug in calculate_byte(). Donna Koechner

Tue Mar 5 1991 - changed method of calculating variance, stddev, skew and kurtosis. Donna Koechner

DESCRIPTION
lvstats 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 lvstat structures, stat.

lvstats returns a zero upon failure and a one upon success.

img1
    img1 is a pointer to the input xvimage structure. lvstats 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. Pixels 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 lvstat. All stat data is stored here and passed back to the calling routine through this structure. The number of lvstat structures 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 processesed as a single raster. If process_dir = DSP_VECTOR = 0, the 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 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 distribution about its mean. A positive skew value signifies a distribution whose tail extends out towards more positive x, and a negative tail signifies a distribution whose tail extends out towards more negative x. Population skewness is unitless and is defined as:

    E[((x-mean)/(stdev))^3],

    where stdev is the standard deviation of the data. lvstats 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. lvstats 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
lvstats 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.