- /* Contributed in the public domain.
- * Licensed to CS GROUP (CS) under one or more
- * contributor license agreements. See the NOTICE file distributed with
- * this work for additional information regarding copyright ownership.
- * CS licenses this file to You under the Apache License, Version 2.0
- * (the "License"); you may not use this file except in compliance with
- * the License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
- package org.orekit.frames;
- import java.util.Collection;
- import java.util.function.BiFunction;
- import java.util.function.Supplier;
- import org.orekit.bodies.CelestialBodies;
- import org.orekit.time.TimeScales;
- import org.orekit.time.UT1Scale;
- import org.orekit.utils.IERSConventions;
- /**
- * A collection of commonly used {@link Frame}s. This interface defines methods for
- * obtaining instances of many commonly used reference frames.
- *
- * @author Guylaine Prat
- * @author Luc Maisonobe
- * @author Pascal Parraud
- * @author Evan Ward
- * @see FramesFactory
- * @since 10.0
- */
- public interface Frames {
- /** Get Earth Orientation Parameters history.
- * @param conventions conventions for which EOP history is requested
- * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
- * @return Earth Orientation Parameters history
- */
- EOPHistory getEOPHistory(IERSConventions conventions, boolean simpleEOP);
- /** Get one of the predefined frames.
- * @param factoryKey key of the frame within the factory
- * @return the predefined frame
- */
- Frame getFrame(Predefined factoryKey);
- /** Get the unique GCRF frame.
- * <p>The GCRF frame is the root frame in the frame tree.</p>
- * @return the unique instance of the GCRF frame
- */
- Frame getGCRF();
- /** Get the unique ICRF frame.
- * <p>The ICRF frame is centered at solar system barycenter and aligned
- * with GCRF.</p>
- * @return the unique instance of the ICRF frame
- */
- Frame getICRF();
- /** Get the ecliptic frame.
- * The IAU defines the ecliptic as "the plane perpendicular to the mean heliocentric
- * orbital angular momentum vector of the Earth-Moon barycentre in the BCRS (IAU 2006
- * Resolution B1)." The +z axis is aligned with the angular momentum vector, and the +x
- * axis is aligned with +x axis of {@link #getMOD(IERSConventions) MOD}.
- *
- * <p> This implementation agrees with the JPL 406 ephemerides to within 0.5 arc seconds.
- * @param conventions IERS conventions to apply
- * @return the selected reference frame singleton.
- */
- Frame getEcliptic(IERSConventions conventions);
- /** Get the unique EME2000 frame.
- * <p>The EME2000 frame is also called the J2000 frame.
- * The former denomination is preferred in Orekit.</p>
- * @return the unique instance of the EME2000 frame
- */
- FactoryManagedFrame getEME2000();
- /** Get an unspecified International Terrestrial Reference Frame.
- * <p>
- * The frame returned uses the {@link EOPEntry Earth Orientation Parameters}
- * blindly. So if for example one loads only EOP 14 C04 files to retrieve
- * the parameters, the frame will be an {@link ITRFVersion#ITRF_2014}. However,
- * if parameters are loaded from different files types, or even for file
- * types that changed their reference (like Bulletin A switching from
- * {@link ITRFVersion#ITRF_2008} to {@link ITRFVersion#ITRF_2014} starting
- * with Vol. XXXI No. 013 published on 2018-03-29), then the ITRF returned
- * by this method will jump from one version to another version.
- * </p>
- * <p>
- * IF a specific version of ITRF is needed, then {@link #getITRF(ITRFVersion,
- * IERSConventions, boolean)} should be used instead.
- * </p>
- * @param conventions IERS conventions to apply
- * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
- * @return the selected reference frame singleton.
- * @see #getITRF(ITRFVersion, IERSConventions, boolean)
- * @since 6.1
- */
- FactoryManagedFrame getITRF(IERSConventions conventions,
- boolean simpleEOP);
- /** Get the TIRF reference frame, ignoring tidal effects.
- * @param conventions IERS conventions to apply
- * @return the selected reference frame singleton.
- * library cannot be read.
- */
- FactoryManagedFrame getTIRF(IERSConventions conventions);
- /** Get an specific International Terrestrial Reference Frame.
- * <p>
- * Note that if a specific version of ITRF is required, then {@code simpleEOP}
- * should most probably be set to {@code false}, as ignoring tidal effects
- * has an effect of the same order of magnitude as the differences between
- * the various {@link ITRFVersion ITRF versions}.
- * </p>
- * @param version ITRF version
- * @param conventions IERS conventions to apply
- * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
- * @return the selected reference frame singleton.
- * @since 9.2
- */
- VersionedITRF getITRF(ITRFVersion version,
- IERSConventions conventions,
- boolean simpleEOP);
- /** Build an uncached International Terrestrial Reference Frame with specific {@link EOPHistory EOP history}.
- * <p>
- * This frame and its parent frames (TIRF and CIRF) will <em>not</em> be cached, they are
- * rebuilt from scratch each time this method is called. This factory method is intended
- * to be used when EOP history is changed at run time. For regular ITRF use, the
- * {@link #getITRF(IERSConventions, boolean)} and {link {@link #getITRF(ITRFVersion, IERSConventions, boolean)}
- * are more suitable.
- * </p>
- * @param ut1 UT1 time scale (contains the {@link EOPHistory EOP history})
- * @return an ITRF frame with specified time scale and embedded EOP history
- * @since 12.0
- */
- Frame buildUncachedITRF(UT1Scale ut1);
- /** Get the TIRF reference frame.
- * @param conventions IERS conventions to apply
- * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
- * @return the selected reference frame singleton.
- * @since 6.1
- */
- FactoryManagedFrame getTIRF(IERSConventions conventions,
- boolean simpleEOP);
- /** Get the CIRF2000 reference frame.
- * @param conventions IERS conventions to apply
- * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
- * @return the selected reference frame singleton.
- */
- FactoryManagedFrame getCIRF(IERSConventions conventions,
- boolean simpleEOP);
- /** Get the VEIS 1950 reference frame.
- * <p>Its parent frame is the GTOD frame with IERS 1996 conventions without EOP corrections.</p>
- * @return the selected reference frame singleton.
- */
- FactoryManagedFrame getVeis1950();
- /** Get the equinox-based ITRF reference frame.
- * @param conventions IERS conventions to apply
- * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
- * @return the selected reference frame singleton.
- * @since 6.1
- */
- FactoryManagedFrame getITRFEquinox(IERSConventions conventions,
- boolean simpleEOP);
- /** Get the GTOD reference frame.
- * <p>
- * The applyEOPCorr parameter is available mainly for testing purposes or for
- * consistency with legacy software that don't handle EOP correction parameters.
- * Beware that setting this parameter to {@code false} leads to crude accuracy
- * (order of magnitudes for errors might be above 250m in LEO and 1400m in GEO).
- * For this reason, setting this parameter to false is restricted to {@link
- * IERSConventions#IERS_1996 IERS 1996} conventions, and hence the {@link
- * IERSConventions IERS conventions} cannot be freely chosen here.
- * </p>
- * @param applyEOPCorr if true, EOP corrections are applied (here, dut1 and lod)
- * @return the selected reference frame singleton.
- */
- FactoryManagedFrame getGTOD(boolean applyEOPCorr);
- /** Get the GTOD reference frame.
- * @param conventions IERS conventions to apply
- * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
- * @return the selected reference frame singleton.
- */
- FactoryManagedFrame getGTOD(IERSConventions conventions,
- boolean simpleEOP);
- /** Get the TOD reference frame.
- * <p>
- * The applyEOPCorr parameter is available mainly for testing purposes or for
- * consistency with legacy software that don't handle EOP correction parameters.
- * Beware that setting this parameter to {@code false} leads to crude accuracy
- * (order of magnitudes for errors might be above 1m in LEO and 10m in GEO).
- * For this reason, setting this parameter to false is restricted to {@link
- * IERSConventions#IERS_1996 IERS 1996} conventions, and hence the {@link
- * IERSConventions IERS conventions} cannot be freely chosen here.
- * </p>
- * @param applyEOPCorr if true, EOP corrections are applied (here, nutation)
- * @return the selected reference frame singleton.
- */
- FactoryManagedFrame getTOD(boolean applyEOPCorr);
- /** Get the TOD reference frame.
- * @param conventions IERS conventions to apply
- * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
- * @return the selected reference frame singleton.
- */
- FactoryManagedFrame getTOD(IERSConventions conventions,
- boolean simpleEOP);
- /** Get the MOD reference frame.
- * <p>
- * The applyEOPCorr parameter is available mainly for testing purposes or for
- * consistency with legacy software that don't handle EOP correction parameters.
- * Beware that setting this parameter to {@code false} leads to crude accuracy
- * (order of magnitudes for errors might be above 1m in LEO and 10m in GEO).
- * For this reason, setting this parameter to false is restricted to {@link
- * IERSConventions#IERS_1996 IERS 1996} conventions, and hence the {@link
- * IERSConventions IERS conventions} cannot be freely chosen here.
- * </p>
- * @param applyEOPCorr if true, EOP corrections are applied (EME2000/GCRF bias compensation)
- * @return the selected reference frame singleton.
- */
- FactoryManagedFrame getMOD(boolean applyEOPCorr);
- /** Get the MOD reference frame.
- * @param conventions IERS conventions to apply
- * @return the selected reference frame singleton.
- */
- FactoryManagedFrame getMOD(IERSConventions conventions);
- /** Get the TEME reference frame.
- * <p>
- * The TEME frame is used for the SGP4 model in TLE propagation. This frame has <em>no</em>
- * official definition and there are some ambiguities about whether it should be used
- * as "of date" or "of epoch". This frame should therefore be used <em>only</em> for
- * TLE propagation and not for anything else, as recommended by the CCSDS Orbit Data Message
- * blue book.
- * </p>
- * @return the selected reference frame singleton.
- */
- FactoryManagedFrame getTEME();
- /** Get the PZ-90.11 (Parametry Zemly – 1990.11) reference frame.
- * <p>
- * The PZ-90.11 reference system was updated on all operational
- * GLONASS satellites starting from 3:00 pm on December 31, 2013.
- * </p>
- * <p>
- * The transition between parent frame (ITRF-2008) and PZ-90.11 frame is performed using
- * a seven parameters Helmert transformation.
- * <pre>
- * From To ΔX(m) ΔY(m) ΔZ(m) RX(mas) RY(mas) RZ(mas) Epoch
- * ITRF-2008 PZ-90.11 +0.003 +0.001 -0.000 +0.019 -0.042 +0.002 2010
- * </pre>
- * @see "Springer Handbook of Global Navigation Satellite Systems, Peter Teunissen & Oliver Montenbruck"
- *
- * @param convention IERS conventions to apply
- * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
- * @return the selected reference frame singleton.
- */
- FactoryManagedFrame getPZ9011(IERSConventions convention,
- boolean simpleEOP);
- /* Helpers for creating instances */
- /**
- * Create a set of frames from the given data.
- *
- * @param timeScales used to build the frames as well as the EOP data set.
- * @param celestialBodies used to get {@link #getICRF()} which is the inertial frame
- * of the solar system barycenter.
- * @return a set of reference frame constructed from the given data.
- * @see #of(TimeScales, Supplier)
- */
- static Frames of(final TimeScales timeScales,
- final CelestialBodies celestialBodies) {
- return of(timeScales, () -> celestialBodies.getSolarSystemBarycenter()
- .getInertiallyOrientedFrame());
- }
- /**
- * Create a set of frames from the given data.
- *
- * @param timeScales used to build the frames as well as the EOP data set.
- * @param icrfSupplier used to get {@link #getICRF()}. For example, {@code
- * celestialBodies.getSolarSystemBarycenter().getInertiallyOrientedFrame()}
- * @return a set of reference frame constructed from the given data.
- * @see CelestialBodies
- * @see TimeScales#of(Collection, BiFunction)
- */
- static Frames of(final TimeScales timeScales,
- final Supplier<Frame> icrfSupplier) {
- return new AbstractFrames(timeScales, icrfSupplier) {
- @Override
- public EOPHistory getEOPHistory(final IERSConventions conventions,
- final boolean simpleEOP) {
- return getTimeScales().getUT1(conventions, simpleEOP).getEOPHistory();
- }
- };
- }
- }