next up previous 264
Next: AST_SPECMAP - Create a SpecMap
Up: AST Routine Descriptions
Previous: AST_SPECFLUXFRAME - Create a SpecFluxFrame


AST_SPECFRAME - Create a SpecFrame

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

A SpecFrame is a specialised form of one-dimensional Frame which represents various coordinate systems used to describe positions within an electro-magnetic spectrum. The particular coordinate system to be used is specified by setting the SpecFrame's System attribute (the default is wavelength) qualified, as necessary, by other attributes such as the rest frequency, the standard of rest, the epoch of observation, etc (see the description of the System attribute for details).

By setting a value for thr SpecOrigin attribute, a SpecFrame can be made to represent offsets from a given spectral position, rather than absolute

Invocation:
RESULT = AST_SPECFRAME( OPTIONS, STATUS )
Arguments:
OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new SpecFrame. 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_SPECFRAME = INTEGER
A pointer to the new SpecFrame.
Examples:
FRAME = AST_SPECFRAME( ' ', STATUS )

Creates a SpecFrame to describe the default wavelength spectral coordinate system. The RestFreq attribute (rest frequency) is unspecified, so it will not be possible to align this SpecFrame with another SpecFrame on the basis of a velocity-based system. The standard of rest is also unspecified. This means that alignment will be possible with other SpecFrames, but no correction will be made for Doppler shift caused by change of rest frame during the alignment.
FRAME = AST_SPECFRAME( 'System=VELO, RestFreq=1.0E15, StdOfRest=LSRK', STATUS )

Creates a SpecFrame describing a apparent radial velocity ("VELO") axis with rest frequency 1.0E15 Hz (about 3000 Angstroms), measured in the kinematic Local Standard of Rest ("LSRK"). Since the source position has not been specified (using attributes RefRA and RefDec), it will only be possible to align this SpecFrame with other SpecFrames which are also measured in the LSRK standard of rest.
Notes:
  • When conversion between two SpecFrames is requested (as when supplying SpecFrames AST_CONVERT), account will be taken of the nature of the spectral coordinate systems they represent, together with any qualifying rest frequency, standard of rest, epoch values, etc. The AlignSystem and AlignStdOfRest attributes will also be taken into account. The results will therefore fully reflect the relationship between positions measured in the two systems. In addition, any difference in the Unit attributes of the two systems will also be taken into account.

  • 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_SPECMAP - Create a SpecMap
Up: AST Routine Descriptions
Previous: AST_SPECFLUXFRAME - Create a SpecFluxFrame

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