Functions 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 functions, astDistance, returns a double distance value when supplied with the Frame coordinates of two points. For example:
double dist; double point1[ 2 ] = { 0.0, 0.0 }; double point2[ 2 ] = { 1.0, 1.0 }; ... dist = astDistance( frame, point1, point2 );
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, astDistance 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 astOffset function is really the inverse of astDistance. 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 point1[ 2 ] = { 0.0, 0.0 }; double point2[ 2 ] = { 1.0, 1.0 }; double point3[ 2 ]; ... astOffset( frame, point1. point2, 0.5, point3 );
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 functions astAxDistance and astAxOffset are similar to astDistance and astOffset, except that the curves which they use as ``straight lines'' are not geodesics, but curves parallel to a specified axis15. One reason for using these functions is to deal with the cyclic ambiguity of longitude and latitude axes.
The astOffset2 function is similar to astOffset, 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 astOffset2 function 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 astOffset2 to calculate the position of each corner, and then add (or subtract) 90 degrees from the position angle returned by astOffset2.
The astAngle function
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 astAxAngle function is similar to astAngle, but the ``reference direction'', from which angles are measured, is a specified axis.
The astResolve function 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
supplied point.
AST A Library for Handling World Coordinate Systems in Astronomy