Craig DeForest,
cdeforest@solar.stanford.edu
V. 1.02; Last Modified: 9-Nov-1998
Because FITS keyword definitions are so random and disparate, and at Sam Freeland's request, I've written including an exhaustive list of the keywords that the ZTOOLS image manipulation routines use. I also include a definition and a listing of where each definition came from. Most of the definitions come from the FITS Standard maintained by the NASA/GSFC Fits Support Office. They are largely compatible with the tags used by the SOHO spacecraft instruments.
There are several other standards documents (all conflicting?) that I use as references. Here are some:
Pointing registration is accomplished in 2-D by defining a Cartesian coordinate system that lays upon the natural pixel coordinate system of the image. This "unitted" coordinate system is defined by a single datum of correspondence between the two systems, a scale for the unitted system, and a rotation angle.
The ztools were developed with single images in mind, and therefore they are not currently well-adapted for multi-dimensional data manipulation.
Pixellized images are assumed to be arranged in horizontal rasters running left to right, which in turn are stacked from bottom to top. X coordinates run left to right and are the fastest-running index; Y coordinates bottom to top and are the slower index.
There is an additional complication: FITS uses a different pixel coordinate system than does IDL. IDL takes (0,0) to be the lower left corner of the image, while FITS takes (1,1) to be the lower left corner.
The ztools follow the FITS standard in maintaining the fits header pointing information -- but routines that return pixel locations return them in IDL pixel coordinates for direct array indexing.
Each pixel is taken to be centered on the appropriate coordinate:
the extreme lower left corner of the lower left pixel is (-0.5,-0.5) in
IDL pixel coordinates; or (0.5,0.5) in FITS pixel coordinates. This is
important, for example, when keeping track of CRPIXn
The "unitted" coordinates in the image are themselves the subject of some ambiguity. The SOHO and Yohkoh communities seem to use "Solar" coordinates a lot; these coordinates have the names "solar-x" and "solar-y", and are angular coordinates defined only for small angles away from Sun center, from the vantage point of the Earth.
Images are usually maps of some scalar quantity against 2-D angle; however, from a particular vantage point and for small angles (such as solar images as seen from Earth), they may be converted to maps versus position. The conversion requires knowledge of the observer's position relative to the Sun (This is accomplished with MDI images by keeping track of the observer's B-angle ('colatitude'), longitude, and radius from the Sun; and by Bill Thompson's PB0R by knowing SOHO's ephemeris). I (CED) recommend keeping images in angular coordinates for as long as possible.
The ztools provide passing support for some coordinate systems that are not semi-cartesian. In particular, heliographic coordinates and image-plane radial coordinates are supported. Currently, there is no way to specify an image's coordinate system explicitly; I have worked around the problem by naming the coordinates themselves. For example, a map of the solar magnetic field in heliographic coordinates would have CTYPE1="degrees-longitude" and CTYPE2="degrees-latitude" instead of merely "degrees". I have made a start at implementing a general coordinate-system naming regimen, with the ztools V4 package of IDL routines; if you have a suggestion for how to incorporate coordinate system naming into FITS images, please let me know.
| Tag | Status | Source | Definition | ||||||||||||||||||||||||||||
NAXIS1, NAXIS2
| FITS std | The width and height of the image, respectively, in pixels. | |||||||||||||||||||||||||||||
CRPIX1, CRPIX2
| FITS std | The X and Y coordinates, respectively, of the alignment datum in
pixel coordinates.
For example, if alignment is with respect to the lower
left corner of the image,
For example, if the pixel coordinates in
(
If the The ztools
recognize most SI units of distance and angle; these are listed in
ZUNITS.PRO in the ztools package. For example, if your telescope has a
platescale of 2.6 arcsec per pixel, set (See the discussion, above, on units and coordinate systems.)
The rotation is specified in degrees CCW about the datum.
(ie the unitted 'X' coordinate is taken to be
If this field is not specified, it is assumed to be zero.
|
It's important to specify the time at which an observation occured. Unfortunately, the standard ways to do this are complex and have been rendered more complex by some of the historical accidents of FITS interpretation with IDL in the solar community. In addition, the time given in the header is not well defined by either the FITS standard or the SOHO documentation.
In particular, the FITS standard defines the keyword
DATE-OBS to specify the date on which an observation
took place; but nothing more precise. Some teams (eg MDI/SOI
data specification) use TIME-OBS to specify when
an observation took place. The SOHO standard (Howard
& Thompson) uses DATE_OBS to store all the time
and date information.
There's an additional complication: Because of limitations of the
IDL language, there has been an ambiguity between dashes and underscores
in the structure returned by mreadfits.pro. So many
FITS files exist which have DATE_OBS and DATE-OBS
confused. (Newer versions of mreadfits.pro do not generate
the same ambiguity.) So timestamp interpretation is not simple.
There is a problem with the definition of the timestamp tags --
neither the FITS standard nor the SOHO definitions specify the exact
time to be given in the DATE_OBS or
TIME-OBS tags; the observation is treated as
instantaneous. This treatment is not entirely valid in solar physics,
as we keep finding temporal variations in the Sun, on the shortest
measureable time scales. The ztools do not directly address this
issue -- but, as time resolution becomes better and interinstrument
comparison of data becomes more common, it will have to be dealt with.
The de facto standard for The ztools use
Here is a brief list of all the suggested and/or required tags
that ZTOOLS uses. Tags in bold are required; tags in
italics are suggested but not used; tags in plaintext are
suggested but have default values in case they are not present.
DATE_OBS
appears to be to use the start time of the observation. (Some
instruments, eg MDI, use the middle of the observation, as that
represents a better "mean time" for the observation as a whole;
caveat emptor!) For timing critical investigations, where the mean time of
the observation is needed, people can use DATE_OBSEXPTIME/2 as the time of the observations.
DATE_OBS for the time of an observation.
If DATE_OBS is not found, then many routines try to
use DATE-OBS and TIME-OBS.
Tag
Status
Source
Definition
DATE_OBS
WT
The time and date of the start of the observation, in
Earth-adjusted UT in a timestamp format recognized by the SSW
ANYTIM routine. (WT specifies CDS timestamp format).
This is currently the preferred way of specifying date and time.
DATE-OBS
FITS std
The date on which the observation was made, UT. The ZTOOLS do not
directly use this tag, but its inclusion in headers is suggested for
FITS conformability. (To access this tag in an IDL structure, remember
to use DATE_d$OBS.)
TIME-OBS
Common usage
The time at which the start of the observation occurred, UT. This
tag is not explicitly defined in the FITS standard, but has been adopted
into common usage. The ZTOOLS do not directly use this tag, but its inclusion
in headers is suggested for conformability with the rest of the FITS world.
(To access this tag in an IDL structure, remember to use
TIME_d$OBS.)
EXPTIME
FITS Std
The duration of the observation, in seconds. This is not used directly --
but is necessary to calculate the "mean time" of an observation with the
agreed standard for DATE_OBS.
Brief List of Tags
CRPIXn
CRVALn
CDELTn
CTYPEn
CROTA
DATE_OBS
DATE-OBS
EXPTIME
NAXISn
TIME-OBS