The process of converting formatted celestial coordinates, such as
might be produced by the AST_FORMAT function
(), into numerical (double
precision) coordinate values is performed by using AST_UNFORMAT
(
) and passing it a pointer to a
SkyFrame. The use of a SkyFrame means that the range of input formats
accepted is appropriate to positions on the sky expressed as angles
and/or times, while the returned value is in radians.
The following describes the forms of celestial coordinate which are supported:
d - degrees h - hours m - minutes (of arc or time) s - seconds (of arc or time) ' - arc-minutes " - arc-seconds
Either lower or upper case may be used. Fields must be given in order
of decreasing significance
(e.g. ``11D 3' 14.4"'' or ``22h14m11.2s'').
d - angle ' - angle " - angle h - time
Incompatible angle/time identification characters may not be mixed (e.g. ``10h14'3"'' is not valid). The remaining field identification characters and separators do not specify a preference for an angle or a time and may be used with either.
10d - degrees 10d12 - degrees and arc-minutes 11:14" - arc-minutes and arc-seconds 9h13s - hours and seconds of time :45:33 - minutes and seconds (of arc or time) :55: - minutes (of arc or time) ::13 - seconds (of arc or time) 6::2.5
- degrees/hours and seconds (of arc or time) 07m14 - minutes and seconds (of arc or time) 8:14'
- degrees and arc-minutes h3:14
- minutes and seconds of time h:2.1 - seconds of time
This final convention is intended to ensure that values formatted by AST_FORMAT which contain less than three fields will be correctly interpreted if read back using AST_UNFORMAT, even if they do not contain field identification characters. However, it also affects other forms of input. For example, if the Format(axis) string were set to ``mst.1'' (producing two fields representing minutes and seconds of time), then formatted input would be interpreted by AST_UNFORMAT as follows:
12 13 - minutes and seconds 12 - minutes :13 - seconds 18:
- minutes 12.8 - minutes 1 2 3 - hours, minutes and seconds 4' - arc-minutes 60::" - degrees 23:"
- arc-minutes 33h
- hours
(in the last four cases, explicit field identification has been given which overrides the implicit identification).
Alternatively, if the Format(axis) string were set to ``s.3'' (producing only an arc-seconds field), then formatted input would be interpreted by AST_UNFORMAT as follows:
12.8 - arc-seconds 12 13 - arc-minutes and arc-seconds :12 - arc-seconds 13: - arc-minutes 1 2 3 - degrees, arc-minutes and arc-seconds
In general, if you are preparing formatted input data containing celestial coordinates and wish to omit certain fields, then you are advised to identify clearly those that you do provide by using the appropriate field identification characters and/or extra colon separators. This prevents you depending on the implicit field identification described above which, in turn, depends on an appropriate Format(axis) string having been set.
When writing software, it is also a good idea to set the Format(axis)
string so that data input will be as simple as possible for the
user. Unless some special effect is desired, this normally means that
it should contain ``d'' or ``h'' to ensure that the first field
entered by the user will be interpreted as degrees or hours, unless
otherwise identified. This is the normal behaviour unless an explicit
Format(axis) value has been set to override the default.
AST A Library for Handling World Coordinate Systems in Astronomy