##
Calculating Distances, Angles and Offsets

Some complementary functions are provided for use with Frames to allow you to perform geometric operations without needing to know the nature of the coordinate system represented by the FrameFrame.

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, astDistanceastDistance, returns a double distance value when supplied with the Frame coordinates of two points. For example:

121#121

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 122#122. 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 SkyFrameSkyFrame, representing the celestial sphere) a great-circle distance might be returned.

The astOffsetastOffset 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:

123#123

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 astAxDistanceastAxDistance and astAxOffsetastAxOffset 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 axis. One reason for using these functions is to deal with the cyclic ambiguity of longitude and latitude axes.

The astOffset2astOffset2 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 astAngleastAngle 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 124#124.

The astAxAngleastAxAngle function is similar to astAngle, but the “reference direction”, from which angles are measured, is a specified axis.

The astResolveastResolve 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.