Next: astSpecMap - Create a SpecMap
Up: AST Function Descriptions
Previous: astSpecAdd - Add a spectral coordinate conversion to a SpecMap
- 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).
- Synopsis:
AstSpecFrame *astSpecFrame( const char *options, ... )
- Parameters:
-
options
-
Pointer to a null-terminated 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 astSet function and may include "printf" format
specifiers identified by "%" symbols in the normal way.
If no initialisation is required, a zero-length string may be
supplied.
-
...
-
If the "options" string contains "%" format specifiers, then
an optional list of additional arguments may follow it in
order to supply values to be substituted for these
specifiers. The rules for supplying these are identical to
those for the astSet function (and for the C "printf"
function).
- Returned Value:
-
astSpecFrame()
-
A pointer to the new SpecFrame.
- Examples:
-
frame = astSpecFrame( "" );
-
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 = astSpecFrame( "System=VELO, RestFreq=1.0E15, StdOfRest=LSRK" );
-
Creates a SpecFrame describing a relativistic 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 to astConvert),
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 the AST error status set, or if it
should fail for any reason.
Next: astSpecMap - Create a SpecMap
Up: AST Function Descriptions
Previous: astSpecAdd - Add a spectral coordinate conversion to a SpecMap
AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 211
R.F. Warren-Smith & D.S. Berry
30th April 2003
E-mail:ussc@star.rl.ac.uk
Copyright (C) 2003 Central Laboratory of the Research Councils