Frames.java

  1. /* Contributed in the public domain.
  2.  * Licensed to CS GROUP (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;

  18. import java.util.Collection;
  19. import java.util.function.BiFunction;
  20. import java.util.function.Supplier;

  21. import org.orekit.bodies.CelestialBodies;
  22. import org.orekit.time.TimeScales;
  23. import org.orekit.time.UT1Scale;
  24. import org.orekit.utils.IERSConventions;

  25. /**
  26.  * A collection of commonly used {@link Frame}s. This interface defines methods for
  27.  * obtaining instances of many commonly used reference frames.
  28.  *
  29.  * @author Guylaine Prat
  30.  * @author Luc Maisonobe
  31.  * @author Pascal Parraud
  32.  * @author Evan Ward
  33.  * @see FramesFactory
  34.  * @since 10.0
  35.  */
  36. public interface Frames {

  37.     /** Get Earth Orientation Parameters history.
  38.      * @param conventions conventions for which EOP history is requested
  39.      * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
  40.      * @return Earth Orientation Parameters history
  41.      */
  42.     EOPHistory getEOPHistory(IERSConventions conventions, boolean simpleEOP);

  43.     /** Get one of the predefined frames.
  44.      * @param factoryKey key of the frame within the factory
  45.      * @return the predefined frame
  46.      */
  47.     Frame getFrame(Predefined factoryKey);

  48.     /** Get the unique GCRF frame.
  49.      * <p>The GCRF frame is the root frame in the frame tree.</p>
  50.      * @return the unique instance of the GCRF frame
  51.      */
  52.     Frame getGCRF();

  53.     /** Get the unique ICRF frame.
  54.      * <p>The ICRF frame is centered at solar system barycenter and aligned
  55.      * with GCRF.</p>
  56.      * @return the unique instance of the ICRF frame
  57.      */
  58.     Frame getICRF();

  59.     /** Get the ecliptic frame.
  60.      * The IAU defines the ecliptic as "the plane perpendicular to the mean heliocentric
  61.      * orbital angular momentum vector of the Earth-Moon barycentre in the BCRS (IAU 2006
  62.      * Resolution B1)." The +z axis is aligned with the angular momentum vector, and the +x
  63.      * axis is aligned with +x axis of {@link #getMOD(IERSConventions) MOD}.
  64.      *
  65.      * <p> This implementation agrees with the JPL 406 ephemerides to within 0.5 arc seconds.
  66.      * @param conventions IERS conventions to apply
  67.      * @return the selected reference frame singleton.
  68.      */
  69.     Frame getEcliptic(IERSConventions conventions);

  70.     /** Get the unique EME2000 frame.
  71.      * <p>The EME2000 frame is also called the J2000 frame.
  72.      * The former denomination is preferred in Orekit.</p>
  73.      * @return the unique instance of the EME2000 frame
  74.      */
  75.     FactoryManagedFrame getEME2000();

  76.     /** Get an unspecified International Terrestrial Reference Frame.
  77.      * <p>
  78.      * The frame returned uses the {@link EOPEntry Earth Orientation Parameters}
  79.      * blindly. So if for example one loads only EOP 14 C04 files to retrieve
  80.      * the parameters, the frame will be an {@link ITRFVersion#ITRF_2014}. However,
  81.      * if parameters are loaded from different files types, or even for file
  82.      * types that changed their reference (like Bulletin A switching from
  83.      * {@link ITRFVersion#ITRF_2008} to {@link ITRFVersion#ITRF_2014} starting
  84.      * with Vol. XXXI No. 013 published on 2018-03-29), then the ITRF returned
  85.      * by this method will jump from one version to another version.
  86.      * </p>
  87.      * <p>
  88.      * IF a specific version of ITRF is needed, then {@link #getITRF(ITRFVersion,
  89.      * IERSConventions, boolean)} should be used instead.
  90.      * </p>
  91.      * @param conventions IERS conventions to apply
  92.      * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
  93.      * @return the selected reference frame singleton.
  94.      * @see #getITRF(ITRFVersion, IERSConventions, boolean)
  95.      * @since 6.1
  96.      */
  97.     FactoryManagedFrame getITRF(IERSConventions conventions,
  98.                                 boolean simpleEOP);

  99.     /** Get the TIRF reference frame, ignoring tidal effects.
  100.      * @param conventions IERS conventions to apply
  101.      * @return the selected reference frame singleton.
  102.      * library cannot be read.
  103.      */
  104.     FactoryManagedFrame getTIRF(IERSConventions conventions);

  105.     /** Get an specific International Terrestrial Reference Frame.
  106.      * <p>
  107.      * Note that if a specific version of ITRF is required, then {@code simpleEOP}
  108.      * should most probably be set to {@code false}, as ignoring tidal effects
  109.      * has an effect of the same order of magnitude as the differences between
  110.      * the various {@link ITRFVersion ITRF versions}.
  111.      * </p>
  112.      * @param version ITRF version
  113.      * @param conventions IERS conventions to apply
  114.      * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
  115.      * @return the selected reference frame singleton.
  116.      * @since 9.2
  117.      */
  118.     VersionedITRF getITRF(ITRFVersion version,
  119.                           IERSConventions conventions,
  120.                           boolean simpleEOP);

  121.     /** Build an uncached International Terrestrial Reference Frame with specific {@link EOPHistory EOP history}.
  122.      * <p>
  123.      * This frame and its parent frames (TIRF and CIRF) will <em>not</em> be cached, they are
  124.      * rebuilt from scratch each time this method is called. This factory method is intended
  125.      * to be used when EOP history is changed at run time. For regular ITRF use, the
  126.      * {@link #getITRF(IERSConventions, boolean)} and {link {@link #getITRF(ITRFVersion, IERSConventions, boolean)}
  127.      * are more suitable.
  128.      * </p>
  129.      * @param ut1 UT1 time scale (contains the {@link EOPHistory EOP history})
  130.      * @return an ITRF frame with specified time scale and embedded EOP history
  131.      * @since 12.0
  132.      */
  133.     Frame buildUncachedITRF(UT1Scale ut1);

  134.     /** Get the TIRF reference frame.
  135.      * @param conventions IERS conventions to apply
  136.      * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
  137.      * @return the selected reference frame singleton.
  138.      * @since 6.1
  139.      */
  140.     FactoryManagedFrame getTIRF(IERSConventions conventions,
  141.                                 boolean simpleEOP);

  142.     /** Get the CIRF2000 reference frame.
  143.      * @param conventions IERS conventions to apply
  144.      * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
  145.      * @return the selected reference frame singleton.
  146.      */
  147.     FactoryManagedFrame getCIRF(IERSConventions conventions,
  148.                                 boolean simpleEOP);

  149.     /** Get the VEIS 1950 reference frame.
  150.      * <p>Its parent frame is the GTOD frame with IERS 1996 conventions without EOP corrections.</p>
  151.      * @return the selected reference frame singleton.
  152.      */
  153.     FactoryManagedFrame getVeis1950();

  154.     /** Get the equinox-based ITRF reference frame.
  155.      * @param conventions IERS conventions to apply
  156.      * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
  157.      * @return the selected reference frame singleton.
  158.      * @since 6.1
  159.      */
  160.     FactoryManagedFrame getITRFEquinox(IERSConventions conventions,
  161.                                        boolean simpleEOP);

  162.     /** Get the GTOD reference frame.
  163.      * <p>
  164.      * The applyEOPCorr parameter is available mainly for testing purposes or for
  165.      * consistency with legacy software that don't handle EOP correction parameters.
  166.      * Beware that setting this parameter to {@code false} leads to crude accuracy
  167.      * (order of magnitudes for errors might be above 250m in LEO and 1400m in GEO).
  168.      * For this reason, setting this parameter to false is restricted to {@link
  169.      * IERSConventions#IERS_1996 IERS 1996} conventions, and hence the {@link
  170.      * IERSConventions IERS conventions} cannot be freely chosen here.
  171.      * </p>
  172.      * @param applyEOPCorr if true, EOP corrections are applied (here, dut1 and lod)
  173.      * @return the selected reference frame singleton.
  174.      */
  175.     FactoryManagedFrame getGTOD(boolean applyEOPCorr);

  176.     /** Get the GTOD reference frame.
  177.      * @param conventions IERS conventions to apply
  178.      * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
  179.      * @return the selected reference frame singleton.
  180.      */
  181.     FactoryManagedFrame getGTOD(IERSConventions conventions,
  182.                                 boolean simpleEOP);

  183.     /** Get the TOD reference frame.
  184.      * <p>
  185.      * The applyEOPCorr parameter is available mainly for testing purposes or for
  186.      * consistency with legacy software that don't handle EOP correction parameters.
  187.      * Beware that setting this parameter to {@code false} leads to crude accuracy
  188.      * (order of magnitudes for errors might be above 1m in LEO and 10m in GEO).
  189.      * For this reason, setting this parameter to false is restricted to {@link
  190.      * IERSConventions#IERS_1996 IERS 1996} conventions, and hence the {@link
  191.      * IERSConventions IERS conventions} cannot be freely chosen here.
  192.      * </p>
  193.      * @param applyEOPCorr if true, EOP corrections are applied (here, nutation)
  194.      * @return the selected reference frame singleton.
  195.      */
  196.     FactoryManagedFrame getTOD(boolean applyEOPCorr);

  197.     /** Get the TOD reference frame.
  198.      * @param conventions IERS conventions to apply
  199.      * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
  200.      * @return the selected reference frame singleton.
  201.      */
  202.     FactoryManagedFrame getTOD(IERSConventions conventions,
  203.                                boolean simpleEOP);

  204.     /** Get the MOD reference frame.
  205.      * <p>
  206.      * The applyEOPCorr parameter is available mainly for testing purposes or for
  207.      * consistency with legacy software that don't handle EOP correction parameters.
  208.      * Beware that setting this parameter to {@code false} leads to crude accuracy
  209.      * (order of magnitudes for errors might be above 1m in LEO and 10m in GEO).
  210.      * For this reason, setting this parameter to false is restricted to {@link
  211.      * IERSConventions#IERS_1996 IERS 1996} conventions, and hence the {@link
  212.      * IERSConventions IERS conventions} cannot be freely chosen here.
  213.      * </p>
  214.      * @param applyEOPCorr if true, EOP corrections are applied (EME2000/GCRF bias compensation)
  215.      * @return the selected reference frame singleton.
  216.      */
  217.     FactoryManagedFrame getMOD(boolean applyEOPCorr);

  218.     /** Get the MOD reference frame.
  219.      * @param conventions IERS conventions to apply
  220.      * @return the selected reference frame singleton.
  221.      */
  222.     FactoryManagedFrame getMOD(IERSConventions conventions);

  223.     /** Get the TEME reference frame.
  224.      * <p>
  225.      * The TEME frame is used for the SGP4 model in TLE propagation. This frame has <em>no</em>
  226.      * official definition and there are some ambiguities about whether it should be used
  227.      * as "of date" or "of epoch". This frame should therefore be used <em>only</em> for
  228.      * TLE propagation and not for anything else, as recommended by the CCSDS Orbit Data Message
  229.      * blue book.
  230.      * </p>
  231.      * @return the selected reference frame singleton.
  232.      */
  233.     FactoryManagedFrame getTEME();

  234.     /** Get the PZ-90.11 (Parametry Zemly  – 1990.11) reference frame.
  235.      * <p>
  236.      * The PZ-90.11 reference system was updated on all operational
  237.      * GLONASS satellites starting from 3:00 pm on December 31, 2013.
  238.      * </p>
  239.      * <p>
  240.      * The transition between parent frame (ITRF-2008) and PZ-90.11 frame is performed using
  241.      * a seven parameters Helmert transformation.
  242.      * <pre>
  243.      *    From       To      ΔX(m)   ΔY(m)   ΔZ(m)   RX(mas)   RY(mas)  RZ(mas)   Epoch
  244.      * ITRF-2008  PZ-90.11  +0.003  +0.001  -0.000   +0.019    -0.042   +0.002     2010
  245.      * </pre>
  246.      * @see "Springer Handbook of Global Navigation Satellite Systems, Peter Teunissen & Oliver Montenbruck"
  247.      *
  248.      * @param convention IERS conventions to apply
  249.      * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
  250.      * @return the selected reference frame singleton.
  251.      */
  252.     FactoryManagedFrame getPZ9011(IERSConventions convention,
  253.                                   boolean simpleEOP);

  254.     /* Helpers for creating instances */

  255.     /**
  256.      * Create a set of frames from the given data.
  257.      *
  258.      * @param timeScales      used to build the frames as well as the EOP data set.
  259.      * @param celestialBodies used to get {@link #getICRF()} which is the inertial frame
  260.      *                        of the solar system barycenter.
  261.      * @return a set of reference frame constructed from the given data.
  262.      * @see #of(TimeScales, Supplier)
  263.      */
  264.     static Frames of(final TimeScales timeScales,
  265.                      final CelestialBodies celestialBodies) {
  266.         return of(timeScales, () -> celestialBodies.getSolarSystemBarycenter()
  267.                 .getInertiallyOrientedFrame());
  268.     }

  269.     /**
  270.      * Create a set of frames from the given data.
  271.      *
  272.      * @param timeScales   used to build the frames as well as the EOP data set.
  273.      * @param icrfSupplier used to get {@link #getICRF()}. For example, {@code
  274.      *                     celestialBodies.getSolarSystemBarycenter().getInertiallyOrientedFrame()}
  275.      * @return a set of reference frame constructed from the given data.
  276.      * @see CelestialBodies
  277.      * @see TimeScales#of(Collection, BiFunction)
  278.      */
  279.     static Frames of(final TimeScales timeScales,
  280.                      final Supplier<Frame> icrfSupplier) {
  281.         return new AbstractFrames(timeScales, icrfSupplier) {
  282.             @Override
  283.             public EOPHistory getEOPHistory(final IERSConventions conventions,
  284.                                             final boolean simpleEOP) {
  285.                 return getTimeScales().getUT1(conventions, simpleEOP).getEOPHistory();
  286.             }
  287.         };
  288.     }

  289. }