Repatch (from linux) of OSX IRAF

1 files changed, 157 insertions, 0 deletions

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