xmaskpass: Driver script for mask pass processing steps

Package: xdimsum

Usage

xmaskpass input expinput sections output outexpmap

Parameters

input

The first pass combined image.

inexpmap

The first pass exposure map image associated with the input combined image input.

sections

The first pass sections file the location of the individual input images in the combined image input.

output

The name of the final output combined image.

outexpmap = ".exp"

The name of the output exposure map image or the string appended to the output image name output to create the output exposure map image name. The exposure map contains the total exposure time for each output image pixel after rejecting bad pixels, cosmic rays, and undefined pixels.

statsec = ""

The image section used to compute the sky statistics for the individual input image in the sky subtraction and cosmic ray removal steps. By default the entire input image is used.

nsigrej = 3.0

The nsigma rejection limits used to compute the sky statistics in the sky subtraction and cosmic ray removal tasks.

maxiter = 20

The maximum number of rejection cycles used to compute the sky statistics by the sky subtraction and cosmic ray removal tasks.

mkmask = yes

Create the combined image object mask and inverse object core mask ? If mkmask is no and the object mask or inverse object core mask do not exist the task will terminate.

omask = ".msk"

The output combined image object mask name or the string appended to the input image name input to create the output combined object mask name. An additional "i" is added to the combined object mask name to create the inverse object core mask name. Object masks consist of 1's in object regions and 0's elsewhere. Inverse object masks are the reverse.

chkmasks = no

Check the displayed mask and optionally enter a new threshold value ?

kpchking = yes

Repeatedly check the mask until satisfied ?

mstatsec = ""

The combined image section used to compute the sky statistics in the mask creation step. By default the entire input image is used.

nsigcrmsk = 1.5

The factor times the recommended threshold used by the mask creation task to compute the combined image inverse object core mask for cosmic ray unzapping.

nsigobjmsk = 1.1

The factor times the recommended threshold used by the mask creation task to compute the combined input image object mask.

negthresh = no

Use negative as well as positive threshold when creating the input image object mask ?

ngrow = 0

The object growing box half-width in pixels.

maskdereg = yes

Create object masks and inverse object core masks for the individual input images by extracting the appropriate sections from the parent combined image masks ?

ocrmasks = ".ocm"

The list of output individual inverse core object masks or the string appended to the individual sky subtracted image names to create the individual output inverse core object mask names. The inverse object masks consist of 0's in the object regions and 1's elsewhere and are used for unzapping cosmic rays detected in object regions.

objmasks = ".objm"

The list of output individual image object masks or the string appended to the individual sky subtracted image names to create the individual output object mask names. The object masks consist of 1's in the object regions and 0's elsewhere and are used for improving the sky subtraction.

xslm = yes

Do the sky subtraction step using object masking with the xnslm task if newslm is yes or xslm is no ? The input images must be sky subtracted before the bad pixel correction, cosmic ray correction, and image combining steps can be performed.

sslist = ".sub"

The output sky subtracted image list or the string appended to the input image names in sections to create the names of the output sky subtracted images.

hmasks = ".hom"

The output holes mask list or the string appended to the sky subtracted image names to create the names of the output holes masks. Holes mask consist of 0's in undefined regions and 1's' elsewhere and are only created if object masking is enabled.

newxslm = no

Use the new xnslm task rather than the original xslm task ?

forcescale = yes

Force recomputation of the input image statistics regardless of whether or not they have been previously computed and stored in the keyword "SKYMED".

useomask = yes

Use the individual object masks objmasks tocomputw the individual image sky statistics ? The object masks are used to create the sky images regardless of the value of useomask.

nmean = 6

The number of neighboring images used by the sky subtraction task to compute the sky image for each input image.

nskymin = 3

The minimum number of input images used by the sky subtraction task to compute the sky image.

nreject = 1

The number of high and low side pixels to reject when the sky image is computed by the sky subtraction task.

cache = yes

Enable image cacheing for improved efficiency in the new xnslm task ?

maskfix = yes

Use the bad pixel mask bpmask to fix bad pixels in the sky subtracted images ?

bpmask

The name of the input bad pixel mask used to fix bad pixels in the sky subtracted images. Bpmask is assumed to be the same for all the input images and to consist of 0's in the bad pixel regions and 1's elsewhere. If bpmask is undefined the bad pixel fixing step is skipped.

forcefix = yes

Force bad pixel fixing by the even though the image haves been previously fixed as indicated by the presense of the keyword "MASKFIX".

xzap = yes

Remove cosmic rays from the sky subtracted images using the xnzap task if newxzap = yes or xzap if newxzap is no ? If xzap is no the existing cosmic ray masks after unzapping with the individual inverse object masks ocrmasks are used in later processing steps.

crmasks = ".crm"

The list of input first pass cosmic ray masks if xzap = no, or the list of output cosmic ray masks if xzap = yes. Crmasks may also be a string appended to the sky subtracted image names to create the names of the input / output cosmic ray masks. Cosmic ray masks consist of 1's in the cosmic ray regions and 0's elsewhere.

newxzap = no

Use the new xnzap task rather than the original xzap task ?

badpixupdate = yes

Update the bad pixel mask bpmask. The bad pixel mask updating task adds those bad pixels detected in 3 or more sky subtracted images to the bad pixel mask using the current cosmic ray mask list. Bad pixel mask updating is only done if xzap is yes.

nrepeats = 3

If a pixel is detected as a cosmic ray in nrepeats or more images and badpixupdate is yes then the pixel is set to bad in the bad pixel mask bpmask.

xnregistar = yes

Compute the final combined output image and exposure map image using offsets and exposure time scaling ?

shiftlist = ""

The input shifts file used to combine the corrected images. Shiftlist consists of the corrected image name, the x and y offsets in user units (usually pixels), and the exposure time used to scale the image. If shiftlist is undefined xmaskpass terminates with a warning message.

rmasks = ".rjm"

The list of output mask pass rejection masks. Rmasks may also be a string appended to the sky subtracted image names to create the names of the output rejection masks. Rejection masks consist of 1's in the good data regions and 0's elsewhere.

nprev_omask = 0

The number of previous individual object masks that are combined to create the object mask used in the image combine step.

fractional = no

Use the fractional as well as integer part of the corrected image offsets if mag = 1. The imshift task and bilinear interpolation are used to do the fractional part of the shift.

pixin = yes

If pixin is yes the input offsets called a and b are assumed to be defined in the reference image pixel coordinate system x and y, and ab_sense, xscale, yscale, and a2x_angle default to yes, -1.0, -1.0, and 0.0 respectively.

ab_sense = yes

Is the rotation of the a to b axis counter-clockwise ? The x and b axes are the axes along which the input offsets are measured. Ab_sense defaults to yes if pixin is yes.

xscale = 1.0, yscale = 1.0

The number of pixel coordinates x and y per input coordinates a and b. For example if the input offsets are measured in arcseconds and the pixel scale is 0.25 arcseconds per pixel then xscale and yscale should be set to 4.0. Xscale and yscale default to -1.0 and -1.0 if pixin is yes.

a2x_angle = 0

The angle in degrees of the a offset axis measured counter-clockwise to the image x axis. A2x_angle defaults to 0.0 if pixin is yes.

mag = 4.0

The factor by which the output image and output exposure map image are block replicated with respect to the input image and input exposure map.

blkrep = yes

Use block replication rather than bilinear interpolation to magnify the images if mag > 1.

ncoavg = 1

The number of co-averages per input image. The total exposure time for an image is ncoavg * exptime * secpexp where exptime is read from shiftlist.

secpexp = 1.0

The number of seconds per unit exposure time.

y2n_angle = 0.0

The angle in degrees from the image y axis to the north axis measured from north through east. Y2n_angle can be used to orient the output image to within 45 degrees of N up and E left if set correctly.

rotation = yes

Is the rotation of the input image north axis to the east axis counter-clockwise ?

del_bigmasks = no

Delete omask and its related inverse mask on task termination ?

del_smallmasks = no

Delete ocrmasks and objmasks and their related inverse on task termination ?

Description

XMASKPASS sky subtracts, bad pixel corrects, and cosmic ray corrects the input images in sections, and combines the corrected images into a single output image output and accompanying exposure map image outexpmap, using the input combined image input and associated exposure map inexpmap produced by XFIRSTPASS to derive object masks for the combined and individual images. The object mask and inverse object core mask for the input combined image are stored in the mask omask. The individual image object masks and inverse object core masks are stored in objmasks and ocrmasks respectively. Object masks consist of 1's in the object regions and 0's elsewhere. Inverse object masks consist of 0's in the object regions and 1's elsewhere. The final output sky subtracted, bad pixel corrected, and cosmic ray corrected images are stored in sslist. The output holes masks and cosmic ray masks are stored in hmasks and crmasks respectively.

If mkmask is yes the combined image object mask omask and inverse object core mask omask are created with the MKMASK task using thresholding factors nsigobjmask and nsigcrmask times the recommand thresholding factor respectively. If negthresh is "yes" both negative and positive thresholds are used to created the combined image object mask. The standard deviation of the background is computed using pixels in the section specified by mstatsec and iterative rejection with parameters nsigrej and maxiter. MKMASK uses default values of 2, 15, and 3 for the MKMASK subsampling factor, median filter size, and smoothing size respectively. More about the MKMASK task can be found in the MKMASK help page. If chkmasks is yes, the recommended threshold is printed, the input combined image normalized by the exposure time is displayed in the image display, the imexamine task is invloked, the user is prompted for a new thresholding value, and the input image and new mask are displayed. If kpchking is set to yes the whole process is repeated until the user is satisfied and sets it to no. If mkmask is no and the combined object mask and inverse object core mask do not already exist XMASKPASS terminates.

If maskdereg is yes then the individual object masks and inverse object core masks objmasks and ocrmasks are created from the combined image object masks omask using positional information in the sections file. The object masks are used to improve the sky subtraction. The inverse object core masks are used to unzap the cosmic rays in object regions where the cosmic rays are defined by the cosmic ray masks crmasks. The object mask and inverse object core mask names are stored in the image header keywords "OBJMASK" and "CROBJMAS" respectively. If maskdereg is no then the object masks and inverse object core masks are assumed to already exist.

If xslm is yes XMASKPASS sky substracts the input images using the XNSLM task if newxslm is yes and XSLM task if it is no with object masking enabled, and writes the results to the output images sslist. Existing sky subtracted images are overwritten. The indivdual object masks are assumed to have been created by the MASKDEREG task. XSLM/XNSLM computes the running mean of the nmean neighboring images, after scaling them by their median pixel values, and rejecting the nreject highest scaled pixels. There must be at least nskymin neighboring images for a sky image to be computed and subtracted from the input image. The input image medians are computed using pixels in the region defined by statsec, the object mask defined in objmasks if useomask is yes, and iterative rejection using rejection parameters nsigrej and maxiter. The reciprocal of the computed median is stored in the image header keyword "SKYMED". If forcescale is no and the "SKYMED" keyword already exists in the image header then the image medians are not recomputed and the value of SKYMED is used as the scaling factor. If use of the object masks results in sky background pixels which are undefined then a holes mask hmasks is written. Holes masks consist of 0's in undefined regions and 1's elsewhere. If a holes mask was created then the keyword "HOLES" containing the name of the holes mask is written to the sky subtracted image. When sky subtraction is complete the keyword SKYSUB is written to the output image headers. More information about the XSLM/XNSLM task can be found in the XSLM/XNSLM help pages.

If maskfix is yes XMASKPASS removes bad pixels from sky subtracted images sslist using the MASKFIX task and the bad pixel mask bpmask. The bad pixel mask consists of 0's in bad pixel regions and 1's elsewhere and must be the same size as the input sky subtracted image. The bad pixels are removed by linearly interpolating across bad columns in each image line. When bad pixel removal is complete the keyword "MASKFIX" is written to the header of the sky subtracted image. If forcefix is no and "MASKFIX" exists in the image header then the bad pixel removal step is skipped. More information on the MASKFIX task can be found in the MASKFIX help page.

If xzap is yes XMASKPASS removes cosmic rays from the sky subtracted images sslist using the XNZAP task if newxzap is yes or the XZAP task if it is no, and writes the cosmic ray masks to crmasks. Existing cosmic ray masks are overwritten. The output cosmic ray masks contain 1's in the cosmic ray regions and 0's elsewhere. Both XZAP and XNZAP write the keyword CRMASK which contains the name of the output cosmic ray MASK to the cosmic ray corrected image. If the CRMASK keyword is present in the sky subtracted image headers cosmic ray cleaning is skipped. XZAP is the tried and true XDIMSUM cosmic ray removal task. XNZAP is experimental but promises to be a faster technique. If xzap is no then the cosmic rays masks created by XFIRSTPASS are used. Cosmic rays in the cores of objects are unzapped using the inverse object core masks ocrlist.

XZAP detects and removes cosmic rays by finding pixels which are more than 5.0 sky sigma above the median of the surrounding box of 5 by 5 pixels and are not part of an object, where an object is any pixel located in an object region defined by the inverse object masks ocrmasks stored in the header keyword "CROBJMAS". The cosmic rays in the input sky subtracted images are replaced with the local median value. More information on the XZAP task can be found in the XZAP help page.

XNZAP detects and removes cosmic rays by finding pixels which are more than 5.0 sky sigma above the mean of the surrounding box of 5 by 5 pixels with the central pixel and the highest pixel removed, and which are not part of an object where an object is defined by the inverse object mask ocrmasks stored in the image header keyword "CROBJMAS". The local background is defined as the median of the pixels in an annulus 5.0 pixels wide around the averaging box. The local sky sigma is estimated by computing the percentile points of pixels in 25 by 25 pixel subsections evenly distributed over the image. The cosmic ray and object growing radii are set to 0.0 and 0.0 respectively. The cosmic rays in the input sky subtracted images are replaced with the local average value. More information on the XNZAP task can be found in the XNZAP help page.

If xzap is yes and badpixupdate is yes then XMASKPASS updates the bad pixel mask bpmask using the BADPIXUPDATE task. BADPIXUPDATE examines the list of cosmic ray masks produced by XZAP or XNZAP, searches for pixels that are bad in 3 or more masks, and sets those pixels in bpmask to 0.

In preparation for image combining the name of the corrected image, its x and y shifts relative to the reference image, and its exposure time are read from the file shiftlist. Shiftlist may have been written by the XDSHIFTS, XMSHIFTS, XFSHIFTS, or XRSHIFTS tasks.

If xnregistar is yes then XMASKPASS combines the corrected images into the output combined image output and output exposure map image outexpmap using the badpixel mask bpmask, the cosmic ray masks crmasks, the holes masks hmasks, the nprev_omask objects masks, and offsets and scaling factors read from shiftlist. The combined rejection masks are written to rmasks. If fractional is no only the integer parts of the shifts are used. XMASKPASS calls the XNREGISTAR task to do the actual image combining. The parameters pixin, ab_sense, xscale, yscale, and a2x_angle are used to convert shifts from user units, e.g. arseconds to units of pixels in the reference image. The magnification factor mag determines the magnification of the final combined image with respect the the initial combined image. if blkrep the magnification is done via block replication, otherwise it is done using bilinear interpolation. The parameters ncoavg and secpexp are used to normalize the input exposure times. The parameters y2n_angle and rotation are used to orient the final combined image and eposure map to within 45 degrees of north up and east to the left.

Examples

1. Perform a first pass image combining operation on the demo images using the default shiftlist demo.slist and follow it with a mask pass.

cl> demos mkdimsum

cl> xfirstpass @demo.list demo13 fpmosaic ".exp" bpmask=demo.pl \
    shiftlist=demo.slist nsigrej=5.0 maxiter=10 secpexp=60.0

cl> xmaskpass fpmosaic fpmosaic.exp fpmosaic.corners mpmosaic   \
    ".exp" bpmask=demo.pl shiftlist=demo.slist nsigrej=5.0      \
    maxiter=10 secpexp=60.0

Time requirements

Bugs

See also

xslm, xnslm, maskfix, xzap, xnzap, badpixupdate, xnregistar