Dealing with Image Headers
List the Header of a FITS uimage (listfits)
CASA can frequently read and write image fits files directly. Nevertheless, it is advisable to convert the images to the CASA format first with importfits for some tasks and applications.
The task listfits can be used to display the HDU (Header Data Unit) of a fits image. The input is pretty obvious:
# listfits :: List the HDU and typical data rows of a fits file:
fitsfile = '' # Name of input fits file
the logger output will be the fits HDU, e.g. for a Digital Sky Survey Image this will look like:
####################################
##### Begin Task: listfits #####
listfits(fitsfile="dss.test.fits")
read fitsfile=dss.test.fits
d 29: DATE-OBS= '1998-11-24T11:83:00' /Observation: Date/Time
time.
Primary Array HDU ------>>>
d 156: DATAMIN = 2701 /GetImage: Minimum returned pixel value
value has wrong data type.
erted to type double.
d 157: DATAMAX = 22189 /GetImage: Maximum returned pixel value
value has wrong data type.
erted to type double.
SIMPLE = T /FITS: Compliance
BITPIX = 16 /FITS: I*2 Data
NAXIS = 2 /FITS: 2-D Image Data
NAXIS1 = 891 /FITS: X Dimension
NAXIS2 = 893 /FITS: Y Dimension
EXTEND = T /FITS: File can contain extensions
DATE = '2016-11-17' /FITS: Creation Date
ORIGIN = 'STScI/MAST' /GSSS: STScI Digitized Sky Survey
SURVEY = 'POSSII-F' /GSSS: Sky Survey
REGION = 'XP061 ' /GSSS: Region Name
PLATEID = 'A2U4 ' /GSSS: Plate ID
SCANNUM = '01 ' /GSSS: Scan Number
DSCNDNUM= '00 ' /GSSS: Descendant Number
TELESCID= 3 /GSSS: Telescope ID
BANDPASS= 35 /GSSS: Bandpass Code
COPYRGHT= 'Caltech/Palomar' /GSSS: Copyright Holder
SITELAT = 33.356 /Observatory: Latitude
SITELONG= 116.863 /Observatory: Longitude
TELESCOP= 'Oschin Schmidt - D' /Observatory: Telescope
INSTRUME= 'Photographic Plate' /Detector: Photographic Plate
EMULSION= 'IIIaF ' /Detector: Emulsion
FILTER = 'RG610 ' /Detector: Filter
PLTSCALE= 67.2 /Detector: Plate Scale arcsec per mm
PLTSIZEX= 355 /Detector: Plate X Dimension mm
PLTSIZEY= 355 /Detector: Plate Y Dimension mm
PLATERA = 144.055 /Observation: Field centre RA degrees
PLATEDEC= 69.812 /Observation: Field centre Dec degrees
PLTLABEL= 'SF07740 ' /Observation: Plate Label
DATE-OBS= '1998-11-24T11:83:00' /Observation: Date/Time
EXPOSURE= 50 /Observation: Exposure Minutes
PLTGRADE= 'A ' /Observation: Plate Grade
OBSHA = 1.28333 /Observation: Hour Angle
OBSZD = 37.9539 /Observation: Zenith Distance
AIRMASS = 1.26743 /Observation: Airmass
REFBETA = 61.7761 /Observation: Refraction Coeff
REFBETAP= -0.082 /Observation: Refraction Coeff
REFK1 = -48616.4 /Observation: Refraction Coeff
REFK2 = -148442 /Observation: Refraction Coeff
CNPIX1 = 4993 /Scan: X Corner
CNPIX2 = 10823 /Scan: Y Corner
XPIXELS = 23040 /Scan: X Dimension
YPIXELS = 23040 /Scan: Y Dimension
XPIXELSZ= 15.0295 /Scan: Pixel Size microns
YPIXELSZ= 15 /Scan: Pixel Size microns
PPO1 = -3.06942e+06 /Scan: Orientation Coeff
PPO2 = 0 /Scan: Orientation Coeff
PPO3 = 177500 /Scan: Orientation Coeff
PPO4 = 0 /Scan: Orientation Coeff
PPO5 = 3.06942e+06 /Scan: Orientation Coeff
PPO6 = 177500 /Scan: Orientation Coeff
PLTRAH = 9 /Astrometry: Plate Centre H
PLTRAM = 36 /Astrometry: Plate Centre M
PLTRAS = 19 /Astrometry: Plate Centre S
PLTDECSN= '+ ' /Astrometry: Plate Centre +/-
PLTDECD = 69 /Astrometry: Plate Centre D
PLTDECM = 47 /Astrometry: Plate Centre M
PLTDECS = 5 /Astrometry: Plate Centre S
EQUINOX = 2000 /Astrometry: Equinox
AMDX1 = 67.136 /Astrometry: GSC1 Coeff
AMDX2 = -0.220786 /Astrometry: GSC1 Coeff
AMDX3 = -323.444 /Astrometry: GSC1 Coeff
AMDX4 = -2.36254e-05 /Astrometry: GSC1 Coeff
AMDX5 = 3.47547e-05 /Astrometry: GSC1 Coeff
AMDX6 = -4.51329e-06 /Astrometry: GSC1 Coeff
AMDX7 = 0 /Astrometry: GSC1 Coeff
AMDX8 = 2.30047e-06 /Astrometry: GSC1 Coeff
AMDX9 = -4.38823e-08 /Astrometry: GSC1 Coeff
AMDX10 = 2.35865e-06 /Astrometry: GSC1 Coeff
AMDX11 = -3.42372e-08 /Astrometry: GSC1 Coeff
AMDX12 = 0 /Astrometry: GSC1 Coeff
AMDX13 = 0 /Astrometry: GSC1 Coeff
AMDX14 = 0 /Astrometry: GSC1 Coeff
AMDX15 = 0 /Astrometry: GSC1 Coeff
AMDX16 = 0 /Astrometry: GSC1 Coeff
AMDX17 = 0 /Astrometry: GSC1 Coeff
AMDX18 = 0 /Astrometry: GSC1 Coeff
AMDX19 = 0 /Astrometry: GSC1 Coeff
AMDX20 = 0 /Astrometry: GSC1 Coeff
AMDY1 = 67.1428 /Astrometry: GSC1 Coeff
AMDY2 = 0.217113 /Astrometry: GSC1 Coeff
AMDY3 = 412.762 /Astrometry: GSC1 Coeff
AMDY4 = 4.85815e-05 /Astrometry: GSC1 Coeff
AMDY5 = -2.68591e-05 /Astrometry: GSC1 Coeff
AMDY6 = 1.60316e-05 /Astrometry: GSC1 Coeff
AMDY7 = 0 /Astrometry: GSC1 Coeff
AMDY8 = 2.31356e-06 /Astrometry: GSC1 Coeff
AMDY9 = -5.59638e-08 /Astrometry: GSC1 Coeff
AMDY10 = 2.3486e-06 /Astrometry: GSC1 Coeff
AMDY11 = 2.00162e-08 /Astrometry: GSC1 Coeff
AMDY12 = 0 /Astrometry: GSC1 Coeff
AMDY13 = 0 /Astrometry: GSC1 Coeff
AMDY14 = 0 /Astrometry: GSC1 Coeff
AMDY15 = 0 /Astrometry: GSC1 Coeff
AMDY16 = 0 /Astrometry: GSC1 Coeff
AMDY17 = 0 /Astrometry: GSC1 Coeff
AMDY18 = 0 /Astrometry: GSC1 Coeff
AMDY19 = 0 /Astrometry: GSC1 Coeff
AMDY20 = 0 /Astrometry: GSC1 Coeff
AMDREX1 = 67.1344 /Astrometry: GSC2 Coeff
AMDREX2 = -0.228086 /Astrometry: GSC2 Coeff
AMDREX3 = -323.419 /Astrometry: GSC2 Coeff
AMDREX4 = 6.58632e-06 /Astrometry: GSC2 Coeff
AMDREX5 = 3.12929e-06 /Astrometry: GSC2 Coeff
AMDREX6 = 4.27259e-06 /Astrometry: GSC2 Coeff
AMDREX7 = 0 /Astrometry: GSC2 Coeff
AMDREX8 = 0 /Astrometry: GSC2 Coeff
AMDREX9 = 0 /Astrometry: GSC2 Coeff
AMDREX10= 0 /Astrometry: GSC2 Coeff
AMDREX11= 0 /Astrometry: GSC2 Coeff
AMDREX12= 0 /Astrometry: GSC2 Coeff
AMDREX13= 0 /Astrometry: GSC2 Coeff
AMDREX14= 0 /Astrometry: GSC2 Coeff
AMDREX15= 0 /Astrometry: GSC2 Coeff
AMDREX16= 0 /Astrometry: GSC2 Coeff
AMDREX17= 0 /Astrometry: GSC2 Coeff
AMDREX18= 0 /Astrometry: GSC2 Coeff
AMDREX19= 0 /Astrometry: GSC2 Coeff
AMDREX20= 0 /Astrometry: GSC2 Coeff
AMDREY1 = 67.132 /Astrometry: GSC2 Coeff
AMDREY2 = 0.217017 /Astrometry: GSC2 Coeff
AMDREY3 = 412.757 /Astrometry: GSC2 Coeff
AMDREY4 = -1.74418e-06 /Astrometry: GSC2 Coeff
AMDREY5 = -5.24281e-06 /Astrometry: GSC2 Coeff
AMDREY6 = -3.47472e-06 /Astrometry: GSC2 Coeff
AMDREY7 = 0 /Astrometry: GSC2 Coeff
AMDREY8 = 0 /Astrometry: GSC2 Coeff
AMDREY9 = 0 /Astrometry: GSC2 Coeff
AMDREY10= 0 /Astrometry: GSC2 Coeff
AMDREY11= 0 /Astrometry: GSC2 Coeff
AMDREY12= 0 /Astrometry: GSC2 Coeff
AMDREY13= 0 /Astrometry: GSC2 Coeff
AMDREY14= 0 /Astrometry: GSC2 Coeff
AMDREY15= 0 /Astrometry: GSC2 Coeff
AMDREY16= 0 /Astrometry: GSC2 Coeff
AMDREY17= 0 /Astrometry: GSC2 Coeff
AMDREY18= 0 /Astrometry: GSC2 Coeff
AMDREY19= 0 /Astrometry: GSC2 Coeff
AMDREY20= 0 /Astrometry: GSC2 Coeff
ASTRMASK= 'xp.mask ' /Astrometry: GSC2 Mask
WCSAXES = 2 /GetImage: Number WCS axes
WCSNAME = 'DSS ' /GetImage: Local WCS approximation from full plat
RADESYS = 'ICRS ' /GetImage: GSC-II calibration using ICRS system
CTYPE1 = 'RA---TAN' /GetImage: RA-Gnomic projection
CRPIX1 = 446 /GetImage: X reference pixel
CRVAL1 = 148.97 /GetImage: RA of reference pixel
CUNIT1 = 'deg ' /GetImage: degrees
CTYPE2 = 'DEC--TAN' /GetImage: Dec-Gnomic projection
CRPIX2 = 447 /GetImage: Y reference pixel
CRVAL2 = 69.6795 /GetImage: Dec of reference pixel
CUNIT2 = 'deg ' /Getimage: degrees
CD1_1 = -0.000279458 /GetImage: rotation matrix coefficient
CD1_2 = 2.15165e-05 /GetImage: rotation matrix coefficient
CD2_1 = 2.14552e-05 /GetImage: rotation matrix coefficient
CD2_2 = 0.00027889 /GetImage: rotation matrix coefficient
OBJECT = 'data ' /GetImage: Requested Object Name
DATAMIN = 2701 /GetImage: Minimum returned pixel value
DATAMAX = 22189 /GetImage: Maximum returned pixel value
OBJCTRA = '09 55 52.730' /GetImage: Requested Right Ascension (J2000)
OBJCTDEC= '+69 40 45.80' /GetImage: Requested Declination (J2000)
OBJCTX = 5438.47 /GetImage: Requested X on plate (pixels)
OBJCTY = 11269.3 /GetImage: Requested Y on plate (pixels)
END
(0,0) = 4058
(0,1) = 4058
....
Image Header Manipulation (imhead)
To summarize and change keywords and values in the “header” of your image, use the imhead task. Its inputs are:
# imhead :: List, get and put image header parameters
imagename = '' # Name of the input image
mode = 'summary' # imhead options: add, del,
# get, history, list, put, summary
verbose = False # Give a full listing of
# beams or just a short summary?
# Only used when the image has multiple beams
# and mode='summary'.
The mode parameter controls the operation of imhead. Setting mode='summary' will print out a summary of the image properties and the header to the logger. It also returns a dictionary with the image header values. Setting mode='list' prints out a list of the header keywords and values to the terminal. The mode='get' allows the user to retrieve the current value for a specified keyword hdkey:
mode = 'get' # imhead options: list, summary, get, put
hdkey = '' # The FITS keyword
Note that to catch this value, you need to assign it to a Python variable. See CASA Tasks for more on return values. The mode='put' allows the user to replace the current value for a given keyword hditem with that specified in hdvalue. There are two sub-parameters that are opened by this option:
mode = 'put' # imhead options: list, summary, get, put
hdkey = '' # The FITS keyword
hdvalue = '' # Value of hdkey
hdtype = '' # Data type of the header keyword.
hdcomment = '' # Comment associated with the header keyword
Alert: Be careful when using mode='put'. This task does no checking on whether the values you specify (e.g. for the axes types) are valid, and you can render your image invalid. Make sure you know what you are doing when using this option!
Examples for imhead
Here is an example – we can print the summary to the logger:
CASA <51>: imhead('ngc5921.demo.cleanimg.image',mode='summary')
prints in the logger:
##### Begin Task: imhead #####
Image name : ngc5921.demo.cleanimg.image
Object name : N5921_2
Image type : PagedImage
Image quantity : Intensity
Pixel mask(s) : None
Region(s) : None
Image units : Jy/beam
Restoring Beam : 52.3782 arcsec, 45.7319 arcsec, -165.572 deg
Direction reference : J2000
Spectral reference : LSRK
Velocity type : RADIO
Rest frequency : 1.42041e+09 Hz
Pointing center : 15:22:00.000000 +05.04.00.000000
Telescope : VLA
Observer : TEST
Date observation : 1995/04/13/00:00:00
Telescope position: [-1.60119e+06m, -5.04198e+06m, 3.55488e+06m] (ITRF)
Axis Coord Type Name Proj Shape Tile Coord value at pixel Coord incr Units
------------------------------------------------------------------------------------------------
0 0 Direction Right Ascension SIN 256 64 15:22:00.000 128.00 -1.500000e+01 arcsec
1 0 Direction Declination SIN 256 64 +05.04.00.000 128.00 1.500000e+01 arcsec
2 1 Stokes Stokes 1 1 I
3 2 Spectral Frequency 46 8 1.41279e+09 0.00 2.4414062e+04 Hz
Velocity 1607.99 0.00 -5.152860e+00 km/s
##### End Task: imhead
If the beam size per plane differs, the beam information will be displayed for the channel with the smallest beam, the one with the largest beam, and the channel closest to the median beam size. E.g.,
Restoring Beams
Pol Type Chan Freq Vel
I Max 0 9.680e+08 0 39.59 arcsec x 22.77 arcsec pa=-70.57 deg
I Min 511 1.990e+09 -316516 20.36 arcsec x 12.05 arcsec pa=-65.67 deg
I Median 255 1.478e+09 -157949 27.11 arcsec x 15.54 arcsec pa=-70.36 deg
If verbose=T the beam information for every plane will be provided. If you choose mode='list', you get the summary in the logger and a listing of keywords and values to the terminal:
CASA <52>: imhead('ngc5921.demo.cleanimg.image',mode='list')
Out[52]:
{'beammajor': 52.378242492675781,
'beamminor': 45.731891632080078,
'beampa': -165.5721435546875,
'bunit': 'Jy/beam',
'cdelt1': '-7.27220521664e-05',
'cdelt2': '7.27220521664e-05',
'cdelt3': '1.0',
'cdelt4': '24414.0625',
'crpix1': 128.0,
'crpix2': 128.0,
'crpix3': 0.0,
'crpix4': 0.0,
'crval1': '4.02298392585',
'crval2': '0.0884300154344',
'crval3': 'I',
'crval4': '1412787144.08',
'ctype1': 'Right Ascension',
'ctype2': 'Declination',
'ctype3': 'Stokes',
'ctype4': 'Frequency',
'cunit1': 'rad',
'cunit2': 'rad',
'cunit3': '',
'cunit4': 'Hz',
'datamax': ' Not Known ',
'datamin': -0.010392956435680389,
'date-obs': '1995/04/13/00:00:00',
'equinox': 'J2000',
'imtype': 'Intensity',
'masks': ' Not Known ',
'maxpixpos': array([134, 134, 0, 38], dtype=int32),
'maxpos': '15:21:53.976, +05.05.29.998, I, 1.41371e+09Hz',
'minpixpos': array([117, 0, 0, 21], dtype=int32),
'minpos': '15:22:11.035, +04.31.59.966, I, 1.4133e+09Hz',
'object': 'N5921_2',
'observer': 'TEST',
'projection': 'SIN',
'reffreqtype': 'LSRK',
'restfreq': [1420405752.0],
'telescope': 'VLA'}
Note that this list is a return value and can be captured in a variable:
mylist = imhead('ngc5921.demo.cleanimg.image',mode='list')
The values for these keywords can be queried using mode='get'. At this point you should capture the return value:
CASA <53>: mybmaj = imhead('ngc5921.demo.cleanimg.image',mode='get',hdkey='beammajor')
CASA <54>: mybmaj
Out[54]: {'unit': 'arcsec', 'value': 52.378242492699997}
CASA <55>: myobserver = imhead('ngc5921.demo.cleanimg.image',mode='get',hdkey='observer')
CASA <56>: print myobserver
{'value': 'TEST', 'unit': ''}
You can set the values for these keywords using mode='put'. For example:
CASA <57>: imhead('ngc5921.demo.cleanimg.image',mode='put',hdkey='observer',hdvalue='CASA')
Out[57]: 'CASA'
CASA <58>: imhead('ngc5921.demo.cleanimg.image',mode='get',hdkey='observer')
Out[58]: {'unit': '', 'value': 'CASA'}
Image History (imhistory)
Tasks that work on images start to record their execution in the image headers. This information can be retrieved via imhistory. The inputs are:
# imhistory :: Retrieve and modify image history
imagename = '' # Name of the input image
mode = 'list' # Mode to run in, 'list' to retrieve history,
# 'append' to append a record to history.
verbose = True # Write history to logger if mode='list'?
The task returns the massages in the form of a list that can be captured by a variable, e.g.
myhistory=imhistory(’image.im’)
With verbose=T (default) the image history is also reported in the CASA logger. It is also possible to add messages to the image headers via mode='append'.