makemask.py

Go to the documentation of this file.

#
# This file was generated using xslt from its XML file
#
# Copyright 2009, Associated Universities Inc., Washington DC
#
import sys
import os
from  casac import *
import string
from taskinit import casalog
#from taskmanager import tm
import task_makemask
def makemask(mode='list', inpimage='', inpmask='', output='', overwrite=False, inpfreqs=[], outfreqs=[]):

        """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')





  
        """

#
#    The following is work around to avoid a bug with current python translation
#
        mytmp = {}

        mytmp['mode'] = mode
        mytmp['inpimage'] = inpimage
        mytmp['inpmask'] = inpmask
        mytmp['output'] = output
        mytmp['overwrite'] = overwrite
        mytmp['inpfreqs'] = inpfreqs
        mytmp['outfreqs'] = outfreqs
        pathname='file:///'+os.environ.get('CASAPATH').split()[0]+'/share/xml/'
        trec = casac.utils().torecord(pathname+'makemask.xml')

        casalog.origin('makemask')
        if trec.has_key('makemask') and casac.utils().verify(mytmp, trec['makemask']) :
            result = task_makemask.makemask(mode, inpimage, inpmask, output, overwrite, inpfreqs, outfreqs)

        else :
          result = False
        return result