next up previous 264
Next: AST_CMPMAP - Create a CmpMap
Up: AST Routine Descriptions
Previous: AST_CLONE - Clone (duplicate) an Object pointer


AST_CMPFRAME - Create a CmpFrame

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

A CmpFrame is a compound Frame which allows two component Frames (of any class) to be merged together to form a more complex Frame. The axes of the two component Frames then appear together in the resulting CmpFrame (those of the first Frame, followed by those of the second Frame).

Since a CmpFrame is itself a Frame, it can be used as a component in forming further CmpFrames. Frames of arbitrary complexity may be built from simple individual Frames in this way.

Also since a Frame is a Mapping, a CmpFrame can also be used as a Mapping. Normally, a CmpFrame is simply equivalent to a UnitMap, but if either of the component Frames within a CmpFrame is a Region (a sub-class of Frame), then the CmpFrame will use the Region as a Mapping when transforming values for axes described by the Region. Thus input axis values corresponding to positions which are outside the Region will result in bad output axis values.

Invocation:
RESULT = AST_CMPFRAME( FRAME1, FRAME2, OPTIONS, STATUS )
Arguments:
FRAME1 = INTEGER (Given)
Pointer to the first component Frame.
FRAME2 = INTEGER (Given)
Pointer to the second component Frame.
OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new CmpFrame. The syntax used is identical to that for the AST_SET routine.
STATUS = INTEGER (Given and Returned)
The global status.
Returned Value:
AST_CMPFRAME = INTEGER
A pointer to the new CmpFrame.
Notes:
  • 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.
Status Handling
The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: "int $*$status".


next up previous 264
Next: AST_CMPMAP - Create a CmpMap
Up: AST Routine Descriptions
Previous: AST_CLONE - Clone (duplicate) an Object pointer

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