Routines can be used to find the distance between two points, and to offset a specified distance along a line joining two points, etc. In essence, these define the metric of the coordinate space which the Frame represents. In the case of a basic Frame, this is a Cartesian metric.
The first of these routines, AST_DISTANCE, returns a double precision distance value when supplied with the Frame coordinates of two points. For example:
DOUBLE PRECISION DIST, POINT1( 2 ), POINT2( 2 ) DATA POINT1 / 0D0, 0D0 / DATA POINT2 / 1D0, 1D0 / ... DIST = AST_DISTANCE( FRAME, POINT1, POINT2, STATUS )
This calculates the distance between the origin (0,0) and a point at position (1,1). In this case, the result, as you would expect, is . However, this is only true for the Cartesian coordinate system which a basic Frame represents. In general, AST_DISTANCE will calculate the geodesic distance between the two points, so that with a more specialised Frame (such as a SkyFrame, representing the celestial sphere) a great-circle distance might be returned.
The AST_OFFSET routine is really the inverse of AST_DISTANCE. Given two points in a Frame, it calculates the coordinates of a third point which is offset a specified distance away from the first point along the geodesic joining it to the second one. For example:
DOUBLE PRECISION POINT1( 2 ), POINT2( 2 ), POINT3( 2 ) DATA POINT1 / 0D0, 0D0 / DATA POINT2 / 1D0, 1D0 / ... CALL AST_OFFSET( FRAME, POINT1, POINT2, 0.5D0, POINT3, STATUS )
This would fill the POINT3 array with the coordinates of a point which is offset 0.5 units away from the origin (0,0) in the direction of the position (1,1). Again, this is a simple result in a Cartesian Frame, as varying the offset will trace out a straight line. On the celestial sphere, however (e.g. using a SkyFrame), it would trace out a great circle.
The routines AST_AXDISTANCE and AST_AXOFFSET are similar to AST_DISTANCE and AST_OFFSET, except that the curves which they use as ``straight lines'' are not geodesics, but curves parallel to a specified axis14. One reason for using these routines is to deal with the cyclic ambiguity of longitude and latitude axes.
The AST_OFFSET2 routine is similar to AST_OFFSET, but instead of using the geodesic which passes through two positions, it uses the geodesic which passes at a given position angle through the starting position.
Position angles are always measured from the positive direction of the second Frame axis to the required line, with positive angles being in the same sense as rotation from the positive direction of the second axis to the positive direction of the first Frame axis. This definition applies to all classes of Frame, including SkyFrame. The default ordering of axes in a SkyFrame makes the second axis equivalent to north, and so the definition of position angle given above corresponds to the normal astronomical usage, ``from north, through east''. However, it should be remembered that it is possible to permute the axes of a SkyFrame (or indeed any Frame), so that north becomes axis 1. In this case, an AST ``position angle'' would be the angle ``from east, through north''. Always take the axis ordering into account when deriving an astronomical position angle from an AST position angle.
Within a Cartesian coordinate system, the position angle of a geodesic (i.e. a straight line) is constant along its entire length, but this is not necessarily true of other coordinate systems. Within a spherical coordinate system, for instance, the position angle of a geodesic will vary along its length (except for the special cases of a meridian and the equator). In addition to returning the required offset position, the AST_OFFSET2 routine returns the position angle of the geodesic at the offset position. This is useful if you want to trace out a path which involves turning through specified angles. For instance, tracing out a rectangle in which each side is a geodesic involves turning through 90 degrees at the corners. To do this, use AST_OFFSET2 to calculate the position of each corner, and then add (or subtract) 90 degrees from the position angle returned by AST_OFFSET2.
The AST_ANGLE routine calculates the angle subtended by two points, at a third point. If used with a 2-dimensional Frame the returned angle is signed to indicate the sense of rotation (clockwise or anti-clockwise) in taking the ``shortest route'' from the first point to the second. If the Frame has more than 2 axes, the result is un-signed and is always in the range zero to .
The AST_AXANGLE routine is similar to AST_AXANGLE, but the ``reference direction'', from which angles are measured, is a specified axis.
The AST_RESOLVE routine resolves a given displacement within a Frame into two components, parallel and perpendicular to a given reference direction.
The displacement is specified by two positions within the Frame; the
starting and ending positions. The reference direction is defined by the
geodesic curve passing through the starting position and a third specified
position. The lengths of the two components are returned, together with
the position on the reference geodesic which is closest to the third
AST A Library for Handling World Coordinate Systems in Astronomy