FramesFactory.java

  1. /* Copyright 2002-2017 CS Systèmes d'Information
  2.  * Licensed to CS Systèmes d'Information (CS) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * CS licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *   http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.orekit.frames;

  19. import java.util.ArrayList;
  20. import java.util.HashMap;
  21. import java.util.List;
  22. import java.util.Map;
  23. import java.util.SortedSet;
  24. import java.util.TreeSet;

  26. import org.hipparchus.RealFieldElement;
  27. import org.orekit.bodies.CelestialBodyFactory;
  28. import org.orekit.errors.OrekitException;
  29. import org.orekit.errors.OrekitInternalError;
  30. import org.orekit.time.AbsoluteDate;
  31. import org.orekit.time.ChronologicalComparator;
  32. import org.orekit.time.FieldAbsoluteDate;
  33. import org.orekit.utils.AngularDerivativesFilter;
  34. import org.orekit.utils.CartesianDerivativesFilter;
  35. import org.orekit.utils.Constants;
  36. import org.orekit.utils.IERSConventions;
  37. import org.orekit.utils.OrekitConfiguration;


  40. /** Factory for predefined reference frames.
  41.  *
  42.  * <h1> FramesFactory Presentation </h1>
  43.  * <p>
  44.  * Several predefined reference {@link Frame frames} are implemented in OREKIT.
  45.  * They are linked together in a tree with the <i>Geocentric
  46.  * Celestial Reference Frame</i> (GCRF) as the root of the tree.
  47.  * This factory is designed to:
  48.  * </p>
  49.  * <ul>
  50.  *   <li>build the frames tree consistently,</li>
  51.  *   <li>avoid rebuilding some frames that may be costly to recreate all the time,</li>
  52.  *   <li>set up interpolation/caching features for some frames that may induce costly computation</li>
  53.  *   <li>streamline the {@link EOPHistory Earth Orientation Parameters} history loading.</li>
  54.  * </ul>
  55.  * <h2> Reference Frames </h2>
  56.  * <p>
  57.  * The user can retrieve those reference frames using various static methods, the most
  58.  * important ones being: {@link #getFrame(Predefined)}, {@link #getGCRF()},
  59.  * {@link #getCIRF(IERSConventions, boolean)} {@link #getTIRF(IERSConventions, boolean)},
  60.  * {@link #getITRF(IERSConventions, boolean)}, {@link #getEME2000()},
  61.  * {@link #getMOD(IERSConventions)}, {@link #getTOD(IERSConventions, boolean)},
  62.  * {@link #getGTOD(IERSConventions, boolean)}, {@link #getITRFEquinox(IERSConventions, boolean)},
  63.  * {@link #getTEME()} and {@link #getVeis1950()}.
  64.  * </p>
  65.  * <h2> International Terrestrial Reference Frame</h2>
  66.  * <p>
  67.  * This frame is the current (as of 2013) reference realization of
  68.  * the International Terrestrial Reference System produced by IERS.
  69.  * It is described in <a href="ftp://tai.bipm.org/iers/conv2010/tn36.pdf">
  70.  * IERS conventions (2010)</a>. It replaces the Earth Centered Earth Fixed
  71.  * frame which is the reference frame for GPS satellites.
  72.  * </p>
  73.  * <p>
  74.  * This frame is used to define position on solid Earth. It rotates with
  75.  * the Earth and includes the pole motion with respect to Earth crust as
  76.  * provided by {@link org.orekit.data.DataProvidersManager IERS data}.
  77.  * Its pole axis is the IERS Reference Pole (IRP).
  78.  * </p>
  79.  * <p>
  80.  * Previous realizations of the ITRS are available and linked together using
  81.  * {@link HelmertTransformation Helmert transformations}. Parameters for all
  82.  * ITRS realizations since 1988 are available from the ITRF site <a
  83.  * href="ftp://itrf.ensg.ign.fr/pub/itrf/ITRF.TP"> ftp://itrf.ensg.ign.fr/pub/itrf/ITRF.TP</a>).
  84.  * Orekit provides a {@link HelmertTransformation.Predefined#createTransformedITRF(Frame,
  85.  * String) utility} method to build simply several of them and link them together.
  86.  * </p>
  87.  * <p>
  88.  * ITRF can be built using the new non-rotating origin paradigm
  89.  * mandated by IAU 2000 resolution B1.8 and any supported {@link IERSConventions
  90.  * IERS conventions} (even IERS 1996 can be used with non-rotating origin paradigm,
  91.  * despite the resolution was not yet adopted at conventions publication time.
  92.  * </p>
  93.  * <p>
  94.  * ITRF can also be built using the classical equinox paradigm used prior to IAU 2000
  95.  * resolution B1.8 and any supported {@link IERSConventions IERS conventions} (even
  96.  * IERS 2003 and 2010 can be used with equinox paradigm, despite the resolution is
  97.  * in effect now). The choice of paradigm (non-rotating origin or equinox) and the
  98.  * choice of IERS conventions (i.e. the choice of precession/nutation models) can
  99.  * be made independently by user, Orekit provides all alternatives.
  100.  * </p>
  101.  * <h2>Intermediate frames</h2>
  102.  * <p>
  103.  * Orekit also provides all the intermediate frames that are needed to transform
  104.  * between GCRF and ITRF, along the two paths: ITRF/TIRF/CIRF/GCRF for the
  105.  * non-rotating origin paradigm and ITRF/GTOD/TOD/MOD/EME2000/GCRF for the equinox
  106.  * paradigm.
  107.  * </p>
  108.  * <h2> Earth Orientation Parameters </h2>
  109.  * <p>
  110.  * This factory also handles loading of Earth Orientation Parameters (EOP) needed
  111.  * for accurate transformations between inertial and Earth fixed frames, using
  112.  * {@link org.orekit.data.DataProvidersManager} features. EOP are IERS conventions
  113.  * dependent, because they correspond to correction to the precession/nutation
  114.  * models. When EOP should be applied, but EOP data are not available, then a null
  115.  * (0.0) correction is used. This can occur when no EOP data is loaded, or when the
  116.  * requested date is beyond the time span of the loaded EOP data. Using a null
  117.  * correction can result in coarse accuracy. To check the time span covered by EOP data use
  118.  * {@link #getEOPHistory(IERSConventions, boolean)}, {@link EOPHistory#getStartDate()},
  119.  * and {@link EOPHistory#getEndDate()}.
  120.  * <p>
  121.  * For more on configuring the EOP data Orekit uses see
  122.  * <a href="https://www.orekit.org/forge/projects/orekit/wiki/Configuration">
  123.  * https://www.orekit.org/forge/projects/orekit/wiki/Configuration</a>.
  124.  * <p>
  125.  * Here is a schematic representation of the predefined reference frames tree:
  126.  * </p>
  127.  * <pre>
  128.  *                                                                  GCRF
  129.  *                                                                    |
  130.  *                                                 |-----------------------------------------------
  131.  *                                                 |                         |     Frame bias     |
  132.  *                                                 |                         |                 EME2000
  133.  *                                                 |                         |                    |
  134.  *                                                 |                         | Precession effects |
  135.  *                                                 |                         |                    |
  136.  *           Bias, Precession and Nutation effects |                        MOD                  MOD  (Mean Equator Of Date)
  137.  *                                                 |                         |             w/o EOP corrections
  138.  *                                                 |                         |  Nutation effects  |
  139.  *    (Celestial Intermediate Reference Frame)   CIRF                        |                    |
  140.  *                                                 |                        TOD                  TOD  (True Equator Of Date)
  141.  *                          Earth natural rotation |                         |             w/o EOP corrections
  142.  *                                                 |-------------            |    Sidereal Time   |
  143.  *                                                 |            |            |                    |
  144.  *  (Terrestrial Intermediate Reference Frame)   TIRF         TIRF         GTOD                 GTOD  (Greenwich True Of Date)
  145.  *                                                 |    w/o tidal effects                  w/o EOP corrections
  146.  *                                     Pole motion |            |                                 |
  147.  *                                                 |            |                                 |-------------
  148.  *                                                 |            |                                 |            |
  149.  * (International Terrestrial Reference Frame)   ITRF         ITRF                              ITRF        VEIS1950
  150.  *                                                 |    w/o tidal effects                   equinox-based
  151.  *                                                 |            |
  152.  *                                           other ITRF     other ITRF
  153.  *                                                      w/o tidal effects
  154.  * </pre>
  155.  * <p>
  156.  * This is a utility class, so its constructor is private.
  157.  * </p>
  158.  * @author Guylaine Prat
  159.  * @author Luc Maisonobe
  160.  * @author Pascal Parraud
  161.  */
  162. public class FramesFactory {

  164.     /** Default regular expression for the Rapid Data and Prediction EOP columns files (IAU1980 compatibles). */
  165.     public static final String RAPID_DATA_PREDICTION_COLUMNS_1980_FILENAME = "^finals\\.[^.]*$";

  167.     /** Default regular expression for the Rapid Data and Prediction EOP XML files (IAU1980 compatibles). */
  168.     public static final String RAPID_DATA_PREDICTION_XML_1980_FILENAME = "^finals\\..*\\.xml$";

  170.     /** Default regular expression for the EOPC04 files (IAU1980 compatibles). */
  171.     public static final String EOPC04_1980_FILENAME = "^eopc04_\\d\\d\\.(\\d\\d)$";

  173.     /** Default regular expression for the BulletinB files (IAU1980 compatibles). */
  174.     public static final String BULLETINB_1980_FILENAME = "^bulletinb(_IAU1980)?((-\\d\\d\\d\\.txt)|(\\.\\d\\d\\d))$";

  176.     /** Default regular expression for the Rapid Data and Prediction EOP columns files (IAU2000 compatibles). */
  177.     public static final String RAPID_DATA_PREDICITON_COLUMNS_2000_FILENAME = "^finals2000A\\.[^.]*$";

  179.     /** Default regular expression for the Rapid Data and Prediction EOP XML files (IAU2000 compatibles). */
  180.     public static final String RAPID_DATA_PREDICITON_XML_2000_FILENAME = "^finals2000A\\..*\\.xml$";

  182.     /** Default regular expression for the EOPC04 files (IAU2000 compatibles). */
  183.     public static final String EOPC04_2000_FILENAME = "^eopc04_\\d\\d_IAU2000\\.(\\d\\d)$";

  185.     /** Default regular expression for the BulletinB files (IAU2000 compatibles). */
  186.     public static final String BULLETINB_2000_FILENAME = "^bulletinb(_IAU2000)?((-\\d\\d\\d\\.txt)|(\\.\\d\\d\\d))$";

  188.     /** Default regular expression for the BulletinA files (IAU1980 and IAU2000 compatibles). */
  189.     public static final String BULLETINA_FILENAME = "^bulletina-[ivxlcdm]+-\\d\\d\\d\\.txt$";

  191.     /** Predefined frames. */
  192.     private static transient Map<Predefined, FactoryManagedFrame> FRAMES =
  193.         new HashMap<Predefined, FactoryManagedFrame>();

  195.     /** Loaders for Earth Orientation parameters. */
  196.     private static final Map<IERSConventions, List<EOPHistoryLoader>> EOP_HISTORY_LOADERS =
  197.         new HashMap<IERSConventions, List<EOPHistoryLoader>>();

  199.     /** Threshold for EOP continuity. */
  200.     private static double EOP_CONTINUITY_THRESHOLD = 5 * Constants.JULIAN_DAY;

  202.     /** Private constructor.
  203.      * <p>This class is a utility class, it should neither have a public
  204.      * nor a default constructor. This private constructor prevents
  205.      * the compiler from generating one automatically.</p>
  206.      */
  207.     private FramesFactory() {
  208.     }

  210.     /** Add the default loaders EOP history (IAU 1980 precession/nutation).
  211.      * <p>
  212.      * The default loaders look for IERS EOP C04 and bulletins B files. They
  213.      * correspond to {@link IERSConventions#IERS_1996 IERS 1996} conventions.
  214.      * </p>
  215.      * @param rapidDataColumnsSupportedNames regular expression for supported
  216.      * rapid data columns EOP files names
  217.      * (may be null if the default IERS file names are used)
  218.      * @param rapidDataXMLSupportedNames regular expression for supported
  219.      * rapid data XML EOP files names
  220.      * (may be null if the default IERS file names are used)
  221.      * @param eopC04SupportedNames regular expression for supported EOP C04 files names
  222.      * (may be null if the default IERS file names are used)
  223.      * @param bulletinBSupportedNames regular expression for supported bulletin B files names
  224.      * (may be null if the default IERS file names are used)
  225.      * @param bulletinASupportedNames regular expression for supported bulletin A files names
  226.      * (may be null if the default IERS file names are used)
  227.      * @see <a href="http://hpiers.obspm.fr/eoppc/eop/eopc04/">IERS EOP C04 files</a>
  228.      * @see #addEOPHistoryLoader(IERSConventions, EOPHistoryLoader)
  229.      * @see #clearEOPHistoryLoaders()
  230.      * @see #addDefaultEOP2000HistoryLoaders(String, String, String, String, String)
  231.      */
  232.     public static void addDefaultEOP1980HistoryLoaders(final String rapidDataColumnsSupportedNames,
  233.                                                        final String rapidDataXMLSupportedNames,
  234.                                                        final String eopC04SupportedNames,
  235.                                                        final String bulletinBSupportedNames,
  236.                                                        final String bulletinASupportedNames) {
  237.         final String rapidColNames =
  238.                 (rapidDataColumnsSupportedNames == null) ?
  239.                 RAPID_DATA_PREDICTION_COLUMNS_1980_FILENAME : rapidDataColumnsSupportedNames;
  240.         addEOPHistoryLoader(IERSConventions.IERS_1996,
  241.                             new RapidDataAndPredictionColumnsLoader(false, rapidColNames));
  242.         final String rapidXmlNames =
  243.                 (rapidDataXMLSupportedNames == null) ?
  244.                 RAPID_DATA_PREDICTION_XML_1980_FILENAME : rapidDataXMLSupportedNames;
  245.         addEOPHistoryLoader(IERSConventions.IERS_1996,
  246.                             new RapidDataAndPredictionXMLLoader(rapidXmlNames));
  247.         final String eopcNames =
  248.                 (eopC04SupportedNames == null) ? EOPC04_1980_FILENAME : eopC04SupportedNames;
  249.         addEOPHistoryLoader(IERSConventions.IERS_1996,
  250.                             new EOPC04FilesLoader(eopcNames));
  251.         final String bulBNames =
  252.                 (bulletinBSupportedNames == null) ? BULLETINB_1980_FILENAME : bulletinBSupportedNames;
  253.         addEOPHistoryLoader(IERSConventions.IERS_1996,
  254.                             new BulletinBFilesLoader(bulBNames));
  255.         final String bulANames =
  256.                     (bulletinASupportedNames == null) ? BULLETINA_FILENAME : bulletinASupportedNames;
  257.         addEOPHistoryLoader(IERSConventions.IERS_1996,
  258.                             new BulletinAFilesLoader(bulANames));
  259.     }

  261.     /** Add the default loaders for EOP history (IAU 2000/2006 precession/nutation).
  262.      * <p>
  263.      * The default loaders look for IERS EOP C04 and bulletins B files. They
  264.      * correspond to both {@link IERSConventions#IERS_2003 IERS 2003} and {@link
  265.      * IERSConventions#IERS_2010 IERS 2010} conventions.
  266.      * </p>
  267.      * @param rapidDataColumnsSupportedNames regular expression for supported
  268.      * rapid data columns EOP files names
  269.      * (may be null if the default IERS file names are used)
  270.      * @param rapidDataXMLSupportedNames regular expression for supported
  271.      * rapid data XML EOP files names
  272.      * (may be null if the default IERS file names are used)
  273.      * @param eopC04SupportedNames regular expression for supported EOP C04 files names
  274.      * (may be null if the default IERS file names are used)
  275.      * @param bulletinBSupportedNames regular expression for supported bulletin B files names
  276.      * (may be null if the default IERS file names are used)
  277.      * @param bulletinASupportedNames regular expression for supported bulletin A files names
  278.      * (may be null if the default IERS file names are used)
  279.      * @see <a href="http://hpiers.obspm.fr/eoppc/eop/eopc04/">IERS EOP C04 files</a>
  280.      * @see #addEOPHistoryLoader(IERSConventions, EOPHistoryLoader)
  281.      * @see #clearEOPHistoryLoaders()
  282.      * @see #addDefaultEOP1980HistoryLoaders(String, String, String, String, String)
  283.      */
  284.     public static void addDefaultEOP2000HistoryLoaders(final String rapidDataColumnsSupportedNames,
  285.                                                        final String rapidDataXMLSupportedNames,
  286.                                                        final String eopC04SupportedNames,
  287.                                                        final String bulletinBSupportedNames,
  288.                                                        final String bulletinASupportedNames) {
  289.         final String rapidColNames =
  290.                 (rapidDataColumnsSupportedNames == null) ?
  291.                 RAPID_DATA_PREDICITON_COLUMNS_2000_FILENAME : rapidDataColumnsSupportedNames;
  292.         addEOPHistoryLoader(IERSConventions.IERS_2003,
  293.                             new RapidDataAndPredictionColumnsLoader(true, rapidColNames));
  294.         addEOPHistoryLoader(IERSConventions.IERS_2010,
  295.                             new RapidDataAndPredictionColumnsLoader(true, rapidColNames));
  296.         final String rapidXmlNames =
  297.             (rapidDataXMLSupportedNames == null) ?
  298.             RAPID_DATA_PREDICITON_XML_2000_FILENAME : rapidDataXMLSupportedNames;
  299.         addEOPHistoryLoader(IERSConventions.IERS_2003,
  300.                             new RapidDataAndPredictionXMLLoader(rapidXmlNames));
  301.         addEOPHistoryLoader(IERSConventions.IERS_2010,
  302.                             new RapidDataAndPredictionXMLLoader(rapidXmlNames));
  303.         final String eopcNames =
  304.             (eopC04SupportedNames == null) ? EOPC04_2000_FILENAME : eopC04SupportedNames;
  305.         addEOPHistoryLoader(IERSConventions.IERS_2003,
  306.                             new EOPC04FilesLoader(eopcNames));
  307.         addEOPHistoryLoader(IERSConventions.IERS_2010,
  308.                             new EOPC04FilesLoader(eopcNames));
  309.         final String bulBNames =
  310.             (bulletinBSupportedNames == null) ? BULLETINB_2000_FILENAME : bulletinBSupportedNames;
  311.         addEOPHistoryLoader(IERSConventions.IERS_2003,
  312.                             new BulletinBFilesLoader(bulBNames));
  313.         addEOPHistoryLoader(IERSConventions.IERS_2010,
  314.                             new BulletinBFilesLoader(bulBNames));
  315.         final String bulANames =
  316.                 (bulletinASupportedNames == null) ? BULLETINA_FILENAME : bulletinASupportedNames;
  317.         addEOPHistoryLoader(IERSConventions.IERS_2003,
  318.                             new BulletinAFilesLoader(bulANames));
  319.         addEOPHistoryLoader(IERSConventions.IERS_2010,
  320.                             new BulletinAFilesLoader(bulANames));
  321.     }

  323.     /** Add a loader for Earth Orientation Parameters history.
  324.      * @param conventions IERS conventions to which EOP history applies
  325.      * @param loader custom loader to add for the EOP history
  326.      * @see #addDefaultEOP1980HistoryLoaders(String, String, String, String, String)
  327.      * @see #clearEOPHistoryLoaders()
  328.      */
  329.     public static void addEOPHistoryLoader(final IERSConventions conventions, final EOPHistoryLoader loader) {
  330.         synchronized (EOP_HISTORY_LOADERS) {
  331.             if (!EOP_HISTORY_LOADERS.containsKey(conventions)) {
  332.                 EOP_HISTORY_LOADERS.put(conventions, new ArrayList<EOPHistoryLoader>());
  333.             }
  334.             EOP_HISTORY_LOADERS.get(conventions).add(loader);
  335.         }
  336.     }

  338.     /** Clear loaders for Earth Orientation Parameters history.
  339.      * @see #addEOPHistoryLoader(IERSConventions, EOPHistoryLoader)
  340.      * @see #addDefaultEOP1980HistoryLoaders(String, String, String, String, String)
  341.      */
  342.     public static void clearEOPHistoryLoaders() {
  343.         synchronized (EOP_HISTORY_LOADERS) {
  344.             EOP_HISTORY_LOADERS.clear();
  345.         }
  346.     }

  348.     /** Set the threshold to check EOP continuity.
  349.      * <p>
  350.      * The default threshold (used if this method is never called)
  351.      * is 5 Julian days. If after loading EOP entries some holes
  352.      * between entries exceed this threshold, an exception will
  353.      * be triggered.
  354.      * </p>
  355.      * <p>
  356.      * One case when calling this method is really useful is for
  357.      * applications that use a single Bulletin A, as these bulletins
  358.      * have a roughly one month wide hole for the first bulletin of
  359.      * each month, which contains older final data in addition to the
  360.      * rapid data and the predicted data.
  361.      * </p>
  362.      * @param threshold threshold to use for checking EOP continuity (in seconds)
  363.      */
  364.     public static void setEOPContinuityThreshold(final double threshold) {
  365.         EOP_CONTINUITY_THRESHOLD = threshold;
  366.     }

  368.     /** Get Earth Orientation Parameters history.
  369.      * <p>
  370.      * If no {@link EOPHistoryLoader} has been added by calling {@link
  371.      * #addEOPHistoryLoader(IERSConventions, EOPHistoryLoader) addEOPHistoryLoader}
  372.      * or if {@link #clearEOPHistoryLoaders() clearEOPHistoryLoaders} has been
  373.      * called afterwards, the {@link #addDefaultEOP1980HistoryLoaders(String, String,
  374.      * String, String, String)} and {@link #addDefaultEOP2000HistoryLoaders(String,
  375.      * String, String, String, String)} methods will be called automatically with
  376.      * supported file names parameters all set to null, in order to get the default
  377.      * loaders configuration.
  378.      * </p>
  379.      * @param conventions conventions for which EOP history is requested
  380.      * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
  381.      * @return Earth Orientation Parameters history
  382.      * @exception OrekitException if the data cannot be loaded
  383.      */
  384.     public static EOPHistory getEOPHistory(final IERSConventions conventions, final boolean simpleEOP)
  385.         throws OrekitException {

  387.         synchronized (EOP_HISTORY_LOADERS) {

  389.             if (EOP_HISTORY_LOADERS.isEmpty()) {
  390.                 // set up using default loaders
  391.                 addDefaultEOP2000HistoryLoaders(null, null, null, null, null);
  392.                 addDefaultEOP1980HistoryLoaders(null, null, null, null, null);
  393.             }

  395.             // TimeStamped based set needed to remove duplicates
  396.             OrekitException pendingException = null;
  397.             final SortedSet<EOPEntry> data = new TreeSet<EOPEntry>(new ChronologicalComparator());

  399.             // try to load canonical data if available
  400.             if (EOP_HISTORY_LOADERS.containsKey(conventions)) {
  401.                 for (final EOPHistoryLoader loader : EOP_HISTORY_LOADERS.get(conventions)) {
  402.                     try {
  403.                         loader.fillHistory(conventions.getNutationCorrectionConverter(), data);
  404.                     } catch (OrekitException oe) {
  405.                         pendingException = oe;
  406.                     }
  407.                 }
  408.             }

  410.             if (data.isEmpty() && pendingException != null) {
  411.                 throw pendingException;
  412.             }

  414.             final EOPHistory history = new EOPHistory(conventions, data, simpleEOP);
  415.             history.checkEOPContinuity(EOP_CONTINUITY_THRESHOLD);
  416.             return history;

  418.         }

  420.     }

  422.     /** Get one of the predefined frames.
  423.      * @param factoryKey key of the frame within the factory
  424.      * @return the predefined frame
  425.      * @exception OrekitException if frame cannot be built due to missing data
  426.      */
  427.     public static Frame getFrame(final Predefined factoryKey)
  428.         throws OrekitException {
  429.         switch (factoryKey) {
  430.             case GCRF :
  431.                 return getGCRF();
  432.             case ICRF :
  433.                 return getICRF();
  434.             case ECLIPTIC_CONVENTIONS_1996 :
  435.                 return getEcliptic(IERSConventions.IERS_1996);
  436.             case ECLIPTIC_CONVENTIONS_2003 :
  437.                 return getEcliptic(IERSConventions.IERS_2003);
  438.             case ECLIPTIC_CONVENTIONS_2010 :
  439.                 return getEcliptic(IERSConventions.IERS_2010);
  440.             case EME2000 :
  441.                 return getEME2000();
  442.             case ITRF_CIO_CONV_2010_SIMPLE_EOP :
  443.                 return getITRF(IERSConventions.IERS_2010, true);
  444.             case ITRF_CIO_CONV_2010_ACCURATE_EOP :
  445.                 return getITRF(IERSConventions.IERS_2010, false);
  446.             case ITRF_CIO_CONV_2003_SIMPLE_EOP :
  447.                 return getITRF(IERSConventions.IERS_2003, true);
  448.             case ITRF_CIO_CONV_2003_ACCURATE_EOP :
  449.                 return getITRF(IERSConventions.IERS_2003, false);
  450.             case ITRF_CIO_CONV_1996_SIMPLE_EOP :
  451.                 return getITRF(IERSConventions.IERS_1996, true);
  452.             case ITRF_CIO_CONV_1996_ACCURATE_EOP :
  453.                 return getITRF(IERSConventions.IERS_1996, false);
  454.             case ITRF_EQUINOX_CONV_2010_SIMPLE_EOP :
  455.                 return getITRFEquinox(IERSConventions.IERS_2010, true);
  456.             case ITRF_EQUINOX_CONV_2010_ACCURATE_EOP :
  457.                 return getITRFEquinox(IERSConventions.IERS_2010, false);
  458.             case ITRF_EQUINOX_CONV_2003_SIMPLE_EOP :
  459.                 return getITRFEquinox(IERSConventions.IERS_2003, true);
  460.             case ITRF_EQUINOX_CONV_2003_ACCURATE_EOP :
  461.                 return getITRFEquinox(IERSConventions.IERS_2003, false);
  462.             case ITRF_EQUINOX_CONV_1996_SIMPLE_EOP :
  463.                 return getITRFEquinox(IERSConventions.IERS_1996, true);
  464.             case ITRF_EQUINOX_CONV_1996_ACCURATE_EOP :
  465.                 return getITRFEquinox(IERSConventions.IERS_1996, false);
  466.             case TIRF_CONVENTIONS_2010_SIMPLE_EOP :
  467.                 return getTIRF(IERSConventions.IERS_2010, true);
  468.             case TIRF_CONVENTIONS_2010_ACCURATE_EOP :
  469.                 return getTIRF(IERSConventions.IERS_2010, false);
  470.             case TIRF_CONVENTIONS_2003_SIMPLE_EOP :
  471.                 return getTIRF(IERSConventions.IERS_2003, true);
  472.             case TIRF_CONVENTIONS_2003_ACCURATE_EOP :
  473.                 return getTIRF(IERSConventions.IERS_2003, false);
  474.             case TIRF_CONVENTIONS_1996_SIMPLE_EOP :
  475.                 return getTIRF(IERSConventions.IERS_1996, true);
  476.             case TIRF_CONVENTIONS_1996_ACCURATE_EOP :
  477.                 return getTIRF(IERSConventions.IERS_1996, false);
  478.             case CIRF_CONVENTIONS_2010_ACCURATE_EOP :
  479.                 return getCIRF(IERSConventions.IERS_2010, false);
  480.             case CIRF_CONVENTIONS_2010_SIMPLE_EOP :
  481.                 return getCIRF(IERSConventions.IERS_2010, true);
  482.             case CIRF_CONVENTIONS_2003_ACCURATE_EOP :
  483.                 return getCIRF(IERSConventions.IERS_2003, false);
  484.             case CIRF_CONVENTIONS_2003_SIMPLE_EOP :
  485.                 return getCIRF(IERSConventions.IERS_2003, true);
  486.             case CIRF_CONVENTIONS_1996_ACCURATE_EOP :
  487.                 return getCIRF(IERSConventions.IERS_1996, false);
  488.             case CIRF_CONVENTIONS_1996_SIMPLE_EOP :
  489.                 return getCIRF(IERSConventions.IERS_1996, true);
  490.             case VEIS_1950 :
  491.                 return getVeis1950();
  492.             case GTOD_WITHOUT_EOP_CORRECTIONS :
  493.                 return getGTOD(IERSConventions.IERS_1996, false, true);
  494.             case GTOD_CONVENTIONS_2010_ACCURATE_EOP :
  495.                 return getGTOD(IERSConventions.IERS_2010, true, false);
  496.             case GTOD_CONVENTIONS_2010_SIMPLE_EOP :
  497.                 return getGTOD(IERSConventions.IERS_2010, true, true);
  498.             case GTOD_CONVENTIONS_2003_ACCURATE_EOP :
  499.                 return getGTOD(IERSConventions.IERS_2003, true, false);
  500.             case GTOD_CONVENTIONS_2003_SIMPLE_EOP :
  501.                 return getGTOD(IERSConventions.IERS_2003, true, true);
  502.             case GTOD_CONVENTIONS_1996_ACCURATE_EOP :
  503.                 return getGTOD(IERSConventions.IERS_1996, true, false);
  504.             case GTOD_CONVENTIONS_1996_SIMPLE_EOP :
  505.                 return getGTOD(IERSConventions.IERS_1996, true, true);
  506.             case TOD_WITHOUT_EOP_CORRECTIONS :
  507.                 return getTOD(IERSConventions.IERS_1996, false, true);
  508.             case TOD_CONVENTIONS_2010_ACCURATE_EOP :
  509.                 return getTOD(IERSConventions.IERS_2010, true, false);
  510.             case TOD_CONVENTIONS_2010_SIMPLE_EOP :
  511.                 return getTOD(IERSConventions.IERS_2010, true, true);
  512.             case TOD_CONVENTIONS_2003_ACCURATE_EOP :
  513.                 return getTOD(IERSConventions.IERS_2003, true, false);
  514.             case TOD_CONVENTIONS_2003_SIMPLE_EOP :
  515.                 return getTOD(IERSConventions.IERS_2003, true, true);
  516.             case TOD_CONVENTIONS_1996_ACCURATE_EOP :
  517.                 return getTOD(IERSConventions.IERS_1996, true, false);
  518.             case TOD_CONVENTIONS_1996_SIMPLE_EOP :
  519.                 return getTOD(IERSConventions.IERS_1996, true, true);
  520.             case MOD_WITHOUT_EOP_CORRECTIONS :
  521.                 return getMOD(IERSConventions.IERS_1996, false);
  522.             case MOD_CONVENTIONS_2010 :
  523.                 return getMOD(IERSConventions.IERS_2010, true);
  524.             case MOD_CONVENTIONS_2003 :
  525.                 return getMOD(IERSConventions.IERS_2003, true);
  526.             case MOD_CONVENTIONS_1996 :
  527.                 return getMOD(IERSConventions.IERS_1996, true);
  528.             case TEME :
  529.                 return getTEME();
  530.             default :
  531.                 // this should never happen
  532.                 throw new OrekitInternalError(null);
  533.         }
  534.     }

  536.     /** Get the unique GCRF frame.
  537.      * <p>The GCRF frame is the root frame in the frame tree.</p>
  538.      * @return the unique instance of the GCRF frame
  539.      */
  540.     public static Frame getGCRF() {
  541.         return Frame.getRoot();
  542.     }

  544.     /** Get the unique ICRF frame.
  545.      * <p>The ICRF frame is centered at solar system barycenter and aligned
  546.      * with EME2000.</p>
  547.      * @return the unique instance of the ICRF frame
  548.      * @exception OrekitException if solar system ephemerides cannot be loaded
  549.      */
  550.     public static Frame getICRF() throws OrekitException {
  551.         return CelestialBodyFactory.getSolarSystemBarycenter().getInertiallyOrientedFrame();
  552.     }

  554.     /** Get the ecliptic frame.
  555.      * The IAU defines the ecliptic as "the plane perpendicular to the mean heliocentric
  556.      * orbital angular momentum vector of the Earth-Moon barycentre in the BCRS (IAU 2006
  557.      * Resolution B1)." The +z axis is aligned with the angular momentum vector, and the +x
  558.      * axis is aligned with +x axis of {@link FramesFactory#getMOD(IERSConventions) MOD}.
  559.      *
  560.      * <p> This implementation agrees with the JPL 406 ephemerides to within 0.5 arc seconds.
  561.      * @param conventions IERS conventions to apply
  562.      * @return the selected reference frame singleton.
  563.      * @exception OrekitException if data embedded in the library cannot be read
  564.      */
  565.     public static Frame getEcliptic(final IERSConventions conventions) throws OrekitException {
  566.         synchronized (FramesFactory.class) {

  568.             final Predefined factoryKey;
  569.             switch (conventions) {
  570.                 case IERS_1996 :
  571.                     factoryKey = Predefined.ECLIPTIC_CONVENTIONS_1996;
  572.                     break;
  573.                 case IERS_2003 :
  574.                     factoryKey = Predefined.ECLIPTIC_CONVENTIONS_2003;
  575.                     break;
  576.                 case IERS_2010 :
  577.                     factoryKey = Predefined.ECLIPTIC_CONVENTIONS_2010;
  578.                     break;
  579.                 default :
  580.                     // this should never happen
  581.                     throw new OrekitInternalError(null);
  582.             }
  583.             final Frame parent = getMOD(conventions);

  585.             // try to find an already built frame
  586.             FactoryManagedFrame frame = FRAMES.get(factoryKey);

  588.             if (frame == null) {
  589.                 // it's the first time we need this frame, build it and store it
  590.                 frame = new FactoryManagedFrame(parent, new EclipticProvider(conventions),
  591.                                                 true, factoryKey);
  592.                 FRAMES.put(factoryKey, frame);
  593.             }

  595.             return frame;

  597.         }
  598.     }

  600.     /** Get the unique EME2000 frame.
  601.      * <p>The EME2000 frame is also called the J2000 frame.
  602.      * The former denomination is preferred in Orekit.</p>
  603.      * @return the unique instance of the EME2000 frame
  604.      */
  605.     public static FactoryManagedFrame getEME2000() {
  606.         synchronized (FramesFactory.class) {

  608.             // try to find an already built frame
  609.             FactoryManagedFrame frame = FRAMES.get(Predefined.EME2000);

  611.             if (frame == null) {
  612.                 // it's the first time we need this frame, build it and store it
  613.                 frame = new FactoryManagedFrame(getGCRF(), new EME2000Provider(), true, Predefined.EME2000);
  614.                 FRAMES.put(Predefined.EME2000, frame);
  615.             }

  617.             return frame;

  619.         }
  620.     }

  622.     /** Get the ITRF2008 reference frame, using IERS 2010 conventions.
  623.      * @param conventions IERS conventions to apply
  624.      * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
  625.      * @return the selected reference frame singleton.
  626.      * @exception OrekitException if data embedded in the library cannot be read
  627.      * @since 6.1
  628.      */
  629.     public static FactoryManagedFrame getITRF(final IERSConventions conventions,
  630.                                               final boolean simpleEOP)
  631.         throws OrekitException {
  632.         synchronized (FramesFactory.class) {

  634.             // try to find an already built frame
  635.             final Predefined factoryKey;
  636.             switch (conventions) {
  637.                 case IERS_1996 :
  638.                     factoryKey = simpleEOP ?
  639.                                  Predefined.ITRF_CIO_CONV_1996_SIMPLE_EOP :
  640.                                  Predefined.ITRF_CIO_CONV_1996_ACCURATE_EOP;
  641.                     break;
  642.                 case IERS_2003 :
  643.                     factoryKey = simpleEOP ?
  644.                                  Predefined.ITRF_CIO_CONV_2003_SIMPLE_EOP :
  645.                                  Predefined.ITRF_CIO_CONV_2003_ACCURATE_EOP;
  646.                     break;
  647.                 case IERS_2010 :
  648.                     factoryKey = simpleEOP ?
  649.                                  Predefined.ITRF_CIO_CONV_2010_SIMPLE_EOP :
  650.                                  Predefined.ITRF_CIO_CONV_2010_ACCURATE_EOP;
  651.                     break;
  652.                 default :
  653.                     // this should never happen
  654.                     throw new OrekitInternalError(null);
  655.             }
  656.             FactoryManagedFrame frame = FRAMES.get(factoryKey);

  658.             if (frame == null) {
  659.                 // it's the first time we need this frame, build it and store it
  660.                 final Frame tirfFrame = getTIRF(conventions, simpleEOP);
  661.                 final TIRFProvider tirfProvider = (TIRFProvider) tirfFrame.getTransformProvider();
  662.                 frame = new FactoryManagedFrame(tirfFrame,
  663.                                                 new ITRFProvider(tirfProvider.getEOPHistory()),
  664.                                                 false, factoryKey);
  665.                 FRAMES.put(factoryKey, frame);
  666.             }

  668.             return frame;

  670.         }
  671.     }

  673.     /** Get the TIRF reference frame, ignoring tidal effects.
  674.      * @param conventions IERS conventions to apply
  675.      * @return the selected reference frame singleton.
  676.      * @exception OrekitException if the precession-nutation model data embedded in the
  677.      * library cannot be read.
  678.      */
  679.     public static FactoryManagedFrame getTIRF(final IERSConventions conventions) throws OrekitException {
  680.         return getTIRF(conventions, true);
  681.     }

  683.     /** Get the TIRF reference frame.
  684.      * @param conventions IERS conventions to apply
  685.      * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
  686.      * @return the selected reference frame singleton.
  687.      * @exception OrekitException if the precession-nutation model data embedded in the
  688.      * library cannot be read.
  689.      * @since 6.1
  690.      */
  691.     public static FactoryManagedFrame getTIRF(final IERSConventions conventions,
  692.                                               final boolean simpleEOP)
  693.         throws OrekitException {
  694.         synchronized (FramesFactory.class) {

  696.             // try to find an already built frame
  697.             final Predefined factoryKey;
  698.             switch (conventions) {
  699.                 case IERS_1996 :
  700.                     factoryKey = simpleEOP ?
  701.                                  Predefined.TIRF_CONVENTIONS_1996_SIMPLE_EOP :
  702.                                  Predefined.TIRF_CONVENTIONS_1996_ACCURATE_EOP;
  703.                     break;
  704.                 case IERS_2003 :
  705.                     factoryKey = simpleEOP ?
  706.                                  Predefined.TIRF_CONVENTIONS_2003_SIMPLE_EOP :
  707.                                  Predefined.TIRF_CONVENTIONS_2003_ACCURATE_EOP;
  708.                     break;
  709.                 case IERS_2010 :
  710.                     factoryKey = simpleEOP ?
  711.                                  Predefined.TIRF_CONVENTIONS_2010_SIMPLE_EOP :
  712.                                  Predefined.TIRF_CONVENTIONS_2010_ACCURATE_EOP;
  713.                     break;
  714.                 default :
  715.                     // this should never happen
  716.                     throw new OrekitInternalError(null);
  717.             }
  718.             FactoryManagedFrame frame = FRAMES.get(factoryKey);

  720.             if (frame == null) {
  721.                 // it's the first time we need this frame, build it and store it
  722.                 final Frame cirf = getCIRF(conventions, simpleEOP);
  723.                 final ShiftingTransformProvider cirfInterpolating =
  724.                         (ShiftingTransformProvider) cirf.getTransformProvider();
  725.                 final CIRFProvider cirfRaw = (CIRFProvider) cirfInterpolating.getRawProvider();
  726.                 final EOPHistory eopHistory = cirfRaw.getEOPHistory();
  727.                 frame = new FactoryManagedFrame(cirf, new TIRFProvider(eopHistory), false, factoryKey);
  728.                 FRAMES.put(factoryKey, frame);
  729.             }

  731.             return frame;

  733.         }
  734.     }

  736.     /** Get the CIRF2000 reference frame.
  737.      * @param conventions IERS conventions to apply
  738.      * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
  739.      * @return the selected reference frame singleton.
  740.      * @exception OrekitException if the precession-nutation model data embedded in the
  741.      * library cannot be read.
  742.      */
  743.     public static FactoryManagedFrame getCIRF(final IERSConventions conventions,
  744.                                               final boolean simpleEOP)
  745.         throws OrekitException {
  746.         synchronized (FramesFactory.class) {

  748.             // try to find an already built frame
  749.             final Predefined factoryKey;
  750.             switch (conventions) {
  751.                 case IERS_1996 :
  752.                     factoryKey = simpleEOP ?
  753.                                  Predefined.CIRF_CONVENTIONS_1996_SIMPLE_EOP :
  754.                                  Predefined.CIRF_CONVENTIONS_1996_ACCURATE_EOP;
  755.                     break;
  756.                 case IERS_2003 :
  757.                     factoryKey = simpleEOP ?
  758.                                  Predefined.CIRF_CONVENTIONS_2003_SIMPLE_EOP :
  759.                                  Predefined.CIRF_CONVENTIONS_2003_ACCURATE_EOP;
  760.                     break;
  761.                 case IERS_2010 :
  762.                     factoryKey = simpleEOP ?
  763.                                  Predefined.CIRF_CONVENTIONS_2010_SIMPLE_EOP :
  764.                                  Predefined.CIRF_CONVENTIONS_2010_ACCURATE_EOP;
  765.                     break;
  766.                 default :
  767.                     // this should never happen
  768.                     throw new OrekitInternalError(null);
  769.             }
  770.             FactoryManagedFrame frame = FRAMES.get(factoryKey);

  772.             if (frame == null) {
  773.                 // it's the first time we need this frame, build it and store it
  774.                 final EOPHistory eopHistory = FramesFactory.getEOPHistory(conventions, simpleEOP);
  775.                 final TransformProvider shifting =
  776.                         new ShiftingTransformProvider(new CIRFProvider(eopHistory),
  777.                                                       CartesianDerivativesFilter.USE_PVA,
  778.                                                       AngularDerivativesFilter.USE_R,
  779.                                                       6, Constants.JULIAN_DAY / 24,
  780.                                                       OrekitConfiguration.getCacheSlotsNumber(),
  781.                                                       Constants.JULIAN_YEAR, 30 * Constants.JULIAN_DAY);
  782.                 frame = new FactoryManagedFrame(getGCRF(), shifting, true, factoryKey);
  783.                 FRAMES.put(factoryKey, frame);
  784.             }

  786.             return frame;

  788.         }
  789.     }

  791.     /** Get the VEIS 1950 reference frame.
  792.      * <p>Its parent frame is the GTOD frame with IERS 1996 conventions without EOP corrections.<p>
  793.      * @return the selected reference frame singleton.
  794.      * @exception OrekitException if data embedded in the library cannot be read
  795.      */
  796.     public static FactoryManagedFrame getVeis1950() throws OrekitException {
  797.         synchronized (FramesFactory.class) {

  799.             // try to find an already built frame
  800.             final Predefined factoryKey = Predefined.VEIS_1950;
  801.             FactoryManagedFrame frame = FRAMES.get(factoryKey);

  803.             if (frame == null) {
  804.                 // it's the first time we need this frame, build it and store it
  805.                 frame = new FactoryManagedFrame(FramesFactory.getGTOD(IERSConventions.IERS_1996, false, true),
  806.                                                 new VEISProvider(), true, factoryKey);
  807.                 FRAMES.put(factoryKey, frame);
  808.             }

  810.             return frame;

  812.         }
  813.     }

  815.     /** Get the equinox-based ITRF reference frame.
  816.      * @param conventions IERS conventions to apply
  817.      * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
  818.      * @return the selected reference frame singleton.
  819.      * @exception OrekitException if data embedded in the library cannot be read
  820.      * @since 6.1
  821.      */
  822.     public static FactoryManagedFrame getITRFEquinox(final IERSConventions conventions,
  823.                                                      final boolean simpleEOP)
  824.         throws OrekitException {
  825.         synchronized (FramesFactory.class) {

  827.             // try to find an already built frame
  828.             final Predefined factoryKey;
  829.             switch (conventions) {
  830.                 case IERS_1996 :
  831.                     factoryKey = simpleEOP ?
  832.                                  Predefined.ITRF_EQUINOX_CONV_1996_SIMPLE_EOP :
  833.                                  Predefined.ITRF_EQUINOX_CONV_1996_ACCURATE_EOP;
  834.                     break;
  835.                 case IERS_2003 :
  836.                     factoryKey = simpleEOP ?
  837.                                  Predefined.ITRF_EQUINOX_CONV_2003_SIMPLE_EOP :
  838.                                  Predefined.ITRF_EQUINOX_CONV_2003_ACCURATE_EOP;
  839.                     break;
  840.                 case IERS_2010 :
  841.                     factoryKey = simpleEOP ?
  842.                                  Predefined.ITRF_EQUINOX_CONV_2010_SIMPLE_EOP :
  843.                                  Predefined.ITRF_EQUINOX_CONV_2010_ACCURATE_EOP;
  844.                     break;
  845.                 default :
  846.                     // this should never happen
  847.                     throw new OrekitInternalError(null);
  848.             }
  849.             FactoryManagedFrame frame = FRAMES.get(factoryKey);

  851.             if (frame == null) {
  852.                 // it's the first time we need this frame, build it and store it
  853.                 final Frame gtod = getGTOD(conventions, true, simpleEOP);
  854.                 final ShiftingTransformProvider gtodShifting =
  855.                         (ShiftingTransformProvider) gtod.getTransformProvider();
  856.                 final GTODProvider gtodRaw    = (GTODProvider) gtodShifting.getRawProvider();
  857.                 final EOPHistory   eopHistory = gtodRaw.getEOPHistory();
  858.                 frame = new FactoryManagedFrame(gtod, new ITRFProvider(eopHistory), false, factoryKey);
  859.                 FRAMES.put(factoryKey, frame);
  860.             }

  862.             return frame;

  864.         }
  865.     }

  867.     /** Get the GTOD reference frame.
  868.      * <p>
  869.      * The applyEOPCorr parameter is available mainly for testing purposes or for
  870.      * consistency with legacy software that don't handle EOP correction parameters.
  871.      * Beware that setting this parameter to {@code false} leads to crude accuracy
  872.      * (order of magnitudes for errors might be above 250m in LEO and 1400m in GEO).
  873.      * For this reason, setting this parameter to false is restricted to {@link
  874.      * IERSConventions#IERS_1996 IERS 1996} conventions, and hence the {@link
  875.      * IERSConventions IERS conventions} cannot be freely chosen here.
  876.      * </p>
  877.      * @param applyEOPCorr if true, EOP corrections are applied (here, dut1 and lod)
  878.      * @return the selected reference frame singleton.
  879.      * @exception OrekitException if data embedded in the library cannot be read
  880.      */
  881.     public static FactoryManagedFrame getGTOD(final boolean applyEOPCorr) throws OrekitException {
  882.         return getGTOD(IERSConventions.IERS_1996, applyEOPCorr, true);
  883.     }

  885.     /** Get the GTOD reference frame.
  886.      * @param conventions IERS conventions to apply
  887.      * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
  888.      * @return the selected reference frame singleton.
  889.      * @exception OrekitException if data embedded in the library cannot be read
  890.      */
  891.     public static FactoryManagedFrame getGTOD(final IERSConventions conventions,
  892.                                               final boolean simpleEOP)
  893.         throws OrekitException {
  894.         return getGTOD(conventions, true, simpleEOP);
  895.     }

  897.     /** Get the GTOD reference frame.
  898.      * <p>
  899.      * The applyEOPCorr parameter is available mainly for testing purposes or for
  900.      * consistency with legacy software that don't handle EOP correction parameters.
  901.      * Beware that setting this parameter to {@code false} leads to crude accuracy
  902.      * (order of magnitudes for errors might be above 250m in LEO and 1400m in GEO).
  903.      * For this reason, setting this parameter to false is restricted to {@link
  904.      * IERSConventions#IERS_1996 IERS 1996} conventions, and hence this method is private.
  905.      * </p>
  906.      * @param conventions IERS conventions to apply
  907.      * @param applyEOPCorr if true, EOP corrections are applied (here, dut1 and lod)
  908.      * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
  909.      * @return the selected reference frame singleton.
  910.      * @exception OrekitException if data embedded in the library cannot be read
  911.      */
  912.     private static FactoryManagedFrame getGTOD(final IERSConventions conventions,
  913.                                                final boolean applyEOPCorr,
  914.                                                final boolean simpleEOP)
  915.         throws OrekitException {

  917.         synchronized (FramesFactory.class) {

  919.             // try to find an already built frame
  920.             final Predefined factoryKey;
  921.             switch (conventions) {
  922.                 case IERS_1996 :
  923.                     factoryKey = applyEOPCorr ?
  924.                                  (simpleEOP ? Predefined.GTOD_CONVENTIONS_1996_SIMPLE_EOP : Predefined.GTOD_CONVENTIONS_1996_ACCURATE_EOP) :
  925.                                  Predefined.GTOD_WITHOUT_EOP_CORRECTIONS;
  926.                     break;
  927.                 case IERS_2003 :
  928.                     factoryKey = simpleEOP ?
  929.                                  Predefined.GTOD_CONVENTIONS_2003_SIMPLE_EOP :
  930.                                  Predefined.GTOD_CONVENTIONS_2003_ACCURATE_EOP;
  931.                     break;
  932.                 case IERS_2010 :
  933.                     factoryKey = simpleEOP ? Predefined.GTOD_CONVENTIONS_2010_SIMPLE_EOP :
  934.                                              Predefined.GTOD_CONVENTIONS_2010_ACCURATE_EOP;
  935.                     break;
  936.                 default :
  937.                     // this should never happen
  938.                     throw new OrekitInternalError(null);
  939.             }
  940.             FactoryManagedFrame frame = FRAMES.get(factoryKey);

  942.             if (frame == null) {
  943.                 // it's the first time we need this frame, build it and store it
  944.                 final Frame tod = getTOD(conventions, applyEOPCorr, simpleEOP);
  945.                 final ShiftingTransformProvider todInterpolating =
  946.                         (ShiftingTransformProvider) tod.getTransformProvider();
  947.                 final TODProvider       todRaw     = (TODProvider) todInterpolating.getRawProvider();
  948.                 final EOPHistory        eopHistory = todRaw.getEOPHistory();
  949.                 final GTODProvider      gtodRaw    = new GTODProvider(conventions, eopHistory);
  950.                 final TransformProvider gtodShifting =
  951.                         new ShiftingTransformProvider(gtodRaw,
  952.                                                       CartesianDerivativesFilter.USE_PVA,
  953.                                                       AngularDerivativesFilter.USE_R,
  954.                                                       todInterpolating.getGridPoints(), todInterpolating.getStep(),
  955.                                                       OrekitConfiguration.getCacheSlotsNumber(),
  956.                                                       Constants.JULIAN_YEAR, 30 * Constants.JULIAN_DAY);
  957.                 frame = new FactoryManagedFrame(tod, gtodShifting, false, factoryKey);
  958.                 FRAMES.put(factoryKey, frame);
  959.             }

  961.             return frame;

  963.         }
  964.     }

  966.     /** Get the TOD reference frame.
  967.      * <p>
  968.      * The applyEOPCorr parameter is available mainly for testing purposes or for
  969.      * consistency with legacy software that don't handle EOP correction parameters.
  970.      * Beware that setting this parameter to {@code false} leads to crude accuracy
  971.      * (order of magnitudes for errors might be above 1m in LEO and 10m in GEO).
  972.      * For this reason, setting this parameter to false is restricted to {@link
  973.      * IERSConventions#IERS_1996 IERS 1996} conventions, and hence the {@link
  974.      * IERSConventions IERS conventions} cannot be freely chosen here.
  975.      * </p>
  976.      * @param applyEOPCorr if true, EOP corrections are applied (here, nutation)
  977.      * @return the selected reference frame singleton.
  978.      * @exception OrekitException if data embedded in the library cannot be read
  979.      */
  980.     public static FactoryManagedFrame getTOD(final boolean applyEOPCorr)
  981.         throws OrekitException {
  982.         return getTOD(IERSConventions.IERS_1996, applyEOPCorr, false);
  983.     }

  985.     /** Get the TOD reference frame.
  986.      * @param conventions IERS conventions to apply
  987.      * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
  988.      * @return the selected reference frame singleton.
  989.      * @exception OrekitException if data embedded in the library cannot be read
  990.      */
  991.     public static FactoryManagedFrame getTOD(final IERSConventions conventions,
  992.                                              final boolean simpleEOP)
  993.         throws OrekitException {
  994.         return getTOD(conventions, true, simpleEOP);
  995.     }

  997.     /** Get the TOD reference frame.
  998.      * <p>
  999.      * The applyEOPCorr parameter is available mainly for testing purposes or for
  1000.      * consistency with legacy software that don't handle EOP correction parameters.
  1001.      * Beware that setting this parameter to {@code false} leads to crude accuracy
  1002.      * (order of magnitudes for errors might be above 1m in LEO and 10m in GEO).
  1003.      * For this reason, setting this parameter to false is restricted to {@link
  1004.      * IERSConventions#IERS_1996 IERS 1996} conventions, and hence this method is private.
  1005.      * </p>
  1006.      * @param conventions IERS conventions to apply
  1007.      * @param applyEOPCorr if true, EOP corrections are applied (here, nutation)
  1008.      * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
  1009.      * @return the selected reference frame singleton.
  1010.      * @exception OrekitException if data embedded in the library cannot be read
  1011.      */
  1012.     private static FactoryManagedFrame getTOD(final IERSConventions conventions,
  1013.                                               final boolean applyEOPCorr,
  1014.                                               final boolean simpleEOP)
  1015.         throws OrekitException {

  1017.         synchronized (FramesFactory.class) {

  1019.             // try to find an already built frame
  1020.             final Predefined factoryKey;
  1021.             switch (conventions) {
  1022.                 case IERS_1996 :
  1023.                     factoryKey = applyEOPCorr ?
  1024.                                  (simpleEOP ? Predefined.TOD_CONVENTIONS_1996_SIMPLE_EOP : Predefined.TOD_CONVENTIONS_1996_ACCURATE_EOP) :
  1025.                                  Predefined.TOD_WITHOUT_EOP_CORRECTIONS;
  1026.                     break;
  1027.                 case IERS_2003 :
  1028.                     factoryKey = simpleEOP ?
  1029.                                  Predefined.TOD_CONVENTIONS_2003_SIMPLE_EOP :
  1030.                                      Predefined.TOD_CONVENTIONS_2003_ACCURATE_EOP;
  1031.                     break;
  1032.                 case IERS_2010 :
  1033.                     factoryKey = simpleEOP ?
  1034.                                  Predefined.TOD_CONVENTIONS_2010_SIMPLE_EOP :
  1035.                                  Predefined.TOD_CONVENTIONS_2010_ACCURATE_EOP;
  1036.                     break;
  1037.                 default :
  1038.                     // this should never happen
  1039.                     throw new OrekitInternalError(null);
  1040.             }
  1041.             final int interpolationPoints;
  1042.             final int pointsPerDay;
  1043.             if (applyEOPCorr) {
  1044.                 interpolationPoints = 6;
  1045.                 pointsPerDay        = 24;
  1046.             } else {
  1047.                 interpolationPoints = 6;
  1048.                 pointsPerDay        = 8;
  1049.             }
  1050.             FactoryManagedFrame frame = FRAMES.get(factoryKey);

  1052.             if (frame == null) {
  1053.                 // it's the first time we need this frame, build it and store it
  1054.                 final EOPHistory eopHistory = applyEOPCorr ? getEOPHistory(conventions, simpleEOP) : null;
  1055.                 final TransformProvider shifting =
  1056.                         new ShiftingTransformProvider(new TODProvider(conventions, eopHistory),
  1057.                                                       CartesianDerivativesFilter.USE_PVA,
  1058.                                                       AngularDerivativesFilter.USE_R,
  1059.                                                       interpolationPoints, Constants.JULIAN_DAY / pointsPerDay,
  1060.                                                       OrekitConfiguration.getCacheSlotsNumber(),
  1061.                                                       Constants.JULIAN_YEAR, 30 * Constants.JULIAN_DAY);
  1062.                 frame = new FactoryManagedFrame(getMOD(conventions, applyEOPCorr), shifting, true, factoryKey);
  1063.                 FRAMES.put(factoryKey, frame);
  1064.             }

  1066.             return frame;

  1068.         }
  1069.     }

  1071.     /** Get the MOD reference frame.
  1072.      * <p>
  1073.      * The applyEOPCorr parameter is available mainly for testing purposes or for
  1074.      * consistency with legacy software that don't handle EOP correction parameters.
  1075.      * Beware that setting this parameter to {@code false} leads to crude accuracy
  1076.      * (order of magnitudes for errors might be above 1m in LEO and 10m in GEO).
  1077.      * For this reason, setting this parameter to false is restricted to {@link
  1078.      * IERSConventions#IERS_1996 IERS 1996} conventions, and hence the {@link
  1079.      * IERSConventions IERS conventions} cannot be freely chosen here.
  1080.      * </p>
  1081.      * @param applyEOPCorr if true, EOP corrections are applied (EME2000/GCRF bias compensation)
  1082.      * @return the selected reference frame singleton.
  1083.      * @exception OrekitException if data embedded in the library cannot be read
  1084.      */
  1085.     public static FactoryManagedFrame getMOD(final boolean applyEOPCorr)
  1086.         throws OrekitException {
  1087.         return getMOD(IERSConventions.IERS_1996, applyEOPCorr);
  1088.     }

  1090.     /** Get the MOD reference frame.
  1091.      * @param conventions IERS conventions to apply
  1092.      * @return the selected reference frame singleton.
  1093.      * @exception OrekitException if data embedded in the library cannot be read
  1094.      */
  1095.     public static FactoryManagedFrame getMOD(final IERSConventions conventions)
  1096.         throws OrekitException {
  1097.         return getMOD(conventions, true);
  1098.     }

  1100.     /** Get the MOD reference frame.
  1101.      * <p>
  1102.      * The applyEOPCorr parameter is available mainly for testing purposes or for
  1103.      * consistency with legacy software that don't handle EOP correction parameters.
  1104.      * Beware that setting this parameter to {@code false} leads to crude accuracy
  1105.      * (order of magnitudes for errors might be above 1m in LEO and 10m in GEO).
  1106.      * For this reason, setting this parameter to false is restricted to {@link
  1107.      * IERSConventions#IERS_1996 IERS 1996} conventions, and hence this method is private.
  1108.      * </p>
  1109.      * @param conventions IERS conventions to apply
  1110.      * @param applyEOPCorr if true, EOP corrections are applied (EME2000/GCRF bias compensation)
  1111.      * @return the selected reference frame singleton.
  1112.      * @exception OrekitException if data embedded in the library cannot be read
  1113.      */
  1114.     private static FactoryManagedFrame getMOD(final IERSConventions conventions, final boolean applyEOPCorr)
  1115.         throws OrekitException {

  1117.         synchronized (FramesFactory.class) {

  1119.             final Predefined factoryKey;
  1120.             final Frame parent;
  1121.             switch (conventions) {
  1122.                 case IERS_1996 :
  1123.                     factoryKey = applyEOPCorr ? Predefined.MOD_CONVENTIONS_1996 : Predefined.MOD_WITHOUT_EOP_CORRECTIONS;
  1124.                     parent     = applyEOPCorr ? FramesFactory.getGCRF() : FramesFactory.getEME2000();
  1125.                     break;
  1126.                 case IERS_2003 :
  1127.                     factoryKey = Predefined.MOD_CONVENTIONS_2003;
  1128.                     // in IERS conventions 2003, the precession angles zetaA, thetaA and zA
  1129.                     // from equation 33 are computed from EME2000, not from GCRF
  1130.                     parent     = FramesFactory.getEME2000();
  1131.                     break;
  1132.                 case IERS_2010 :
  1133.                     factoryKey = Predefined.MOD_CONVENTIONS_2010;
  1134.                     // precession angles epsilon0, psiA, omegaA and chiA
  1135.                     // from equations 5.39 and 5.40 are computed from EME2000
  1136.                     parent     = FramesFactory.getEME2000();
  1137.                     break;
  1138.                 default :
  1139.                     // this should never happen
  1140.                     throw new OrekitInternalError(null);
  1141.             }

  1143.             // try to find an already built frame
  1144.             FactoryManagedFrame frame = FRAMES.get(factoryKey);

  1146.             if (frame == null) {
  1147.                 // it's the first time we need this frame, build it and store it
  1148.                 frame = new FactoryManagedFrame(parent, new MODProvider(conventions), true, factoryKey);
  1149.                 FRAMES.put(factoryKey, frame);
  1150.             }

  1152.             return frame;

  1154.         }
  1155.     }

  1157.     /** Get the TEME reference frame.
  1158.      * <p>
  1159.      * The TEME frame is used for the SGP4 model in TLE propagation. This frame has <em>no</em>
  1160.      * official definition and there are some ambiguities about whether it should be used
  1161.      * as "of date" or "of epoch". This frame should therefore be used <em>only</em> for
  1162.      * TLE propagation and not for anything else, as recommended by the CCSDS Orbit Data Message
  1163.      * blue book.
  1164.      * </p>
  1165.      * @return the selected reference frame singleton.
  1166.      * @exception OrekitException if data embedded in the library cannot be read
  1167.      */
  1168.     public static FactoryManagedFrame getTEME() throws OrekitException {
  1169.         synchronized (FramesFactory.class) {

  1171.             // try to find an already built frame
  1172.             final Predefined factoryKey = Predefined.TEME;
  1173.             FactoryManagedFrame frame = FRAMES.get(factoryKey);

  1175.             if (frame == null) {
  1176.                 // it's the first time we need this frame, build it and store it
  1177.                 final Frame tod = getTOD(IERSConventions.IERS_1996, false, true);
  1178.                 final ShiftingTransformProvider todShifting =
  1179.                         (ShiftingTransformProvider) tod.getTransformProvider();
  1180.                 final TEMEProvider temeRaw = new TEMEProvider(IERSConventions.IERS_1996, null);
  1181.                 final TransformProvider temeShifting =
  1182.                         new ShiftingTransformProvider(temeRaw,
  1183.                                                       CartesianDerivativesFilter.USE_PVA,
  1184.                                                       AngularDerivativesFilter.USE_R,
  1185.                                                       todShifting.getGridPoints(), todShifting.getStep(),
  1186.                                                       OrekitConfiguration.getCacheSlotsNumber(),
  1187.                                                       Constants.JULIAN_YEAR, 30 * Constants.JULIAN_DAY);

  1189.                 frame = new FactoryManagedFrame(tod, temeShifting, true, factoryKey);
  1190.                 FRAMES.put(factoryKey, frame);
  1191.             }

  1193.             return frame;

  1195.         }
  1196.     }

  1198.     /** Get the transform between two frames, suppressing all interpolation.
  1199.      * <p>
  1200.      * This method is similar to {@link Frame#getTransformTo(Frame, AbsoluteDate)}
  1201.      * except it removes the performance enhancing interpolation features that are
  1202.      * added by the {@link FramesFactory factory} to some frames, in order to focus
  1203.      * on accuracy. The interpolation features are intended to save processing time
  1204.      * by avoiding doing some lengthy computation like nutation evaluation at each
  1205.      * time step and caching some results. This method can be used to avoid this,
  1206.      * when very high accuracy is desired, or for testing purposes. It should be
  1207.      * used with care, as doing the full computation is <em>really</em> costly for
  1208.      * some frames.
  1209.      * </p>
  1210.      * @param from frame from which transformation starts
  1211.      * @param to frame to which transformation ends
  1212.      * @param date date of the transform
  1213.      * @return transform between the two frames, avoiding interpolation
  1214.      * @throws OrekitException if transform cannot be computed at this date
  1215.      */
  1216.     public static Transform getNonInterpolatingTransform(final Frame from, final Frame to,
  1217.                                                          final AbsoluteDate date)
  1218.         throws OrekitException {

  1220.         // common ancestor to both frames in the frames tree
  1221.         Frame currentF = from.getDepth() > to.getDepth() ? from.getAncestor(from.getDepth() - to.getDepth()) : from;
  1222.         Frame currentT = from.getDepth() > to.getDepth() ? to : to.getAncestor(to.getDepth() - from.getDepth());
  1223.         while (currentF != currentT) {
  1224.             currentF = currentF.getParent();
  1225.             currentT = currentT.getParent();
  1226.         }
  1227.         final Frame common = currentF;

  1229.         // transform from common to origin
  1230.         Transform commonToOrigin = Transform.IDENTITY;
  1231.         for (Frame frame = from; frame != common; frame = frame.getParent()) {
  1232.             commonToOrigin = new Transform(date,
  1233.                                              peel(frame.getTransformProvider()).getTransform(date),
  1234.                                              commonToOrigin);
  1235.         }

  1237.         // transform from destination up to common
  1238.         Transform commonToDestination = Transform.IDENTITY;
  1239.         for (Frame frame = to; frame != common; frame = frame.getParent()) {
  1240.             commonToDestination = new Transform(date,
  1241.                                                 peel(frame.getTransformProvider()).getTransform(date),
  1242.                                                 commonToDestination);
  1243.         }

  1245.         // transform from origin to destination via common
  1246.         return new Transform(date, commonToOrigin.getInverse(), commonToDestination);

  1248.     }

  1250.     /** Get the transform between two frames, suppressing all interpolation.
  1251.      * <p>
  1252.      * This method is similar to {@link Frame#getTransformTo(Frame, AbsoluteDate)}
  1253.      * except it removes the performance enhancing interpolation features that are
  1254.      * added by the {@link FramesFactory factory} to some frames, in order to focus
  1255.      * on accuracy. The interpolation features are intended to save processing time
  1256.      * by avoiding doing some lengthy computation like nutation evaluation at each
  1257.      * time step and caching some results. This method can be used to avoid this,
  1258.      * when very high accuracy is desired, or for testing purposes. It should be
  1259.      * used with care, as doing the full computation is <em>really</em> costly for
  1260.      * some frames.
  1261.      * </p>
  1262.      * @param from frame from which transformation starts
  1263.      * @param to frame to which transformation ends
  1264.      * @param date date of the transform
  1265.      * @param <T> type of the field elements
  1266.      * @return transform between the two frames, avoiding interpolation
  1267.      * @throws OrekitException if transform cannot be computed at this date
  1268.      * @since 9.0
  1269.      */
  1270.     public static <T extends RealFieldElement<T>> FieldTransform<T> getNonInterpolatingTransform(final Frame from, final Frame to,
  1271.                                                                                                  final FieldAbsoluteDate<T> date)
  1272.         throws OrekitException {

  1274.         // common ancestor to both frames in the frames tree
  1275.         Frame currentF = from.getDepth() > to.getDepth() ? from.getAncestor(from.getDepth() - to.getDepth()) : from;
  1276.         Frame currentT = from.getDepth() > to.getDepth() ? to : to.getAncestor(to.getDepth() - from.getDepth());
  1277.         while (currentF != currentT) {
  1278.             currentF = currentF.getParent();
  1279.             currentT = currentT.getParent();
  1280.         }
  1281.         final Frame common = currentF;

  1283.         // transform from common to origin
  1284.         FieldTransform<T> commonToOrigin = FieldTransform.getIdentity(date.getField());
  1285.         for (Frame frame = from; frame != common; frame = frame.getParent()) {
  1286.             commonToOrigin = new FieldTransform<>(date,
  1287.                                                    peel(frame.getTransformProvider()).getTransform(date),
  1288.                                                    commonToOrigin);
  1289.         }

  1291.         // transform from destination up to common
  1292.         FieldTransform<T> commonToDestination = FieldTransform.getIdentity(date.getField());
  1293.         for (Frame frame = to; frame != common; frame = frame.getParent()) {
  1294.             commonToDestination = new FieldTransform<>(date,
  1295.                                                        peel(frame.getTransformProvider()).getTransform(date),
  1296.                                                        commonToDestination);
  1297.         }

  1299.         // transform from origin to destination via common
  1300.         return new FieldTransform<>(date, commonToOrigin.getInverse(), commonToDestination);

  1302.     }

  1304.     /** Retrieve EOP from a frame hierarchy.
  1305.      * <p>
  1306.      * The frame hierarchy tree is walked from specified frame up to root
  1307.      * goind though parent frames, and the providers are checked to see if they
  1308.      * reference EOP history.the first EOP history found is returned.
  1309.      * </p>
  1310.      * @param start frame from which to start search, will typically be some
  1311.      * Earth related frame, like a topocentric frame or an ITRF frame
  1312.      * @return EOP history found while walking the frames tree, or null if
  1313.      * no EOP history is found
  1314.      * @since 9.1
  1315.      */
  1316.     public static EOPHistory findEOP(final Frame start) {

  1318.         for (Frame frame = start; frame != null; frame = frame.getParent()) {

  1320.             TransformProvider peeled = frame.getTransformProvider();

  1322.             boolean peeling = true;
  1323.             while (peeling) {
  1324.                 if (peeled instanceof InterpolatingTransformProvider) {
  1325.                     peeled = ((InterpolatingTransformProvider) peeled).getRawProvider();
  1326.                 } else if (peeled instanceof ShiftingTransformProvider) {
  1327.                     peeled = ((ShiftingTransformProvider) peeled).getRawProvider();
  1328.                 } else if (peeled instanceof EOPBasedTransformProvider &&
  1329.                            ((EOPBasedTransformProvider) peeled).getEOPHistory() != null) {
  1330.                     return ((EOPBasedTransformProvider) peeled).getEOPHistory();
  1331.                 } else {
  1332.                     peeling = false;
  1333.                 }
  1334.             }

  1336.         }

  1338.         // no history found
  1339.         return null;

  1341.     }

  1343.     /** Peel interpolation and shifting from a transform provider.
  1344.      * @param provider transform provider to peel
  1345.      * @return peeled transform provider
  1346.      * @exception OrekitException if EOP cannot be retrieved
  1347.      */
  1348.     private static TransformProvider peel(final TransformProvider provider)
  1349.         throws OrekitException {

  1351.         TransformProvider peeled = provider;

  1353.         boolean peeling = true;
  1354.         while (peeling) {
  1355.             if (peeled instanceof InterpolatingTransformProvider) {
  1356.                 peeled = ((InterpolatingTransformProvider) peeled).getRawProvider();
  1357.             } else if (peeled instanceof ShiftingTransformProvider) {
  1358.                 peeled = ((ShiftingTransformProvider) peeled).getRawProvider();
  1359.             } else if (peeled instanceof EOPBasedTransformProvider &&
  1360.                        ((EOPBasedTransformProvider) peeled).getEOPHistory() != null &&
  1361.                        ((EOPBasedTransformProvider) peeled).getEOPHistory().usesInterpolation()) {
  1362.                 peeled = ((EOPBasedTransformProvider) peeled).getNonInterpolatingProvider();
  1363.             } else {
  1364.                 peeling = false;
  1365.             }
  1366.         }

  1368.         return peeled;

  1370.     }

  1372. }
Created with JaCoCo 0.7.9.201702052155