PICTRANS - Transforms a graphics position from one picture co-ordinate Frame to another

Description:

This application transforms a position on a graphics device from one co-ordinate Frame  to another. The input and output Frames may be chosen freely from the Frames available in the WCS  information stored with the current picture in the AGI graphics database. The transformed position is formatted for display and written to the screen and also to an output parameter.

Usage:

pictrans posin framein [frameout] [device]

Parameters:

DEVICE = DEVICE (Read)

The graphics workstation. [The current graphics device]

EPOCHIN = _DOUBLE (Read)

If a `Sky Co-ordinate System' specification is supplied (using Parameter FRAMEIN) for a celestial co-ordinate system, then an epoch value is needed to qualify it. This is the epoch at which the supplied sky position was determined. It should be given as a decimal years value, with or without decimal places ("1996.8" for example). Such values are interpreted as a Besselian epoch if less than 1984.0 and as a Julian epoch otherwise.

EPOCHOUT = _DOUBLE (Read)

If a `Sky Co-ordinate System' specification is supplied (using Parameter FRAMEOUT) for a celestial co-ordinate system, then an epoch value is needed to qualify it. This is the epoch at which the transformed sky position is required. It should be given as a decimal years value, with or without decimal places ("1996.8" for example). Such values are interpreted as a Besselian epoch if less than 1984.0 and as a Julian epoch otherwise.

FRAMEIN = LITERAL (Read)

A string specifying the co-ordinate Frame in which the input position is supplied (see Parameter POSIN). The string can be one of the following options.

• A domain name  such as SKY, AXIS, PIXEL, NDC, BASEPIC, CURPIC.

• An integer value giving the index of the required Frame within the WCS component.

• An IRAS90 Sky Co-ordinate System (SCS) values such as "EQUAT(J2000)" (see SUN/163).

If a null parameter value is supplied, then the current Frame  in the current picture is used. [!]

FRAMEOUT = LITERAL (Read)

A string specifying the co-ordinate Frame in which the transformed position is required. If a null parameter value is supplied, then the current Frame in the picture is used. The string can be one of the following options.

• A domain name such as SKY, AXIS, PIXEL, GRAPHICS, CURPIC, NDC, BASEPIC.

• An integer value giving the index of the required Frame within the WCS component.

• An IRAS90 Sky Co-ordinate System (SCS) values such as "EQUAT(J2000)" (see SUN/163).

If a null parameter value is supplied, then the BASEPIC Frame is used. ["BASEPIC"]

POSIN = LITERAL (Read)

The co-ordinates of the position to be transformed, in the co-ordinate Frame specified by Parameter FRAMEIN (supplying a colon ":" will display details of the required co-ordinate Frame). The position should be supplied as a list of formatted axis values separated by spaces or commas.

Results Parameters:

BOUND = _LOGICAL (Write)

BOUND is TRUE when the supplied point lies within the bounds of the current picture.

POSOUT = LITERAL (Write)

The formatted co-ordinates of the transformed position, in the co-ordinate Frame specified by Parameter FRAMEOUT. The position will be stored as a list of formatted axis values separated by spaces.

Examples:

pictrans "100.3,-20.1" framein=pixel

This converts the position (100.3, $-$ 20.1), in pixel co-ordinates within the current picture of the current graphics device, to the BASEPIC co-ordinates of that point in the BASE picture.

pictrans "100.3,-20.1" framein=pixel frameout=graphics

This converts the position (100.3, $-$ 20.1), in pixel co-ordinates within the current picture of the current graphics device, to the GRAPHICS co-ordinates of that point (i.e. millimetres from the bottom-left corner of the graphics device).

pictrans "10 10" framein=graphics frameout=basepic

This converts the position (10, 10), in graphics co-ordinates (i.e. the point which is 10mm above and to the right of the lower-left corner of the graphics device), into BASEPIC co-ordinates.

Notes:

• BASEPIC co-ordinates locate a position within the entire graphics device. The bottom-left corner of the device screen has BASEPIC co-ordinates of (0, 0). The shorter dimension of the screen has length 1.0, and the other axis has a length greater than 1.0.

• NDC co-ordinates are like BASEPIC co-ordinates except that the top-right corner of the screen has NDC co-ordinates of (1, 1). That is, both axes of the screen have unit length.

• GRAPHICS co-ordinates also span the entire graphics device but are measured in millimetres from the bottom-left corner.

• CURPIC co-ordinates locate a point within the current picture. The bottom-left corner of the current picture has CURPIC co-ordinates of (0, 0). The shorter dimension of the current picture has length 1.0, and the other axis has a length greater than 1.0.

• The transformed position is not written to the screen when the message filter environment variable MSG_FILTER is set to QUIET. The creation of the output Parameter POSOUT is unaffected by MSG_FILTER.

Related Applications :

KAPPA: GDSTATE, PICIN, PICXY.