image.summary - Function

Summarize basic information about the image

Synopsis
summary(header, doppler, list, pixelorder)

Returns
T or fail

Arguments

header	out	Header information
		Default:	empty
doppler	in	If there is a spectral axis, list velocity too, with this doppler definition
		Allowed:	String
		Default:	RADIO
list	in	List the summary to the logger
		Allowed:	T or F
		Default:	T
pixelorder	in	List axis descriptors in pixel or world axis order
		Allowed:	T or F
		Default:	T

Description

This function summarizes miscellaneous information such as shape, Coordinate System, restoring beams, and masks.

If called without any arguments, this function displays a summary of the image header to the logger only; where appropriate, values will be formatted nicely (e.g. HH:MM:SS.SS for the reference value of RA axes).

For spectral axes, the information is listed as a velocity as well as a frequency. The argument doppler allows you to specify what velocity doppler convention it is listed in. You can choose from radio, optical and true. Alternative names are z for optical, and beta or relativistic for true. The default is radio. The definitions are

radio: 1 - F
optical: -1 + 1/F
true: (1 - F²)/(1 + F²)

where F = $\nu$ / $\nu_{0}^{}$ and $\nu_{0}^{}$ is the rest frequency. If the rest frequency has not been set in your image, you can set it via a Coordsys tool with the function setrestfrequency.

If the header argument is supplied, that argument will be a Glish record with the following fields filled in:

ndim: Dimension of the image.
shape: Length of each axis in the image.
tileshape: Shape of the chunk which is most efficient for I/O.
axisnames: Name of each axis.
refpix: Reference pixel for each axis (1 relative)
refval: Reference value for each axis.
incr: Increment for each axis.
axisunits: Unit name for each axis.
unit: Brightness units for the pixels.
hasmask: True if the image has a mask.
defaultmask: The name of the mask which is applied by default.
masks: The names of all the masks stored in this image.
restoringbeam: The restoring beam if present.
imagetype: The image type.

If you set list=F, then the summary will not be written to the logger. However, in addition to the output record, the return value of the function will be a vector strings containing the formatted output that would normally have gone to the logger. If list=T the return value is always T or a fail.

Example

- im := image('myim1')
- im.summary()                 # summarize to logging only

Image name       : test
Image mask       : mask0 [mask1, mask2]
Image units      : JY/BEAM

Direction reference : J2000
Spectral  reference : LSRK
Velocity  type      : RADIO
Rest frequency      : 1.42041e+09 Hz

Telescope        : ATCA
Observer         : NEBK
Date observation : 1997/02/121/03:03:26

Axis Type      Name             Proj Shape Tile   Coord value at pixel    Coord incr Units
------------------------------------------------------------------------------------------ 
1    Direction Right Ascension   SIN  512   10  00:00:00.000     6.00 -6.000000e+01 arcsec
2    Direction Declination       SIN  512   20 +00.00.00.000    11.00  6.000000e+01 arcsec
3    Spectral  Frequency             1024   30  1.415000e+09    16.00  1.000000e+03 Hz
               Velocity                         1.140944e+03    16.00 -2.110611e-01 km/s

- im.summary(header,list=F)      # store header in Glish record
- if (header.ndim == 3) ...      # program using header values

Note that the Spectral Coordinate is listed twice; once with frequency and once with velocity units. You can distinguish this double listing because the shape of the axis is only listed once (in this case on the Frequency line).

Note also that this image has three masks present. The first one is the default which means that it is applied by applications. Any of the other masks, listed in square brackets, could be made the default mask by application of the maskhandler function. If there was no default mask (effectively that means an all good mask would be applied), all the mask names would be listed in square brackets.

Next: image.tofits - Function Up: image - Tool Previous: image.subimage - Function Contents Index

	Package	general
	Module	images
	Tool	image