next up previous 264
Next: astTimeMap - Create a TimeMap
Up: AST Function Descriptions
Previous: astTimeAdd - Add a time coordinate conversion to a TimeMap


astTimeFrame - Create a TimeFrame

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

A TimeFrame is a specialised form of one-dimensional Frame which represents various coordinate systems used to describe positions in time.

A TimeFrame represents a moment in time as either an Modified Julian Date (MJD), a Julian Date (JD), a Besselian epoch or a Julian epoch, as determined by the System attribute. Optionally, a zero point can be specified (using attribute TimeOrigin) which results in the TimeFrame representing time offsets from the specified zero point.

Even though JD and MJD are defined as being in units of days, the TimeFrame class allows other units to be used (via the Unit attribute) on the basis of simple scalings (60 seconds = 1 minute, 60 minutes = 1 hour, 24 hours = 1 day, 365.25 days = 1 year). Likewise, Julian epochs can be described in units other than the usual years. Besselian epoch are always represented in units of (tropical) years.

The TimeScale attribute allows the time scale to be specified (that is, the physical proces used to define the rate of flow of time). MJD, JD and Julian epoch can be used to represent a time in any supported time scale. However, Besselian epoch may only be used with the "TT" (Terrestrial Time) time scale. The list of supported time scales includes universal time and siderial time. Strictly, these represent angles rather than time scales, but are included in the list since they are in common use and are often thought of as time scales.

When a time value is formatted it can be formated either as a simple floating point value, or as a Gregorian date (see the Format attribute).

Synopsis:
AstTimeFrame $*$astTimeFrame( 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 TimeFrame. 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:
astTimeFrame()
A pointer to the new TimeFrame.
Notes:
  • When conversion between two TimeFrames is requested (as when supplying TimeFrames to astConvert), account will be taken of the nature of the time coordinate systems they represent, together with any qualifying time scale, offset, unit, etc. The AlignSystem and AlignTimeScale attributes 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 up previous 264
Next: astTimeMap - Create a TimeMap
Up: AST Function Descriptions
Previous: astTimeAdd - Add a time coordinate conversion to a TimeMap

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

Copyright (C) 2009 Science \& Technology Facilities Council