diff options
Diffstat (limited to 'pkg/xtools/doc/xtpmmap.hlp')
| -rw-r--r-- | pkg/xtools/doc/xtpmmap.hlp | 144 |
1 files changed, 144 insertions, 0 deletions
diff --git a/pkg/xtools/doc/xtpmmap.hlp b/pkg/xtools/doc/xtpmmap.hlp new file mode 100644 index 00000000..94752da3 --- /dev/null +++ b/pkg/xtools/doc/xtpmmap.hlp @@ -0,0 +1,144 @@ +.help xt_pmmap Mar07 xtools +.ih +NAME +.nf +xt_pmmap -- map a mask and match it to a reference image +.fi +.ih +SYNOPSIS +.nf +# Open a mask. +pointer procedure xt_pmmap (pmname, refim, mname, sz_mname) + +char pmname[ARB] #I Pixel mask name +pointer refim #I Reference image pointer +char mname[ARB] #O Expanded mask name +int sz_mname #O Size of expanded mask name + + +# Close the mask. +procedure xt_pmunmap (im) + +pointer im #I IMIO pointer for mask +.fi +.ih +DESCRIPTION +This interface maps (opens) and unmaps (closes) a mask for use in an +application. It includes resolving mask files from image header keywords +in a reference image, inverting masks, matching masks spatially to a +reference image, and access to non-pixel list formats. + +The \fIpmname\fR argument is a file name or a reference to an image header +keyword using the syntax "!<keyword>". As a special case the name "BPM" +is equivalent to "!BPM". It is also legal for the file name to be a null +string which returns a NULL pointer for the application to interpret +as desired. Most applications will treat this case as all image pixels +are good. + +If the file name, or the file name obtained from a keyword reference, +begins with the character '^' the mask will be inverted to a boolean mask. +This means that input mask values which are zero are set to 1 and non-zero +mask values are set to 0. + +The \fIrefim\fR argument is the IMIO image pointer for a reference image +used to resolve keyword references and for spatial matching. + +The map routine returns the mask name through the \fImname\fR argument. +Typically an application would use the mask name for logging purposes +since it will expand keyword mask references. + +.sh +SPATIAL MATCHING + +The matching of masks to a reference image is a powerful feature though it +can also cause confusion. The advantage of matching is that when images +are modified by trimming or other linear geometric operations the mask, +often referenced in the image header, will still correctly identify +the bad pixels. Note that this does not apply to non-linear coordinate +transformations. + +The matching is based on a "physical" coordinate system. This is typically +the image pixel coordinate system prior to any linear transformation. +IRAF tasks which extract subrasters, subsample, block average, block +replicate, transpose, etc. update header keywords describing the mapping +from the image pixel coordinate system (called the "logical" coordinate +system) to the parent physical coordinate system. Some applications +also attach a meaning to the physical coordinate system such as detector +array coordinates. + +The transformation between logical coordinates (lx,ly) and physical +coordinates (px,py) is defined by the header keywords LTM1_1, LTM2_1, +LTM1_2, LTM_2_2, LTV1, and LTV2 as shown below. + +.nf + lx = px * LTM1_1 + py * LTM2_1 + LTV1 + ly = px * LTM1_2 + py * LTM2_2 + LTV2 + + px = ( LTM2_2 * (lx - LTV1) - LTM2_1 * (ly - LTV2)) / + (LTM1_1 * LTM2_2 - LTM1_2 * LTM2_1) + py = (-LTM1_2 * (lx - LTV1) + LTM1_1 * (ly - LTV2)) / + (LTM1_1 * LTM2_2 - LTM1_2 * LTM2_1) +.fi + +Note that a missing keyword defaults to a value of zero. When all +LTM/LTV keywords are missing then the physical and logical coordinate +systems are identical. In other words the implied transformation is +an identify transformation. Note that one cannot just have +LTV keywords because then the implied transformation matrix is +ill-defined (all matrix elements are assumed zero). + +The matching consists of deriving a transformation between the +logical pixels in the image and the mask by combining the two physical +transformations. This means that even if the logical to physical +transformations are complex, such as a rotation, if the two are the same +a identity or a simple offset relative transformation may still exist +between the two. In this combined logical-to-logical transformation +the current version does not allow a rotation though, as just noted, the +separate logical-to-pixel transformation may be rotated by the same amount. + +When the image is sampled more finely than the mask, that is the same mask +pixel overlaps multiple image pixels, then the nearest mask value (pixel +center to pixel center) is used for each image pixel. When the image is +more coarsely sampled, that is more than one mask pixel overlaps an image +pixel, then the maximum mask value becomes the mask value for the pixel. +This latter choice means that if an image pixel is touched by any bad +pixel then it will be indicated as bad. + +If after matching the mask to the image the mask does not cover +the image, the mask is extended by adding zero mask values. + +The above description is fairly general which makes this seem complex. +However, by far the most common mismatch between an image and its mask +is that an image has been derived as a subraster of a parent image. +In this case the LTM values will be LTM1_1=LTM2_2=1 and LTM2_1=LTM1_2=0 +(or missing) and the matching just depends on the origin offset keywords +LTV1 and LTV2. + +Note that to eliminate this matching one resets the physical coordinate +system to be equivalent to the logical coordinate system. The task +\fIwcsreset\fR can be used or the above LTM/LTV keywords can be deleted +using a header keyword editor. + +.sh +ALTERNATIVE MASK DESCRIPTIONS + +This interface accepts alternate mask descriptions that are internally +converted to the same mask structure for transparent use by the application. +The preferred input mask description is a pixel mask in either pixel list +format (.pl extension) or a FITS pixel mask (a binary table representation). +The alternate representations are a regular image and a text description. + +The pixels values in a regular image are truncated (towards zero) to integers. +Then negative values are set to 0. + +A text description consists of lines in a text file with either two or +four values. The values are truncated to integers if needed. Two values +define a mask value of 2 at the (x,y) coordinate. Four values define a +region, given as (x1,x2,y1,y2) of mask values. The mask values are 2 if +the width of the region is narrower or equal to the height. Otherwise the +value is 3. This is a convention used by task which then interpolate +across bad pixel regions. + +Note that a text description is always tied directly to the input +image; that is, the physical and logical coordinate systems are the same. +.endhelp |