Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatasks/makemask.py: 89%
27 statements
« prev ^ index » next coverage.py v7.6.4, created at 2024-11-01 07:19 +0000
1##################### generated by xml-casa (v2) from makemask.xml ##################
2##################### 8eacce9c9cbe61ce734b2e6da8ec5f9c ##############################
3from __future__ import absolute_import
4import numpy
5from casatools.typecheck import CasaValidator as _val_ctor
6_pc = _val_ctor( )
7from casatools.coercetype import coerce as _coerce
8from casatools.errors import create_error_string
9from .private.task_makemask import makemask as _makemask_t
10from casatasks.private.task_logging import start_log as _start_log
11from casatasks.private.task_logging import end_log as _end_log
12from casatasks.private.task_logging import except_log as _except_log
14class _makemask:
15 """
16 makemask ---- Makes and manipulates image masks
18 Construct masks based on various criteria, convert between mask-types, and generate a mask for clean
20 --------- parameter descriptions ---------------------------------------------
22 mode Mask method (list, copy,expand,delete,setdefaultmask)
23 inpimage Name of input image.
24 inpmask mask(s) to be processed: image masks,T/F internal masks(Need to include parent image names),regions(for copy mode)
25 output Name of output mask (imagename or imagename:internal_maskname)
26 overwrite overwrite output if exists?
27 inpfreqs List of chans/freqs (in inpmask) to read masks from
28 outfreqs List of chans/freqs (in output) on which to expand the mask
29 [1;42mRETURNS[1;m void
31 --------- examples -----------------------------------------------------------
35 Modes :
36 -------------
38 list : list internal masks in inpimage to the log
39 copy : Copy/merge masks and regrid if necessary to a new or existing mask
40 expand : Expand a mask from one range of freqs to another range
41 delete : delete an internal mask from an image (if the deleted mask was a default mask,
42 the task chooses the first one in the remaining internal mask list (as appears
43 in the log when do listing with mode='list')
44 setdefaultmask : set a specified internal mask as a default internal mask
49 In all cases (for output mask is expected), if the output image has a different coordinate system from the
50 result of input and processing, the mask will be re-gridded to the output
51 coordinate system.
54 Parameter Descriptions and rules:
55 ------------------------------
56 inpimage : Name of input image to use as a reference for the output coordinates (if output does not exist).
57 Also used as a reference image when regions are specified in inpmask for copy mode
58 If output is a new image specified with an internal T/F mask, the pixel values in the input image
59 are copied to the output image and the regions specified in inpmask are merged (if mutliple regions
60 specified) and treated as a valid region therefore will be UNMASKED in output.
61 default: none (must specify for list, copy, expand modes)
63 Expandable parameters for mode='copy','expand','delete' and 'setdefaultmask':
64 inpmask : Name(s) of input mask(s)
65 default: none
66 To specify an image (zero/non-zero) mask, just give a image name (e.g. myimage1.im)
67 To specify an internal (T/F) mask, you must give a parent image name and the internal mask name
68 separated by a colon. (e.g. myimage1.im:mask0). The internal mask names can be found by running
69 the makemask task in mode='list'.
71 (expand mode)
72 'myimage:mask0' : use(true/false) internal mask
73 'myimage' : use the inpimage values to make a mask (zero/non-zero).
74 Non-zero values are normalized to one in the process.
75 (copy mode)
76 Specify the image mask(s), T/F mask(s), and region(s) to be merged in a list of strings.
77 The regions can be specified directly in the CASA region format or in the text file(s) contains
78 the regions.
80 (delete and setdefaultmask mode)
81 Specify the internal mask with the format, image:mask
84 output : Name of output image.
85 default: none
86 *The resultant mask is written as an image (zero/one) mask if the output is a plain image name
87 *The resultant mask is written as an internal (T/F) mask if the output name is the form of 'imagename:maskname'
88 The created mask is set as a default internal mask.
89 *To re-grid a mask to a different coordinate system,
90 give an image with the target coordinate system in inpimage. Or make a copy an image
91 with the target coordinate system and specified the name of the copy in output.
94 - If output is specified as a plain image, if it exists, it will regrid the mask to
95 the new coordinate system and modify output (if overwrite=True).
96 - If output is specified as an image with an internal mask, if the internal mask exists,
97 it will regrid the mask to the new coordinate system and modify the internal mask only (if overwrite=True).
98 - If output does not exist, it will only copy inpimage.
99 - If output == inpimage, do not regrid. Only modify in-place.
101 *** Please note that the term 'mask' is used in the image analysis and clean tasks in opposite
102 sense. In the image analysis, the masked region in general a region to be excluded while
103 clean's input mask defines the region to be used as a clean box/region.
104 In the makemask task, since the most common use case of output image mask is to use as
105 an input mask in clean, when it converts an internal mask to the image mask,
106 the 'masked' region (where the pixels are masked and have the Boolean values 'False')
107 of the internal mask is translated to the pixels with value of 0 in output image mask.
109 overwrite : overwrite the mask specified in output? (see also the output rules above)
110 default: False
111 * Note that for a cube mask, overwrite=True generally overwrites in the specified channel planes only and
112 so any pre-existed masks in other channels will be remain untouched.
114 Additional expandable parameters for mode='expand':
115 inpfreqs : input channel/frequency/velocity range
116 Specify channels in a list of integers. for frequency/velocity,
117 a range is specified in a string with '~', e.g. '1.5MHz~1.6MHz', '-8km/s~-14km/s'
118 (for the cube with ascending frequencies)
119 default: [] - all channels
120 * Note that the range in frequency or velocity needs to be specified as the same order
121 as in the template cube specified in inpimage. E.g., if a template cube has descending
122 frequencies, then the range will be, for example,'1.6MHz~1.5MHz' or '-14km/s~-8km/s'
124 outfreqs : output channel/frequency/velocity range
125 Specify same way as inpfreqs
126 default: [] - all channels
129 Usage examples :
130 ---------------------------
131 (1) (list mode):
132 makemask(mode='list', inpimage='mymask.im')
133 it prints out a list of the internal mask(s) exist in mymask.im to the log
135 (2) (copy mode):
136 Regrid a Boolean mask from one coordinate system to another and save as Boolean mask
137 in the output image.
139 makemask(mode='copy', inpimage='oldmask.im', inpmask='oldmask.im:mask0', output='newmask.im:mask0')
141 (3) (copy mode):
142 Same as (1), but save as integer mask in the output image.
144 makemask(mode='copy', inpimage='oldmask.im', inpmask='oldmask.im:mask0', output='newmask.im')
146 * mask0 is translated so that pixels in oldmask.im that appears as 'masked' in the viewer or
147 has the pixel mask value = 'False' when extracted in imval, are to have pixel value of 1 in
148 the output image, newmask.im.
150 (4) (copy mode):
151 Convert a Boolean(true/false) mask to an integer(one/zero) mask in the same image
153 makemask(mode='copy', inpimage='oldmask.im', inpmask='oldmask.im:mask0', output='', overwrite=True)
156 (5) (copy mode):
157 Convert an integer(one/zero) mask to a Boolean(true/false) mask in the same image
159 makemask(mode='copy', inpimage='oldmask.im', inpmask='oldmask.im', output='oldmask.im:mask0')
161 (6) (copy mode):
162 Copy a CRTF mask defined in mybox.txt to a Boolean(true/false) mask in a new image
164 makemask(mode='copy', inpimage='image1.im', inpmask='mybox.txt', output='image2.im:mask0')
166 The pixel values of image1.im will be copied to image2.im and the region outside mybox.txt
167 will be masked.
169 (7) (copy mode):
170 Apply a region defined in a CRTF file to mask part of an image
172 makemask(mode='copy', inpimage='image1.im', inpmask='myregion.crtf', output='image1.im:mask0')
174 The region is copied as a T/F mask (mask0) inside the image, image1.im. The region outside myregion.crtf
175 will be masked.
178 (8) (copy mode):
180 Merge a (one/zero) mask and T/F masks, using the input coordinate-sys of inpimage and
181 saving in a new output file. Remember, if the image specified in output already exist and
182 has a different coordinate system from inpimage, the mask will be regridded to it.
183 All masks to be merged are specified in a list in inpmask.
184 The name of internal masks must be given in the format, 'parent_image_name:internal_mask_name',
185 as shown the example below.
187 In the example below, image1.im (the 1/0 mask), the internal masks, mask0 from image1.im
188 and mask1 from image2.im, and a region (on image1.im as defined in inpimage) are combined.
189 The output, newmask.im is a new mask name which has not
190 yet exist so image specified in inpimage, image1.im's coordinates are used as a target
191 image coordinates. If image1.im and image2.im has different coordinates, image2.im:mask1 is
192 regridded before it is combined to the other two masks.
194 makemask(mode='copy',
195 inpimage='image1.im',
196 inpmask=['image1.im', image1.im:mask0','image2.mask:mask1', 'circle[[15pix , 15pix] ,8pix ]'],
197 output='newmask.im);
199 (9) (expand mode):
200 Expand a (one/zero) mask from continuum imaging to use as an input mask image for
201 spectral line imaging. Use an existing spectral line clean image as a template by
202 specified in inpimage.
203 The inpfreqs is left out as it uses a default (=[], means all channels).
205 makemask(mode='expand', inpimage='spec.clean.image', inpmask='cont.clean.mask'
206 outfreqs=[4,5,6,7], output='spec.clean.mask')
208 (10) (expand mode):
209 Expand a Boolean mask from one range of channels to another range
210 in the same image.
212 makemask(mode='expand', inpimage='oldmask.im', inpmask='oldmask.im:mask0', inpfreqs=[5,6], outfreqs=[4,5,6,7],
213 output='oldmask.im:mask0', overwrite=True)
216 (11) (expand mode):
217 Expand a Boolean mask from a range of channels in the input image to another range
218 of channels in a different image with a different spectral-coordinate system.
219 Save the mask as ones/zeros so that it can be used as an input mask in the clean task.
220 As the inpimage is used as a template for the CoordinateSystem of the output cube, it is
221 a prerequisite to have the cube image (a dirty image, etc). In this particular example,
222 it is assumed that bigmask.im is a working copy made from the cube image of a previous clean
223 execution. It is used as an input template and the resultant mask is overwritten to the same image.
225 Specify the infreqs and outfreqs in frequency (assuming here bigmask.im has frequencies in ascending order)
226 makemask(mode='expand', inpimage='bigmask.im', inpmask='smallmask.im:mask0',
227 inpfreqs='1.5MHz~1.6MHz', outfreqs='1.2MHz~1.8MHz', output='bigmask.im', overwrite=True)
229 or to specify the ranges in velocities,
230 makemask(mode='expand', inpimage='bigmask.im', inpmask='smallmask.im:mask0',
231 inpfreqs=4.0km/s~0.5km/s', outfreqs='6.5km/s~-2.4km/s', output='bigmask.im', overwrite=True)
234 (12) (delete mode)
235 Delete an internal mask from an image.
237 makemask(mode='delete', inpmask='newmask.im:mask0')
239 (13) (setdefaultmask mode)
240 Set an internal mask as a default internal mask.
242 makemask(mode='setdefaultmask', inpmask='newmask.im:mask1')
251 """
253 _info_group_ = """imaging"""
254 _info_desc_ = """Makes and manipulates image masks"""
256 def __call__( self, mode='list', inpimage='', inpmask='', output='', overwrite=False, inpfreqs=[ ], outfreqs=[ ] ):
257 schema = {'mode': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'delete', 'copy', 'expand', 'list', 'setdefaultmask' ]}, 'inpimage': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}]}, 'inpmask': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}]}, 'output': {'type': 'cStr', 'coerce': _coerce.to_str}, 'overwrite': {'type': 'cBool'}, 'inpfreqs': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cIntVec', 'coerce': [_coerce.to_list,_coerce.to_intvec]}]}, 'outfreqs': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cIntVec', 'coerce': [_coerce.to_list,_coerce.to_intvec]}]}}
258 doc = {'mode': mode, 'inpimage': inpimage, 'inpmask': inpmask, 'output': output, 'overwrite': overwrite, 'inpfreqs': inpfreqs, 'outfreqs': outfreqs}
259 assert _pc.validate(doc,schema), create_error_string(_pc.errors)
260 _logging_state_ = _start_log( 'makemask', [ 'mode=' + repr(_pc.document['mode']), 'inpimage=' + repr(_pc.document['inpimage']), 'inpmask=' + repr(_pc.document['inpmask']), 'output=' + repr(_pc.document['output']), 'overwrite=' + repr(_pc.document['overwrite']), 'inpfreqs=' + repr(_pc.document['inpfreqs']), 'outfreqs=' + repr(_pc.document['outfreqs']) ] )
261 task_result = None
262 try:
263 task_result = _makemask_t( _pc.document['mode'], _pc.document['inpimage'], _pc.document['inpmask'], _pc.document['output'], _pc.document['overwrite'], _pc.document['inpfreqs'], _pc.document['outfreqs'] )
264 except Exception as exc:
265 _except_log('makemask', exc)
266 raise
267 finally:
268 task_result = _end_log( _logging_state_, 'makemask', task_result )
269 return task_result
271makemask = _makemask( )