uk.ac.starlink.ast

Class TimeFrame

java.lang.Object

uk.ac.starlink.ast.AstObject

uk.ac.starlink.ast.Mapping

uk.ac.starlink.ast.Frame

uk.ac.starlink.ast.TimeFrame

public class TimeFrame
extends Frame

Java interface to the AST TimeFrame class - time coordinate system description. 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 process 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).

Licence

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public Licence as published by the Free Software Foundation; either version 2 of the Licence, or (at your option) any later version.

This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public Licence for more details.

You should have received a copy of the GNU General Public Licence along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street,Fifth Floor, Boston, MA 02110-1301, USA

See Also:

AST TimeFrame

Nested Class Summary

Nested classes/interfaces inherited from class uk.ac.starlink.ast.Mapping

Mapping.Interpolator, Mapping.Spreader

Field Summary

Fields inherited from class uk.ac.starlink.ast.Mapping

LINEAR_INTERPOLATOR, LINEAR_SPREADER, NEAREST_INTERPOLATOR, NEAREST_SPREADER

Fields inherited from class uk.ac.starlink.ast.AstObject

AST__BAD, AST__TUNULL, pointer

Constructor Summary

Constructors

Constructor and Description
TimeFrame() Create a TimeFrame.

Method Summary

Modifier and Type	Method and Description
double	currentTime() Return the current system time.
String	getAlignTimeScale() Get time scale to use when aligning TimeFrames.
String	getClockLat() Synonym for Frame.getObsLat().
String	getClockLon() Synonym for Frame.getObsLon().
double	getLtOffset() Get the offset from UTC to Local Time, in hours.
double	getTimeOrigin() Get the zero point for TimeFrame axis values.
String	getTimeScale() Get time scale.
void	setAlignTimeScale(String alignTimeScale) Set time scale to use when aligning TimeFrames.
void	setClockLat(String clockLat) Synonym for Frame.setObsLat(java.lang.String).
void	setClockLon(String clockLon) Synonym for Frame.setObsLon(java.lang.String).
void	setLtOffset(double ltOffset) Set the offset from UTC to Local Time, in hours.
void	setTimeOrigin(double timeOrigin) Set the zero point for TimeFrame axis values.
void	setTimeOrigin(String timeOrigin) Set the zero point for TimeFrame axis values.
void	setTimeScale(String timeScale) Set time scale.

Methods inherited from class uk.ac.starlink.ast.Frame

angle, axAngle, axDistance, axOffset, convert, distance, findFrame, format, getActiveUnit, getAlignSystem, getBottom, getDigits, getDigits, getDirection, getDomain, getDut1, getEpoch, getFormat, getLabel, getMatchEnd, getMaxAxes, getMinAxes, getNaxes, getNormUnit, getObsLat, getObsLon, getPermute, getPreserveAxes, getSymbol, getSystem, getTitle, getTop, getUnit, intersect, norm, offset, offset2, permAxes, pickAxes, resolve, setActiveUnit, setAlignSystem, setBottom, setDigits, setDigits, setDirection, setDomain, setDut1, setEpoch, setEpoch, setFormat, setLabel, setMatchEnd, setMaxAxes, setMinAxes, setObsLat, setObsLon, setPermute, setPreserveAxes, setSymbol, setSystem, setTitle, setTop, setUnit, unformat

Methods inherited from class uk.ac.starlink.ast.Mapping

decompose, getInvert, getNin, getNout, getReport, getTranForward, getTranInverse, invert, linearApprox, mapBox, mapSplit, rate, rebin, rebinD, rebinF, rebinI, resample, resampleB, resampleD, resampleF, resampleI, resampleL, resampleS, setInvert, setReport, simplify, tran1, tran2, tranGrid, tranN, tranP

Methods inherited from class uk.ac.starlink.ast.AstObject

annul, clear, copy, delete, equals, finalize, getAstConstantI, getB, getC, getD, getF, getI, getID, getIdent, getL, getNobject, getObjSize, getRefCount, hashCode, isThreaded, reportVersions, sameObject, set, setB, setC, setD, setF, setI, setID, setIdent, setL, show, test, tune

Methods inherited from class java.lang.Object

clone, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TimeFrame

public TimeFrame()

Create a TimeFrame. 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).

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.

Throws:

AstException - if an error occurred in the AST library

Method Detail

currentTime

public double currentTime()

Return the current system time. This function returns the current system time, represented in the form specified by the supplied TimeFrame. That is, the returned floating point value should be interpreted using the attribute values of the TimeFrame. This includes System, TimeOrigin, LTOffset, TimeScale, and Unit.

Notes

- Values of AST__BAD will be returned if this function is invoked with the AST error status set, or if it should fail for any reason.
- It is assumes that the system time (returned by the C time() function) follows the POSIX standard, representing a continuous monotonic increasing count of SI seconds since the epoch 00:00:00 UTC 1 January 1970 AD (equivalent to TAI with a constant offset). Resolution is one second.
- An error will be reported if the TimeFrame has a TimeScale value which cannot be converted to TAI (e.g. "angular" systems such as UT1, GMST, LMST and LAST).
- Any inaccuracy in the system clock will be reflected in the value returned by this function.

Returns:

A TimeFrame axis value representing the current system time.

Throws:

AstException - if an error occurred in the AST library

getAlignTimeScale

public String getAlignTimeScale()

Get time scale to use when aligning TimeFrames. This attribute controls how a TimeFrame behaves when it is used (by astFindFrame or astConvert) as a template to match another (target) TimeFrame. It identifies the time scale in which alignment is to occur. See the TimeScale attribute for a desription of the values which may be assigned to this attribute. The default AlignTimeScale value depends on the current value of TimeScale: if TimeScale is UT1, GMST, LMST or LAST, the default for AlignTimeScale is UT1, for all other TimeScales the default is TAI.

When astFindFrame or astConvert is used on two TimeFrames (potentially describing different time coordinate systems), it returns a Mapping which can be used to transform a position in one TimeFrame into the corresponding position in the other. The Mapping is made up of the following steps in the indicated order:

- Map values from the system used by the target (MJD, JD, etc) to the system specified by the AlignSystem attribute.

- Map these values from the target's time scale to the time scale specified by the AlignTimeScale attribute.

- Map these values from the time scale specified by the AlignTimeScale attribute, to the template's time scale.

- Map these values from the system specified by the AlignSystem attribute, to the system used by the template.

Returns:

this object's AlignTimeScale attribute

setAlignTimeScale

public void setAlignTimeScale(String alignTimeScale)

Set time scale to use when aligning TimeFrames. This attribute controls how a TimeFrame behaves when it is used (by astFindFrame or astConvert) as a template to match another (target) TimeFrame. It identifies the time scale in which alignment is to occur. See the TimeScale attribute for a desription of the values which may be assigned to this attribute. The default AlignTimeScale value depends on the current value of TimeScale: if TimeScale is UT1, GMST, LMST or LAST, the default for AlignTimeScale is UT1, for all other TimeScales the default is TAI.

When astFindFrame or astConvert is used on two TimeFrames (potentially describing different time coordinate systems), it returns a Mapping which can be used to transform a position in one TimeFrame into the corresponding position in the other. The Mapping is made up of the following steps in the indicated order:

- Map values from the system used by the target (MJD, JD, etc) to the system specified by the AlignSystem attribute.

- Map these values from the target's time scale to the time scale specified by the AlignTimeScale attribute.

- Map these values from the time scale specified by the AlignTimeScale attribute, to the template's time scale.

- Map these values from the system specified by the AlignSystem attribute, to the system used by the template.

Parameters:

alignTimeScale - the AlignTimeScale attribute of this object

getLtOffset

public double getLtOffset()

Get the offset from UTC to Local Time, in hours. This specifies the offset from UTC to Local Time, in hours (fractional hours can be supplied). It is positive for time zones east of Greenwich. AST uses the figure as given, without making any attempt to correct for daylight saving. The default value is zero.

Returns:

this object's LtOffset attribute

setLtOffset

public void setLtOffset(double ltOffset)

Set the offset from UTC to Local Time, in hours. This specifies the offset from UTC to Local Time, in hours (fractional hours can be supplied). It is positive for time zones east of Greenwich. AST uses the figure as given, without making any attempt to correct for daylight saving. The default value is zero.

Parameters:

ltOffset - the LtOffset attribute of this object

getTimeOrigin

public double getTimeOrigin()

Get the zero point for TimeFrame axis values. This specifies the origin from which all time values are measured. The default value (zero) results in the TimeFrame describing absolute time values in the system given by the System attribute (e.g. MJD, Julian epoch, etc). If a TimeFrame is to be used to describe elapsed time since some origin, the TimeOrigin attribute should be set to hold the required origin value. The TimeOrigin value stored inside the TimeFrame structure is modified whenever TimeFrame attribute values are changed so that it refers to the original moment in time.

Input Formats

The formats accepted when setting a TimeOrigin value are listed below. They are all case-insensitive and are generally tolerant of extra white space and alternative field delimiters:

- Besselian Epoch: Expressed in decimal years, with or without decimal places ("B1950" or "B1976.13" for example).

- Julian Epoch: Expressed in decimal years, with or without decimal places ("J2000" or "J2100.9" for example).

- Units: An unqualified decimal value is interpreted as a value in the system specified by the TimeFrame's System attribute, in the units given by the TimeFrame's Unit attribute. Alternatively, an appropriate unit string can be appended to the end of the floating point value ("123.4 d" for example), in which case the supplied value is scaled into the units specified by the Unit attribute.

- Julian Date: With or without decimal places ("JD 2454321.9" for example).

- Modified Julian Date: With or without decimal places ("MJD 54321.4" for example).

- Gregorian Calendar Date: With the month expressed either as an integer or a 3-character abbreviation, and with optional decimal places to represent a fraction of a day ("1996-10-2" or "1996-Oct-2.6" for example). If no fractional part of a day is given, the time refers to the start of the day (zero hours).

- Gregorian Date and Time: Any calendar date (as above) but with a fraction of a day expressed as hours, minutes and seconds ("1996-Oct-2 12:13:56.985" for example). The date and time can be separated by a space or by a "T" (as used by ISO8601 format).

Output Format

When enquiring TimeOrigin values, the returned formatted floating point value represents a value in the TimeFrame's System, in the unit specified by the TimeFrame's Unit attribute.

Returns:

this object's TimeOrigin attribute

setTimeOrigin

public void setTimeOrigin(double timeOrigin)

Set the zero point for TimeFrame axis values. This specifies the origin from which all time values are measured. The default value (zero) results in the TimeFrame describing absolute time values in the system given by the System attribute (e.g. MJD, Julian epoch, etc). If a TimeFrame is to be used to describe elapsed time since some origin, the TimeOrigin attribute should be set to hold the required origin value. The TimeOrigin value stored inside the TimeFrame structure is modified whenever TimeFrame attribute values are changed so that it refers to the original moment in time.

Input Formats

The formats accepted when setting a TimeOrigin value are listed below. They are all case-insensitive and are generally tolerant of extra white space and alternative field delimiters:

- Besselian Epoch: Expressed in decimal years, with or without decimal places ("B1950" or "B1976.13" for example).

- Julian Epoch: Expressed in decimal years, with or without decimal places ("J2000" or "J2100.9" for example).

- Units: An unqualified decimal value is interpreted as a value in the system specified by the TimeFrame's System attribute, in the units given by the TimeFrame's Unit attribute. Alternatively, an appropriate unit string can be appended to the end of the floating point value ("123.4 d" for example), in which case the supplied value is scaled into the units specified by the Unit attribute.

- Julian Date: With or without decimal places ("JD 2454321.9" for example).

- Modified Julian Date: With or without decimal places ("MJD 54321.4" for example).

- Gregorian Calendar Date: With the month expressed either as an integer or a 3-character abbreviation, and with optional decimal places to represent a fraction of a day ("1996-10-2" or "1996-Oct-2.6" for example). If no fractional part of a day is given, the time refers to the start of the day (zero hours).

- Gregorian Date and Time: Any calendar date (as above) but with a fraction of a day expressed as hours, minutes and seconds ("1996-Oct-2 12:13:56.985" for example). The date and time can be separated by a space or by a "T" (as used by ISO8601 format).

Output Format

When enquiring TimeOrigin values, the returned formatted floating point value represents a value in the TimeFrame's System, in the unit specified by the TimeFrame's Unit attribute.

Parameters:

timeOrigin - the TimeOrigin attribute of this object

setTimeOrigin

public void setTimeOrigin(String timeOrigin)

Set the zero point for TimeFrame axis values. This specifies the origin from which all time values are measured. The default value (zero) results in the TimeFrame describing absolute time values in the system given by the System attribute (e.g. MJD, Julian epoch, etc). If a TimeFrame is to be used to describe elapsed time since some origin, the TimeOrigin attribute should be set to hold the required origin value. The TimeOrigin value stored inside the TimeFrame structure is modified whenever TimeFrame attribute values are changed so that it refers to the original moment in time.

Input Formats

The formats accepted when setting a TimeOrigin value are listed below. They are all case-insensitive and are generally tolerant of extra white space and alternative field delimiters:

- Besselian Epoch: Expressed in decimal years, with or without decimal places ("B1950" or "B1976.13" for example).

- Julian Epoch: Expressed in decimal years, with or without decimal places ("J2000" or "J2100.9" for example).

- Units: An unqualified decimal value is interpreted as a value in the system specified by the TimeFrame's System attribute, in the units given by the TimeFrame's Unit attribute. Alternatively, an appropriate unit string can be appended to the end of the floating point value ("123.4 d" for example), in which case the supplied value is scaled into the units specified by the Unit attribute.

- Julian Date: With or without decimal places ("JD 2454321.9" for example).

- Modified Julian Date: With or without decimal places ("MJD 54321.4" for example).

- Gregorian Calendar Date: With the month expressed either as an integer or a 3-character abbreviation, and with optional decimal places to represent a fraction of a day ("1996-10-2" or "1996-Oct-2.6" for example). If no fractional part of a day is given, the time refers to the start of the day (zero hours).

- Gregorian Date and Time: Any calendar date (as above) but with a fraction of a day expressed as hours, minutes and seconds ("1996-Oct-2 12:13:56.985" for example). The date and time can be separated by a space or by a "T" (as used by ISO8601 format).

Output Format

When enquiring TimeOrigin values, the returned formatted floating point value represents a value in the TimeFrame's System, in the unit specified by the TimeFrame's Unit attribute.

Parameters:

timeOrigin - formatted string giving the TimeOrigin attribute of this object

getTimeScale

public String getTimeScale()

Get time scale. This attribute identifies the time scale to which the time axis values of a TimeFrame refer, and may take any of the values listed in the "Time Scales" section (below).

The default TimeScale value depends on the current System value; if the current TimeFrame system is "Besselian epoch" the default is "TT", otherwise it is "TAI". Note, if the System attribute is set so that the TimeFrame represents Besselian Epoch, then an error will be reported if an attempt is made to set the TimeScale to anything other than TT.

Note, the supported time scales fall into two groups. The first group containing UT1, GMST, LAST and LMST define time in terms of the orientation of the earth. The second group (containing all the remaining time scales) define time in terms of an atomic process. Since the rate of rotation of the earth varies in an unpredictable way, conversion between two timescales in different groups relies on a value being supplied for the Dut1 attribute (defined by the parent Frame class). This attribute specifies the difference between the UT1 and UTC time scales, in seconds, and defaults to zero. See the documentation for the Dut1 attribute for further details.

Time Scales

The TimeFrame class supports the following TimeScale values (all are case-insensitive):

- "TAI" - International Atomic Time
- "UTC" - Coordinated Universal Time
- "UT1" - Universal Time
- "GMST" - Greenwich Mean Sidereal Time
- "LAST" - Local Apparent Sidereal Time
- "LMST" - Local Mean Sidereal Time
- "TT" - Terrestrial Time
- "TDB" - Barycentric Dynamical Time
- "TCB" - Barycentric Coordinate Time
- "TCG" - Geocentric Coordinate Time
- "LT" - Local Time (the offset from UTC is given by attribute LTOffset)

An very informative description of these and other time scales is available at http://www.ucolick.org/~sla/leapsecs/timescales.html.

UTC Warnings

UTC should ideally be expressed using separate hours, minutes and seconds fields (or at least in seconds for a given date) if leap seconds are to be taken into account. Since the TimeFrame class represents each moment in time using a single floating point number (the axis value) there will be an ambiguity during a leap second. Thus an error of up to 1 second can result when using AST to convert a UTC time to another time scale if the time occurs within a leap second. Leap seconds occur at most twice a year, and are introduced to take account of variation in the rotation of the earth. The most recent leap second occurred on 1st January 1999. Although in the vast majority of cases leap second ambiguities won't matter, there are potential problems in on-line data acquisition systems and in critical applications involving taking the difference between two times.

Returns:

this object's TimeScale attribute

setTimeScale

public void setTimeScale(String timeScale)

Set time scale. This attribute identifies the time scale to which the time axis values of a TimeFrame refer, and may take any of the values listed in the "Time Scales" section (below).

The default TimeScale value depends on the current System value; if the current TimeFrame system is "Besselian epoch" the default is "TT", otherwise it is "TAI". Note, if the System attribute is set so that the TimeFrame represents Besselian Epoch, then an error will be reported if an attempt is made to set the TimeScale to anything other than TT.

Note, the supported time scales fall into two groups. The first group containing UT1, GMST, LAST and LMST define time in terms of the orientation of the earth. The second group (containing all the remaining time scales) define time in terms of an atomic process. Since the rate of rotation of the earth varies in an unpredictable way, conversion between two timescales in different groups relies on a value being supplied for the Dut1 attribute (defined by the parent Frame class). This attribute specifies the difference between the UT1 and UTC time scales, in seconds, and defaults to zero. See the documentation for the Dut1 attribute for further details.

Time Scales

The TimeFrame class supports the following TimeScale values (all are case-insensitive):

- "TAI" - International Atomic Time
- "UTC" - Coordinated Universal Time
- "UT1" - Universal Time
- "GMST" - Greenwich Mean Sidereal Time
- "LAST" - Local Apparent Sidereal Time
- "LMST" - Local Mean Sidereal Time
- "TT" - Terrestrial Time
- "TDB" - Barycentric Dynamical Time
- "TCB" - Barycentric Coordinate Time
- "TCG" - Geocentric Coordinate Time
- "LT" - Local Time (the offset from UTC is given by attribute LTOffset)

An very informative description of these and other time scales is available at http://www.ucolick.org/~sla/leapsecs/timescales.html.

UTC Warnings

UTC should ideally be expressed using separate hours, minutes and seconds fields (or at least in seconds for a given date) if leap seconds are to be taken into account. Since the TimeFrame class represents each moment in time using a single floating point number (the axis value) there will be an ambiguity during a leap second. Thus an error of up to 1 second can result when using AST to convert a UTC time to another time scale if the time occurs within a leap second. Leap seconds occur at most twice a year, and are introduced to take account of variation in the rotation of the earth. The most recent leap second occurred on 1st January 1999. Although in the vast majority of cases leap second ambiguities won't matter, there are potential problems in on-line data acquisition systems and in critical applications involving taking the difference between two times.

Parameters:

timeScale - the TimeScale attribute of this object

setClockLat

public void setClockLat(String clockLat)

Synonym for Frame.setObsLat(java.lang.String).

getClockLat

public String getClockLat()

Synonym for Frame.getObsLat().

setClockLon

public void setClockLon(String clockLon)

Synonym for Frame.setObsLon(java.lang.String).

getClockLon

public String getClockLon()

Synonym for Frame.getObsLon().