##
Converting between Celestial Coordinate Systems

We begin by examining how to convert between two celestial coordinate systems represented by SkyFrames, as this is both an illuminating and practical example. Consider the problem of converting celestial coordinates between:

1. The old FK4 system, with no E terms, a Besselian epoch of 1958.0 and a Besselian equinox of 1960.0.

2. An ecliptic coordinate system based on the mean equinox and ecliptic of Julian epoch 2010.5.

This example is arbitrary but not completely unrealistic. Unless you already have expertise with such conversions, you are unlikely to find it straightforward.

Using AST, we begin by creating two SkyFrames to represent these coordinate systems, as follows:

183#183

Note how specifying the coordinate systems consists simply of initialising the attributes of each SkyFrameSkyFrame appropriately. The next step is to find a way of converting between these SkyFrames. This is done using astConvertastConvert, as follows:

184#184

The third argument of astConvert is not used here and should be an empty string.

astConvert will return a null result, AST__NULL (as defined in the “ast.h” header file), if conversion is not possible. In this example, conversion is possible, so it will return a pointer to a new ObjectObject that describes the conversion.

The Object returned is called a FrameSetFrameSet. We have not discussed FrameSets yet (§13), but for the present purposes we can consider them simply as Objects that can behave both as Mappings and as Frames. It is the FrameSet's behaviour as a MappingMapping in which we are mainly interested here, because the Mapping it implements is the one we require—i.e. it converts between the two celestial coordinate systems (§14.1).

For example, if “alpha1” and “delta1” are two arrays containing the longitude and latitude, in radians, of N points on the sky in the original coordinate system (corresponding to “skyframe1”), then they could be converted into the new coordinate system (represented by “skyframe2”) as follows:

185#185

The new coordinates are returned via the “alpha2” and “delta2” arrays. To transform coordinates in the opposite direction, we simply invert the 5th (boolean int) argument to astTran2astTran2, as follows:

186#186

The FrameSet returned by astConvert also contains information about the SkyFrames used in the conversion (§14.1). As we mentioned above, a FrameSet may be used as a FrameFrame and in this case it behaves like the “destination” Frame used in the conversion (i.e. like “skyframe2”). We could therefore use the “cvt” FrameSet to calculate the distance between two points (with coordinates in radians) in the destination coordinate system, using astDistanceastDistance:

187#187

and the result would be the same as if the “skyframe2” SkyFrame had been used.

Another way to see how the FrameSet produced by astConvert retains information about the coordinate systems involved is to set its ReportReport attribute (inherited from the Mapping class) so that it displays the coordinates before and after conversion (§4.8):

188#188

The output from this might look like the following:

189#189

Here, we see that the input FK4 equatorial coordinate values (given in radians) have been formatted automatically in sexagesimal notation using the conventional hours for right ascension and degrees for declination. Conversely, the output ecliptic coordinates are shown in decimal degrees, as is conventional for ecliptic coordinates. Both are displayed using the default precision of 7 digits.

In fact, the “cvt” FrameSet has access to all the information in the original SkyFrames which were passed to astConvert. If you had set a new Digits attribute value for either of these, the formatting above would reflect the different precision you requested by displaying a greater or smaller number of digits.