copymask -- Copy mask from one format into another.
copymask input output
This task creates a copy of the input mask, possibly changing the format when writing the output mask. If the input mask has multiple groups, all groups will be copied to the output mask unless a group specifier is included in the input image name, in which case only the specified group will be copied. There are three mask formats supported by this task. The first format is a full image mask, in either STF (GEIS) or OIF format. The second format is a bad pixel list file. The third format is an STSDAS table. When reading the input file, this task looks at the file characteristics to determine the mask format. When writing the output file, it looks at the file name extension. Files with extensions ending in the letter `h' are assumed to be full images. Files with the extension `.pl' are assumed to be bad pixel lists. All other files are assumed to be STSDAS tables.
Both the STF image format masks and the STSDAS table format masks support multiple groups. However, the bad pixel list masks only allow a single group. To facilitate using bad pixel list masks with mutigroup images, an extra dimension is created when a multigroup image is copied into a bad pixel list mask and each group is stored as a plane (or a line) in the bad pixel list mask. To convert a bad pixel list mask back into the original multigroup mask, set the parameter NDIM to the number of dimensions in the output mask. All dimensions higher than this number will be converted to groups in the output mask. Otherwise the value of NDIM should be left to its default value, zero.
Masks stored as STSDAS tables have the following user parameters: PIXTYPE, GROUPNUM, NAXES, and AXLENi. PIXTYPE contains the data type of the original mask as an integer constant. GROUPNUM contains the number of groups in the mask. NAXES contains the number of dimensions in the mask. And AXLENi contains the length of each dimension. The last letter i is a digit that runs from 1 to NAXES, e.g., AXLEN1 and AXLEN2.
The column names in STSDAS table masks are the following: GROUP, PIXi, LENGTH, and VALUE. The GROUP column contains the group number from the original mask. If the original mask was not in group format, or only had a single group, the GROUP column will not be present. The PIXi columns give the location of the first pixel in a run of pixels. (A run of pixels is a consecutive sequence of pixels in the same line which has the same value.) Each column gives the location in one of the dimensions of the mask. For example, PIX1 and PIX2 give the location of the starting pixel in a two dimensional image. The LENGTH column gives the length of the run of pixels. If this column is missing, the length of the run is assumed to be one. The VALUE column contains the value of the run of pixels. An STSDAS table mask only contains information about non-zero runs of pixels. All pixels not mentioned are assumed to be zeroes. The STSDAS table mask is sorted in increasing order, with the GROUP column being the most significant, if present, followed by the PIXi columns from the highest to the lowest.
- input [file name template]
- The input mask file(s). If masks do not contain a group specifier, all groups will be copied. Otherwise, the specified group will be copied.
- output [file name template]
- The output mask file(s). If this parameter is the name of a directory, the mask file(s) will be written in the directory. Otherwise, the number of input and output masks must match.
- (ndim = 0) [int, min = 0, max = 7]
- Dimensionality of the output image. If the value is zero, the output mask will have the same number of dimensions as the input mask. If the value is less than the number of dimensions in the input mask, the extra dimensions will be converted into groups. If the value is greater than the number of groups in the input mask, groups in the input mask will be converted into the extra dimension. The one exception is when a multigroup mask is copied into a bad pixel list mask. Then the groups are copied to an extra dimension, even if the value of this parameter is zero.
- (verbose = yes) [boolean]
- Print a message as each mask in copied?
1. Copy a four group WF/PC mask into an STSDAS table mask:
im> copymask w0001.q0h w0001.tab
2. Copy just the first group into a bad pixel list mask:
im> copymask w0001.q0h w0001.pl
3. Convert each group to an extra dimension in the bad pixel list mask:
im> copymask w0001.q0h w0001.pl
4. Convert the bad pixel list mask back to a multi-group image
im> copymask w0001.pl w0001.q0h ndim=2