next up previous 264
Next: AST_GENCURVE - Draw a generalized curve
Up: AST Routine Descriptions
Previous: AST_FRAME - Create a Frame


AST_FRAMESET - Create a FrameSet

Description:
This function creates a new FrameSet and optionally initialises its attributes.

A FrameSet consists of a set of one or more Frames (which describe coordinate systems), connected together by Mappings (which describe how the coordinate systems are inter-related). A FrameSet makes it possible to obtain a Mapping between any pair of these Frames (i.e. to convert between any of the coordinate systems which it describes). The individual Frames are identified within the FrameSet by an integer index, with Frames being numbered consecutively from one as they are added to the FrameSet.

Every FrameSet has a "base" Frame and a "current" Frame (which are allowed to be the same). Any of the Frames may be nominated to hold these positions, and the choice is determined by the values of the FrameSet's Base and Current attributes, which hold the indices of the relevant Frames. By default, the first Frame added to a FrameSet is its base Frame, and the last one added is its current Frame.

The base Frame describes the "native" coordinate system of whatever the FrameSet is used to calibrate (e.g. the pixel coordinates of an image) and the current Frame describes the "apparent" coordinate system in which it should be viewed (e.g. displayed, etc.). Any further Frames represent a library of alternative coordinate systems, which may be selected by making them current.

When a FrameSet is used in a context that requires a Frame, (e.g. obtaining its Title value, or number of axes), the current Frame is used. A FrameSet may therefore be used in place of its current Frame in most situations.

When a FrameSet is used in a context that requires a Mapping, the Mapping used is the one between its base Frame and its current Frame. Thus, a FrameSet may be used to convert "native" coordinates into "apparent" ones, and vice versa. Like any Mapping, a FrameSet may also be inverted (see AST_INVERT), which has the effect of interchanging its base and current Frames and hence of reversing the Mapping between them.

Regions may be added into a FrameSet (since a Region is a type of Frame), either explicitly or as components within CmpFrames. In this case the Mapping between a pair of Frames within a FrameSet will include the effects of the clipping produced by any Regions included in the path between the Frames.

Invocation:
RESULT = AST_FRAMESET( FRAME, OPTIONS, STATUS )
Arguments:
FRAME = INTEGER (Given)
Pointer to the first Frame to be inserted into the FrameSet. This initially becomes both the base and the current Frame. (Further Frames may be added using the AST_ADDFRAME routine.)
OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new FrameSet. The syntax used is identical to that for the AST_SET routine. If no initialisation is required, a blank value may be supplied.
STATUS = INTEGER (Given and Returned)
The global status.
Returned Value:
AST_FRAMESET
A pointer to the new FrameSet.
Notes:
  • If a pointer to an existing FrameSet is given for the FRAME argument, then the new FrameSet will (as a special case) be initialised to contain the same Frames and Mappings, and to have the same attribute values, as the one supplied. This process is similar to making a copy of a FrameSet (see AST_COPY), except that the Frames and Mappings contained in the original are not themselves copied, but are shared by both FrameSets.

  • A null Object pointer (AST__NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason.


next up previous 264
Next: AST_GENCURVE - Draw a generalized curve
Up: AST Routine Descriptions
Previous: AST_FRAME - Create a Frame

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 210
R.F. Warren-Smith & D.S. Berry
24th May 2011
E-mail:ussc@star.rl.ac.uk

Copyright (C) 2009 Science \& Technology Facilities Council