org.orekit.frames

Class FramesFactory

java.lang.Object

org.orekit.frames.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), 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 data. Its pole axis is the IERS Reference Pole (IRP).

Previous realizations of the ITRS are available and linked together using Helmert transformations. Parameters for all ITRS realizations since 1988 are available from the ITRF site ftp://itrf.ensg.ign.fr/pub/itrf/ITRF.TP). Orekit provides a utility method to build simply several of them and link them together.

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 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 Summary

Fields

Modifier and Type	Field and Description
static String	BULLETINA_FILENAME Default regular expression for the BulletinA files (IAU1980 and IAU2000 compatibles).
static String	BULLETINB_1980_FILENAME Default regular expression for the BulletinB files (IAU1980 compatibles).
static String	BULLETINB_2000_FILENAME Default regular expression for the BulletinB files (IAU2000 compatibles).
static String	EOPC04_1980_FILENAME Default regular expression for the EOPC04 files (IAU1980 compatibles).
static String	EOPC04_2000_FILENAME Default regular expression for the EOPC04 files (IAU2000 compatibles).
static String	RAPID_DATA_PREDICITON_COLUMNS_2000_FILENAME Default regular expression for the Rapid Data and Prediction EOP columns files (IAU2000 compatibles).
static String	RAPID_DATA_PREDICITON_XML_2000_FILENAME Default regular expression for the Rapid Data and Prediction EOP XML files (IAU2000 compatibles).
static String	RAPID_DATA_PREDICTION_COLUMNS_1980_FILENAME Default regular expression for the Rapid Data and Prediction EOP columns files (IAU1980 compatibles).
static String	RAPID_DATA_PREDICTION_XML_1980_FILENAME Default regular expression for the Rapid Data and Prediction EOP XML files (IAU1980 compatibles).

Method Summary

Methods

Modifier and Type	Method and Description
static void	addDefaultEOP1980HistoryLoaders(String rapidDataColumnsSupportedNames, String rapidDataXMLSupportedNames, String eopC04SupportedNames, String bulletinBSupportedNames, String bulletinASupportedNames) Add the default loaders EOP history (IAU 1980 precession/nutation).
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).
static void	addEOPHistoryLoader(IERSConventions conventions, EOPHistoryLoader loader) Add a loader for Earth Orientation Parameters history.
static void	clearEOPHistoryLoaders() Clear loaders for Earth Orientation Parameters history.
static FactoryManagedFrame	getCIRF(IERSConventions conventions, boolean simpleEOP) Get the CIRF2000 reference frame.
static Frame	getEcliptic(IERSConventions conventions) Get the ecliptic frame.
static FactoryManagedFrame	getEME2000() Get the unique EME2000 frame.
static EOPHistory	getEOPHistory(IERSConventions conventions, boolean simpleEOP) Get Earth Orientation Parameters history.
static Frame	getFrame(Predefined factoryKey) Get one of the predefined frames.
static Frame	getGCRF() Get the unique GCRF frame.
static FactoryManagedFrame	getGTOD(boolean applyEOPCorr) Get the GTOD reference frame.
static FactoryManagedFrame	getGTOD(IERSConventions conventions, boolean simpleEOP) Get the GTOD reference frame.
static Frame	getICRF() Get the unique ICRF frame.
static FactoryManagedFrame	getITRF(IERSConventions conventions, boolean simpleEOP) Get the ITRF2008 reference frame, using IERS 2010 conventions.
static FactoryManagedFrame	getITRFEquinox(IERSConventions conventions, boolean simpleEOP) Get the equinox-based ITRF reference frame.
static FactoryManagedFrame	getMOD(boolean applyEOPCorr) Get the MOD reference frame.
static FactoryManagedFrame	getMOD(IERSConventions conventions) Get the MOD reference frame.
static Transform	getNonInterpolatingTransform(Frame from, Frame to, AbsoluteDate date) Get the transform between two frames, suppressing all interpolation.
static FactoryManagedFrame	getTEME() Get the TEME reference frame.
static FactoryManagedFrame	getTIRF(IERSConventions conventions) Get the TIRF reference frame, ignoring tidal effects.
static FactoryManagedFrame	getTIRF(IERSConventions conventions, boolean simpleEOP) Get the TIRF reference frame.
static FactoryManagedFrame	getTOD(boolean applyEOPCorr) Get the TOD reference frame.
static FactoryManagedFrame	getTOD(IERSConventions conventions, boolean simpleEOP) Get the TOD reference frame.
static FactoryManagedFrame	getVeis1950() Get the VEIS 1950 reference frame.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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 08 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 08 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 08 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 08 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 08 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 08 C04 files, addEOPHistoryLoader(IERSConventions, EOPHistoryLoader), clearEOPHistoryLoaders(), addDefaultEOP1980HistoryLoaders(String, String, String, String, String)

addEOPHistoryLoader

public static void addEOPHistoryLoader(IERSConventions conventions,
                       EOPHistoryLoader loader)

Add a loader for Earth Orientation Parameters history.

Parameters:

conventions - IERS conventions to which EOP history applies

loader - custom loader to add for the EOP history

See Also:

addDefaultEOP1980HistoryLoaders(String, String, String, String, String), clearEOPHistoryLoaders()

clearEOPHistoryLoaders

public static void clearEOPHistoryLoaders()

Clear loaders for Earth Orientation Parameters history.

See Also:

addEOPHistoryLoader(IERSConventions, EOPHistoryLoader), addDefaultEOP1980HistoryLoaders(String, String, String, String, String)

getEOPHistory

public static EOPHistory getEOPHistory(IERSConventions conventions,
                       boolean simpleEOP)
                                throws OrekitException

Get Earth Orientation Parameters history.

If no EOPHistoryLoader has been added by calling addEOPHistoryLoader or if clearEOPHistoryLoaders has been called afterwards, the addDefaultEOP1980HistoryLoaders(String, String, String, String, String) and addDefaultEOP2000HistoryLoaders(String, String, String, String, String) methods will be called automatically with supported file names parameters all set to null, in order to get the default loaders configuration.

Parameters:

conventions - conventions for which EOP history is requested

simpleEOP - if true, tidal effects are ignored when interpolating EOP

Returns:

Earth Orientation Parameters history

Throws:

OrekitException - if the data cannot be loaded

getFrame

public static Frame getFrame(Predefined factoryKey)
                      throws OrekitException

Get one of the predefined frames.

Parameters:

factoryKey - key of the frame within the factory

Returns:

the predefined frame

Throws:

OrekitException - if frame cannot be built due to missing data

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()
                     throws OrekitException

Get the unique ICRF frame.

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

Returns:

the unique instance of the ICRF frame

Throws:

OrekitException - if solar system ephemerides cannot be loaded

getEcliptic

public static Frame getEcliptic(IERSConventions conventions)
                         throws OrekitException

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.

Throws:

OrekitException - if data embedded in the library cannot be read

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

getITRF

public static FactoryManagedFrame getITRF(IERSConventions conventions,
                          boolean simpleEOP)
                                   throws OrekitException

Get the ITRF2008 reference frame, using IERS 2010 conventions.

Parameters:

conventions - IERS conventions to apply

simpleEOP - if true, tidal effects are ignored when interpolating EOP

Returns:

the selected reference frame singleton.

Throws:

OrekitException - if data embedded in the library cannot be read

Since:

6.1

getTIRF

public static FactoryManagedFrame getTIRF(IERSConventions conventions)
                                   throws OrekitException

Get the TIRF reference frame, ignoring tidal effects.

Parameters:

conventions - IERS conventions to apply

Returns:

the selected reference frame singleton.

Throws:

OrekitException - if the precession-nutation model data embedded in the library cannot be read.

getTIRF

public static FactoryManagedFrame getTIRF(IERSConventions conventions,
                          boolean simpleEOP)
                                   throws OrekitException

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.

Throws:

OrekitException - if the precession-nutation model data embedded in the library cannot be read.

Since:

6.1

getCIRF

public static FactoryManagedFrame getCIRF(IERSConventions conventions,
                          boolean simpleEOP)
                                   throws OrekitException

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.

Throws:

OrekitException - if the precession-nutation model data embedded in the library cannot be read.

getVeis1950

public static FactoryManagedFrame getVeis1950()
                                       throws OrekitException

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.

Throws:

OrekitException - if data embedded in the library cannot be read

getITRFEquinox

public static FactoryManagedFrame getITRFEquinox(IERSConventions conventions,
                                 boolean simpleEOP)
                                          throws OrekitException

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.

Throws:

OrekitException - if data embedded in the library cannot be read

Since:

6.1

getGTOD

public static FactoryManagedFrame getGTOD(boolean applyEOPCorr)
                                   throws OrekitException

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.

Throws:

OrekitException - if data embedded in the library cannot be read

getGTOD

public static FactoryManagedFrame getGTOD(IERSConventions conventions,
                          boolean simpleEOP)
                                   throws OrekitException

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.

Throws:

OrekitException - if data embedded in the library cannot be read

getTOD

public static FactoryManagedFrame getTOD(boolean applyEOPCorr)
                                  throws OrekitException

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.

Throws:

OrekitException - if data embedded in the library cannot be read

getTOD

public static FactoryManagedFrame getTOD(IERSConventions conventions,
                         boolean simpleEOP)
                                  throws OrekitException

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.

Throws:

OrekitException - if data embedded in the library cannot be read

getMOD

public static FactoryManagedFrame getMOD(boolean applyEOPCorr)
                                  throws OrekitException

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.

Throws:

OrekitException - if data embedded in the library cannot be read

getMOD

public static FactoryManagedFrame getMOD(IERSConventions conventions)
                                  throws OrekitException

Get the MOD reference frame.

Parameters:

conventions - IERS conventions to apply

Returns:

the selected reference frame singleton.

Throws:

OrekitException - if data embedded in the library cannot be read

getTEME

public static FactoryManagedFrame getTEME()
                                   throws OrekitException

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.

Throws:

OrekitException - if data embedded in the library cannot be read

getNonInterpolatingTransform

public static Transform getNonInterpolatingTransform(Frame from,
                                     Frame to,
                                     AbsoluteDate date)
                                              throws OrekitException

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

Throws:

OrekitException - if transform cannot be computed at this date