Class AbsoluteDate

    • Field Detail

      • JULIAN_EPOCH

        public static final AbsoluteDate JULIAN_EPOCH
        Reference epoch for julian dates: -4712-01-01T12:00:00 Terrestrial Time.

        Both java.util.Date and DateComponents classes follow the astronomical conventions and consider a year 0 between years -1 and +1, hence this reference date lies in year -4712 and not in year -4713 as can be seen in other documents or programs that obey a different convention (for example the convcal utility).

      • MODIFIED_JULIAN_EPOCH

        public static final AbsoluteDate MODIFIED_JULIAN_EPOCH
        Reference epoch for modified julian dates: 1858-11-17T00:00:00 Terrestrial Time.
      • FIFTIES_EPOCH

        public static final AbsoluteDate FIFTIES_EPOCH
        Reference epoch for 1950 dates: 1950-01-01T00:00:00 Terrestrial Time.
      • CCSDS_EPOCH

        public static final AbsoluteDate CCSDS_EPOCH
        Reference epoch for CCSDS Time Code Format (CCSDS 301.0-B-4): 1958-01-01T00:00:00 International Atomic Time (not UTC).
      • GALILEO_EPOCH

        public static final AbsoluteDate GALILEO_EPOCH
        Reference epoch for Galileo System Time: 1999-08-22T00:00:00 UTC.
      • GPS_EPOCH

        public static final AbsoluteDate GPS_EPOCH
        Reference epoch for GPS weeks: 1980-01-06T00:00:00 GPS time.
      • JAVA_EPOCH

        public static final AbsoluteDate JAVA_EPOCH
        Java Reference epoch: 1970-01-01T00:00:00 Universal Time Coordinate.

        Between 1968-02-01 and 1972-01-01, UTC-TAI = 4.213 170 0s + (MJD - 39 126) x 0.002 592s. As on 1970-01-01 MJD = 40587, UTC-TAI = 8.000082s

      • PAST_INFINITY

        public static final AbsoluteDate PAST_INFINITY
        Dummy date at infinity in the past direction.
      • FUTURE_INFINITY

        public static final AbsoluteDate FUTURE_INFINITY
        Dummy date at infinity in the future direction.
    • Constructor Detail

      • AbsoluteDate

        public AbsoluteDate()
        Create an instance with a default value (J2000_EPOCH).
      • AbsoluteDate

        public AbsoluteDate​(DateTimeComponents location,
                            TimeScale timeScale)
        Build an instance from a location in a time scale.
        Parameters:
        location - location in the time scale
        timeScale - time scale
      • AbsoluteDate

        public AbsoluteDate​(DateComponents date,
                            TimeComponents time,
                            TimeScale timeScale)
        Build an instance from a location in a time scale.
        Parameters:
        date - date location in the time scale
        time - time location in the time scale
        timeScale - time scale
      • AbsoluteDate

        public AbsoluteDate​(int year,
                            int month,
                            int day,
                            int hour,
                            int minute,
                            double second,
                            TimeScale timeScale)
                     throws IllegalArgumentException
        Build an instance from a location in a time scale.
        Parameters:
        year - year number (may be 0 or negative for BC years)
        month - month number from 1 to 12
        day - day number from 1 to 31
        hour - hour number from 0 to 23
        minute - minute number from 0 to 59
        second - second number from 0.0 to 60.0 (excluded)
        timeScale - time scale
        Throws:
        IllegalArgumentException - if inconsistent arguments are given (parameters out of range)
      • AbsoluteDate

        public AbsoluteDate​(int year,
                            Month month,
                            int day,
                            int hour,
                            int minute,
                            double second,
                            TimeScale timeScale)
                     throws IllegalArgumentException
        Build an instance from a location in a time scale.
        Parameters:
        year - year number (may be 0 or negative for BC years)
        month - month enumerate
        day - day number from 1 to 31
        hour - hour number from 0 to 23
        minute - minute number from 0 to 59
        second - second number from 0.0 to 60.0 (excluded)
        timeScale - time scale
        Throws:
        IllegalArgumentException - if inconsistent arguments are given (parameters out of range)
      • AbsoluteDate

        public AbsoluteDate​(int year,
                            int month,
                            int day,
                            TimeScale timeScale)
                     throws IllegalArgumentException
        Build an instance from a location in a time scale.

        The hour is set to 00:00:00.000.

        Parameters:
        year - year number (may be 0 or negative for BC years)
        month - month number from 1 to 12
        day - day number from 1 to 31
        timeScale - time scale
        Throws:
        IllegalArgumentException - if inconsistent arguments are given (parameters out of range)
      • AbsoluteDate

        public AbsoluteDate​(int year,
                            Month month,
                            int day,
                            TimeScale timeScale)
                     throws IllegalArgumentException
        Build an instance from a location in a time scale.

        The hour is set to 00:00:00.000.

        Parameters:
        year - year number (may be 0 or negative for BC years)
        month - month enumerate
        day - day number from 1 to 31
        timeScale - time scale
        Throws:
        IllegalArgumentException - if inconsistent arguments are given (parameters out of range)
      • AbsoluteDate

        public AbsoluteDate​(Date location,
                            TimeScale timeScale)
        Build an instance from a location in a time scale.
        Parameters:
        location - location in the time scale
        timeScale - time scale
      • AbsoluteDate

        public AbsoluteDate​(AbsoluteDate since,
                            double elapsedDuration)
        Build an instance from an elapsed duration since to another instant.

        It is important to note that the elapsed duration is not the difference between two readings on a time scale. As an example, the duration between the two instants leading to the readings 2005-12-31T23:59:59 and 2006-01-01T00:00:00 in the UTC time scale is not 1 second, but a stop watch would have measured an elapsed duration of 2 seconds between these two instances because a leap second was introduced at the end of 2005 in this time scale.

        This constructor is the reverse of the durationFrom(AbsoluteDate) method.

        Parameters:
        since - start instant of the measured duration
        elapsedDuration - physically elapsed duration from the since instant, as measured in a regular time scale
        See Also:
        durationFrom(AbsoluteDate)
      • AbsoluteDate

        public AbsoluteDate​(AbsoluteDate reference,
                            double apparentOffset,
                            TimeScale timeScale)
        Build an instance from an apparent clock offset with respect to another instant in the perspective of a specific time scale.

        It is important to note that the apparent clock offset is the difference between two readings on a time scale and not an elapsed duration. As an example, the apparent clock offset between the two instants leading to the readings 2005-12-31T23:59:59 and 2006-01-01T00:00:00 in the UTC time scale is 1 second, but the elapsed duration is 2 seconds because a leap second has been introduced at the end of 2005 in this time scale.

        This constructor is the reverse of the offsetFrom(AbsoluteDate, TimeScale) method.

        Parameters:
        reference - reference instant
        apparentOffset - apparent clock offset from the reference instant (difference between two readings in the specified time scale)
        timeScale - time scale with respect to which the offset is defined
        See Also:
        offsetFrom(AbsoluteDate, TimeScale)
    • Method Detail

      • parseCCSDSUnsegmentedTimeCode

        public static AbsoluteDate parseCCSDSUnsegmentedTimeCode​(byte preambleField1,
                                                                 byte preambleField2,
                                                                 byte[] timeField,
                                                                 AbsoluteDate agencyDefinedEpoch)
        Build an instance from a CCSDS Unsegmented Time Code (CUC).

        CCSDS Unsegmented Time Code is defined in the blue book: CCSDS Time Code Format (CCSDS 301.0-B-4) published in November 2010

        If the date to be parsed is formatted using version 3 of the standard (CCSDS 301.0-B-3 published in 2002) or if the extension of the preamble field introduced in version 4 of the standard is not used, then the preambleField2 parameter can be set to 0.

        Parameters:
        preambleField1 - first byte of the field specifying the format, often not transmitted in data interfaces, as it is constant for a given data interface
        preambleField2 - second byte of the field specifying the format (added in revision 4 of the CCSDS standard in 2010), often not transmitted in data interfaces, as it is constant for a given data interface (value ignored if presence not signaled in preambleField1)
        timeField - byte array containing the time code
        agencyDefinedEpoch - reference epoch, ignored if the preamble field specifies the CCSDS reference epoch is used (and hence may be null in this case)
        Returns:
        an instance corresponding to the specified date
      • parseCCSDSDaySegmentedTimeCode

        public static AbsoluteDate parseCCSDSDaySegmentedTimeCode​(byte preambleField,
                                                                  byte[] timeField,
                                                                  DateComponents agencyDefinedEpoch)
        Build an instance from a CCSDS Day Segmented Time Code (CDS).

        CCSDS Day Segmented Time Code is defined in the blue book: CCSDS Time Code Format (CCSDS 301.0-B-4) published in November 2010

        Parameters:
        preambleField - field specifying the format, often not transmitted in data interfaces, as it is constant for a given data interface
        timeField - byte array containing the time code
        agencyDefinedEpoch - reference epoch, ignored if the preamble field specifies the CCSDS reference epoch is used (and hence may be null in this case)
        Returns:
        an instance corresponding to the specified date
      • parseCCSDSCalendarSegmentedTimeCode

        public static AbsoluteDate parseCCSDSCalendarSegmentedTimeCode​(byte preambleField,
                                                                       byte[] timeField)
        Build an instance from a CCSDS Calendar Segmented Time Code (CCS).

        CCSDS Calendar Segmented Time Code is defined in the blue book: CCSDS Time Code Format (CCSDS 301.0-B-4) published in November 2010

        Parameters:
        preambleField - field specifying the format, often not transmitted in data interfaces, as it is constant for a given data interface
        timeField - byte array containing the time code
        Returns:
        an instance corresponding to the specified date
      • createJDDate

        public static AbsoluteDate createJDDate​(int jd,
                                                double secondsSinceNoon,
                                                TimeScale timeScale)
        Build an instance corresponding to a Julian Day date.
        Parameters:
        jd - Julian day
        secondsSinceNoon - seconds in the Julian day (BEWARE, Julian days start at noon, so 0.0 is noon)
        timeScale - time scale in which the seconds in day are defined
        Returns:
        a new instant
      • createMJDDate

        public static AbsoluteDate createMJDDate​(int mjd,
                                                 double secondsInDay,
                                                 TimeScale timeScale)
                                          throws OrekitIllegalArgumentException
        Build an instance corresponding to a Modified Julian Day date.
        Parameters:
        mjd - modified Julian day
        secondsInDay - seconds in the day
        timeScale - time scale in which the seconds in day are defined
        Returns:
        a new instant
        Throws:
        OrekitIllegalArgumentException - if seconds number is out of range
      • createGPSDate

        @Deprecated
        public static AbsoluteDate createGPSDate​(int weekNumber,
                                                 double milliInWeek)
        Deprecated.
        Build an instance corresponding to a GPS date.

        GPS dates are provided as a week number starting at GPS epoch and as a number of milliseconds since week start.

        Parameters:
        weekNumber - week number since GPS epoch
        milliInWeek - number of milliseconds since week start
        Returns:
        a new instant
      • createJulianEpoch

        public static AbsoluteDate createJulianEpoch​(double julianEpoch)
        Build an instance corresponding to a Julian Epoch (JE).

        According to Lieske paper: Precession Matrix Based on IAU (1976) System of Astronomical Constants, Astronomy and Astrophysics, vol. 73, no. 3, Mar. 1979, p. 282-284, Julian Epoch is related to Julian Ephemeris Date as:

         JE = 2000.0 + (JED - 2451545.0) / 365.25
         

        This method reverts the formula above and computes an AbsoluteDate from the Julian Epoch.

        Parameters:
        julianEpoch - Julian epoch, like 2000.0 for defining the classical reference J2000.0
        Returns:
        a new instant
        See Also:
        J2000_EPOCH, createBesselianEpoch(double)
      • createBesselianEpoch

        public static AbsoluteDate createBesselianEpoch​(double besselianEpoch)
        Build an instance corresponding to a Besselian Epoch (BE).

        According to Lieske paper: Precession Matrix Based on IAU (1976) System of Astronomical Constants, Astronomy and Astrophysics, vol. 73, no. 3, Mar. 1979, p. 282-284, Besselian Epoch is related to Julian Ephemeris Date as:

         BE = 1900.0 + (JED - 2415020.31352) / 365.242198781
         

        This method reverts the formula above and computes an AbsoluteDate from the Besselian Epoch.

        Parameters:
        besselianEpoch - Besselian epoch, like 1950 for defining the classical reference B1950.0
        Returns:
        a new instant
        See Also:
        createJulianEpoch(double)
      • durationFrom

        public double durationFrom​(AbsoluteDate instant)
        Compute the physically elapsed duration between two instants.

        The returned duration is the number of seconds physically elapsed between the two instants, measured in a regular time scale with respect to surface of the Earth (i.e either the TAI scale, the TT scale or the GPS scale). It is the only method that gives a duration with a physical meaning.

        This method gives the same result (with less computation) as calling offsetFrom(AbsoluteDate, TimeScale) with a second argument set to one of the regular scales cited above.

        This method is the reverse of the AbsoluteDate(AbsoluteDate, double) constructor.

        Parameters:
        instant - instant to subtract from the instance
        Returns:
        offset in seconds between the two instants (positive if the instance is posterior to the argument)
        See Also:
        offsetFrom(AbsoluteDate, TimeScale), AbsoluteDate(AbsoluteDate, double)
      • offsetFrom

        public double offsetFrom​(AbsoluteDate instant,
                                 TimeScale timeScale)
        Compute the apparent clock offset between two instant in the perspective of a specific time scale.

        The offset is the number of seconds counted in the given time scale between the locations of the two instants, with all time scale irregularities removed (i.e. considering all days are exactly 86400 seconds long). This method will give a result that may not have a physical meaning if the time scale is irregular. For example since a leap second was introduced at the end of 2005, the apparent offset between 2005-12-31T23:59:59 and 2006-01-01T00:00:00 is 1 second, but the physical duration of the corresponding time interval as returned by the durationFrom(AbsoluteDate) method is 2 seconds.

        This method is the reverse of the AbsoluteDate(AbsoluteDate, double, TimeScale) constructor.

        Parameters:
        instant - instant to subtract from the instance
        timeScale - time scale with respect to which the offset should be computed
        Returns:
        apparent clock offset in seconds between the two instants (positive if the instance is posterior to the argument)
        See Also:
        durationFrom(AbsoluteDate), AbsoluteDate(AbsoluteDate, double, TimeScale)
      • timeScalesOffset

        public double timeScalesOffset​(TimeScale scale1,
                                       TimeScale scale2)
        Compute the offset between two time scales at the current instant.

        The offset is defined as l₁-l₂ where l₁ is the location of the instant in the scale1 time scale and l₂ is the location of the instant in the scale2 time scale.

        Parameters:
        scale1 - first time scale
        scale2 - second time scale
        Returns:
        offset in seconds between the two time scales at the current instant
      • toDate

        public Date toDate​(TimeScale timeScale)
        Convert the instance to a Java Date.

        Conversion to the Date class induces a loss of precision because the Date class does not provide sub-millisecond information. Java Dates are considered to be locations in some times scales.

        Parameters:
        timeScale - time scale to use
        Returns:
        a Date instance representing the location of the instant in the time scale
      • getComponents

        public DateTimeComponents getComponents​(TimeScale timeScale)
        Split the instance into date/time components.
        Parameters:
        timeScale - time scale to use
        Returns:
        date/time components
      • getComponents

        public DateTimeComponents getComponents​(int minutesFromUTC)
        Split the instance into date/time components for a local time.
        Parameters:
        minutesFromUTC - offset in minutes from UTC (positive Eastwards UTC, negative Westward UTC)
        Returns:
        date/time components
        Since:
        7.2
      • getComponents

        public DateTimeComponents getComponents​(TimeZone timeZone)
        Split the instance into date/time components for a time zone.
        Parameters:
        timeZone - time zone
        Returns:
        date/time components
        Since:
        7.2
      • compareTo

        public int compareTo​(AbsoluteDate date)
        Compare the instance with another date.
        Specified by:
        compareTo in interface Comparable<AbsoluteDate>
        Parameters:
        date - other date to compare the instance to
        Returns:
        a negative integer, zero, or a positive integer as this date is before, simultaneous, or after the specified date.
      • equals

        public boolean equals​(Object date)
        Check if the instance represent the same time as another instance.
        Overrides:
        equals in class Object
        Parameters:
        date - other date
        Returns:
        true if the instance and the other date refer to the same instant
      • hashCode

        public int hashCode()
        Get a hashcode for this date.
        Overrides:
        hashCode in class Object
        Returns:
        hashcode
      • toString

        public String toString()
        Get a String representation of the instant location in UTC time scale.
        Overrides:
        toString in class Object
        Returns:
        a string representation of the instance, in ISO-8601 format with milliseconds accuracy
      • toString

        public String toString​(TimeScale timeScale)
        Get a String representation of the instant location.
        Parameters:
        timeScale - time scale to use
        Returns:
        a string representation of the instance, in ISO-8601 format with milliseconds accuracy
      • toString

        public String toString​(int minutesFromUTC)
        Get a String representation of the instant location for a local time.
        Parameters:
        minutesFromUTC - offset in minutes from UTC (positive Eastwards UTC, negative Westward UTC).
        Returns:
        string representation of the instance, in ISO-8601 format with milliseconds accuracy
        Since:
        7.2
      • toString

        public String toString​(TimeZone timeZone)
        Get a String representation of the instant location for a time zone.
        Parameters:
        timeZone - time zone
        Returns:
        string representation of the instance, in ISO-8601 format with milliseconds accuracy
        Since:
        7.2