Next Previous Up Contents
Next: TrigDegrees
Up: Functions
Previous: Tilings
Functions for conversion of time values between various forms.
The forms used are

Modified Julian Date (MJD)
 A continuous measure in days since midnight at the start of
17 November 1858. Based on UTC.

Julian Day (JD)
 MJD plus a fixed offset of 2400000.5.
The number of days since the notional creation of the universe,
midday on 1 Jan 4713 BC.

ISO 8601
 A string representation of the form
yyyymmddThh:mm:ss.s
, where the T
is a literal character (a space character may be used instead).
Based on UTC.

Julian Epoch
 A continuous measure based on a Julian year of exactly 365.25 days.
For approximate purposes this resembles the fractional number
of years AD represented by the date. Sometimes (but not here)
represented by prefixing a 'J'; J2000.0 is defined as
2000 January 1.5 in the TT timescale.

Besselian Epoch
 A continuous measure based on a tropical year of about 365.2422 days.
For approximate purposes this resembles the fractional number of
years AD represented by the date. Sometimes (but not here)
represented by prefixing a 'B'.

Decimal Year
 Fractional number of years AD represented by the date.
2000.0, or equivalently 1999.99recurring, is midnight at the start
of the first of January 2000. Because of leap years, the size of
a unit depends on what year it is in.
Therefore midday on the 25th of October 2004 is
20041025T12:00:00
in ISO 8601 format,
53303.5 as an MJD value,
2004.81588 as a Julian Epoch and
2004.81726 as a Besselian Epoch.
Currently this implementation cannot be relied upon to
better than a millisecond.

isoToMjd( isoDate )

Converts an ISO8601 date string to Modified Julian Date.
The basic format of the
isoDate
argument is
yyyymmddThh:mm:ss.s
, though some deviations
from this form are permitted:
 The '
T
' which separates date from time
can be replaced by a space
 The seconds, minutes and/or hours can be omitted
 The decimal part of the seconds can be any length,
and is optional
 The '
mmdd
' part may be replaced by a 3digit
day of year 'ddd
'
 A '
Z
' (which indicates UTC) may be appended
to the time
Some legal examples are therefore:
"19941221T14:18:23.2
",
"19680114
",
"21120525 16:45Z
", and
"1987172T22:12
".
 Parameters:

isoDate
(String): date in ISO 8601 format
 Return value

(floating point): modified Julian date corresponding to
isoDate
 Examples:

isoToMjd("20041025T18:00:00") = 53303.75

isoToMjd("19700101") = 40587.0

dateToMjd( year, month, day, hour, min, sec )

Converts a calendar date and time to Modified Julian Date.
 Parameters:

year
(integer): year AD

month
(integer): index of month; January is 1, December is 12

day
(integer): day of month (the first day is 1)

hour
(integer): hour (023)

min
(integer): minute (059)

sec
(floating point): second (0<=sec<60)
 Return value

(floating point): modified Julian date corresponding to arguments
 Example:

dateToMjd(1999, 12, 31, 23, 59, 59.) = 51543.99998

dateToMjd( year, month, day )

Converts a calendar date to Modified Julian Date.
 Parameters:

year
(integer): year AD

month
(integer): index of month; January is 1, December is 12

day
(integer): day of month (the first day is 1)
 Return value

(floating point): modified Julian date corresponding to 00:00:00 of the date
specified by the arguments
 Example:

dateToMjd(1999, 12, 31) = 51543.0

decYearToMjd( decYear )

Converts a Decimal Year to a Modified Julian Date.
 Parameters:

decYear
(floating point): decimal year
 Return value

(floating point): modified Julian Date
 Example:

decYearToMjd(2000.0) = 51544.0

isoToUnixSec( isoDate )

Converts an ISO8601 date string to seconds since 19700101.
The basic format of the
isoDate
argument is
yyyymmddThh:mm:ss.s
, though some deviations
from this form are permitted:
 The '
T
' which separates date from time
can be replaced by a space
 The seconds, minutes and/or hours can be omitted
 The decimal part of the seconds can be any length,
and is optional
 The '
mmdd
' part may be replaced by a 3digit
day of year 'ddd
'
 A '
Z
' (which indicates UTC) may be appended
to the time
Some legal examples are therefore:
"19941221T14:18:23.2
",
"19680114
",
"21120525 16:45Z
and
"1987172T22:12
".
 Parameters:

isoDate
(String): date in ISO 8601 format
 Return value

(floating point): seconds since the Unix epoch
 Examples:

isoToUnixSec("20041025T18:00:00") = 1098727200

isoToUnixSec("19700101") = 0

decYearToUnixSec( decYear )

Converts a Decimal Year to seconds since 19700101.
 Parameters:

decYear
(floating point): decimal year
 Return value

(floating point): seconds since the Unix epoch
 Examples:

decYearToUnixSec(2000.0) = 946684800

decYearToUnixSec(1970) = 0

mjdToUnixSec( mjd )

Converts a Modified Julian Date to seconds since 19700101.
 Parameters:

mjd
(floating point): modified Julian date
 Return value

(floating point): seconds since the Unix epoch

jdToUnixSec( jd )

Converts a Julian day to seconds since 19700101.
 Parameters:

jd
(floating point): Julian day
 Return value

(floating point): seconds since the Unix epoch

mjdToIso( mjd )

Converts a Modified Julian Date value to an ISO 8601format datetime
string. The output format is
yyyymmddThh:mm:ss
.
If the result predates the Common Era, the string "(BCE)" is prepended.
 Parameters:

mjd
(floating point): modified Julian date
 Return value

(String): ISO 8601 format date corresponding to
mjd
 Example:

mjdToIso(53551.72917) = "20050630T17:30:00"

mjdToDate( mjd )

Converts a Modified Julian Date value to an ISO 8601format date
string. The output format is
yyyymmdd
.
If the result predates the Common Era, the string "(BCE)" is prepended.
 Parameters:

mjd
(floating point): modified Julian date
 Return value

(String): ISO 8601 format date corresponding to
mjd
 Example:

mjdToDate(53551.72917) = "20050630"

mjdToTime( mjd )

Converts a Modified Julian Date value to an ISO 8601format timeonly
string. The output format is
hh:mm:ss
.
 Parameters:

mjd
(floating point): modified Julian date
 Return value

(String): ISO 8601 format time corresponding to
mjd
 Example:

mjdToTime(53551.72917) = "17:30:00"

mjdToDecYear( mjd )

Converts a Modified Julian Date to Decimal Year.
 Parameters:

mjd
(floating point): modified Julian Date
 Return value

(floating point): decimal year
 Example:

mjdToDecYear(0.0) = 1858.87671

formatMjd( mjd, format )

Converts a Modified Julian Date value to a date using a customisable
date format.
The format is as defined by the
java.text.SimpleDateFormat
class.
The default output corresponds to the string
"yyyyMMdd'T'HH:mm:ss
"
Note that the output from certain formatting characters
(such as MMM
for month, EEE
for day of week)
is dependent on your locale (system language settings).
The output time zone however always corresponds to UTC.
 Parameters:

mjd
(floating point): modified Julian date

format
(String): formatting patttern
 Return value

(String): custom formatted time corresponding to
mjd
 Examples:

formatMjd(50000.3, "EEE dd, MMM, yy")
= "Tue 10 Oct, 95"

formatMjd(50000.1234, "'time 'H:mm:ss.SSS")
= "time 2:57:41.760"

jdToMjd( jd )

Converts a Julian Day to Modified Julian Date.
The calculation is simply
jd2400000.5
.
 Parameters:

jd
(floating point): Julian day number
 Return value

(floating point): MJD value

mjdToJd( mjd )

Converts a Modified Julian Date to Julian Day.
The calculation is simply
jd+2400000.5
.
 Parameters:

mjd
(floating point): MJD value
 Return value

(floating point): Julian day number

mjdToJulian( mjd )

Converts a Modified Julian Date to Julian Epoch.
For approximate purposes, the result
of this routine consists of an integral part which gives the
year AD and a fractional part which represents the distance
through that year, so that for instance 2000.5 is approximately
1 July 2000.
 Parameters:

mjd
(floating point): modified Julian date
 Return value

(floating point): Julian epoch
 Example:

mjdToJulian(0.0) = 1858.87885

julianToMjd( julianEpoch )

Converts a Julian Epoch to Modified Julian Date.
For approximate purposes, the argument
of this routine consists of an integral part which gives the
year AD and a fractional part which represents the distance
through that year, so that for instance 2000.5 is approximately
1 July 2000.
 Parameters:

julianEpoch
(floating point): Julian epoch
 Return value

(floating point): modified Julian date
 Example:

julianToMjd(2000.0) = 51544.5

mjdToBesselian( mjd )

Converts Modified Julian Date to Besselian Epoch.
For approximate purposes, the result
of this routine consists of an integral part which gives the
year AD and a fractional part which represents the distance
through that year, so that for instance 1950.5 is approximately
1 July 1950.
 Parameters:

mjd
(floating point): modified Julian date
 Return value

(floating point): Besselian epoch
 Example:

mjdToBesselian(0.0) = 1858.87711

besselianToMjd( besselianEpoch )

Converts Besselian Epoch to Modified Julian Date.
For approximate purposes, the argument
of this routine consists of an integral part which gives the
year AD and a fractional part which represents the distance
through that year, so that for instance 1950.5 is approximately
1 July 1950.
 Parameters:

besselianEpoch
(floating point): Besselian epoch
 Return value

(floating point): modified Julian date
 Example:

besselianToMjd(1950.0) = 33281.92346

unixMillisToMjd( unixMillis )

Converts from milliseconds since the Unix epoch (19700101T00:00:00)
to a modified Julian date value
 Parameters:

unixMillis
(long integer): milliseconds since the Unix epoch
 Return value

(floating point): modified Julian date

mjdToUnixMillis( mjd )

Converts from modified Julian date to milliseconds since the Unix
epoch (19700101T00:00:00).
 Parameters:

mjd
(floating point): modified Julian date
 Return value

(long integer): milliseconds since the Unix epoch

MJD_OFFSET

JD value for MJD = 0 (=2400000.5).
Next Previous Up Contents
Next: TrigDegrees
Up: Functions
Previous: Tilings
STILTS  Starlink Tables Infrastructure Library Tool Set
Starlink User Note256
STILTS web page:
http://www.starlink.ac.uk/stilts/
Author email:
m.b.taylor@bristol.ac.uk
Mailing list:
topcatuser@jiscmail.ac.uk