A unit is defined by the settings of the -w,-h,-d,-t,-e and -whole options. For example, if it is desired to compute an independent histogram for each WxH plane of a WHDTE=(512,480,1,1,256) object, then the unit we want is specified by supplying -w and -h and there will be 256 columns in the output object, each column being the histogram of a WxH plane. If we want a single histogram for the whole data object, then we can obtain that result by supplying -whole, or -w -h -e, or -w -h -d -t -e since these combinations all cause the histogram unit to span all of the data. In this case the output object will have only a single column representing the histogram of the whole data set.
Histograms are stored in the output data object as column vectors in the WxH plane, one column per histogram unit. The computed histograms are stored in the order in which the units are accessed in the index order assigned to the value segment of the input data object. For example, for a value segment with WHDTE=(512,126,48,1,1), with a HxD unit (specified by -h -d) and the default index order (WHDTE), then there will be 512 columns in the output object. The histogram for the HxD plane at (0,x,x,0,0) will be stored in column #0; that for the HxD plane at (1,x,x,0,0) will be stored in column #1, and that for the HxD plane at (N,x,x,0,0) will be stored in column #N.
Within each column, the count computed for bin #M is stored in row #M.
The histogram structure is specified by three parameters:
min side of minimum bin (starting value) This number specifies the most negative number that can be trapped in the histogram array. Another way to define it is as the lower edge of first histogram bin.
binwidth This is the width of each histogram bin.
bins This is the total number of bins to be used in the histogram.
Values are assigned to bin index [0...bins-1] using the following procedure:
With this arrangement, a bin collects input values ranging from the value of the left edge inclusively up to the value of the right edge exclusively. The exception is the last bin which collects values between the left and right edges inclusively (for both edges). If the computed bin_num falls outside of the array, then that data point is ignored in the histogram unless the -oob (append out-of-bounds bins) flag is supplied (described below).bin_num = (input_val - mina) / binwidth
if (input_val == min + bins*binwidth) bin_num = bins - 1
If the input data object has a mask, then data points marked as invalid by the mask are ignored in the histogram calculations.
If a gate object is supplied, then only those data points with a value corresponding to non-zero in the gate image will be histogrammed. If a a gate object is supplied and the input has a mask, then data points are ignored if masked or marked for "ignore" by the gate object. The gate object must have the same value segment dimensions as the input object.
If the input data object has a map, then the data can be optionally pulled through the map before histogramming depending on the setting of the -map flag. If the input object has a map and -map is supplied, then the data will be pulled through the map before histogramming, potentially greatly multiplying the size of the data set. If the input object has a map and -map is not supplied, then the histogram operation will be carried out on the map indices since that is what is stored in the data (this may be useful for data that has been pseudocolored, for example).
If the out-of-bounds flag (-oob) is supplied, then two additional bins will be placed at the end of the histogram. The first one will contain the number of data values that fell outside of the histogram array on the low (more negative) side, and the second will contain the number of data values that fell outside the histogram array on the high (more positive) side. This option is useful when little is known about the range of the data and one is not sure if the specified range of the histogram array is capturing all of the data.
The optional integrated histogram output object conforms to the same size and structure as the histogram output object except that it is of data type KDOUBLE and each histogram has been integrated. The integrated histograms can optionally be normalized (each histogram independently) to the range [0..1].
khisto utilizes data services internally and can process large data sets. All internal calculations are done in double precision. All input data is converted to KDOUBLE by data services after being read from the input data object. The output histogram data object is of type KULONG. Complex input data is converted before histogramming by taking the real part.
Mutually Exclusive Group; if desired, specify ONE of:
OR
AT LEAST ONE OF the Group:
AND/OR
AND/OR
AND/OR
AND/OR
% khisto -i clouds.seq -o h.clouds -w -h -min 0
-binwidth 1 -bins 256
will construct an interesting histogram data set from the cloud sequence. This sequence is comprised of a set of 582 512x480 frames, taken 15 seconds apart, stored as WHDTE=(512,480,1,582,1). Each frame views the same section of sky as a storm develops. The output is best visualized using editimage with the SA pseudocolor option turned on. Here, the columns of the output image are for the frames in time order, so it is easy to see how the storm phases develop, modulate, and peak during this period.
If the input data is complex, then you may want to convert it yourself using whatever means you require; the default for complex input is to take only the real part.