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;

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

  23. import org.orekit.bodies.CelestialBodies;
  24. import org.orekit.time.TimeScales;
  25. import org.orekit.utils.IERSConventions;

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

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

  47.     /** Get one of the predefined frames.
  48.      * @param factoryKey key of the frame within the factory
  49.      * @return the predefined frame
  50.      */
  51.     Frame getFrame(Predefined factoryKey);

  53.     /** Get the unique GCRF frame.
  54.      * <p>The GCRF frame is the root frame in the frame tree.</p>
  55.      * @return the unique instance of the GCRF frame
  56.      */
  57.     Frame getGCRF();

  59.     /** Get the unique ICRF frame.
  60.      * <p>The ICRF frame is centered at solar system barycenter and aligned
  61.      * with GCRF.</p>
  62.      * @return the unique instance of the ICRF frame
  63.      */
  64.     Frame getICRF();

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

  78.     /** Get the unique EME2000 frame.
  79.      * <p>The EME2000 frame is also called the J2000 frame.
  80.      * The former denomination is preferred in Orekit.</p>
  81.      * @return the unique instance of the EME2000 frame
  82.      */
  83.     FactoryManagedFrame getEME2000();

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

  109.     /** Get the TIRF reference frame, ignoring tidal effects.
  110.      * @param conventions IERS conventions to apply
  111.      * @return the selected reference frame singleton.
  112.      * library cannot be read.
  113.      */
  114.     FactoryManagedFrame getTIRF(IERSConventions conventions);

  116.     /** Get an specific International Terrestrial Reference Frame.
  117.      * <p>
  118.      * Note that if a specific version of ITRF is required, then {@code simpleEOP}
  119.      * should most probably be set to {@code false}, as ignoring tidal effects
  120.      * has an effect of the same order of magnitude as the differences between
  121.      * the various {@link ITRFVersion ITRF versions}.
  122.      * </p>
  123.      * @param version ITRF version
  124.      * @param conventions IERS conventions to apply
  125.      * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
  126.      * @return the selected reference frame singleton.
  127.      * @since 9.2
  128.      */
  129.     VersionedITRF getITRF(ITRFVersion version,
  130.                           IERSConventions conventions,
  131.                           boolean simpleEOP);

  133.     /** Get the TIRF reference frame.
  134.      * @param conventions IERS conventions to apply
  135.      * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
  136.      * @return the selected reference frame singleton.
  137.      * @since 6.1
  138.      */
  139.     FactoryManagedFrame getTIRF(IERSConventions conventions,
  140.                                 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);

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

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

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

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

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

  203.     /** Get the TOD reference frame.
  204.      * @param conventions IERS conventions to apply
  205.      * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
  206.      * @return the selected reference frame singleton.
  207.      */
  208.     FactoryManagedFrame getTOD(IERSConventions conventions,
  209.                                boolean simpleEOP);

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

  226.     /** Get the MOD reference frame.
  227.      * @param conventions IERS conventions to apply
  228.      * @return the selected reference frame singleton.
  229.      */
  230.     FactoryManagedFrame getMOD(IERSConventions conventions);

  232.     /** Get the TEME reference frame.
  233.      * <p>
  234.      * The TEME frame is used for the SGP4 model in TLE propagation. This frame has <em>no</em>
  235.      * official definition and there are some ambiguities about whether it should be used
  236.      * as "of date" or "of epoch". This frame should therefore be used <em>only</em> for
  237.      * TLE propagation and not for anything else, as recommended by the CCSDS Orbit Data Message
  238.      * blue book.
  239.      * </p>
  240.      * @return the selected reference frame singleton.
  241.      */
  242.     FactoryManagedFrame getTEME();

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

  265.     /* Helpers for creating instances */

  267.     /**
  268.      * Create a set of frames from the given data.
  269.      *
  270.      * @param timeScales      used to build the frames as well as the EOP data set.
  271.      * @param celestialBodies used to get {@link #getICRF()} which is the inertial frame
  272.      *                        of the solar system barycenter.
  273.      * @return a set of reference frame constructed from the given data.
  274.      * @see #of(TimeScales, Supplier)
  275.      */
  276.     static Frames of(final TimeScales timeScales,
  277.                      final CelestialBodies celestialBodies) {
  278.         return of(timeScales, () -> celestialBodies.getSolarSystemBarycenter()
  279.                 .getInertiallyOrientedFrame());
  280.     }

  282.     /**
  283.      * Create a set of frames from the given data.
  284.      *
  285.      * @param timeScales   used to build the frames as well as the EOP data set.
  286.      * @param icrfSupplier used to get {@link #getICRF()}. For example, {@code
  287.      *                     celestialBodies.getSolarSystemBarycenter().getInertiallyOrientedFrame()}
  288.      * @return a set of reference frame constructed from the given data.
  289.      * @see CelestialBodies
  290.      * @see TimeScales#of(Collection, BiFunction)
  291.      */
  292.     static Frames of(final TimeScales timeScales,
  293.                      final Supplier<Frame> icrfSupplier) {
  294.         return new AbstractFrames(timeScales, icrfSupplier) {
  295.             @Override
  296.             public EOPHistory getEOPHistory(final IERSConventions conventions,
  297.                                             final boolean simpleEOP) {
  298.                 return getTimeScales().getUT1(conventions, simpleEOP).getEOPHistory();
  299.             }
  300.         };
  301.     }

  303. }
Created with JaCoCo 0.8.8.202204050719