imsmooth.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_imsmooth
def imsmooth(imagename='', kernel='gauss', major='2.0arcsec', minor='2.0arcsec', pa='0deg', targetres=False, region='', box='', chans='', stokes='', mask='', outfile='', stretch=False, overwrite=False, beam=''):

        """Smooth an image or portion of an image
This task performs a Fourier-based convolution to 'smooth' the
image. Smoothing is typically performed in order to reduce the noise in
an image.

        Keyword arguments:
        imagename -- Input image name
                Default: none; Example: imagename='ngc5921_task.im'
        outfile -- Output smoothed image file name
                default: 'imsmooth_results.im'; 
                example: outfile='my.image.smooth';
    kernel -- Type of kernel to use when smoothing (gaussian or boxcar).
                default: 'gauss'; example: kernel='gauss'
                options: 'gauss' or 'boxcar' 
    major -- Depends on the kernel type, see explanation below.
    minor -- Depends on the kernel type, see explanation below.       
    pa    -- position angle to use for gaussian kernel, unused for boxcar.
    beam  -- When kernel="gauss", this parameter can be used instead of major,
             minor, and pa to specify the gaussian parameters. See details below.
    targetres -- Used only for gaussian kernels. If True, major, minor, and
             pa, or beam, are the resolution of the output image. If false, a gaussian
             with these parameters is convolved with the input image to produce
             the output image.
    mask --  Mask to use. See help par.mask. Default is none.
    region -- region file or name.
              Use the viewer, then region manager to select regions of
              the image to process.  Similar to box, but graphical
              Or the name of a region stored with the image, 
              use rg.namesintable()
              to retrieve the list of names.
              Default: none
              Example: region='myimage.im.rgn'
                         region='region1'
        box --  A box region on the directional plane
                ONLY pixel values acceptable at this time.
                Default: none (whole 2-D plane); Example: box='10,10,50,50'
        chans -- channel numbers to select for the continuum,
                ONLY channel numbers accepted at this time.
                Default: none (all); 
                  Example: chans='3~6;>40'
        stokes -- Stokes parameters to image
                Example: 'I'
                Default: none (all);
                Options: 'I','Q','U','V','RR','RL','LR','LL','XX','YX','XY','YY', ... 

Kernel Parameters
-----------------
Finally, and most importantly the kernel is specified via the
major and minor parameters. 

Gaussian kernel: major and minor are the full width at half maximum 
                 (FWHM) of the Gaussian. pa is the position angle
                 of the gaussian. In addition, the targetres parameter
                 indicates if the specified gaussian is to be the
                 resolution of the final image (True) or if it is to
                 be used to convolve the input image to create the
                 output image. If True, the input image must have
                 a restoring beam in its header.
                 If the image has multiple beams and targetres=True,
                 all planes in the image will be convolved so that the
                 resulting resolution is that specified by the beam parameter.
                 If the image has multiple beams and targetres=False, each plane
                 will be convolved with a Gaussian specified by beam (and hence, in
                 general, the output image will also have multiple beams that vary
                 with spectral channel and/or polarization).
Boxcar kernel:   major, length of the box along the y-axis and
                 minor, length of the box along the x-axis

The major, minor, and pa parameters can be specified in one of three ways
   Quantity -- for example major=qa.quantity(1, 'arcsec')
               Note that you can use pixel units, such as 
               major=qa.quantity(1, 'pix')
   String -- for example minor='1pix' or major='0.5km'
             (i.e. a string that the Quanta quantity function accepts).
   Numeric -- for example major=10.
              In this case, the units of major and minor are assumed to 
              be in arcsec and units of pa are assumed to be degrees. 

In the case of a Gaussian, the beam parameter offers an alternate way of
describing the convolving Gaussian. If used, neither major, minor,
nor pa can be specified. The beam parameter must have exactly three
fields: "major", "minor", and "pa" (or "positionangle"). This is, not coincidentally,
the record format for the output of ia.restoringbeam(). For example

beam = {"major": "5arcsec", "minor": "2arcsec", "pa": "20deg"}

If both beam and any of major, minor, and/or pa is specified for a Gaussian kernel,
an exception will be thrown.

Note: Using pixel units allows you to convolve axes with different units.

# EXAMPLE 1
# smoothing with a gaussian kernel 20arseconds by 10 arseconds
imsmooth( imagename='my.image', kernel='gauss', major='10arcsec', minor='10arcsec')

# EXAMPLE 2
# Smoothing using pixel coordinates and a boxcar kernel.
imsmooth( imagename='new.image', major='20pix', minor='10pix', kernel='boxcar')


        """

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

        mytmp['imagename'] = imagename
        mytmp['kernel'] = kernel
        mytmp['major'] = major
        mytmp['minor'] = minor
        mytmp['pa'] = pa
        mytmp['targetres'] = targetres
        mytmp['region'] = region
        mytmp['box'] = box
        mytmp['chans'] = chans
        mytmp['stokes'] = stokes
        mytmp['mask'] = mask
        mytmp['outfile'] = outfile
        mytmp['stretch'] = stretch
        mytmp['overwrite'] = overwrite
        mytmp['beam'] = beam
        pathname='file:///'+os.environ.get('CASAPATH').split()[0]+'/share/xml/'
        trec = casac.utils().torecord(pathname+'imsmooth.xml')

        casalog.origin('imsmooth')
        if trec.has_key('imsmooth') and casac.utils().verify(mytmp, trec['imsmooth']) :
            result = task_imsmooth.imsmooth(imagename, kernel, major, minor, pa, targetres, region, box, chans, stokes, mask, outfile, stretch, overwrite, beam)

        else :
          result = False
        return result