.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
