imhead.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_imhead
def imhead(imagename='', mode='summary', hdkey='', hdvalue='', hdtype='', hdcomment='', verbose=False):

        """List, get and put image header parameters

        This task allows the user to manipulate some meta-data parameters in an
        image.  The mode='list' shows those keywords that are
        presently implemented, with their values.  The contents associated
        with the keywords can be obtained (get) and changed (put).

        Additional image parameter listings are available.

        [For visibility files, the taskname='vishead' should be used.]

        The modes that are available are:

           list    --- Lists the image header keywords and values.
                       Use this if 'get' and 'put' are executed.
           get     --- Get the specified keyword value(s) from the image
           put     --- Put the specified keyword value(s) into the image 

           history --- Display the history information in hte CASA logger.
           summary --- Information summarizing the CASA image file.
           fits    --- Lists the header information in a FITS style (not available)
           add     --- Adds a new header key.  Use with caution
           del     --- Delete a header key, hdkey.  Use with caution
        
        Parameters currently implemented are listed using mode = 'list'

           beammaj         Major axis of the clean beam
           beammin         Minor axis of the clean beam
           beampa          Position angle of the clean beam
           NOTE: If the image contains multiple beams, use mode="summary" to get
           a listing.
           bunit           Brightness unit (K, Jy/beam, etc)
           cdeltn          Pixel size, nth axis  (max n is 4)
           crpixn          Pixel coordinate of reference point, nth axis
           crvaln          Pixel location of reference point, nth axis
           ctypen          Axis name, nth axis
           cunitn          Pixel units, nth axis
           datamax         Maximum pixel value in image
           datamin         Minimum pixel value in image
           date-obs        Date of the observation
           equinox         Reference frame for directional coordinates
           imtype          Image type: intensity, 
           minpos
           minpixpos
           maxpos
           maxpixpos
           object          Source name
           observer        Observer name
           projection      Image projection ('SIN','TAN', or 'ZEA')
           reffreqtype     Reference frame for the spectral coordinates
           restfreq        Rest Frequency
           shape           Number of pixels along each axis
           telescope       Telescope name

        Keyword arguments:

        imagename --- Name of input image
                        default: none; example: imagename='ngc5921_task.image'
        mode      --- Mode: options: 
                        default: none; 'list', 'summary', 'fits', 'history',
                        'get', 'put', 'add', and 'del'

                        NOTE:  'add' and 'del' should be used with caution

        hdkey     --- keyword to use with get, put, add, or del
                        default: none;  example: hdkey='telescope'
        hdvalue   --- keyword value that is 'got', or to be 'put' or
                      to be 'added'
                        default: ''; example: hdvalue='VLA'
        hdcomment --- comment to be stored with the keyword for mode='put' or mode='add'
        Examples: 
                  hdkey='date-obs';hdvalue='2007/06/20/00:00:00'
                  hdkey='beammajor';hdvalue='55arcsec'
                  hdkey='beampa'';hdvalue='0deg'
                  hdkey='restfrequency';hdvalue='1.421GHz'
                  hdkey='restfrequency';hdvalue='1.421GHz, 115.272GHz'
                  hdkey='projection';hdvalue='TAN'
                  hdkey='cdelt4';hdvalue=24415.05
                  hdkey='cdelt1';hdvalue='7.75e-5deg'
                  hdkey='crval1';hdvalue=qa.quantity( '763180', 'arsec')
                  hdkey='crval1';hdvalue='14:07:58'
                  hdkey='crval4';hdvalue='6250000Hz'

        hdtype    --- Used only with 'add' mode.  It is the data type that
                           is used to store the hdkey.  It can not be used to
                           change the data type of an exiting keyword.
                      options: bool, int, string, doubple, complex
                      default: none; example hdtype='double'


        Note that hdvalue will contain numbers, strings as well as units.
        
        If mode="summary", verbose=True and the image contains multiple beams, the output,
        will contain information on every beam in the dataset. If mode="summary",
        verbose=False and the image has multiple beams, only a brief summary of
        beams for each polarization is listed. In this
        case, the beams with the maximum area, the minimum area, and the median area for
        each polarization are listed. If mode is not "summary" and/or the image does not
        have multiple beams, verbose is not used.
        
        Examples:

        1)  get the clean beam from one image and put it in a second image

           Get the clean beam from image1 into hdvalue
                imagename = 'image1.im'; mode = 'get'; hdkey = 'beam'
                hdvalue = imhead()
                print hdvalue   #  to see values

           To then put the clean beam into image2
                imagename = 'image2.im', mode = 'put'; imhead()

        2)  Most output values are dictionaries:


               mode = 'get'; hdkey = 'maxpos'; aa = imhead()

            would give for the command print aa
                {'value': '03:19:48.160, +41.30.42.103, I, 4.88163e+09Hz', 'unit': ''}
            print aa['value'] gives 
                03:19:48.160, +41.30.42.103, I, 4.88163e+09Hz
            print aa['value'[1][0:12] gives 03:19:48.160

      
               mode = 'get'; hdkey = 'crpix1'; aa = imhead()

            would give for the command print aa
                {'value': '128.0', 'unit': ''}
            print aa['value'] gives 
                128.0    (a string)

        3)  The use of put is a bit more straight-forward

               mode = 'put'; hdkey = 'crpix1'; hdvalue = '200'; imhead()
             then
               mode = 'get'; hdkey = 'crpix1'; aa = imhead()  would give
                   {'value': '200.0', 'unit': ''}



        """

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

        mytmp['imagename'] = imagename
        mytmp['mode'] = mode
        mytmp['hdkey'] = hdkey
        mytmp['hdvalue'] = hdvalue
        mytmp['hdtype'] = hdtype
        mytmp['hdcomment'] = hdcomment
        mytmp['verbose'] = verbose
        pathname='file:///'+os.environ.get('CASAPATH').split()[0]+'/share/xml/'
        trec = casac.utils().torecord(pathname+'imhead.xml')

        casalog.origin('imhead')
        if trec.has_key('imhead') and casac.utils().verify(mytmp, trec['imhead']) :
            result = task_imhead.imhead(imagename, mode, hdkey, hdvalue, hdtype, hdcomment, verbose)

        else :
          result = False
        return result