.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
