diff options
Diffstat (limited to 'pkg/proto/doc/rskysub.hlp')
| -rw-r--r-- | pkg/proto/doc/rskysub.hlp | 234 |
1 files changed, 234 insertions, 0 deletions
diff --git a/pkg/proto/doc/rskysub.hlp b/pkg/proto/doc/rskysub.hlp new file mode 100644 index 00000000..ab6c8543 --- /dev/null +++ b/pkg/proto/doc/rskysub.hlp @@ -0,0 +1,234 @@ +.help rskysub Sep01 proto +.ih +NAME +rskysub -- sky subtract images using running mean or median +.ih +USAGE +rskysub input output +.ih +PARAMETERS +.ls input +The list of input images to be sky subtracted in time of observation order. +.le +.ls output +The list of output sky subtracted images. The number of output images must +equal the number of input images. If output is "default", "dir$default", or +"dir$" then for every input image an output image called "dir$image.sub.?" +is created, where "dir$" is the optional directory specification, "image" is +the root input image name, and "?" is the next available version number. +.le +.ls imasks = "" +The optional list of input image masks. The input image masks are assumed to +consist of 0's in good pixel regions and > 0 integer values elsewhere. The +number of input images masks must be 0, 1, or equal to the number of input +images. If imasks is "default", "dir$default", or "dir$" then for every input +image a default input image mask called "dir$image.obm.?" is searched for, +where "dir$" is the optional directory specification, "image" is the root +input image name, and "?" is the highest available version number. +.le +.ls omasks = "" +The optional list of output masks. If output masks are defined they are +used to created the sky image in place of the input masks. The output masks +are a combination of the original input mask and pixels masked during the +input image scale factor computation and consist of 0's in good data regions +and 1's elsewhere. Output masks are only computed if \fIscale\fR = "median". +The number of output masks must be 0 or equal to the number of input images. +If imasks is "default", "dir$default", or "dir$" then for every input image +an output mask image called "dir$image.skm.?" is created, where "dir$" is +the optional directory specification, "image" is the root input image name, +and "?" is the next available version number. +.le +.ls hmasks = "" +The list of output holes masks. The holes masks defined bad pixels in the +output images, i.e. those for which the underlying sky image was undefined. +Holes masks are created only if \fIhmasks\fR is defined and there is at least +1 undefined sky image pixel in the output image. Holes masks contain 0's in +undefined sky regions and 1's elsewhere. If hmasks is "default", "dir$default", +or "dir$" then for every input image an output mask image called +"dir$image.hom.?" is created, where "dir$" is the optional directory +specification, "image" is the root input image name, and "?" is the next +available version number. +.le + +.ls rescale = yes +Force recomputation of the individual input image scale factors even though +they have been previously computed and stored in the keyword \fIskyscale\fR? +.le +.ls scale = "median" +The method used to compute the individual image scale factors. The options +are: +.ls none +The individual scale factors are all set to 1.0. +.le +.ls !<keyword> +The individual scale factors are all set to the value of the input image header +keyword \fIkeyword\fR. +.le +.ls median +The individual scale factors are set to 1 / median. The medians are estimated +using the input masks \fIimasks\fR, input image section \fIstatsec\fR, +the minimum and maximum good data values \fIlower\fR and \fIupper\R, the +clipping factors \fImaxiter\fR, \fIlnsigrej\fR, and \fIunsigrej\fR and the +histogram binning parameter \fIbinwidth\fR. +.le +.ls @<file> +The individual image scale factors are read from the file \fIfile\fR. +.le +.le +.ls skyscale = "SKYSCALE" +The image header keyword containing the computed scaling factor. +\fISkyscale\fR is written to both the input and output images. +.le + +.ls statsec = "" +The input image section used to compute the individual image scaling factors. +Statsec is independent of the input image section if any. +.le +.ls lower = INDEF, upper = INDEF +The minimum and maximum input image good data values. +.le +.ls maxiter = 20 +The maximum number of clipping iterations. +.le +.ls lnsigrej = 3.0, unsigrej = 3.0 +The lower and upper side sigma clipping factors. +.le +.ls binwidth = 0.1 +The histogram bin width in sigma used in estimating the median value. +.le + +.ls resubtract = yes +Force recomputation and subtraction of the sky image even though it exists +already ? +.le +.ls combine = "average" +The method used to create the sky images. The options are "average" and +"median". +.le +.ls ncombine = 6 +The default number of images used to create the sky images. +.le +.ls nmin = 3 +The minimum number of images used to create the sky images. +.le +.ls nlorej = 0, nhirej = 0 +The number of high and low side pixels to reject if \fIcombine\fR is "average". +.le +.ls blank = 0.0 +The value assigned to undefined output image pixels, i.e. those for +which the corresponding sky image pixel is undefined. +.le +.ls skysub = "SKYSUB" +The sky subtraction processing keyword which is written to the output +image when processing is complete. +.le +.ls holes = "HOLES" +The homes mask name keyword which is written to the output image if an output +holes mask is created. +.le + +.ls cache = yes +Cache the input images in memory if possible ? +.le +.ls verbose = yes +Print messages about the progress of the task ? +.le + +.ih +DESCRIPTION + +RSKYSUB computes the average sky image for each image in the input image +list \fIinlist\fR using a running mean or median technique and subtracts +it from the input image to create the output sky subtracted images +\fIoutlist\fR. The input image list is assumed to be ordered by time of +observation. If the input image masks list \fIimasks\fR is defined then the +input image pixels in the bad pixel regions are removed from the sky statistics +and sky image computation. RSKYSUB optionally creates a list of output pixel +masks \fIomasks\fR and a list of holes masks \fIhmasks\fR. + +The input masks \fIimasks\fR can be specified in a variety of ways as +shown below. + +.nf + "" - empty mask, use all the pixels + EMPTY - empty mask, use all the pixels + !KEYWORD - use mask specified by header keyword KEYWORD + !^KEYWORD - use inverse of mask specified by header keyword KEYWORD + mask - use specified mask + ^mask - use inverse of specified mask +.fi + +In all cases the mask values are assumed to be 0 in good data regions and +non-zero in rejected data regions. The input masks may in pixel list, e.g. +".pl" format, or any supported integer image format, e.g. ".imh", ".fits", etc. + +The optional output pixel masks \fIomasks\fR are a combination of the +input image masks and the scaling factor computation masks. They consist +entirely of 0's and 1's with 0's defining the good data regions. + +The optional output holes masks \fIhmasks\fR which specify those pixels +in the output images which are undefined consist entirely of 1's and 0's +with 0's defining the holes. + +Before beginning the sky subtraction step RSKYSUB computes a scaling factor for +each individual input image in \fIinlist\fR and stores it in the input image +header keyword \fIskyscale\fR. If \fIscale\fR is "median" then the median of +the input image pixels is computed using the input image masks \fIimasks\fR, +the good data limits \fIlower\fR and \fIupper\fR, the clipping factors +\fImaxiter\fR, \fIlnsigrej\fR, and \fIunisgrej\fR, and the histogram +resolution parameter \fIbinwidth\fR. The scaling factor is set to 1 / median. +If \fIscale\fR is "none", "!<keyword>", or "@<file>" the individual +scale factors are set to 1, read from the input image header keyword +\fI<keyword>\fR, or from a file \fI@<file>\fR respectively. If \fIrescale\fR is +yes and \fIscale\fR is "median" then the scaling computation is redone +regardless of whether or not the \fIskyscale\fR keyword is present in the +input image header. + +RSKYSUB computes the sky image for each input image by multiplying each +input image by the value of its scaling factor and then computing the +combination of \fIncombine\fR neighbor images using the algorithm +specified by \fIcombine\fR. If \fIcombine\fR is average then the +\fInlorej\fR and \fInhirej\fR lowest and highest pixels are rejected from +the stack to be combined. For example if the number of input images is 25 and +ncombine is 6 then images 2-4 are used to compute the sky image for image 1, +images 10-12 and 14-16 are used to compute the sky for image 13, and images +22-24 are used to compute the sky image for image 25. There must be a minimum +of \fInmin\fR neighbor images or the sky image will not be computed. If the +input masks are defined then pixels in bad regions are also rejected +from the final sky image computation. Undefined output image pixels, +i.e. those for which the corresponding sky image pixel is undefined, are +assigned the value \fIblank\fR. The sky subtraction processing keyword +\fIskysub\fR is written to the output image when sky subtraction is complete. + +If \fIcache\fR is "yes" then RSKYSUB will attempt to buffer the active images +in memory and will run significantly faster. If \fIverbose\fR = yes then +the task prints messages about its actions as it goes along. + +.ih +EXAMPLES + +1. Sky subtract a list of 25 images without masking. + +.nf +cl> rskysub @inlist @outlist maxiter=10 lnsigrej=5.0 unsigrej=5.0 +.fi + + +2. Sky subtract the same list of 25 images with masking where the masks +are assumed to be stored in the BPM keyword. + +.nf +cl> rskysub @inlist @outlist imasks="!BPM" maxiter=10 lnsigrej=5.0 \ +unsigrej=5.0 +.fi + +.ih +TIME REQUIREMENTS + +.ih +BUGS + +.ih +SEE ALSO +imcombine, imexpr +.endhelp |