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  
19  import java.util.Collection;
20  import java.util.function.BiFunction;
21  import java.util.function.Supplier;
22  
23  import org.orekit.bodies.CelestialBodies;
24  import org.orekit.time.TimeScales;
25  import org.orekit.utils.IERSConventions;
26  
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 {
39  
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);
46  
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);
52  
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();
58  
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();
65  
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);
77  
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();
84  
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);
108 
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);
115 
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);
132 
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);
141 
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 
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();
155 
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);
164 
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);
179 
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);
187 
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);
202 
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);
210 
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);
225 
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);
231 
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();
243 
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);
264 
265     /* Helpers for creating instances */
266 
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     }
281 
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     }
302 
303 }