Initial commit

1 files changed, 138 insertions, 0 deletions

diff --git a/noao/imred/ccdred/doc/ccdmask.hlp b/noao/imred/ccdred/doc/ccdmask.hlp
new file mode 100644
index 00000000..190ef016
--- /dev/null
+++ b/noao/imred/ccdred/doc/ccdmask.hlp
@@ -0,0 +1,138 @@
+.help ccdmask Jun96 noao.imred.ccdred
+.ih
+NAME
+ccdmask -- create a pixel mask from a CCD image
+.ih
+USAGE	
+.nf
+ccdmask image mask
+.fi
+.ih
+PARAMETERS
+.ls image
+CCD image to use in defining bad pixels.  Typically this is
+a flat field image or, even better, the ratio of two flat field
+images of different exposure levels.
+.le
+.ls mask
+Pixel mask name to be created.  A pixel list image, .pl extension,
+is created so no extension is necessary.
+.le
+.ls ncmed = 7, nlmed = 7
+The column and line size of a moving median rectangle used to estimate the
+uncontaminated local signal.  The column median size should be at least 3
+pixels to span single bad columns.
+.le
+.ls ncsig = 15, nlsig = 15
+The column and line size of regions used to estimate the uncontaminated
+local sigma using a percentile.  The size of the box should contain
+of order 100 pixels or more.
+.le
+.ls lsigma = 6, hsigma = 6
+Positive sigma factors to use for selecting pixels below and above
+the median level based on the local percentile sigma.
+.le
+.ls ngood = 5
+Gaps of undetected pixels along the column direction of length less
+than this amount are also flagged as bad pixels.
+.le
+.ls linterp = 2
+Mask code for pixels having a bounding good pixel separation which is
+smaller along lines; i.e.  to use line interpolation along the narrower
+dimension.
+.le
+.ls cinterp = 3
+Mask code for pixels having a bounding good pixel separation which is
+smaller along columns; i.e.  to use columns interpolation along the narrower
+dimension.
+.le
+.ls eqinterp = 2
+Mask code for pixels having a bounding good pixel separation which is
+equal along lines and columns.
+.le
+.ih
+DESCRIPTION
+\fBCcdmask\fR makes a pixel mask from pixels deviating by a specified
+statistical amount from the local median level.  The input images may be of
+any type but this task was designed primarily for detecting column oriented
+CCD defects such as charge traps that cause bad columns and non-linear
+sensitivities.  The ideal input is a ratio of two flat fields having
+different exposure levels so that all features which would normally flat
+field properly are removed and only pixels which are not corrected by flat
+fielding are found to make the pixel mask.  A single flat field may also be
+used but pixels of low or high sensitivity may be included as well as true
+bad pixels.
+
+The input image is first subtracted by a moving box median.  The median is
+unaffected by bad pixels provided the median size is larger that twice
+the size of a bad region.  Thus, if 3 pixel wide bad columns are present
+then the column median box size should be at least 7 pixels.  The median
+box can be a single pixel wide along one dimension if needed.  This may be
+appropriate for spectroscopic long slit data.
+
+The median subtracted image is then divided into blocks of size
+\fInclsig\fR by \fInlsig\fR.  In each block the pixel values are sorted and
+the pixels nearest the 30.9 and 69.1 percentile points are found; this
+would be the one sigma points in a Gaussian noise distribution.  The
+difference between the two count levels divided by two is then the local
+sigma estimate.  This algorithm is used to avoid contamination by the bad
+pixel values.  The block size must be at least 10 pixels in each dimension
+to provide sufficient pixels for a good estimate of the percentile sigma.  The
+sigma uncertainty estimate of each pixel in the image is then the sigma
+from the nearest block.
+
+The deviant pixels are found by comparing the median subtracted residual to
+a specified sigma threshold factor times the local sigma above and below
+zero (the \fIlsigma\fR and \fIhsigma\fR parameters).  This is done for
+individual pixels and then for column sums of pixels (excluding previously
+flagged bad pixels) from two to the number of lines in the image.  The sigma
+of the sums is scaled by the square root of the number of pixels summed so
+that statistically low or high column regions may be detected even though
+individual pixels may not be statistically deviant.  For the purpose of
+this task one would normally select large sigma threshold factors such as
+six or greater to detect only true bad pixels and not the extremes of the
+noise distribution.
+
+As a final step each column is examined to see if there are small
+segments of unflagged pixels between bad pixels.  If the length
+of a segment is less than that given by the \fIngood\fR parameter
+all the pixels in the segment are also marked as bad.
+
+The bad pixel mask is created with good pixels identified by zero values
+and the bad pixels by non-zero values.
+The nearest good pixels along the columns and lines for
+each bad pixel are located and the separation along the columns and lines
+between those pixels is computed.  The smaller separation is used to select
+the mask value.  If the smaller separation is along lines the \fIlinterp\fR
+value is set, if the smaller separation is along columns the \fIcinterp\fR
+value is set, and if the two are equal the \fIeqinterp\fR value is set.
+The purpose of this is to allow interpolating across bad pixels using the
+narrowest dimension.  The task \fBfixpix\fR can select the type of pixel
+replacement to use for each mask value.  So one can chose, for example,
+line interpolation for the linterp values and the eqinterp values, and
+column interpolation for the cinterp values.
+
+In addition to this task, pixel mask images may be made in a variety of
+ways.  Any task which produces and modifies image values may be used.  Some
+useful tasks are \fBimexpr, imreplace, imcopy, text2mask\fR and
+\fBmkpattern\fR.  If a new image is specified with an explicit ".pl"
+extension then the pixel mask format is produced.
+.ih
+EXAMPLES
+1.  Two flat fields of exposures 1 second and 3 seconds are taken,
+overscan and zero corrected, and trimmed.  These are then used
+to generate a CCD mask.
+
+.nf
+    cl> imarith flat1 / flat2 ratio
+    cl> ccdmask ratio mask
+.fi
+.ih
+REVISIONS
+.ls CCDMASK V2.11
+This task is new.
+.le
+.ih
+SEE ALSO
+imreplace, imexpr, imcopy, imedit, fixpix, text2mask
+.endhelp