KPG1_GTPLR

Gets a spatial position from the environment as polar co-ordinates

Description:

This routine obtains a two-dimensional spatial position from the environment, using a specified parameter. The user supplies the position in polar co-ordinates about a supplied centre within the co-ordinate system of the Current Frame in the supplied WCS FrameSet. This FrameSet must have two axes, otherwise the routine will exit with an error.

To be acceptable, the supplied position must correspond to a valid position (on both axes) in the Base Frame of the supplied FrameSet. If a Frame is supplied instead of a FrameSet this restriction is not imposed, however polar co-ordinates cannot be supplied, only regular co-ordinates along both axes.

If the polar position supplied in argument CC on entry is valid (i.e. does not contain any AST__BAD values), then it is used as a dynamic default for the parameter. Otherwise, no dynamic default is used.

The parameter is accessed as a single literal string containing a space- or comma-separated list of radius and position-angle values. For SkyFrames the position angle is measured in degrees from North via East; for other Frames, it is anticlockwise from the origin defined by argument PAORIG. The allowed formats for the co-ordinates depends on the class of the Current Frame in the supplied FrameSet, and are described in SUN/210.

If the string supplied for the parameter consists of a single colon, then a description of the Current co-ordinate Frame is displayed, together with an indication of the format required for each axis value, and a new parameter value is then obtained.

Invocation

CALL KPG1_GTPLR( PARAM, IWCS, NULL, POLE, PAORIG, CC, BC, STATUS )

Arguments

PARAM = CHARACTER ∗ ( ∗ ) (Given)
The name of the parameter to use.
IWCS = INTEGER (Given)
A pointer to an AST FrameSet. If a pointer to a Frame is supplied instead the routine will issue a warning that it is unable to handle polar co-ordinates and will expect spatial positions like routine KPG1_GTPOS. This can be aborted (!!) at the parameter prompt.
NULL = LOGICAL (Given)
If TRUE, a null (!) parameter value will result in the dynamic default value being used. If FALSE (or if there is no dynamic default), a null parameter value will result in a PAR__NULL error status.
PAORIG = DOUBLE PRECISION (Given)
This applies when the current Frame is not a SkyFrame. It specifies the origin for the position angle in degrees from the the first WCS axis. The normal convention is for this to be zero (i.e. from X in a Cartesian co-ordinate system) but another may be 90 for starting from up or Y.
POLE( 2 ) = DOUBLE PRECISION (Given)
The position of the pole of the polar co-ordinates measured in the current co-ordinate Frame along each axis. If any of the co-ordinates are bad, the routine will issue a warning that it is unable to handle polar co-ordinates and will expect two spatial positions like routine KPG1_GTPOS. This can be aborted (!!) at the parameter prompt.
CC( 2 ) = DOUBLE PRECISION (Given and Returned)
On entry, holds the position to use as the dynamic default for the parameter, in the Current Frame of the supplied FrameSet (or Frame). On exit, it holds the supplied position in the Current Frame. There should be one element for both axes.
BC( 2 ) = DOUBLE PRECISION (Returned)
Returned holding the Base Frame position corresponding to the supplied Current Frame position. If a Frame is supplied for IWCS instead of a FrameSet, then BC will not be accessed. The returned values will be good on both axes.
STATUS = INTEGER (Given and Returned)
The global status.

Notes: