The process of converting formatted celestial coordinates, such as might be produced by the astFormatastFormat function (§8.6), into numerical (double) coordinate values is performed by using astUnformatastUnformat (§7.8) and passing it a pointer to a SkyFrameSkyFrame. 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 astFormat which contain less than three fields will be correctly interpreted if read back using astUnformat, even if they do not contain field identification characters. However, it also affects other forms of input. For example, if the Format(axis)Format(axis) string were set to “mst.1” (producing two fields representing minutes and seconds of time), then formatted input would be interpreted by astUnformat 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 astUnformat 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.