Makes and manipulates image masks
Modes :
-------------
copy : Copy/merge masks and regrid if necessary to a new or existing mask
expand : Expand a mask from one range of freqs to another range
list : list internal masks in inpimage to the log
delete : delete an internal mask from an image (if the deleted mask was a default mask,
the task chooses the first one in the remaining internal mask list (as appears
in the log when do listing with mode='list')
setdefaultmask : set a specified internal mask as a defult internal mask
In all cases (for output mask is expected), if the output image has a different coordinate system from the
result of input and processing, the mask will be regridded to the output
coordinate system.
Parameter Descriptions and rules:
------------------------------
inpimage : Name of input image to use as a reference for the output coordinates (if output does not exist).
Also used as a reference image when regions are specified in inpmask for copy mode
default: none (must specify for list, copy, expand modes)
Expandable parameters for mode='copy','expand','delete' and 'setdefaultmask':
inpmask : Name(s) of input mask(s)
default: none
To specify an image (zero/non-zero) mask, just give a image name (e.g. myimage1.im)
To specify an internal (T/F) mask, you must give a parent image name and the internal mask name
seperated by a colon. (e.g. myimage1.im:mask0). The internal mask names can be found by running
the makemask task in mode='list'.
(expand mode)
'myimage:mask0' : use(true/false) internal mask
'myimage' : use the inpimage values to make a mask (zero/non-zero).
Non-zero values are normalized to one in the process.
(merge mode)
Specify the image mask(s), T/F mask(s), and region(s) to be merged in a list of strings.
The regions can be specified directly in the CASA region format or in the text file(s) contains
the regions.
(delete and setdefaultmask mode)
Specify the internal mask with the format, image:mask
output : Name of output image.
default: none
*The resultant mask is written as an image (zero/one) mask if the output is a plain image name
*The resultant mask is written as an internal (T/F) mask if the output name is the form of 'imagename:maskname'
The created mask is set as a default internal mask.
*To re-grid a mask to a different coordinate system,
give an image with the target coordinate system in inpimage. Or make a copy an imge
with the target coordinate system and specified the name of the copy in output.
- If output is specifield as a plain image, if it exists, it will regrid the mask to
the new coordinate system and modify output (if overwrite=True).
- If output is specifield as an image with an internal mask, if the internal mask exists,
it will regrid the mask to the new coordinate system and modify the internal mask only (if overwrite=True).
- If output does not exist, it will only copy inpimage
- If output == inpimage, do not regrid. Only modify in-place.
overwrite : overwrite the mask specified in output? (see also the output rules above)
default: False
Additional expandable parameters for mode='expand':
inpfreqs : input channel/frequency/velocity range
Specify channels in a list of integers. for frequency/velocity,
a range is specified in a string with '~', e.g. '1.5MHz~1.6MHz'
default: [] - all channels
outfreqs : output channel/frequency/velocity range
Specify same way as inpfreqs
default: [] - all channels
Usage examples :
---------------------------
(1) (list mode):
makemask(mode='list', inpimage='mymask.im')
it prints out a list of the internal mask(s) exist in mymask.im to the log
(2) (copy mode):
Regrid a boolean mask from one coordinate system to another and save as boolean mask
in the output image.
makemask(mode='copy', inpimage='oldmask.im', inpmask='oldmask.im:mask0', output='newmask.im:mask0')
(3) (copy mode):
Same as (1), but save as integer mask in the output image.
makemask(mode='copy', inpimage='oldmask.im', inpmask='oldmask.im:mask0', output='newmask.im')
(4) (copy mode):
Convert a boolean(true/false) mask to integer(one/zero) mask in the same image
makemask(mode='copy', inpimage='oldmask.im', inpmask='oldmask.im:mask0', output='', overwrite=True)
(5) (copy mode):
Convert an integer (one/zero) mask to boolean(true/false) mask in the same image
makemask(mode='copy', inpimage='oldmask.im', inpmask='oldmask.im', output='oldmask.im:mask0')
(6) (copy mode):
Merge a one/zero mask and T/F masks, using the input coordinate-sys of inpimage and
saving in a new output file. Remember, if the image specified in output already exist and
has a different coordinate system from inpimage, the mask will be regridded to it.
All masks to be merged are specified in a list in inpmask.
The name of internal masks must be given in the format, 'parent_image_name:internal_mask_name',
as shown the example below.
In the example below, image1.im (the 1/0 mask), the internal masks, mask0 from image1.im
and mask1 from image2.im, and a region (on image1.im as defined in inpimage) are combined.
The output, newmask.im is a new mask name which has not
yet exist so image specified in inpimage, image1.im's coordinates are used as a target
image coordinates. If image1.im and image2.im has different coordinates, image2.im:mask1 is
regridded before it is combined to the other two masks.
makemask(mode='copy',
inpimage='image1.im',
inpmask=['image1.im', image1.im:mask0','image2.mask:mask1', 'circle[[15pix , 15pix] ,8pix ]'],
output='newmask.im);
(7) (expand mode):
Expand a (one/zero) mask from continuum imaging to use as an input mask image for
spectral line imaging. Use an existing spectral line clean image as a template by
sepecified in inpimage.
The inpfreqs is left out as it uses a default (=[], means all channels).
makemask(mode='expand', inpimage='spec.clean.image', inpmask='cont.clean.mask'
outfreqs=[4,5,6,7], output='spec.clean.mask')
(8) (expand mode):
Expand a boolean mask from one range of channels to another range
in the same image.
makemask(mode='expand', inpimage='oldmask.im', inpmask='oldmask.im:mask0', inpfreqs=[5,6], outfreqs=[4,5,6,7],
output='oldmask.im:mask0', overwrite=True)
(9) (expand mode):
Expand a boolean mask from a range of channels in the input image to another range
of channels in a different image with a different spectral-coordinate system.
Save the mask as ones/zeros so that it can be used as an input mask in the clean task.
makemask(mode='expand', inpimage='bigmask.im', inpmask='smallmask.im:mask0',
inpfreqs='1.5MHz~1.6MHz', outfreqs='1.2MHz~1.8MHz', output='bigmask.im', overwrite=True)
(10) (delete mode)
Delete an internal mask from an image.
makemask(mode='delete', inpmask='newmask.im:mask0')
(11) (setdefaultmask mode)
Set an internal mask as a default internal mask.
makemask(mode='setdefaultmask', inpmask='newmask.im:mask1')
1.8.0