Package org.orekit.frames

Class FramesFactory

  • public class FramesFactory
extends Object
    Factory for predefined reference frames.

    FramesFactory Presentation

    Several predefined reference frames are implemented in OREKIT. They are linked together in a tree with the Geocentric Celestial Reference Frame (GCRF) as the root of the tree. This factory is designed to:

    • build the frames tree consistently,
    • avoid rebuilding some frames that may be costly to recreate all the time,
    • set up interpolation/caching features for some frames that may induce costly computation
    • streamline the Earth Orientation Parameters history loading.

    Reference Frames

    The user can retrieve those reference frames using various static methods, the most important ones being: getFrame(Predefined), getGCRF(), getCIRF(IERSConventions, boolean) getTIRF(IERSConventions, boolean), getITRF(IERSConventions, boolean), getITRF(ITRFVersion, IERSConventions, boolean), getEME2000(), getMOD(IERSConventions), getTOD(IERSConventions, boolean), getGTOD(IERSConventions, boolean), getITRFEquinox(IERSConventions, boolean), getTEME() and getVeis1950().

    International Terrestrial Reference Frame

    This frame is the current (as of 2013) reference realization of the International Terrestrial Reference System produced by IERS. It is described in IERS conventions (2010). It replaces the Earth Centered Earth Fixed frame which is the reference frame for GPS satellites.

    This frame is used to define position on solid Earth. It rotates with the Earth and includes the pole motion with respect to Earth crust as provided by IERS Earth Orientation Parameters. Its pole axis is the IERS Reference Pole (IRP).

    Depending on the Earth Orientation Parameters source, different ITRS realization may be returned by getITRF(IERSConventions, boolean), and if EOP are mixed, the ITRF may even jump from one realization to another one. This is not a problem for most users as different ITRS realizations are very close to each other (a few millimeters at Earth surface). If however a specific ITRF version (i.e. an ITRS realization) is needed for very high accuracy, Orekit provides the getITRF(ITRFVersion, IERSConventions, boolean) method to get it and take care of jumps in EOP.

    ITRF can be built using the new non-rotating origin paradigm mandated by IAU 2000 resolution B1.8 and any supported IERS conventions (even IERS 1996 can be used with non-rotating origin paradigm, despite the resolution was not yet adopted at conventions publication time).

    ITRF can also be built using the classical equinox paradigm used prior to IAU 2000 resolution B1.8 and any supported IERS conventions (even IERS 2003 and 2010 can be used with equinox paradigm, despite the resolution is in effect now). The choice of paradigm (non-rotating origin or equinox) and the choice of IERS conventions (i.e. the choice of precession/nutation models) can be made independently by user, Orekit provides all alternatives.

    Intermediate frames

    Orekit also provides all the intermediate frames that are needed to transform between GCRF and ITRF, along the two paths: ITRF/TIRF/CIRF/GCRF for the non-rotating origin paradigm and ITRF/GTOD/TOD/MOD/EME2000/GCRF for the equinox paradigm.

    Earth Orientation Parameters

    This factory also handles loading of Earth Orientation Parameters (EOP) needed for accurate transformations between inertial and Earth fixed frames, using DataProvidersManager features. EOP are IERS conventions dependent, because they correspond to correction to the precession/nutation models. When EOP should be applied, but EOP data are not available, then a null (0.0) correction is used. This can occur when no EOP data is loaded, or when the requested date is beyond the time span of the loaded EOP data. Using a null correction can result in coarse accuracy. To check the time span covered by EOP data use getEOPHistory(IERSConventions, boolean), EOPHistory.getStartDate(), and EOPHistory.getEndDate().

    For more information on configuring the EOP data Orekit uses see https://www.orekit.org/forge/projects/orekit/wiki/Configuration.

    Here is a schematic representation of the predefined reference frames tree: 

                                                                      GCRF
                                                                    |
                                                 |-----------------------------------------------
                                                 |                         |     Frame bias     |
                                                 |                         |                 EME2000
                                                 |                         |                    |
                                                 |                         | Precession effects |
                                                 |                         |                    |
           Bias, Precession and Nutation effects |                        MOD                  MOD  (Mean Equator Of Date)
                                                 |                         |             w/o EOP corrections
                                                 |                         |  Nutation effects  |
    (Celestial Intermediate Reference Frame)   CIRF                        |                    |
                                                 |                        TOD                  TOD  (True Equator Of Date)
                          Earth natural rotation |                         |             w/o EOP corrections
                                                 |-------------            |    Sidereal Time   |
                                                 |            |            |                    |
  (Terrestrial Intermediate Reference Frame)   TIRF         TIRF         GTOD                 GTOD  (Greenwich True Of Date)
                                                 |    w/o tidal effects                  w/o EOP corrections
                                     Pole motion |            |                                 |
                                                 |            |                                 |-------------
                                                 |            |                                 |            |
 (International Terrestrial Reference Frame)   ITRF         ITRF                              ITRF        VEIS1950
                                                 |    w/o tidal effects                   equinox-based
                                                 |            |
                                           other ITRF     other ITRF
                                                      w/o tidal effects

    This is a utility class, so its constructor is private.

    Author:
    Guylaine Prat, Luc Maisonobe, Pascal Parraud

    • Field Detail

      • RAPID_DATA_PREDICTION_COLUMNS_1980_FILENAME

        public static final String RAPID_DATA_PREDICTION_COLUMNS_1980_FILENAME
        Default regular expression for the Rapid Data and Prediction EOP columns files (IAU1980 compatibles).
        See Also:
        Constant Field Values

      • RAPID_DATA_PREDICTION_XML_1980_FILENAME

        public static final String RAPID_DATA_PREDICTION_XML_1980_FILENAME
        Default regular expression for the Rapid Data and Prediction EOP XML files (IAU1980 compatibles).
        See Also:
        Constant Field Values

      • EOPC04_1980_FILENAME

        public static final String EOPC04_1980_FILENAME
        Default regular expression for the EOPC04 files (IAU1980 compatibles).
        See Also:
        Constant Field Values

      • BULLETINB_1980_FILENAME

        public static final String BULLETINB_1980_FILENAME
        Default regular expression for the BulletinB files (IAU1980 compatibles).
        See Also:
        Constant Field Values

      • RAPID_DATA_PREDICITON_COLUMNS_2000_FILENAME

        public static final String RAPID_DATA_PREDICITON_COLUMNS_2000_FILENAME
        Default regular expression for the Rapid Data and Prediction EOP columns files (IAU2000 compatibles).
        See Also:
        Constant Field Values

      • RAPID_DATA_PREDICITON_XML_2000_FILENAME

        public static final String RAPID_DATA_PREDICITON_XML_2000_FILENAME
        Default regular expression for the Rapid Data and Prediction EOP XML files (IAU2000 compatibles).
        See Also:
        Constant Field Values

      • EOPC04_2000_FILENAME

        public static final String EOPC04_2000_FILENAME
        Default regular expression for the EOPC04 files (IAU2000 compatibles).
        See Also:
        Constant Field Values

      • BULLETINB_2000_FILENAME

        public static final String BULLETINB_2000_FILENAME
        Default regular expression for the BulletinB files (IAU2000 compatibles).
        See Also:
        Constant Field Values

      • BULLETINA_FILENAME

        public static final String BULLETINA_FILENAME
        Default regular expression for the BulletinA files (IAU1980 and IAU2000 compatibles).
        See Also:
        Constant Field Values

    • Method Detail

      • addDefaultEOP1980HistoryLoaders

        public static void addDefaultEOP1980HistoryLoaders​(String rapidDataColumnsSupportedNames,
                                                   String rapidDataXMLSupportedNames,
                                                   String eopC04SupportedNames,
                                                   String bulletinBSupportedNames,
                                                   String bulletinASupportedNames)
        Add the default loaders EOP history (IAU 1980 precession/nutation).

        The default loaders look for IERS EOP C04 and bulletins B files. They correspond to IERS 1996 conventions.

        Parameters:
        rapidDataColumnsSupportedNames - regular expression for supported rapid data columns EOP files names (may be null if the default IERS file names are used)
        rapidDataXMLSupportedNames - regular expression for supported rapid data XML EOP files names (may be null if the default IERS file names are used)
        eopC04SupportedNames - regular expression for supported EOP C04 files names (may be null if the default IERS file names are used)
        bulletinBSupportedNames - regular expression for supported bulletin B files names (may be null if the default IERS file names are used)
        bulletinASupportedNames - regular expression for supported bulletin A files names (may be null if the default IERS file names are used)
        See Also:
        IERS EOP C04 files, addEOPHistoryLoader(IERSConventions, EOPHistoryLoader), clearEOPHistoryLoaders(), addDefaultEOP2000HistoryLoaders(String, String, String, String, String)

      • addDefaultEOP2000HistoryLoaders

        public static void addDefaultEOP2000HistoryLoaders​(String rapidDataColumnsSupportedNames,
                                                   String rapidDataXMLSupportedNames,
                                                   String eopC04SupportedNames,
                                                   String bulletinBSupportedNames,
                                                   String bulletinASupportedNames)
        Add the default loaders for EOP history (IAU 2000/2006 precession/nutation).

        The default loaders look for IERS EOP C04 and bulletins B files. They correspond to both IERS 2003 and IERS 2010 conventions.

        Parameters:
        rapidDataColumnsSupportedNames - regular expression for supported rapid data columns EOP files names (may be null if the default IERS file names are used)
        rapidDataXMLSupportedNames - regular expression for supported rapid data XML EOP files names (may be null if the default IERS file names are used)
        eopC04SupportedNames - regular expression for supported EOP C04 files names (may be null if the default IERS file names are used)
        bulletinBSupportedNames - regular expression for supported bulletin B files names (may be null if the default IERS file names are used)
        bulletinASupportedNames - regular expression for supported bulletin A files names (may be null if the default IERS file names are used)
        See Also:
        IERS EOP C04 files, addEOPHistoryLoader(IERSConventions, EOPHistoryLoader), clearEOPHistoryLoaders(), addDefaultEOP1980HistoryLoaders(String, String, String, String, String)

      • setEOPContinuityThreshold

        public static void setEOPContinuityThreshold​(double threshold)
        Set the threshold to check EOP continuity.

        The default threshold (used if this method is never called) is 5 Julian days. If after loading EOP entries some holes between entries exceed this threshold, an exception will be triggered.

        One case when calling this method is really useful is for applications that use a single Bulletin A, as these bulletins have a roughly one month wide hole for the first bulletin of each month, which contains older final data in addition to the rapid data and the predicted data.

        Parameters:
        threshold - threshold to use for checking EOP continuity (in seconds)

      • getFrame

        public static Frame getFrame​(Predefined factoryKey)
        Get one of the predefined frames.
        Parameters:
        factoryKey - key of the frame within the factory
        Returns:
        the predefined frame

      • getGCRF

        public static Frame getGCRF()
        Get the unique GCRF frame.

        The GCRF frame is the root frame in the frame tree.

        Returns:
        the unique instance of the GCRF frame

      • getICRF

        public static Frame getICRF()
        Get the unique ICRF frame.

        The ICRF frame is centered at solar system barycenter and aligned with GCRF.

        Returns:
        the unique instance of the ICRF frame

      • getEcliptic

        public static Frame getEcliptic​(IERSConventions conventions)
        Get the ecliptic frame. The IAU defines the ecliptic as "the plane perpendicular to the mean heliocentric orbital angular momentum vector of the Earth-Moon barycentre in the BCRS (IAU 2006 Resolution B1)." The +z axis is aligned with the angular momentum vector, and the +x axis is aligned with +x axis of MOD.

        This implementation agrees with the JPL 406 ephemerides to within 0.5 arc seconds.

        Parameters:
        conventions - IERS conventions to apply
        Returns:
        the selected reference frame singleton.

      • getEME2000

        public static FactoryManagedFrame getEME2000()
        Get the unique EME2000 frame.

        The EME2000 frame is also called the J2000 frame. The former denomination is preferred in Orekit.

        Returns:
        the unique instance of the EME2000 frame

      • getTIRF

        public static FactoryManagedFrame getTIRF​(IERSConventions conventions)
        Get the TIRF reference frame, ignoring tidal effects.
        Parameters:
        conventions - IERS conventions to apply
        Returns:
        the selected reference frame singleton. library cannot be read.

      • getITRF

        public static VersionedITRF getITRF​(ITRFVersion version,
                                    IERSConventions conventions,
                                    boolean simpleEOP)
        Get an specific International Terrestrial Reference Frame.

        Note that if a specific version of ITRF is required, then simpleEOP should most probably be set to false, as ignoring tidal effects has an effect of the same order of magnitude as the differences between the various ITRF versions.

        Parameters:
        version - ITRF version
        conventions - IERS conventions to apply
        simpleEOP - if true, tidal effects are ignored when interpolating EOP
        Returns:
        the selected reference frame singleton.
        Since:
        9.2

      • getTIRF

        public static FactoryManagedFrame getTIRF​(IERSConventions conventions,
                                          boolean simpleEOP)
        Get the TIRF reference frame.
        Parameters:
        conventions - IERS conventions to apply
        simpleEOP - if true, tidal effects are ignored when interpolating EOP
        Returns:
        the selected reference frame singleton.
        Since:
        6.1

      • getCIRF

        public static FactoryManagedFrame getCIRF​(IERSConventions conventions,
                                          boolean simpleEOP)
        Get the CIRF2000 reference frame.
        Parameters:
        conventions - IERS conventions to apply
        simpleEOP - if true, tidal effects are ignored when interpolating EOP
        Returns:
        the selected reference frame singleton.

      • getVeis1950

        public static FactoryManagedFrame getVeis1950()
        Get the VEIS 1950 reference frame.

        Its parent frame is the GTOD frame with IERS 1996 conventions without EOP corrections.

        Returns:
        the selected reference frame singleton.

      • getITRFEquinox

        public static FactoryManagedFrame getITRFEquinox​(IERSConventions conventions,
                                                 boolean simpleEOP)
        Get the equinox-based ITRF reference frame.
        Parameters:
        conventions - IERS conventions to apply
        simpleEOP - if true, tidal effects are ignored when interpolating EOP
        Returns:
        the selected reference frame singleton.
        Since:
        6.1

      • getGTOD

        public static FactoryManagedFrame getGTOD​(boolean applyEOPCorr)
        Get the GTOD reference frame.

        The applyEOPCorr parameter is available mainly for testing purposes or for consistency with legacy software that don't handle EOP correction parameters. Beware that setting this parameter to false leads to crude accuracy (order of magnitudes for errors might be above 250m in LEO and 1400m in GEO). For this reason, setting this parameter to false is restricted to IERS 1996 conventions, and hence the IERS conventions cannot be freely chosen here.

        Parameters:
        applyEOPCorr - if true, EOP corrections are applied (here, dut1 and lod)
        Returns:
        the selected reference frame singleton.

      • getGTOD

        public static FactoryManagedFrame getGTOD​(IERSConventions conventions,
                                          boolean simpleEOP)
        Get the GTOD reference frame.
        Parameters:
        conventions - IERS conventions to apply
        simpleEOP - if true, tidal effects are ignored when interpolating EOP
        Returns:
        the selected reference frame singleton.

      • getTOD

        public static FactoryManagedFrame getTOD​(boolean applyEOPCorr)
        Get the TOD reference frame.

        The applyEOPCorr parameter is available mainly for testing purposes or for consistency with legacy software that don't handle EOP correction parameters. Beware that setting this parameter to false leads to crude accuracy (order of magnitudes for errors might be above 1m in LEO and 10m in GEO). For this reason, setting this parameter to false is restricted to IERS 1996 conventions, and hence the IERS conventions cannot be freely chosen here.

        Parameters:
        applyEOPCorr - if true, EOP corrections are applied (here, nutation)
        Returns:
        the selected reference frame singleton.

      • getTOD

        public static FactoryManagedFrame getTOD​(IERSConventions conventions,
                                         boolean simpleEOP)
        Get the TOD reference frame.
        Parameters:
        conventions - IERS conventions to apply
        simpleEOP - if true, tidal effects are ignored when interpolating EOP
        Returns:
        the selected reference frame singleton.

      • getMOD

        public static FactoryManagedFrame getMOD​(boolean applyEOPCorr)
        Get the MOD reference frame.

        The applyEOPCorr parameter is available mainly for testing purposes or for consistency with legacy software that don't handle EOP correction parameters. Beware that setting this parameter to false leads to crude accuracy (order of magnitudes for errors might be above 1m in LEO and 10m in GEO). For this reason, setting this parameter to false is restricted to IERS 1996 conventions, and hence the IERS conventions cannot be freely chosen here.

        Parameters:
        applyEOPCorr - if true, EOP corrections are applied (EME2000/GCRF bias compensation)
        Returns:
        the selected reference frame singleton.

      • getMOD

        public static FactoryManagedFrame getMOD​(IERSConventions conventions)
        Get the MOD reference frame.
        Parameters:
        conventions - IERS conventions to apply
        Returns:
        the selected reference frame singleton.

      • getTEME

        public static FactoryManagedFrame getTEME()
        Get the TEME reference frame.

        The TEME frame is used for the SGP4 model in TLE propagation. This frame has no official definition and there are some ambiguities about whether it should be used as "of date" or "of epoch". This frame should therefore be used only for TLE propagation and not for anything else, as recommended by the CCSDS Orbit Data Message blue book.

        Returns:
        the selected reference frame singleton.

      • getNonInterpolatingTransform

        public static Transform getNonInterpolatingTransform​(Frame from,
                                                     Frame to,
                                                     AbsoluteDate date)
        Get the transform between two frames, suppressing all interpolation.

        This method is similar to Frame.getTransformTo(Frame, AbsoluteDate) except it removes the performance enhancing interpolation features that are added by the factory to some frames, in order to focus on accuracy. The interpolation features are intended to save processing time by avoiding doing some lengthy computation like nutation evaluation at each time step and caching some results. This method can be used to avoid this, when very high accuracy is desired, or for testing purposes. It should be used with care, as doing the full computation is really costly for some frames.

        Parameters:
        from - frame from which transformation starts
        to - frame to which transformation ends
        date - date of the transform
        Returns:
        transform between the two frames, avoiding interpolation

      • getNonInterpolatingTransform

        public static <T extends org.hipparchus.RealFieldElement<T>> FieldTransform<T> getNonInterpolatingTransform​(Frame from,
                                                                                                            Frame to,
                                                                                                            FieldAbsoluteDate<T> date)
        Get the transform between two frames, suppressing all interpolation.

        This method is similar to Frame.getTransformTo(Frame, AbsoluteDate) except it removes the performance enhancing interpolation features that are added by the factory to some frames, in order to focus on accuracy. The interpolation features are intended to save processing time by avoiding doing some lengthy computation like nutation evaluation at each time step and caching some results. This method can be used to avoid this, when very high accuracy is desired, or for testing purposes. It should be used with care, as doing the full computation is really costly for some frames.

        Type Parameters:
        T - type of the field elements
        Parameters:
        from - frame from which transformation starts
        to - frame to which transformation ends
        date - date of the transform
        Returns:
        transform between the two frames, avoiding interpolation
        Since:
        9.0

      • findEOP

        public static EOPHistory findEOP​(Frame start)
        Retrieve EOP from a frame hierarchy.

        The frame hierarchy tree is walked from specified frame up to root goind though parent frames, and the providers are checked to see if they reference EOP history.the first EOP history found is returned.

        Parameters:
        start - frame from which to start search, will typically be some Earth related frame, like a topocentric frame or an ITRF frame
        Returns:
        EOP history found while walking the frames tree, or null if no EOP history is found
        Since:
        9.1