KPG1_GDGET

Gets the AST Plot associated with a graphics-database picture

Description:

This routine makes the specified graphics-database (AGI) picture current, creates a corresponding PGPLOT viewport and window, and returns a Plot associated with the picture.

On exit, the PGPLOT viewport corresponds to the area encompassed by the specified picture. The world co-ordinate bounds within this viewport are set so that the PGPLOT world co-ordinate system is millimetres from the bottom-left corner of the view surface. This corresponds to the Base (GRAPHICS) Frame in the returned Plot.

The returned Plot will normally be obtained from the MORE structure in the graphics database (where it was stored by a previous AST-based application). The Base Frame will be a GRAPHICS Frame, giving millimetres from the bottom-left corner of the view surface.

If no Plot is available in the database, then an initial PLOT is created containing a Base Frame with Domain GRAPHICS (giving millimetres from the bottom-left corner of the view surface), and a Current Frame corresponding to AGI world co-ordinates. The Frame to represent AGI world co-ordinates in the Plot may be supplied by the calling application (for instance, an application may supply a PIXEL Frame on the assumption that AGI world co-ordinates are pixel co-ordinates). If no such Frame is supplied then a simple Frame is used, with Domain set to AGI_WORLD.

A third Frame may optionally be added to the Plot representing AGI DATA co-ordinates. This Frame will have Domain AGI_DATA, and the Mapping from world to data co-ordinates will be given by the TRANSFORM structure stored with the picture in the database. If present, it will be the Current Frame in the Plot on exit. See " Usage" below for warnings about using this option.

Finally, some other Frames are added to the Plot representing various normalised co-ordinates:

BASEPIC: The co-ordinates of the bottom-left corner of the BASE picture are (0,0). The shorter dimension of the BASE picture has length 1.0, and the other axis has a length greater than 1.0.

NDC: Normalized device co-ordinates. The bottom-left corner of the screen is (0,0) and the top-right corner is (1,1).

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

CURNDC: The co-ordinates of the bottom-left corner of the current picture are (0,0), and the top-right corner is (1,1).

If the Plot read from the database already contains any of these Frames then they are retained and no new Frame is added.

Invocation

CALL KPG1_GDGET( IPIC, WCFRM, MKDATA, IPLOT, STATUS )

Arguments

IPIC = INTEGER (Given)
The AGI identifier for the picture. If a value of -1 is supplied, the identifier for the current picture is used.
WCFRM = INTEGER (Given)
A pointer to an AST Frame which will be used to describe AGI world co-ordinates if the picture has no associated Plot. This argument is ignored if the picture already has a Plot stored with it in the database. If a null pointer (AST__NULL) is supplied, then a default Frame is used with Domain set to AGI_WORLD.
MKDATA = LOGICAL (Given)
Should a Frame with Domain AGI_DATA be included in the returned Plot to represent AGI DATA co-ordinates? This is ignored if the picture has a Plot already stored with it in the database.
IPLOT = INTEGER (Returned)
An AST pointer to the Plot. Returned equal to AST__NULL if an error occurs.
STATUS = INTEGER (Given and Returned)
The global status.

Notes: