Initial commit

1 files changed, 139 insertions, 0 deletions

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