Initial commit

1 files changed, 121 insertions, 0 deletions

diff --git a/pkg/images/imutil/doc/imstat.hlp b/pkg/images/imutil/doc/imstat.hlp
new file mode 100644
index 00000000..ed5183d9
--- /dev/null
+++ b/pkg/images/imutil/doc/imstat.hlp
@@ -0,0 +1,121 @@
+.help imstatistics Feb01 images.imutil
+.ih
+NAME
+imstatistics -- compute and print image pixel statistics
+.ih
+USAGE	
+imstatistics images
+.ih
+PARAMETERS
+.ls images
+The input images or image sections for which pixel statistics are to be
+computed.
+.le
+.ls fields = "image,npix,mean,stddev,min,max"
+The statistical quantities to be computed and printed.
+.le
+.ls lower = INDEF
+The minimum good data limit.  All pixels are above the default value of INDEF.
+.le
+.ls upper = INDEF
+The maximum good data limit.  All pixels are above the default value of INDEF.
+.le
+.ls nclip = 0
+The maximum number of iterative clipping cycles. By default no clipping is
+performed.
+.le
+.ls lsigma = 3.0
+The low side clipping factor in sigma.
+.le
+.ls usigma = 3.0
+The high side clipping factor in sigma.
+.le
+.ls binwidth = 0.1
+The width of the histogram bins used for computing the midpoint (estimate
+of the median) and the mode.
+The units are in sigma.
+.le
+.ls format = yes
+Label the output columns and print the result in fixed format. If format
+is "no" no column labels are printed and the output is in free format.
+.le
+.ls cache = no
+Cache the image data in memory ? This can increase the efficiency of the
+task if nclip > 0 or either of the midpt and mode statistics are computed.
+.le
+.ih
+DESCRIPTION
+The statistical quantities specified by the parameter \fIfields\fR are
+computed and printed for each image in the list specified by \fIimages\fR.
+The results are printed in tabular form with the fields listed in the order
+they are specified in the fields parameter. The available fields are the
+following.
+
+.nf
+	 image - the image name
+	  npix - the number of pixels used to do the statistics
+	  mean - the mean of the pixel distribution
+	 midpt - estimate of the median of the pixel distribution
+	  mode - the mode of the pixel distribution
+	stddev - the standard deviation of the pixel distribution
+	  skew - the skew of the pixel distribution
+      kurtosis - the kurtosis of the pixel distribution
+	   min - the minimum pixel value
+	   max - the maximum pixel value
+.fi
+
+The mean, standard deviation, skew, kurtosis, min and max are computed in a
+single pass through the image using the expressions listed below.
+Only the quantities selected by the fields parameter are actually computed.
+
+.nf
+          mean = sum (x1,...,xN) / N
+	     y = x - mean
+      variance = sum (y1 ** 2,...,yN ** 2) / (N-1)
+        stddev = sqrt (variance)
+          skew = sum ((y1 / stddev) ** 3,...,(yN / stddev) ** 3) / (N-1)
+      kurtosis = sum ((y1 / stddev) ** 4,...,(yN / stddev) ** 4) / (N-1) - 3
+.fi
+
+The midpoint and mode are computed in two passes through the image. In the
+first pass the standard deviation of the pixels is calculated and used
+with the \fIbinwidth\fR parameter to compute the resolution of the data
+histogram. The midpoint is estimated by integrating the histogram and
+computing by interpolation the data value at which exactly half the
+pixels are below that data value and half are above it. The mode is
+computed by locating the maximum of the data histogram and fitting the
+peak by parabolic interpolation.
+
+.ih
+EXAMPLES
+1. To find the number of pixels, mean, standard deviation and the minimum
+and maximum pixel value of a bias region in an image.
+
+.nf
+    cl> imstat flat*[*,1]
+    #      IMAGE      NPIX      MEAN    STDDEV       MIN       MAX
+      flat1[*,1]       800     999.5     14.09      941.     1062.
+      flat2[*,1]       800     999.4     28.87      918.     1413.
+.fi
+
+The string "flat*" uses a wildcard to select all images beginning with the
+word flat.  The string "[*,1]" is an image section selecting row 1.
+
+2. Compute the mean, midpoint, mode and standard deviation of a pixel
+distribution.
+
+.nf
+    cl> imstat m51 fields="image,mean,midpt,mode,stddev"
+    #      IMAGE    PIXELS      MEAN     MIDPT     MODE     STDDEV
+	     M51    262144     108.3     88.75    49.4       131.3
+.fi
+
+.ih
+BUGS
+When using a very large number of pixels the accumulation of the sums
+of the pixel values to the various powers may
+encounter roundoff error.  This is significant when the true standard
+deviation is small compared to the mean.
+.ih
+SEE ALSO
+.endhelp