Source code for casatasks.imaging.makemask

#
# stub function definition file for docstring parsing
#

[docs]def makemask(mode='list', inpimage='', inpmask='', output='', overwrite=False, inpfreqs='', outfreqs=''): r""" Makes and manipulates image masks [`Description`_] [`Examples`_] [`Development`_] [`Details`_] Parameters - mode_ (string='list') - Mask method (list, copy,expand,delete,setdefaultmask) .. raw:: html <details><summary><i> mode = list </i></summary> - inpimage_ ({string, stringVec}='') - Name of input image. .. raw:: html </details> .. raw:: html <details><summary><i> mode = copy </i></summary> - inpimage_ ({string, stringVec}='') - Name of input image. - inpmask_ ({string, stringVec}='') - mask(s) to be processed: image masks,T/F internal masks(Need to include parent image names),regions(for copy mode) - output_ (string='') - Name of output mask (imagename or imagename:internal_maskname) - overwrite_ (bool=False) - overwrite output if exists? .. raw:: html </details> .. raw:: html <details><summary><i> mode = expand </i></summary> - inpimage_ ({string, stringVec}='') - Name of input image. - inpmask_ ({string, stringVec}='') - mask(s) to be processed: image masks,T/F internal masks(Need to include parent image names),regions(for copy mode) - inpfreqs_ ({string, intVec}='') - List of chans/freqs (in inpmask) to read masks from - outfreqs_ ({string, intVec}='') - List of chans/freqs (in output) on which to expand the mask - output_ (string='') - Name of output mask (imagename or imagename:internal_maskname) - overwrite_ (bool=False) - overwrite output if exists? .. raw:: html </details> .. raw:: html <details><summary><i> mode = delete </i></summary> - inpmask_ ({string, stringVec}='') - mask(s) to be processed: image masks,T/F internal masks(Need to include parent image names),regions(for copy mode) .. raw:: html </details> .. raw:: html <details><summary><i> mode = setdefaultmask </i></summary> - inpmask_ ({string, stringVec}='') - mask(s) to be processed: image masks,T/F internal masks(Need to include parent image names),regions(for copy mode) .. raw:: html </details> .. _Description: Description makemask manages Boolean masks in an image, converts and regrids Boolean to value-based masks (and vice versa), stretches single-plane masks to cubes, and generates masks from CASA region files. Detailed background information on masks, and examples on how to create them, can be found in the CASA Docs Chapter pages on `image masks <../../notebooks/image_analysis.ipynb#Image-Masks>`__ (image analysis) and `masks for deconvolution <../../notebooks/synthesis_imaging.ipynb#Masks-for-Deconvolution>`__ (synthesis imaging). .. rubric:: Parameter descriptions *mode* Mask method to use by makemask task. Below are the allowed values: - list: list internal Boolean masks in inpimage to the log (default value) - copy: copy/merge masks and regrid if necessary to a new or existing mask - expand: expand a mask from one range of frequencies to another range - 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 default (as appears in the log when do listing with mode='list') - setdefaultmask: set a specified internal mask as a default 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 re-gridded to the output coordinate system. *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 mode='copy'. If output is a new image specified with an internal True/False mask, the pixel values in the input image are copied to the output image and the regions specified in inpmask are merged (if multiple regions specified) and treated as a valid region, therefore will be UNMASKED in output. .. rubric:: Expandable parameters for mode='copy', 'expand', 'delete' and 'setdefaultmask': *inpmask* Name(s) of input mask(s).The default is set to inpmask='', for when no mask is given. To specify an image (zero=bad/non-zero=good) mask, just give a image name (e.g. myimage1.im). To specify an internal (True=good/False=bad) mask, you must give a parent image name and the internal mask name separated by a colon. (e.g. myimage1.im:mask0). The internal mask names can be found by running the makemask task in mode='list'. For mode='expand', use the inpimage values to make a mask (zero/non-zero). Non-zero values are normalized to one in the process. For mode='copy', a list of strings can be used to merge specific image mask(s), True/False mask(s), and region(s). The regions can be specified directly in the CASA region format or in the text file(s) contains the regions. *output* Name of output image (no default value). Ifthe output is a plain image name, the resultant mask is written as an image (zero/one) mask. If the output name is the form of 'imagename:maskname', the resultant mask is written as an internal (True/False) 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 of an image with the target coordinate system and specified the name of the copy in output. If output is specified 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 specified 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, makemask will not regrid but only modify in-place. .. note:: NOTE: The term 'mask' is used in the image analysis and clean tasks in opposite sense. In the image analysis, the masked region is a region to be excluded, while clean's input mask defines the region to be used as a clean box/region. In the makemask task, since the most common use case of output image mask is to use as an input mask in clean, when it converts an internal mask to the image mask, the 'masked' region (where the pixels are masked and have the Boolean value False) of the internal mask is translated to the pixels with value of 0 in output image mask. *overwrite* Overwrite the mask specified in output (see also the output rules above). The default value is False. .. note:: NOTE: For a cube mask, overwrite=True generally overwrites in the specified channel planes only and so any pre-existed masks in other channels will be remain untouched. .. rubric:: 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', '-8km/s~-14km/s' (for a cube with ascending frequencies/velocities). The default is all channels. .. note:: NOTE: The range in frequency or velocity needs to be specified as the same order as in the template cube specified in inpimage. E.g., if a template cube has descending frequencies, then the range will be, e.g. '1.6MHz~1.5MHz' or '-14km/s~-8km/s'. *outfreqs* Output channel/frequency/velocity range. Specify same way as inpfreqs. The default is all channels. .. _Examples: Examples (1) list mode: prints out a list of the internal mask(s) that exist in mymask.im to the log :: makemask(mode='list', inpimage='mymask.im') (2) copy mode: Regrid a Boolean (True/False) 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 (2), but save as integer (one/zero) mask in the output image. :: makemask(mode='copy', inpimage='oldmask.im', inpmask='oldmask.im:mask0', output='newmask.im') mask0 is translated so that pixels in oldmask.im that appears as 'masked' in the viewer orhas the pixel mask value = False when extracted in imval, are to have pixel value of 1 inthe output image, newmask.im. (4) copy mode: Convert a Boolean mask to an integer mask in the same image :: makemask(mode='copy', inpimage='oldmask.im', inpmask='oldmask.im:mask0', output='', overwrite=True) (5) copy mode: Convert an integer mask to a Boolean mask in the same image :: makemask(mode='copy', inpimage='oldmask.im', inpmask='oldmask.im', output='oldmask.im:mask0') (6) copy mode: Copy a CRTF mask defined in mybox.txt to a Boolean mask in a new image :: makemask(mode='copy', inpimage='image1.im', inpmask='mybox.txt', output='image2.im:mask0') The pixel values of image1.im will be copied to image2.im and the region outside mybox.txt will be masked. (7) copy mode: Apply a region defined in a CRTF file to mask part of an image :: makemask(mode='copy', inpimage='image1.im', inpmask='myregion.crtf', output='image1.im:mask0') The region is copied as a Boolean mask (mask0) inside the image, image1.im. The region outside myregion.crtf will be masked. (8) copy mode:Merge integer andBoolean 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 integer 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) (9) expand mode: Expand an integer 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 specified 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') (10) 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) (11) 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. As the inpimage is used as a template for the CoordinateSystem of the output cube, it is a prerequisite to have the cube image (a dirty image, etc). In this particular example, it is assumed that bigmask.im is a working copy made from the cube image of a previous clean execution. It is used as an input template and the resultant mask is overwritten to the same image. Specify the infreqs and outfreqs in frequency (assuming here bigmask.im has frequencies in ascending order), :: 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) or to specify the ranges in velocities, :: makemask(mode='expand', inpimage='bigmask.im', inpmask='smallmask.im:mask0', inpfreqs=4.0km/s~0.5km/s', outfreqs='6.5km/s~-2.4km/s', output='bigmask.im', overwrite=True) (12) delete mode: Delete an internal mask from an image. :: makemask(mode='delete', inpmask='newmask.im:mask0') (13) setdefaultmask mode: Set an internal mask as a default internal mask. :: makemask(mode='setdefaultmask', inpmask='newmask.im:mask1') .. _Development: Development No additional development details .. _Details: Parameter Details Detailed descriptions of each function parameter .. _mode: | ``mode (string='list')`` - Mask method (list, copy,expand,delete,setdefaultmask) .. _inpimage: | ``inpimage ({string, stringVec}='')`` - Name of input image. .. _inpmask: | ``inpmask ({string, stringVec}='')`` - mask(s) to be processed: image masks,T/F internal masks(Need to include parent image names),regions(for copy mode) .. _output: | ``output (string='')`` - Name of output mask (imagename or imagename:internal_maskname) .. _overwrite: | ``overwrite (bool=False)`` - overwrite output if exists? .. _inpfreqs: | ``inpfreqs ({string, intVec}='')`` - List of chans/freqs (in inpmask) to read masks from .. _outfreqs: | ``outfreqs ({string, intVec}='')`` - List of chans/freqs (in output) on which to expand the mask """ pass