PICIN - Finds the attributes of a picture interior to the current picture

Description:

This application finds the attributes of a picture, selected by name, that was created since the current picture and lies within the bounds of the current picture. The search starts from the most-recent picture, unless the current picture is included, whereupon the current picture is tested first.

The attributes reported are the name, comment, label, name of the reference data object, the bounds in the co-ordinate Frame  selected by Parameter FRAME.

Usage:

picin [name] [device] [frame]

Parameters:

CURRENT = _LOGICAL (Read)

If this is TRUE, the current picture is compared against the chosen name before searching from the most-recent picture within the current picture. [FALSE]

DEVICE = DEVICE (Read)

Name of the graphics device about which information is required. [Current graphics device]

EPOCH = _DOUBLE (Read)

If a `Sky Co-ordinate System' specification is supplied (using Parameter FRAME) for a celestial co-ordinate system, then an epoch value is needed to qualify it. This is the epoch at which the displayed sky co-ordinates were 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.

FRAME = LITERAL (Read)

A string determining the co-ordinate Frame in which the bounds of the picture are to be reported. When a picture is created by an application such as PICDEF, DISPLAY, the WCS information describing the available co-ordinate systems are stored with the picture in the graphics database. This application can report bounds in any of the co-ordinate Frames stored with the current picture. The string supplied for FRAME can be one of the following:

• A domain name  such as SKY, AXIS, PIXEL, NDC, BASEPIC, CURPIC. the special domain AGI_WORLD is used to refer to the world co-ordinate system stored in the AGI graphics database. This can be useful if no WCS information was store with the picture when it was created.

• An integer value giving the index of the required Frame.

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

If a null value (!) is supplied, bounds are reported in the co-ordinate Frame which was current when the picture was created. [!]

NAME = LITERAL (Read)

The name of the picture to be found within the current picture. If it is null (!), the first interior picture is selected. [DATA]

PNAME = LITERAL (Write)

The name of the picture.

REPORT = _LOGICAL (Read)

If this is FALSE details of the picture are not reported, merely the results are written to the output parameters. It is intended for use within procedures. [TRUE]

Results Parameters:

COMMENT = LITERAL (Write)

The comment of the picture. Up to 132 characters will be written.

DOMAIN = LITERAL (Write)

The Domain name of the current co-ordinate Frame for the picture.

LABEL = LITERAL (Write)

The label of the picture. It is blank if there is no label.

REFNAM = LITERAL (Write)

The reference object associated with the picture. It is blank if there is no reference object. Up to 132 characters will be written.

X1 = LITERAL (Write)

The lowest value found within the picture for axis 1 of the requested co-ordinate Frame (see Parameter FRAME).

X2 = LITERAL (Write)

The highest value found within the picture for axis 1 of the requested co-ordinate Frame (see Parameter FRAME).

Y1 = LITERAL (Write)

The lowest value found within the picture for axis 2 of the requested co-ordinate Frame (see Parameter FRAME).

Y2 = LITERAL (Write)

The highest value found within the picture for axis 2 of the requested co-ordinate Frame (see Parameter FRAME).

Examples:

picin

This reports the attributes of the last DATA picture within the current picture for the current graphics device. The bounds of the picture in its current co-ordinate Frame are reported.

picin frame=pixel

As above but the bounds of the picture in the PIXEL Frame are reported.

picin refnam=(object) current

This reports the attributes of the last data picture within the current picture for the current graphics device. If there is a reference data object, its name is written to the ICL variable OBJECT. The search includes the current picture.

picin x1=(x1) x2=(x2) y1=(y1) y2=(y2)

This reports the attributes of the last DATA picture within the current picture for the current graphics device. The bounds of the current picture are written to the ICL  variables: X1, X2, Y1, Y2.

Notes:

This application is intended for use within procedures. Also if a DATA picture is selected and the current picture is included in the search, this application informs about the same picture that an application that works in a cursor interaction mode  would select, and so acts as a check that the correct picture will be accessed.

Related Applications

KAPPA: GDSTATE, PICDEF, PICLIST, PICTRANS, PICXY.