AST_OFFSET2

Calculate an offset along a geodesic curve in a 2D Frame

Description:

This routine finds the Frame coordinate values of a point which is offset a specified distance along the geodesic curve at a given angle from a specified starting point. It can only be used with 2-dimensional Frames.

For example, in a basic Frame, this offset will be along the straight line joining two points. For a more specialised Frame describing a sky coordinate system, however, it would be along the great circle passing through two sky positions.

Invocation

RESULT = AST_OFFSET2( THIS, POINT1, ANGLE, OFFSET, POINT2, STATUS )

Arguments

THIS = INTEGER (Given)
Pointer to the Frame.
POINT1( $\ast$ ) = DOUBLE PRECISION (Given)
An array with one element for each Frame axis (Naxes attribute). This should contain the coordinates of the point marking the start of the geodesic curve.
ANGLE = DOUBLE PRECISION (Given)
The angle (in radians) from the positive direction of the second axis, to the direction of the required position, as seen from the starting position. Positive rotation is in the sense of rotation from the positive direction of axis 2 to the positive direction of axis 1.
OFFSET = DOUBLE PRECISION
The required offset from the first point along the geodesic curve. If this is positive, it will be in the direction of the given angle. If it is negative, it will be in the opposite direction.
POINT2( $\ast$ ) = DOUBLE PRECISION (Returned)
An array with one element for each Frame axis in which the coordinates of the required point will be returned.
STATUS = INTEGER (Given and Returned)
The global status.

Returned Value

AST_OFFSET2 = DOUBLE PRECISION
The direction of the geodesic curve at the end point. That is, the angle (in radians) between the positive direction of the second axis and the continuation of the geodesic curve at the requested end point. Positive rotation is in the sense of rotation from the positive direction of axis 2 to the positive direction of axis 1.

Notes:

• The geodesic curve used by this routine is the path of shortest distance between two points, as defined by the AST_DISTANCE function.

• An error will be reported if the Frame is not 2-dimensional.

• This function will return " bad" coordinate values (AST__BAD) if any of the input coordinates has this value.