Repatch (from linux) of OSX IRAF

9 files changed, 1087 insertions, 0 deletions

diff --git a/noao/imred/crutil/doc/cosmicrays.hlp b/noao/imred/crutil/doc/cosmicrays.hlp
new file mode 100644
index 00000000..55a284da
--- /dev/null
+++ b/noao/imred/crutil/doc/cosmicrays.hlp
@@ -0,0 +1,306 @@
+.help cosmicrays Apr98 noao.imred.crutil
+.ih
+NAME
+cosmicrays -- detect and replace cosmic rays
+.ih
+USAGE
+cosmicrays input output
+.ih
+PARAMETERS
+.ls input
+List of input images in which to detect cosmic rays.
+.le
+.ls output
+List of output images in which the detected cosmic rays will be replaced
+by an average of neighboring pixels.  If the output image name differs
+from the input image name then a copy of the input image is made with
+the detected cosmic rays replaced.  If no output images are specified
+then the input images are modified in place.  In place modification of
+an input image also occurs when the output image name is the same as
+the input image name.
+.le
+.ls crmasks = ""
+List of cosmic ray mask files to be created; one for each input image.  If no
+file names are given then no cosmic ray mask is created.  If an existing
+mask is specified the newly detected cosmic rays will be added.
+.le
+
+.ls threshold = 25.
+Detection threshold above the mean of the surrounding pixels for cosmic
+rays.  The threshold will depend on the noise characteristics of the
+image and how weak the cosmic rays may be for detection.  A typical value
+is 5 or more times the sigma of the background.
+.le
+.ls fluxratio = 2.
+The ratio (as a percent) of the mean neighboring pixel flux to the candidate
+cosmic ray pixel for rejection.  The value depends on the seeing and the
+characteristics of the cosmic rays.  Typical values are in the range
+2 to 10 percent.  This value may be reset interactively from a plot
+or defined by identifying selected objects as stars or cosmic rays.
+.le
+.ls npasses = 5
+Number of cosmic ray detection passes.  Since only the locally strongest
+pixel is considered a cosmic ray, multiple detection passes are needed to
+detect and replace cosmic ray events with multiple neighboring pixels.
+.le
+.ls window = 5
+Size of cosmic ray detection window.  A square window of either 5 by 5 or
+7 by 7 is used to detect cosmic rays.  The smaller window allows detection
+in the presence of greater background gradients but is less sensitive at
+discriminating multiple event cosmic rays from stars.  It is also marginally
+faster.
+.le
+.ls interactive = yes
+Examine parameters interactively?  A plot of the mean flux within the
+detection window (x100) vs the flux ratio (x100) is plotted and the user may
+set the flux ratio threshold, delete and undelete specific events, and
+examine specific events.  This is useful for new data in which one is
+uncertain of an appropriate flux ratio threshold.  Once determined the
+task need not be used interactively.
+.le
+.ls train = no
+Define the flux ratio threshold by using a set of objects identified
+as stars (or other astronomical objects) or cosmic rays?
+.le
+.ls objects = ""
+Cursor list of coordinates of training objects.  If null (the null string "")
+then the image display cursor will be read.  The user is responsible for first
+displaying the image.  Otherwise a file containing cursor coordinates
+may be given.  The format of the cursor file is "x y wcs key" where
+x and y are the pixel coordinates, wcs is an arbitrary number such as 1,
+and key may be 's' for star or 'c' for cosmic ray.
+.le
+.ls savefile = ""
+File to save (by appending) the training object coordinates.  This is of
+use when the objects are identified using the image display cursor.  The
+saved file can then be input as the object cursor list for repeating the
+execution.
+.le
+.ls plotfile
+If a plot file is specified then the graph of the flux ratio (x100) vs
+the mean flux (x100) is recorded as metacode.  This may be spooled or examined
+later.
+.le
+.ls graphics = "stdgraph"
+Interactive graphic output device for interactive examination of the
+detection parameters.
+.le
+.ls cursor = ""
+Interactive graphics cursor input.  If null the graphics display cursor
+is used, otherwise a file containing cursor input may be specified.
+.le
+.ls answer
+This parameter is used for interactive queries when processing a list of
+images.  The responses may be "no", "yes", "NO", or "YES".  The upper case
+responses permanently enable or disable the interactive review while
+the lower case reponses allow selective examination of certain input
+images.  \fIThis parameter should not be specified on the command line.
+If it is then the value will be ignored and the task will act as if
+the answer "yes" is given for each image; i.e. it will enter the interactive
+phase without prompting.\fR
+.le
+.ih
+IMAGE CURSOR COMMANDS
+
+.nf
+?	Help
+c	Identify the object as a cosmic ray
+s	Identify the object as a star
+g	Switch to the graphics plot
+q	Quit and continue with the cleaning
+.fi
+
+GRAPHICS CURSOR COMMANDS
+
+.nf
+?	Help
+a	Toggle between showing all candidates and only the training points
+d	Mark candidate for replacement (applys to '+' points)
+e	Mark candidates in a region for replacement (applys to '+' points)
+q	Quit and return to image cursor or replace the selected pixels
+r	Redraw the graph
+s	Make a surface plot for the candidate nearest the cursor
+t	Set the flux ratio threshold at the y cursor position
+u	Mark candidate to not be replaced (applys to 'x' points)
+v	Mark candidates in a region to not be replaced (applys to 'x' points)
+w	Adjust the graph window (see \fBgtools\fR)
+<space>	Print the pixel coordinates
+.fi
+
+There are no colon commands except those for the windowing options (type
+:\help or see \fBgtools\fR).
+.ih
+DESCRIPTION
+Cosmic ray events in each input image are detected and replaced by the
+average of the four neighbors.  The replacement may be performed
+directly on the input image if no output image is specified or if the
+output image name is the same as the input image name.  If a new image
+is created it is a copy of the input image except for the replaced
+pixels.  
+Optional output includes
+a plot file showing the parameters of the
+detected cosmic ray candidates and the flux ratio threshold used, a
+cosmic ray mask identifying the cosmic rays found, and
+a file of training objects marked with the image display cursor.  The
+cosmic ray mask may be used for display purposes, combined with other
+masks, and with \fBcrfix\fR.
+
+This task may be applied to an image previously processed to detect
+additional cosmic rays.
+
+The cosmic ray detection algorithm consists of the following steps.
+First a pixel must be the brightest pixel within the specified
+detection window (either 5x5 or 7x7).  The mean flux in the surrounding
+pixels with the second brightest pixel excluded (which may also be a
+cosmic ray event) is computed and the candidate pixel must exceed this
+mean by the amount specified by the parameter \fIthreshold\fR.  A plane
+is fit to the border pixels of the window and the fitted background is
+subtracted.  The mean flux (now background subtracted) and the ratio of
+this mean to the cosmic ray candidate (the brightest pixel) are
+computed.  The mean flux (x100) and the ratio (x100) are recorded for
+interactive examination if desired.
+
+Once the list of cosmic ray candidates has been created and a threshold for
+the flux ratio established (by the parameter \fIfluxratio\fR, by the
+"training" method, or by using the graphics cursor in the interactive plot)
+the pixels with ratios below the threshold are replaced in the output by
+the average of the four neighboring pixels (with the second strongest pixel
+in the detection window excluded if it is one of these pixels).  Additonal
+pixels may then be detected and replaced in further passes as specified by
+the parameter \fInpasses\fR.  Note that only pixels in the vicinity of
+replaced pixels need be considered in further passes.
+
+The division between the peaks of real objects and cosmic rays is made
+based on the flux ratio between the mean flux (excluding the center
+pixel and the second strongest pixel) and the candidate pixel.  This
+threshold depends on the point spread function and the distribution of
+multiple cosmic ray events and any additional neighboring light caused
+by the events.  This threshold is not strongly coupled to small changes
+in the data so that once it is set for a new type of image data it may
+be used for similar images.  To set it initially one may examine the
+scatter plot of the flux ratio as a function of the mean flux.  This
+may be done interactively or from the optional plot file produced.
+
+After the initial list of cosmic ray candidates has been created and before
+the final replacing cosmic rays there are two optional steps to allow
+examining the candidates and setting the flux ratio threshold dividing
+cosmic rays from real objects.  The first optional step is define the flux
+ratio boundary by reference to user specified classifications; that is
+"training".  To do this step the \fItrain\fR parameter must be set to yes.
+The user classified objects are specified by a cursor input list.  This
+list can be an actual file or the image display cursor as defined by the
+\fIobjects\fR parameter.  The \fIsavefile\fR parameter is also used during
+the training to record the objects specified.  The parameter specifies a
+file to append the objects selected.  This is useful when the objects are
+defined by interactive image cursor and does not make much sense when using
+an input list.
+
+If the \fIobjects\fR parameter is specified as a null string then
+the image display cursor will be repeatedly read until a 'q' is
+entered.  The user first displays the image and then when the task
+reads the display cursor the cursor shape will change.  The user
+points at objects and types 's' for a star (or other astronomical
+object) and 'c' for a cosmic ray.  Note that this input is used
+to search for the matching object in the cosmic ray candidate list
+and so it is possible the selected object is not in the list though
+it is unlikely.  The selection will be quietly ignored in that case.
+To exit the interactive selection of training objects type 'q'.
+
+If 'g' is typed a graph of all the candidates is drawn showing
+"flux" vs. "flux ratio" (see below for more).  Training objects will
+be shown with a box and the currently set flux ratio threshold will
+also be shown.  Exiting the plot will return to entering more training
+objects.  The plot will remain and additional objects will immediately
+be shown with a new box.  Thus, if one wants to see the training
+objects identified in the plot as one selects them from the image
+display first type a 'g' to draw the initial plot.  Also by switching
+to the plot with 'g' allows you to draw surface plots (with 's') or
+get the pixel coordinates of a candidate (the space key) to be
+found in the display using the coordinate readout of the display.
+Note that the display interaction is simpler than might be desired
+because this task does not directly connect to the display.
+
+The most likely use for training is with the interactive image display.
+However one may prepare an input list by other means, one example
+is with \fBrimcursor\fR, and then specify the file name.  The savefile
+may also be used a cursor input to repeat the cosmic ray operation
+(but be careful not to have the cursor input and save file be the
+same file!).
+
+The flux ratio threshold is determined from the training objects by
+finding the point with the minimum number of misclassifications
+(stars as cosmic rays or cosmic rays as stars).  The threshold is
+set at the lowest value so that it will always go through one of
+the cosmic ray objects.  There should be at least one of each type
+of object defined for this to work.  The following option of
+examining the cosmic ray candidates and parameters may still be
+used to modify the derived flux ratio threshold.  One last point
+about the training objects is that even if some of the points
+lie on the wrong side of the threshold they will remain classified
+as cosmic ray or non-cosmic ray.  In other words, any object
+classified by the user will remain in that classification regardless
+of the final flux ratio threshold.
+
+After the training step the user will be queried to examine the candidates
+in the flux vs flux ratio plane if the \fIinteractive\fR flag is set.
+Responses may be made for specific images or for all images by using
+lower or upper case answers respectively.  When the parameters are
+examined interactively the user may change the flux ratio threshold
+('t' key).  Changes made are stored in the parameter file and, thus,
+learned for further images.  Pixels to be deleted are marked by crosses
+and pixels which are peaks of objects are marked by pluses.  The user
+may explicitly delete or undelete any point if desired but this is only
+for special cases near the threshold.  In the future keys for
+interactive display of the specific detections will be added.
+Currently a surface plot of any candidate may be displayed graphically
+in four 90 degree rotated views using the 's' key.  Note that the
+initial graph does not show all the points some of which are clearly
+cosmic rays because they have negative mean flux or flux ratio.  To
+view all data one must rewindow the graph with the 'w' key or ":/"
+commands (see \fBgtools\fR).
+.ih
+EXAMPLES
+1. To replace cosmic rays in a set of images ccd* without training:
+
+.nf
+    cl> cosmicrays ccd* new//ccd*
+    ccd001: Examine parameters interactively? (yes):
+    [A scatter plot graph is made.  One can adjust the threshold.]
+    [Looking at a few points using the 's' key can be instructive.]
+    [When done type 'q'.]
+    ccd002: Examine parameters interactively? (yes): NO
+    [No further interactive examination is done.]
+.fi
+
+After cleaning one typically displays the images and  possibly blinks them.
+A difference image or mask image may also be created.
+
+2. To use the interactive training method for setting the flux ratio threshold:
+
+.nf
+    # First display the image.
+    cl> display ccd001 1
+    z1 = 123.45 z2= 543.21
+    cl> cosmicrays ccd001 ccd001cr train+
+    [After the cosmic ray candidates are found the image display
+    [cursor will be activated.  Mark a cosmic ray with 'c' and
+    [a star with 's'.  Type 'g' to get a plot showing the two
+    [points with boxes.  Type 'q' to go back to the image display.
+    [As each new object is marked a box will appear in the plot and
+    [the threshold may change.  To find the location of an object
+    [seen in the plot use 'g' to go to the graph, space key to find
+    [the pixel coordinates, 'q' to go back to the image display,
+    [and the image display coordinate box to find the object.
+    [When done with the training type 'q'.
+    ccd001: Examine parameters interactively? (yes): no
+.fi
+
+3.  To create a mask image a bad pixel file must be specified.
+
+.nf
+    cl> cosmicrays ccd001 ccd001 crmask=crccd001
+.fi
+.ih
+SEE ALSO
+crmedian, crnebula, crgrow, crfix, credit, gtools, imedit, rimcursor
+.endhelp
diff --git a/noao/imred/crutil/doc/craverage.hlp b/noao/imred/crutil/doc/craverage.hlp
new file mode 100644
index 00000000..bd4ef7c9
--- /dev/null
+++ b/noao/imred/crutil/doc/craverage.hlp
@@ -0,0 +1,232 @@
+.help craverage Apr98 noao.imred.crutil
+.ih
+NAME
+craverage -- detect CRs and objects using average filter
+.ih
+SYNOPSIS
+\fBCraverage\fR detects cosmic rays and objects using a moving block
+average filter with the central pixel plus some number of additional high
+pixels  excluded and a median of an annulus around the block average box.
+It avoids identification of the cores of objects as cosmic rays by
+excluding pixels within the detected objects as cosmic ray candidates.
+.ih
+USAGE   
+.nf
+craverage input output
+.fi
+.ih
+PARAMETERS
+.ls input
+List of input images in which to detect cosmic rays and objects.
+.le
+.ls output
+List of output images in which cosmic rays are replaced by the block average
+value excluding the cosmic ray.  If no output image name is given then
+no output image will be created.
+.le
+.ls crmask = ""
+List of input and output cosmic ray and object masks.  If the mask exists
+then the mask values are used to exclude data pixels from the calculations
+and zero mask values are candidates for cosmic rays or objects.
+Detected cosmic rays and objects are identified in the mask with values
+given by the \fIcrval\fR and \fIobjval\fR parameters.  If no output cosmic
+ray mask is given then no mask will be created.
+.le
+.ls average = ""
+List of output block average filtered images.  If no image name is given
+then no image will be created.
+.le
+.ls sigma = ""
+List of output sigma images.  If no image name is given then no image
+will be created.
+.le
+
+.ls navg = 5 (minimum of 3)
+Square block average filter size given as the number of pixels along an
+edge.  The value will be rounded up to an odd value to be symmetrical
+around the center pixel excluded from the average.
+.le
+.ls nrej = 0 (minimum of 0)
+Number of additional highest pixels to exclude, in addition to the
+central pixel, in the block average.  The value should be small but it
+is needed to deal with cosmic rays that are bigger than a single pixel.
+.le
+.ls nbkg = 5 (minimum of 1)
+Background annulus width around the box average filter in pixels.  The
+median of the pixels in this annulus is used to estimate the background.
+.le
+.ls nsig = 25 (minimum of 10)
+Square box size for empirical sigma estimates given as the number of
+pixels along an edge.  The sigma is estimated using percentile points
+of the pixels in the box.  The size of the box should contain
+of order 100 pixels or more.
+.le
+.ls var0 = 0., var1 = 0., var2 = 0.
+Variance coefficients for the variance model.  The variance model is
+
+.nf
+    variance = var0 + var1 * data + var2 * data^2
+.fi
+
+where data is the maximum of zero and the average filtered pixel value and
+the variance is in data numbers.  All the coefficients must be positive or
+zero.  If they are all zero then empirical data sigmas are estimated by a
+percentile method in boxes of size given by \fInsig\fR.
+.le
+
+.ls crval = 1
+Mask value for detected cosmic rays.  It is legal for the value to be
+zero to not mark the cosmic rays in the output mask.
+.le
+.ls lcrsig = 10., hcrsig = 5.
+Low and high sigma factors for detecting cosmic rays.  These factors
+multiply the computed or estimated sigma at each pixel and these threshold
+values are compared to the difference between the candidate pixel and the
+block average filter value (average of box around the pixel).  This only
+applies to pixels where the block average filter value is within a
+specified threshold of the background estimate; i.e. the average value is
+not considered as part of an object.
+.le
+.ls crgrow = 0.
+Cosmic ray growing radius.  Pixels detected and marked in the output cosmic
+ray mask by the \fIcrval\fR value are increased in size in the mask (but
+not replaced in the output image) by also flagging all zero valued mask
+pixels within this specified radius with the cosmic ray mask value.  This
+is done after the detection phase is complete.  The separation between
+pixels is the distance between pixel centers computed as a real value.
+Note a value of at least one is required to affect other mask pixels.
+.le
+
+.ls objval = 0
+Mask value for detected objects.  It is legal for the value to be
+zero to not mark the objects in the output mask.
+.le
+.ls lobjsig = 10., hobjsig = 5.
+Low and high sigma factors for detecting objects.  These factors multiply
+the computed or estimated sigma at each pixel and these threshold values
+are compared to the difference between the block average filter value and
+the background annulus median.  If the values are made very large then
+object detection can be eliminated and cosmic rays will be detected
+everywhere.
+.le
+.ls objgrow = 0.
+Object detection growing radius.  Pixels detected and marked in the output
+mask by the \fIobjval\fR value are increased in size in the mask by also
+flagging all zero valued mask pixels within this specified radius with the
+cosmic ray mask value.  This is done after the detection phase is complete
+and so object grown pixels are not used in excluding cosmic ray
+candidates.  The separation between pixels is the distance between pixel
+centers computed as a real value.  Note a value of at least one is
+required to affect other mask pixels.
+.le
+.ih
+DESCRIPTION
+\fBCraverage\fR detects cosmic rays and objects using a moving block
+average filter with the central pixel and a specified number of additional
+highest pixels excluded and a median of an annulus around the block average
+box.  It avoids identification of the cores of objects as cosmic rays by
+excluding pixels within the detected objects as cosmic ray candidates.
+
+The block average filter computes the average of pixels in a box with the
+central or target pixel excluded.  In addition the \fInrej\fR parameter can
+be used to exclude that number of highest remaining pixels as possible
+contamination from cosmic rays which are larger than one pixel or possibly
+a very nearby additional cosmic ray.  The \fInrej\fR value should be kept
+small relative to the total number of pixels in the average so that the
+average will still be elevated over the median in real underlying objects.
+The resulting average is used as the prediction for the value of the target
+pixel.  The median of the pixels in a square background annulus around the
+block average box provides the prediction for the background at the target
+pixel.
+
+The target pixel is considered part of an object if the difference between
+the average value and the median background exceeds a specified threshold.
+If the pixel is NOT considered to be part of an object then if the
+difference between the pixel value and the average value exceeds a
+different specified threshold it is identified as a cosmic ray.
+
+The thresholds are defined in terms of sigma factors, which may be
+different for positive and negative deviations and for object and
+cosmic ray identification.  The sigma factors multiply an estimate
+for the statistical sigma of the target pixel.  The estimate is
+either based on a noise model or sigma of pixels in a box near the
+target pixel.
+
+The \fIcrmask\fR parameter specifies a pixel mask for the image.  If the
+mask exists then non-zero mask values will be used to exclude pixels from
+the average, background median, and empirical sigma estimates.  Also any
+pixels with non-zero mask values will not be altered either in the output
+image or in the final mask.  If the  mask does not exist then it behaves as
+if all mask values are zero.  If all pixels in the average box or median
+annulus are previously flagged then the estimates will be undefined and
+nothing will be done to the output image or mask.  Because the task can
+use an input mask to mark pixels not to be considered it can be used
+in an iterative fashion.
+
+The noise model is given by the formula
+
+.nf
+    variance = var0 + var1 * data + var2 * data^2
+.fi
+
+where data is the maximum of zero and the average estimate for the target
+pixel.  The coefficients are all given in terms of the data numbers.  This
+model can be related to common detector parameters.  For CCDs var0 is the
+readout noise expressed as a variance in data numbers and var1 is the
+inverse gain (DN/electrons).  The second order coefficient has the
+interpretation of flat field introduced variance.
+
+If all the coefficients are zero then an empirical sigma is estimated as
+follows.  The input image is divided into square blocks of size
+\fInsig\fR.  The (unmasked) pixel values in a block are sorted and the
+pixel values nearest the 15.9 and 84.1 percentiles are selected.  These are
+the one sigma points in a Gaussian distribution.  The sigma estimate is the
+difference of these two values divided by two.  This algorithm is used to
+avoid contamination of the sigma estimate 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 points.  The sigma
+estimate for a pixel is the sigma from the nearest block.  A moving box is
+not used for reasons of efficiency.
+
+If an output image name is specified then the output image is produced as a
+copy of the input image but with the identified cosmic ray pixels replaced
+by the average predicted value.  Other optional output images are
+the average filtered values and the sigma values.
+
+If a mask is specified the detected cosmic rays will be identified with
+values given by the \fIcrval\fR parameter and object pixels will be
+identified with values given by the \fIobjval\fR parameter.  Note that one
+does not need to use an output image and the cosmic rays can be replaced by
+interpolation in the data using the tasks \fIcrfix\fR, \fIfixpix\fR, or
+\fIccdproc\fR.
+
+One final step may be applied to the output mask.  The mask values
+identified with the \fIcrval\fR and \fIobjval\fR values may be grown
+by identifying pixel values within a specified radius with the same
+mask value.  Note that this step is done at the end and so any pixels
+in a preexisting input mask with the same values will also be grown.
+Also the grown pixels will not affect the output cosmic ray replaced
+image.  See \fIcrgrow\fR for a further discussion.
+.ih
+EXAMPLES
+This example illustrates using the \fBcraverage\fR task to
+create a mask with cosmic rays and objects identified and displayed.
+The image is a CCD image with a readout noise of 5 electrons
+and a gain of 3 electrons per data number.  This implies variance
+model coefficients of
+
+.nf
+    var0 = (5/3)^2 = 2.78
+    var1 = 1/3 = 0.34
+.fi
+
+.nf
+    cl> display obj001 1                  # Display in first frame
+    cl> craverage obj001 "" crmask=mask001 var0=2.78 var1=0.34\
+    >>> crval=1 objval=2
+    cl> display crobj001 2 overlay=mask001 ocol="1=green,2=red"
+.fi
+.ih
+SEE ALSO
+cosmicrays, crnebula, median, crfix, crgrow, crmedian
+.endhelp
diff --git a/noao/imred/crutil/doc/crcombine.hlp b/noao/imred/crutil/doc/crcombine.hlp
new file mode 100644
index 00000000..3dddaebe
--- /dev/null
+++ b/noao/imred/crutil/doc/crcombine.hlp
@@ -0,0 +1,35 @@
+.help crcombine Apr98 noao.imred.crutil
+.ih
+NAME
+crcombine -- combine multiple exposures to eliminate cosmic rays
+.ih
+USAGE	
+.nf
+crcombine input output
+.fi
+.ih
+PARAMETERS
+See parameters for \fBimcombine\fR.
+.ih
+DESCRIPTION
+This task is a version of \fBimcombine\fR.  See the help for that task
+for a description of the parameters and algorithms.
+
+For the purpose of removing cosmic rays the most useful options
+are the "crreject" algorithm and/or combining with a median.  Many other
+options may work as well.  The best use of this task depends on the
+number of images available.  If there are more than a few images the
+images should be combined with an "average" and using a rejection
+algorithm.
+.ih
+EXAMPLES
+1.  To combine two images using the gain and read noise parameters in
+the image header:
+
+.nf
+    cl> crcombine obj012,obj013 abc gain=gain rdnoise=rdnoise 
+.fi
+.ih
+SEE ALSO
+imcombine
+.endhelp
diff --git a/noao/imred/crutil/doc/credit.hlp b/noao/imred/crutil/doc/credit.hlp
new file mode 100644
index 00000000..f038e5c1
--- /dev/null
+++ b/noao/imred/crutil/doc/credit.hlp
@@ -0,0 +1,39 @@
+.help credit Apr98 noao.imred.crutil
+.ih
+NAME
+credit -- interactively edit cosmic rays using an image display
+.ih
+USAGE	
+.nf
+credit input output
+.fi
+.ih
+PARAMETERS
+See parameters for \fBimedit\fR.
+.ih
+DESCRIPTION
+This task is a version of \fBimedit\fR.  See the help for that task
+for a description of the parameters and algorithms.
+
+For the purpose of editing cosmic rays the most useful editing option
+is 'b' to replace cosmic rays in a circular annulus using local sky
+values.  This can be done interactively or using a list of positions
+along with the \fIdefault\fR parameter value.
+.ih
+EXAMPLES
+1.  To replace cosmic rays interactively.
+
+.nf
+    cl> credit obj012 crobj012 crmask012
+.fi
+
+2.  To use a two column list of positions and remove the cosmic rays using
+the 'b' key algorithm.
+
+.nf
+    cl> credit obj012 crobj012 cursor=crlist.dat display-
+.fi
+.ih
+SEE ALSO
+imedit, epix
+.endhelp
diff --git a/noao/imred/crutil/doc/crfix.hlp b/noao/imred/crutil/doc/crfix.hlp
new file mode 100644
index 00000000..5794a001
--- /dev/null
+++ b/noao/imred/crutil/doc/crfix.hlp
@@ -0,0 +1,48 @@
+.help crfix Apr98 noao.imred.crutil
+.ih
+NAME
+crfix -- fix cosmic rays in images using cosmic ray masks
+.ih
+USAGE	
+.nf
+crfix input output masks
+.fi
+.ih
+PARAMETERS
+.ls input
+Input two dimensional image to be "fixed" (modified) by linear interpolation.
+.le
+.ls output
+Output image.  If the output image name exactly matches the input
+image name (including extensions) then the image will be modified in place.
+.le
+.ls crmask
+Cosmic ray mask identifying the cosmic rays to be fixed.  The mask
+values are zero for good data and non-zero for cosmic rays.
+.le
+.ih
+DESCRIPTION
+The input and output images are specified by the \fIinput\fR and
+\fIoutput\fR parameters.  If the input and output image names are
+identifical (including extensions) then image is modified in place.  Cosmic
+rays, identified in a cosmic ray mask specified by the \fIcrmask\fR
+parameter, are replaced in the output image by linear interpolation along
+lines or columns using the nearest good pixels.  The special mask name
+"BPM" may be used to select a mask name given in the input image header
+under the keyword "BPM".
+
+Cosmic ray pixels are "fixed" by replacing them with values
+by linear interpolation to the nearest pixels not identified as bad.
+The interpolation direction is the shortest length between good pixels
+along columns or lines.
+.ih
+EXAMPLES
+1.  To replace cosmic rays in an image:
+
+.nf
+    cl> crfix obj012 crobj012 crmask012
+.fi
+.ih
+SEE ALSO
+fixpix, crmedian, crnebula, cosmicrays, credit, epix
+.endhelp
diff --git a/noao/imred/crutil/doc/crgrow.hlp b/noao/imred/crutil/doc/crgrow.hlp
new file mode 100644
index 00000000..f3a1ff5c
--- /dev/null
+++ b/noao/imred/crutil/doc/crgrow.hlp
@@ -0,0 +1,55 @@
+.help crgrow Apr98 noao.imred.crutil
+.ih
+NAME
+crgrow -- grow cosmic rays in cosmic ray masks
+.ih
+USAGE	
+crgrow input output radius
+.ih
+PARAMETERS
+.ls input
+List of cosmic ray masks to be modified.
+.le
+.ls output
+List of output modified cosmic ray masks.  The input and output lists must
+match.  If the input and output cosmic ray masks are specified as the same
+then the input mask will be modified in place.
+.le
+.ls radius = 1.
+Replacement radius around cosmic rays.
+If a pixel is within this distance of a cosmic ray pixel
+it is identified by a value of 1 in the output cosmic ray mask.  Distances are
+measured between pixel centers which are have integer coordinates.
+.le
+.ls inval = INDEF
+Mask value to be grown.  A value of INDEF will grow all non-zero values.
+.le
+.ls outval = INDEF
+Mask value for grown pixels.  A value of INDEF will use the value of the
+pixel being grown for the grown pixel value.
+.le
+.ih
+DESCRIPTION
+The cosmic ray pixels, identified by the "inval" parameter, in the input
+mask are located and all unmasked (zero valued) pixels within the specified
+grow radius are set to a value given by the "outval" parameter. The
+distance between pixels is measured as a cartisian logical pixel coordinate
+distance.
+.ih
+EXAMPLES
+1.  A radius of 1 will grow cosmic rays in a "plus" pattern.
+
+.nf
+    cl> crgrow crmask1 crmask2 1
+.fi
+
+2.  A radius of 1.5 will grow cosmic rays in a box pattern.  The following
+will modify the input mask.
+
+.nf
+    cl> crgrow crmask crmask 1.5
+.fi
+.ih
+SEE ALSO
+imreplace
+.endhelp
diff --git a/noao/imred/crutil/doc/crmedian.hlp b/noao/imred/crutil/doc/crmedian.hlp
new file mode 100644
index 00000000..3147b676
--- /dev/null
+++ b/noao/imred/crutil/doc/crmedian.hlp
@@ -0,0 +1,157 @@
+.help crmedian Apr98 noao.imred.crutil
+.ih
+NAME
+crmedian -- detect, fix, and flag cosmic rays using median filtering
+.ih
+USAGE   
+.nf
+crmedian input output
+.fi
+.ih
+PARAMETERS
+.ls input
+Input image in which to detect cosmic rays.
+.le
+.ls output
+Output image in which cosmic rays are replaced by the median value.
+If no output image name is given then no output image will be created.
+.le
+.ls crmask = ""
+Output cosmic ray mask.  Detected cosmic rays (and other deviant pixels)
+are identified in the mask with values of one and good pixels with a values
+of zero.  If no output cosmic ray mask is given then no mask will be
+created.
+.le
+.ls median = ""
+Output median filtered image.  If no image name is given then no output will be
+created.
+.le
+.ls sigma = ""
+Output sigma image.  If no image name is given then no output will be
+created.
+.le
+.ls residual = ""
+Output residual image.  This is the input image minus the median filtered
+image divided by the sigma image.  Thresholds in this image determine the
+cosmic rays detected.  If no image name is given then no output will be
+created.
+.le
+.ls var0 = 0., var1 = 0., var2 = 0.
+Variance coefficients for the variance model.  The variance model is
+
+.nf
+    variance = var0 + var1 * data + var2 * data^2
+.fi
+
+where data is the maximum of zero and median pixel value and the variance
+is in data numbers.  All the coefficients must be positive or zero.  If
+they are all zero then empirical data sigmas are estimated by a percentile
+method in boxes of size given by \fIncsig\fR and \fInlsig\fR.
+.le
+.ls lsigma = 10, hsigma = 3
+Positive sigma factors to use for selecting pixels below and above
+the median level based on the local percentile sigma.  Cosmic rays will
+appear above the median level.
+.le
+.ls ncmed = 5, nlmed = 5
+The column and line size of a moving median rectangle used to estimate the
+uncontaminated local image.
+.le
+.ls ncsig = 25, nlsig = 25
+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
+.ih
+DESCRIPTION
+\fBCrmedian\fR detects cosmic rays from pixels deviating by a specified
+statistical amount from the median at each pixel.  It outputs and set of
+the following: a copy of the input image with cosmic rays replaced by the
+median value, a cosmic ray mask identifying the cosmic rays, the median
+filtered image, a sigma image where each pixel has the estimated sigma, and
+the residual image used in detecting the cosmic rays.
+
+The residual image is computed by subtracting a median filtered version
+of the input data from the unfiltered input data and dividing by an
+estimate of the pixel sigmas.  The median filter
+box size is given by the \fIncmed\fR and \fInlmed\fR parameters.
+If a name for the median image is specified the median filtered image
+will be output.  The variance at each pixel is determined either from
+a variance model or empirically.  If a name for the sigma image is specified
+then the sigma values (the square root of the variance) will be output.
+If a name for the residual image is given then the residual image
+will be output.
+
+The empirical variance model is given by the formula
+
+.nf
+    variance = var0 + var1 * data + var2 * data^2
+.fi
+
+where data is the maximum of zero and median pixel value and the variance
+is in data numbers.  This model can be related to common detector
+parameters.  For CCDs var0 is the readout noise expressed as a variance in
+data numbers and var1 is the inverse gain (DN/electrons).  The second order
+coefficient has the interpretation of flat field introduced variance.
+
+If all the coefficients are zero then an empirical sigma is estimated
+as follows.  The input image is divided into blocks of size
+\fIncsig\fR and \fInlsig\fR.  The pixel values in a block are sorted
+and the pixel values nearest the 15.9 and 84.1 percentiles are
+selected.  These are the one sigma points in a Gaussian distribution.
+The sigma estimate is the difference of these two values divided by
+two.  This algorithm is used to avoid contamination of the sigma
+estimate 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 points.  The sigma estimate for a pixel is the sigma
+from the nearest block.  A moving box is not used for efficiency.
+
+The residual image is divided by the sigma estimate at each pixel.
+Cosmic rays are identified by finding those pixels in the
+residual image which have values greater than \fIhsigma\fR and bad
+pixels with values below \fIlsigma\fR are also identified.
+
+If an output image name is specified then the output image is produced as a
+copy of the input image but with the identified cosmic ray pixels replaced
+by the median value.  If an output cosmic ray mask is specified a cosmic
+ray mask will be produced with values of zero for good pixels and one for
+bad pixels.  The cosmic ray mask is used to display the cosmic ray
+positions found and the cosmic rays can be replaced by interpolation (as
+opposed to the median value) using the task \fIcrfix\fR.
+
+The \fBcrmedian\fR detections are very simple and do not take into account
+real structure with scales of a pixel.  Thus this may clip the cores of
+stars and narrow nebular features in the data.  More sophisticated
+algorithms are found in \fBcosmicrays\fR, \fIcraverage\fR, and
+\fBcrnebula\fR.  The median, sigma, and residual images are available as
+output to evaluate the various aspects of the algorithm.
+.ih
+EXAMPLES
+This example illustrates using the \fBcrmedian\fR task to
+give a cosmic ray removed image and examining the results with an image
+display.  The image is a CCD image with a readout noise of 5 electrons
+and a gain of 3 electrons per data number.  This implies variance
+model coefficients of
+
+.nf
+    var0 = (5/3)^2 = 2.78
+    var1 = 1/3 = 0.34
+.fi
+
+.nf
+    cl> display obj001 1                  # Display in first frame
+    cl> # Determine output image, cosmic ray mask, and residual image
+    cl> crmedian obj001 crobj001 crmask=mask001 resid=res001\
+    >>> var0=2.78 var1=0.34
+    cl> display crobj001 2                # Display final image
+    cl> display mask001 3 zs- zr- z1=-1 z2=2 # Display mask
+    cl> display res001 4 zs- zr- z1=-5 z2=5  # Display residuals
+.fi
+
+By looking at the residual image the sigma clippig threshold can be
+adjusted and the noise parameters can be tweaked to minimize clipping
+of real extended structure.
+.ih
+SEE ALSO
+cosmicrays, craverage, crnebula, median, crfix, crgrow
+.endhelp
diff --git a/noao/imred/crutil/doc/crnebula.hlp b/noao/imred/crutil/doc/crnebula.hlp
new file mode 100644
index 00000000..174a6771
--- /dev/null
+++ b/noao/imred/crutil/doc/crnebula.hlp
@@ -0,0 +1,139 @@
+.help crnebula Apr98 noao.imred.crutil
+.ih
+NAME
+crnebula -- create a cosmic ray mask from nebular images
+.ih
+USAGE	
+.nf
+crnebula input output
+.fi
+.ih
+PARAMETERS
+.ls input
+Input image in which cosmic rays are to be detected.
+.le
+.ls output
+Output image in which cosmic rays are to be replaced by the median.
+If no output image is given (specified as "") then no output image
+is created.
+.le
+.ls crmask = ""
+Output cosmic ray mask identifying the cosmic rays found.  The mask
+will have values of one for cosmic rays and zero for non-cosmic rays.
+If no output cosmic ray mask is given (specified as "") then no mask
+is created.
+.le
+.ls residual = ""
+Output residual image.  This is the input image minus the median filtered
+image divided by the estimated sigma at each pixel.  Thresholds in this
+image determine the cosmic rays detected.  If no image name is given then
+no output will be created.
+.le
+.ls rmedresid = ""
+Output image for the difference between the box median filter image and
+the ring median filtered image divided by the estimated sigma at each
+pixel.  If no image name is given then no output will be created.
+.le
+.ls var0 = 0., var1 = 0., var2 = 0.
+Variance coefficients for the variance model.  The variance model is
+
+.nf
+    variance = var0 + var1 * data + var2 * data^2
+.fi
+
+where data is the maximum of zero and median pixel value and the variance is in
+data numbers.  All the coefficients must be positive or zero.  If they are
+all zero then empirical data sigmas are estimated by a percentile method in
+boxes of size given by \fIncsig\fR and \fInlsig\fR.
+.le
+.ls sigmed = 3.
+Sigma clipping factor for the residual image.
+.le
+.ls sigdiff = 3.
+Sigma clipping factor for the residuals between the box median and ring median
+filtered images.
+.le
+.ls mbox = 5
+Box size, in pixels, for the box median filtering.
+.le
+.ls rin = 1.5, rout = 6.
+Inner and outer radii, in pixels, for the ring median filtering.
+.le
+.ls verbose = no
+Print some progress information?
+.le
+.ih
+DESCRIPTION
+This task uses a combination of box median filtering to detect cosmic rays
+and the difference between box and ring median filtering to identify
+regions of fine nebular structure which should not be treated as cosmic
+rays.  The output consists of some set of the input image with cosmic rays
+replaced by the median, a cosmic ray mask, the residual image used to
+detect the cosmic rays, and the residual image used to exclude cosmic rays
+in regions of nebular fine structure.  The cosmic ray mask may be used
+later with \fBcrgrow\fR and \fBcrfix\fR to grow and remove the cosmic rays
+from the data by interpolation rather than the median.
+
+The algorithm is as follows.  The input image is median filtered using a
+box of size given by \fImbox\fR.  The residual image between the unfiltered
+and filter data is computed.  The residuals are divided by the estimated
+sigma of the pixel.  Cosmic rays are those which are more than \fIsigmed\fR
+above zero in the residual image.  This residual image may be output if an
+output name is specified.  This part of the algorithm is identical to that
+of the task \fIcrmedian\fR and, in fact, that task is used.
+
+The median image not only enhances cosmic rays it also enhances narrow fine
+structure in the input image.  To avoid identifying this structure as
+cosmic rays a second filtered residual image is created which
+preferentially identifies this structure over the cosmic rays.  The input
+image is filtered using a ring median of specified inner and outer radius.
+The inner radius is slightly larger than the scale of the cosmic rays and
+the outer radius is comparable to the box size of the box median filter.  A
+ring filter replaces the center of the ring by the median of the ring.  The
+difference between the input and ring median filtered image divided by the
+estimated sigma will then be very similar to the box median residual image both
+where there are cosmic rays and where there is diffuse structure but will
+be different where there are linear fine structure patterns.  The
+difference between the median residual image and this ring median residual
+image highlights the regions of fine structure. If a image name is specified
+for the difference of the residual images it will be output.
+
+The difference of the median residual images is used to exclude any cosmic
+ray candidate pixels determined from sigma clipping the box median residual
+image which lie where the difference of the median residual images is
+greater than \fIsigdiff\fR different from zero (both positive or
+negative).
+
+To understand this algorithm it is recommended that the user save the
+residual and residual difference images and display them and blink against
+the original data.
+.ih
+EXAMPLES
+This example, the same as in \fBcrmedian\fR, illustrates using the
+\fBcrnebual\fR task to give a cosmic ray removed image and examining the
+results with an image display.  The image is a CCD image with a readout
+noise of 5 electrons and a gain of 3 electrons per data number.  This
+implies variance model coefficients of
+
+.nf
+    var0 = (5/3)^2 = 2.78
+    var1 = 1/3 = 0.34
+.fi
+
+.nf
+    cl> display obj001 1                  # Display in first frame
+    cl> # Determine output image, cosmic ray mask, and residual images
+    cl> crnebula obj001 crobj001 crmask=mask001 resid=res001\
+    >>> rmedresid=rmed001 var0=2.78 var1=0.34
+    cl> display crobj001 2                # Display final image
+    cl> display res001 3 zs- zr- z1=-5 z2=5  # Display residuals
+    cl> display rmed001 4 zs- zr- z1=-5 z2=5
+.fi
+
+By looking at the residual image the sigma clippig threshold can be
+adjusted and the noise parameters can be tweaked to minimize clipping
+of real extended structure.
+.ih
+SEE ALSO
+cosmicrays, crmedian, median, rmedian, crfix, crgrow
+.endhelp
diff --git a/noao/imred/crutil/doc/overview.hlp b/noao/imred/crutil/doc/overview.hlp
new file mode 100644
index 00000000..cb4dc3de
--- /dev/null
+++ b/noao/imred/crutil/doc/overview.hlp
@@ -0,0 +1,76 @@
+.help overview Apr98 noao.imred.crutil
+
+.ce
+\fBThe Cosmic Ray Package: CRUTIL\fR
+
+The cosmic ray package provides tools for identifying and removing cosmic
+rays in images.  The tasks are:
+
+.nf
+ cosmicrays - Remove cosmic rays using flux ratio algorithm
+  craverage - Detect CRs against average and avoid objects
+  crcombine - Combine multiple exposures to eliminate cosmic rays
+     credit - Interactively edit cosmic rays using an image display
+      crfix - Fix cosmic rays in images using cosmic ray masks
+     crgrow - Grow cosmic rays in cosmic ray masks
+   crmedian - Detect and replace cosmic rays with median filter
+   crnebula - Detect and replace cosmic rays in nebular data
+.fi
+
+The best way to remove cosmic rays is using multiple exposures of the same
+field.  When this is done the task \fBcrcombine\fR is used to combine the
+exposures into a final single image with cosmic rays removed.  The images
+are scaled (if necessary) to a common data level either by multiplicative
+scaling, an additive background offset, or some combination of both.
+Cosmic rays are then found as pixels which differ by some statistical
+amount away for the average or median of the data.
+
+A median is the simplest way to remove cosmic rays.  This is an option
+with \fBcrcombine\fR.  But this does not make optimal use of the data.
+An average of the pixels remaining after some rejection operation is better.
+If the noise characteristics of the data can be described by a gain and
+read noise then cosmic rays can be optimally rejected using the
+"crreject" algorithm.  This works on two or more images.  There are
+a number of other rejection algorithms which can be used as described in
+the task help.
+
+The rest of the tasks in the package are used when only a single exposure
+is available.  These include interactive editing with \fBcredit\fR.  The
+replacement algorithms in this task may also be used non-interactively if
+you have a list of pixel coordinates as input.  Other tasks automatically
+identifying pixels which are significantly higher than surrounding pixels.
+
+The simplest of these tasks is \fBcrmedian\fR.  This replaces
+cosmic rays with a median value and produces a cosmic ray
+mask which is a simple type of integer image where good pixels have a value
+of zero and bad pixels have a non-zero value.  The tasks \fBcrgrow\fR and
+\fBcrfix\fR are provided to use this type of cosmic ray mask.  The former
+will flag additional pixels within some radius of the flagged pixels in the
+mask.  The latter is the basic tool for replacing the identified pixels in
+the data by neighboring data.  It uses linear interpolation along lines or
+columns.  The median task is simple but it often will flag the cores of
+stars or other small but real features.
+
+The task \fBcraverage\fR is similar to \fBcrmedian\fR in that it compares
+the pixel values against a smoothed version.  Instead of a median it uses
+an average with the central pixel excluded.  It is more sophisticated
+in that it also compares the average against a larger median to see if
+the region corresponds to an object.  Thus it can detect objects and
+the task could be used as a simple object detection task in its own right.
+Because the hardest part of cosmic ray detection from a single image is
+avoiding truncation of the cores of stars this task does not allow cosmic
+rays to be detected where it thinks there is an object.  This task is
+also more versatile in allow separate mask values and works on a list
+of images.
+
+Somewhat more sophisticated algorithms are available in the tasks
+\fBcosmicrays\fR and \fBcrnebula\fR.  These attempt to determine if a
+deviant pixel is the core of a star or part of a linear nebular feature
+respectively.
+
+The best use of these tasks is to experiment and iterate.  In particular,
+one may want to iterate a task several times and use both \fBcosmicrays\fR
+and \fBcraverage\fR.
+
+Good hunting!
+.endhelp