|
|||
NRAO Home > CASA > CASA Task Reference Manual |
|
0.1.40 imhead
Requires:
Synopsis
List, get and put image header parameters
Arguments
Inputs |
| ||
imagename |
| Name of the input image
| |
| allowed: | string |
|
| Default: |
| |
mode |
| Mode of operation: ”add”, ”del”, ”get”, ”history”, ”list”,
”put”, or ”summary”. Modes ”add”, ”del”, and ”put”
will not work if the image is read-only (eg a FITS image).
| |
| allowed: | string |
|
| Default: | summary |
|
hdkey |
| The associated keyword for modes ”add”, ”del”, ”get”,
or ”put”. Only ”get” will work if the image is read-only
(eg, a FITS image).
| |
| allowed: | string |
|
| Default: |
|
|
hdvalue |
| Value of keyword for modes add or put.
| |
| allowed: | any |
|
| Default: | variant
|
|
verbose |
| Give a full listing of beams or just a short summary?
Only used when the image has multiple beams and
mode=”summary”.
| |
| allowed: | bool |
|
| Default: | False |
|
variant
Example
PARAMETER SUMMARY
imagename Input image name. example: imagename=’ngc5921_task.image’
mode Mode of operation. Supoorted values: ’list’, ’summary’, ’history’,
’get’, ’put’, ’add’, ’del’.
NOTE: ’add’, ’del’, and ’put’ should be used with caution, and will not work if the image is
read-only (eg FITS images are read-only in CASA).
hdkey Keyword to use with get, put, add, or del. example: hdkey=’telescope’
hdvalue keyword value used for modes "put" and "add". Also used for mode="del" when
hdvalue="masks. example: hdvalue=’VLA’
This task allows the user to manipulate metadata associated with a CASA
image. Both float and complex valued images are fully supported. The supported mode values are:
add Add a new metadata value to the image.
del Delete a key or reset its value to a fidicual value if possible.
Ignores all but imagename, mode, and hdkey parameters.
get Return the specified keyword value. Ignores all but imagename, mode, and hdkey parameters.
history Log image history. Ignores all but imagename and mode parameters.
list Show supported keywords and their values. Ignores all but imagename and mode parameters.
put Modify the specified value associated with the keyword.
summary Log a summary of the image and return a dictionary of various metadata values.
Ignores all but imagename and mode parameters.
See below for details about how these modes act for specific keywords.
NOTE: Only limited checking is implemented to ensure modifying a specific value
will leave the image metadata in a consistent state, so, if one is not careful, one could
end up with an image that has an inconsistent set of metadata and is therefore,
nonsensical and useless That is, PROCEED AT YOUR OWN RISK when using modes add, del, or put.
NOTE: For measurement sets, the task vishead should be used.
Supported keywords can be listed using mode = ’list’
beammajor/bmaj Major axis of the clean beam
beamminor/bmin Minor axis of the clean beam
beampa/bpa Position angle of the clean beam
NOTE: If the image contains multiple beams, use mode="summary" to list them
with verbose=True.
bunit Image units (K, Jy/beam, etc)
cdeltn Pixel size, nth axis. n is one-based.
crpixn The pixel designated as the reference location, nth axis n is one-based.
crvaln World coordinate value of the reference pixel for the nth axis. n is one-based.
ctypen Name of nth axis. n is one-based.
cunitn Units of nth axis. n is one based.
datamax Maximum pixel value.
datamin Minimum pixel value.
date-obs Date (epoch) of the observation.
equinox Direction reference frame.
imtype Image type (eg Intensity)
minpos World coordinate position of minimum pixel value.
minpixpos Pixel coordinate position of minimum pixel value.
maxpos World coordinate position of maximum pixel value.
maxpixpos Pixel coordinate position of maximum pixel value.
object Source name
observer Observer name
projection Direction coordinate projection (eg ’SIN’,’TAN’, or ’ZEA’).
reffreqtype Spectral reference frame.
restfreq Rest Frequency.
shape Number of pixels along each axis.
telescope Telescope name.
NOTES on mode="add"
The behavior of mode="add" depends on the keyword. Below is a summary of the per keyword
behavior of this mode. In general, the return value will be True if the operation succeeds,
or False if it fails or is not supported. If unsuccessful or not supported, a message
is normally logged which describes the failure. In most cases, you probably want to use
mode=’put’ rather than mode=’add’. We continue to support mode=’add’ mainly for backward
compatibility.
Keyword Behavior for mode="del"
beammajor or bmaj If image has no beam(s), a single, global, circular beam of diameter
specified in hdvalue is added. hdvalue must be a valid angular quantity (string
or dictionary) or the operation will fail and False will be returned.
If the image has a beam(s), the operation fails and False is returned.
Examples of acceptable values of hdvalue are "4arcsec", qa.quantity("4arcsec"),
{’unit’: ’arcsec’, ’value’: 4.0}.
If you wish an image to have multiple beams, use ia.setrestoringbeam().
beamminor or bmin Behavior is the same as that for beammajor or bmaj.
beampa or bpa Operation has no effect and always returns false. If you wish to add a beam, use
beammajor, bmaj, beamminor, or bmin.
bunit If image has no brightness unit, add the value specified in hdvalue which must
be a unit supported by CASA. Else do nothing and return False.
cdelt* No effect. Addition of coordinate system parameters is not supported. Always returns
False. Use the cs tool to add coordinates.
crpix* No effect. Addition of coordinate system parameters is not supported. Always returns
False. Use the cs tool to add coordinates.
crval* No effect. Addition of coordinate system parameters is not supported. Always returns
False. Use the cs tool to add coordinates.
ctype* No effect. Addition of coordinate system parameters is not supported. Always returns
False. Use the cs tool to add coordinates.
cunit* No effect. Addition of coordinate system parameters is not supported. Always returns
False. Use the cs tool to add coordinates.
datamax No effect. Addition of statistical parameters is not supported.
datamin No effect. Addition of statistical parameters is not supported.
date-obs or epoch No effect.
equinox No effect.
imtype If image type does not exist, add the type specified in hdvalue. hdvalue must be one of
"Undefined", "Intensity", "Beam", "Column Density", "Depolarization Ratio",
"Kinetic Temperature", "Magnetic Field", "Optical Depth", "Rotation Measure",
"Rotational Temperature", "Spectral Index","Velocity", or "Velocity Dispersion".
masks No effect. Addition of masks is not supported. Use ia.calcmask().
maxpos No effect. Addition of statistical parameters is not supported.
maxpixpos No effect. Addition of statistical parameters is not supported.
minpos No effect. Addition of statistical parameters is not supported.
minpixpos No effect. Addition of statistical parameters is not supported.
object If image has no object, add the value specified in hdvalue. Else do nothing and return False.
observer If image has no observer, add the value specified in hdvalue. Else do nothing and return False.
projection No effect.
reffreqtype No effect.
restfreq If image has a spectral coordinate and no rest frequency, set the rest frequency
to the value specified in hdvalue. This value must be a valid CASA quantity with frequency
units. Else do nothing and return False. Examples of valid values are "1GHz", qa.quantity("1GHz"),
{’unit’: ’GHz’, ’value’: 1.0}
shape No effect.
telescope If image has no telescope, add the value specified in hdvalue. Else do nothing and return False.
any user defined key Add the key-value pair if the key does not exist. Else do nothing and return False.
NOTES on mode="del"
The behavior of mode="del" depends on the keyword. Below is a summary of the per keyword
behavior of this mode. In general, the return value will be True if the operation succeeds,
or False if it fails or is not supported. If unsuccessful or not supported, a warning message
is normally logged which describes the failure.
Keyword Behavior for mode="del"
beammajor or bmaj Deletes all beams. Returns False if the image has no beams.
beamminor or bmin Deletes all beams. Returns False if the image has no beams.
beampa or bpa Deletes all beams. Returns False if the image has no beams.
bunit Sets the associated value to the empty string.
cdelt* No effect. Deletion of coordinate system parameters is not supported.
crpix* No effect. Deletion of coordinate system parameters is not supported.
crval* No effect. Deletion of coordinate system parameters is not supported.
ctype* No effect. Deletion of coordinate system parameters is not supported.
cunit* No effect. Deletion of coordinate system parameters is not supported.
datamax No effect. Deletion of statistical parameters is not supported.
datamin No effect. Deletion of statistical parameters is not supported.
date-obs or epoch No effect.
equinox No effect.
imtype No effect.
masks Deletes the single mask specified in hdvalue, or if hdvalue="", deletes all masks.
maxpos No effect. Deletion of statistical parameters is not supported.
maxpixpos No effect. Deletion of statistical parameters is not supported.
minpos No effect. Deletion of statistical parameters is not supported.
minpixpos No effect. Deletion of statistical parameters is not supported.
object Sets the associated value to the empty string.
observer Sets the associated value to the empty string.
projection No effect.
reffreqtype No effect.
restfreq No effect.
shape No effect.
telescope Sets the associated value to the empty string.
any user defined key Deletes the key-value pair.
NOTES ON mode=’get’
The data type of the value returned by imhead when mode=’get’ depends on the keyword. Below
is a list of keywords on the data type that will be returned when mode=’get’ for each. A
"quantity dictionary" is a dictionary with ’value’ and ’unit’ keys that can be used as
input to various methods of the qa tool.
keyword data type returned when mode=’get’
beammajor quantity dictionary
beamminor quantity dictionary
beampa quantity dictionary
bmaj quantity dictionary
bmin quantity dictionary
bpa quantity dictionary
bunit string
cdelt* quantity dictionary
crpix* float
crval* quantity dictionary, unless the value
for the stokes axis is requested in which case
an array of strings is returned
ctype* string
cunit* string
datamax image pixel data type
datamin image pixel data type
date-obs or epoch string (YYYY/MM/DD/hh:mm:ss format)
equinox string
imtype string
masks string array
maxpos string
maxpixpos integer array
minpos string
minpixpos integer array
object string
observer string
projection string
reffreqtype string
restfreq quantity dictionary
shape integer array
telescope string
any user defined key string
NOTES on mode=’put’
In general, mode=’put’ will modify the specified key to the specified value, with
the following examples. True is returned if the metadatum was successfully modified,
False otherwise. Normally, a diagnostic message is logged if there is a failure. Only the
parameter specified is modified; eg, no modification of reference direction occurs to implicitly
account for precession to a new reference frame. The following are the exceptional cases for mode=’put’.
beammajor or bmaj Will always fail if image has multiple beams. Use ia.setrestoringbeam()
in this case. If image has no beam(s), a single, global, circular beam of diameter
specified in hdvalue is added. hdvalue must be a valid angular quantity (string
or dictionary) or the operation will fail and False will be returned.
If the image has a single beam, the value of the major axis will be modified,
unless the specified value is smaller than the minor axis of the existing beam,
in which case nothing is modified and False is returned.
Examples of acceptable values of hdvalue are "4arcsec", qa.quantity("4arcsec"),
{’unit’: ’arcsec’, ’value’: 4.0}.
beamminor or bmin Behavior is the same for bmaj, although of course if the image already has
a single beam, the specified value must be less than the existing major
axis value, or nothing is modified and False is returned.
beampa or bpa If the image does not already have a single beam, nothing is modified and
False is returned. Angular units are required.
bunit Fails if hdvalue is not a supported CASA unit.
cdelt* One-based axis must be less than or equal to the number of axes in the image.
hdvalue type must be a number (in which case the unit of the corresponding axis
is assumed) or a quantity (string or dictionary). If a quantity, the unit must
conform to the existing axis unit.
crpix* One-based axis must be less than or equal to the number of axes in the image.
hdvalue type must be a number. Will fail if the polarization axis.
crval* One-based axis must be less than or equal to the number of axes in the image.
If not the polarization/stokes axis, hdvalue type must be a number (in which
case the unit of the corresponding axis is assumed), a quantity (string or
dictionary), or a valid measure format (such as a sexigesimal direction axis
specification for an axis with angular units). If a quantity, the unit must
conform to the existing axis unit. If the stokes/polarization axis, one must
provide an array of stokes/polarization strings (["I", "Q", "XX"]) that is the
same length as the stokes axis. If the stokes axis is degenerate, one can
alternatively provide a string indicating the stokes value (eg "U").
ctype* One-based axis must be less than or equal to the number of axes in the image.
hdvalue type must be a string.
cunit* One-based axis must be less than or equal to the number of axes in the image. Specified
unit must conform to the existing axis unit. Will fail if stokes/polarization axis.
datamax This cannot be modified. False is always returned.
datamin This cannot be modified. False is always returned.
date-obs or epoch A valid time specification must be given.
equinox A valid direction reference frame specification string must be given.
imtype A CASA-supported image type string must be given or the image type will
be set to ’Intensity’
masks Masks may not be modified. False is always returned.
maxpos This cannot be modified.
maxpixpos This cannot be modified.
minpos This cannot be modified.
minpixpos This cannot be modified.
object hdvalue must be a string.
observer hdvalue must be a string.
projection hdvalue must be a string representing a supported CASA projection specification.
reffreqtype hdvalue must be a string representing a supported CASA velocity reference frame
specification.
restfreq hdvalue can be a number (in which case frequency axis units are assumed) or a valid
quantity string or quantity dictionary in which case the unit must conform to Hz.
Only the active rest frequency may be modified. For more functionality, see
cs.setrestfrequency().
shape This cannot be modified.
telescope hdvalue must be a string.
any user defined key hdvalue can be practically any supported input parameter type.
EXAMPLES
# mode=’get’. Image has direction and spectral coordinates
epoch = imhead(imagename=imagename, mode="get", hdkey="date-obs")
observer = imhead(imagename=imagename, mode="get", hdkey="observer")
projection = imhead(imagename=imagename, mode="get", hdkey="projection")
restfreq = imhead(imagename=imagename, mode="get", hdkey="restfreq")
# mode=’add’
if imhead(imagename=imagename, mode="add", hdkey="mykey", hdvalue="myvalue"):
print "mykey added".
else:
print "addition of mykey failed".
# mode="del"
if imhead(imagename=imagename, mode="del", hdkey="mykey"):
print "mykey deleted".
else:
print "deletion of mykey failed".
# mode="put"
# change the reference RA value
key = ’crval1’
imhead(imagename=imagename, mode="put", hdkey=key, hdvalue="3:00:00")
# or equivalently
imhead(imagename=imagename, mode="put", hdkey=key, hdvalue="45deg")
# change the direction reference frame (NOTE, no precession of the existing
# reference values is done!)
imhead(imagename=imagename, mode="put", hdkey="equinox", hdvalue="GALACTIC")
# change the object
imhead(imagename=imagename, mode="put", hdkey="object", hdvalue="Milliways, also known as The Restaraunt at the End of the Universe")
More information about CASA may be found at the
CASA web page
Copyright © 2016 Associated Universities Inc., Washington, D.C.
This code is available under the terms of the GNU General Public Lincense
Home |
Contact Us |
Directories |
Site Map |
Help |
Privacy Policy |
Search