next up previous
Next: astSlaAdd - Add a celestial coordinate conversion to an SlaMap
Up: AST Function Descriptions
Previous: astSimplify - Simplify a Mapping

astSkyFrame - Create a SkyFrame   

Description:
This function creates a new SkyFrame and optionally initialises its attributes. A SkyFrame is a specialised form of Frame which describes celestial longitude/latitude coordinate systems. The particular celestial coordinate system to be represented is specified by setting the SkyFrame's System attribute (currently, the default is FK5) qualified, as necessary, by a mean Equinox value and/or an Epoch.

All the coordinate values used by a SkyFrame are in radians. These may be formatted in more conventional ways for display by using astFormat.

Synopsis:
AstSkyFrame *astSkyFrame( 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 SkyFrame. 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:
astSkyFrame()
A pointer to the new SkyFrame.

Examples:
frame = astSkyFrame( "" );

Creates a SkyFrame to describe the default FK5 celestial coordinate system, with the standard (default) mean Equinox of J2000.0.

frame = astSkyFrame( "Equinox = J2005, Digits = 10" );

Creates a SkyFrame to describe the default FK5 celestial coordinate system, but this time with a mean Equinox of J2005.0. Because especially accurate coordinates will be used, additional precision (10 digits) has been requested. This will be used when coordinate values are formatted for display.

frame = astSkyFrame( "System = FK4, Equinox = 1955-sep-2" );

Creates a SkyFrame to describe the old FK4 celestial coordinate system. A default Epoch value (B1950.0) is used, but the mean Equinox value is given explicitly as "1955-sep-2".

frame = astSkyFrame( "System = GAPPT, Epoch = %s", date );

Creates a SkyFrame to describe the Geocentric Apparent celestial coordinate system. The Epoch value, which specifies the date of observation, is obtained from a date/time string supplied via the string pointer "date".

Notes:
  • Currently, the default celestial coordinate system is FK5. However, this default may change in future as new astrometric standards evolve. The intention is to track the most modern appropriate standard. For this reason, you should use the default only if this is what you intend (and can tolerate any associated slight change in behaviour with future versions of this function). If you intend to use the FK5 system indefinitely, then you should specify it explicitly using an "options" value of "System=FK5".
  • Whichever celestial coordinate system is represented, it will have two axes. The first of these will be the longitude axis and the second will be the latitude axis. This order can be changed using astPermAxes if required.
  • When conversion between two SkyFrames is requested (as when supplying SkyFrames to astConvert), account will be taken of the nature of the celestial coordinate systems they represent, together with any qualifying mean Equinox or Epoch values, etc. The AlignSystem attribute will also be taken into account. The results will therefore fully reflect the relationship between positions on the sky measured in the two systems.
  • 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 up previous
Next: astSlaAdd - Add a celestial coordinate conversion to an SlaMap
Up: AST Function Descriptions
Previous: astSimplify - Simplify a Mapping

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