From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Wed, 8 Jul 2015 20:46:52 -0400 Subject: Initial commit --- noao/imred/crutil/doc/crmedian.hlp | 157 +++++++++++++++++++++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 noao/imred/crutil/doc/crmedian.hlp (limited to 'noao/imred/crutil/doc/crmedian.hlp') 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 -- cgit