1 /* Copyright 2002-2018 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;
18
19 import java.io.Serializable;
20
21 import org.hipparchus.RealFieldElement;
22 import org.orekit.errors.OrekitException;
23 import org.orekit.errors.OrekitIllegalArgumentException;
24 import org.orekit.errors.OrekitMessages;
25 import org.orekit.time.AbsoluteDate;
26 import org.orekit.time.FieldAbsoluteDate;
27
28
29 /** Tridimensional references frames class.
30 *
31 * <h1> Frame Presentation </h1>
32 * <p>This class is the base class for all frames in OREKIT. The frames are
33 * linked together in a tree with some specific frame chosen as the root of the tree.
34 * Each frame is defined by {@link Transform transforms} combining any number
35 * of translations and rotations from a reference frame which is its
36 * parent frame in the tree structure.</p>
37 * <p>When we say a {@link Transform transform} t is <em>from frame<sub>A</sub>
38 * to frame<sub>B</sub></em>, we mean that if the coordinates of some absolute
39 * vector (say the direction of a distant star for example) has coordinates
40 * u<sub>A</sub> in frame<sub>A</sub> and u<sub>B</sub> in frame<sub>B</sub>,
41 * then u<sub>B</sub>={@link
42 * Transform#transformVector(org.hipparchus.geometry.euclidean.threed.Vector3D)
43 * t.transformVector(u<sub>A</sub>)}.
44 * <p>The transforms may be constant or varying, depending on the implementation of
45 * the {@link TransformProvider transform provider} used to define the frame. For simple
46 * fixed transforms, using {@link FixedTransformProvider} is sufficient. For varying
47 * transforms (time-dependent or telemetry-based for example), it may be useful to define
48 * specific implementations of {@link TransformProvider transform provider}.</p>
49 *
50 * @author Guylaine Prat
51 * @author Luc Maisonobe
52 * @author Pascal Parraud
53 */
54 public class Frame implements Serializable {
55
56 /** Serializable UID. */
57 private static final long serialVersionUID = -6981146543760234087L;
58
59 /** Parent frame (only the root frame doesn't have a parent). */
60 private final Frame parent;
61
62 /** Depth of the frame with respect to tree root. */
63 private final int depth;
64
65 /** Provider for transform from parent frame to instance. */
66 private final TransformProvider transformProvider;
67
68 /** Instance name. */
69 private final String name;
70
71 /** Indicator for pseudo-inertial frames. */
72 private final boolean pseudoInertial;
73
74 /** Private constructor used only for the root frame.
75 * @param name name of the frame
76 * @param pseudoInertial true if frame is considered pseudo-inertial
77 * (i.e. suitable for propagating orbit)
78 */
79 private Frame(final String name, final boolean pseudoInertial) {
80 parent = null;
81 depth = 0;
82 transformProvider = new FixedTransformProvider(Transform.IDENTITY);
83 this.name = name;
84 this.pseudoInertial = pseudoInertial;
85 }
86
87 /** Build a non-inertial frame from its transform with respect to its parent.
88 * <p>calling this constructor is equivalent to call
89 * <code>{link {@link #Frame(Frame, Transform, String, boolean)
90 * Frame(parent, transform, name, false)}</code>.</p>
91 * @param parent parent frame (must be non-null)
92 * @param transform transform from parent frame to instance
93 * @param name name of the frame
94 * @exception IllegalArgumentException if the parent frame is null
95 */
96 public Frame(final Frame parent, final Transform transform, final String name)
97 throws IllegalArgumentException {
98 this(parent, transform, name, false);
99 }
100
101 /** Build a non-inertial frame from its transform with respect to its parent.
102 * <p>calling this constructor is equivalent to call
103 * <code>{link {@link #Frame(Frame, Transform, String, boolean)
104 * Frame(parent, transform, name, false)}</code>.</p>
105 * @param parent parent frame (must be non-null)
106 * @param transformProvider provider for transform from parent frame to instance
107 * @param name name of the frame
108 * @exception IllegalArgumentException if the parent frame is null
109 */
110 public Frame(final Frame parent, final TransformProvider transformProvider, final String name)
111 throws IllegalArgumentException {
112 this(parent, transformProvider, name, false);
113 }
114
115 /** Build a frame from its transform with respect to its parent.
116 * <p>The convention for the transform is that it is from parent
117 * frame to instance. This means that the two following frames
118 * are similar:</p>
119 * <pre>
120 * Frame frame1 = new Frame(FramesFactory.getGCRF(), new Transform(t1, t2));
121 * Frame frame2 = new Frame(new Frame(FramesFactory.getGCRF(), t1), t2);
122 * </pre>
123 * @param parent parent frame (must be non-null)
124 * @param transform transform from parent frame to instance
125 * @param name name of the frame
126 * @param pseudoInertial true if frame is considered pseudo-inertial
127 * (i.e. suitable for propagating orbit)
128 * @exception IllegalArgumentException if the parent frame is null
129 */
130 public Frame(final Frame parent, final Transform transform, final String name,
131 final boolean pseudoInertial)
132 throws IllegalArgumentException {
133 this(parent, new FixedTransformProvider(transform), name, pseudoInertial);
134 }
135
136 /** Build a frame from its transform with respect to its parent.
137 * <p>The convention for the transform is that it is from parent
138 * frame to instance. This means that the two following frames
139 * are similar:</p>
140 * <pre>
141 * Frame frame1 = new Frame(FramesFactory.getGCRF(), new Transform(t1, t2));
142 * Frame frame2 = new Frame(new Frame(FramesFactory.getGCRF(), t1), t2);
143 * </pre>
144 * @param parent parent frame (must be non-null)
145 * @param transformProvider provider for transform from parent frame to instance
146 * @param name name of the frame
147 * @param pseudoInertial true if frame is considered pseudo-inertial
148 * (i.e. suitable for propagating orbit)
149 * @exception IllegalArgumentException if the parent frame is null
150 */
151 public Frame(final Frame parent, final TransformProvider transformProvider, final String name,
152 final boolean pseudoInertial)
153 throws IllegalArgumentException {
154
155 if (parent == null) {
156 throw new OrekitIllegalArgumentException(OrekitMessages.NULL_PARENT_FOR_FRAME, name);
157 }
158 this.parent = parent;
159 this.depth = parent.depth + 1;
160 this.transformProvider = transformProvider;
161 this.name = name;
162 this.pseudoInertial = pseudoInertial;
163
164 }
165
166 /** Get the name.
167 * @return the name
168 */
169 public String getName() {
170 return this.name;
171 }
172
173 /** Check if the frame is pseudo-inertial.
174 * <p>Pseudo-inertial frames are frames that do have a linear motion and
175 * either do not rotate or rotate at a very low rate resulting in
176 * neglectible inertial forces. This means they are suitable for orbit
177 * definition and propagation using Newtonian mechanics. Frames that are
178 * <em>not</em> pseudo-inertial are <em>not</em> suitable for orbit
179 * definition and propagation.</p>
180 * @return true if frame is pseudo-inertial
181 */
182 public boolean isPseudoInertial() {
183 return pseudoInertial;
184 }
185
186 /** New definition of the java.util toString() method.
187 * @return the name
188 */
189 public String toString() {
190 return this.name;
191 }
192
193 /** Get the parent frame.
194 * @return parent frame
195 */
196 public Frame getParent() {
197 return parent;
198 }
199
200 /** Get the depth of the frame.
201 * <p>
202 * The depth of a frame is the number of parents frame between
203 * it and the frames tree root. It is 0 for the root frame, and
204 * the depth of a frame is the depth of its parent frame plus one.
205 * </p>
206 * @return depth of the frame
207 */
208 public int getDepth() {
209 return depth;
210 }
211
212 /** Get the n<sup>th</sup> ancestor of the frame.
213 * @param n index of the ancestor (0 is the instance, 1 is its parent,
214 * 2 is the parent of its parent...)
215 * @return n<sup>th</sup> ancestor of the frame (must be between 0
216 * and the depth of the frame)
217 * @exception IllegalArgumentException if n is larger than the depth
218 * of the instance
219 */
220 public Frame getAncestor(final int n) throws IllegalArgumentException {
221
222 // safety check
223 if (n > depth) {
224 throw new OrekitIllegalArgumentException(OrekitMessages.FRAME_NO_NTH_ANCESTOR,
225 name, depth, n);
226 }
227
228 // go upward to find ancestor
229 Frame current = this;
230 for (int i = 0; i < n; ++i) {
231 current = current.parent;
232 }
233
234 return current;
235
236 }
237
238 /** Get the transform from the instance to another frame.
239 * @param destination destination frame to which we want to transform vectors
240 * @param date the date (can be null if it is sure than no date dependent frame is used)
241 * @return transform from the instance to the destination frame
242 * @exception OrekitException if some frame specific error occurs
243 */
244 public Transform getTransformTo(final Frame destination, final AbsoluteDate date)
245 throws OrekitException {
246
247 if (this == destination) {
248 // shortcut for special case that may be frequent
249 return Transform.IDENTITY;
250 }
251
252 // common ancestor to both frames in the frames tree
253 final Frame common = findCommon(this, destination);
254
255 // transform from common to instance
256 Transform commonToInstance = Transform.IDENTITY;
257 for (Frame frame = this; frame != common; frame = frame.parent) {
258 commonToInstance =
259 new Transform(date, frame.transformProvider.getTransform(date), commonToInstance);
260 }
261
262 // transform from destination up to common
263 Transform commonToDestination = Transform.IDENTITY;
264 for (Frame frame = destination; frame != common; frame = frame.parent) {
265 commonToDestination =
266 new Transform(date, frame.transformProvider.getTransform(date), commonToDestination);
267 }
268
269 // transform from instance to destination via common
270 return new Transform(date, commonToInstance.getInverse(), commonToDestination);
271
272 }
273
274 /** Get the transform from the instance to another frame.
275 * @param destination destination frame to which we want to transform vectors
276 * @param date the date (can be null if it is sure than no date dependent frame is used)
277 * @param <T> the type of the field elements
278 * @return transform from the instance to the destination frame
279 * @exception OrekitException if some frame specific error occurs
280 */
281 public <T extends RealFieldElement<T>> FieldTransform<T> getTransformTo(final Frame destination, final FieldAbsoluteDate<T> date)
282 throws OrekitException {
283
284 if (this == destination) {
285 // shortcut for special case that may be frequent
286 return FieldTransform.getIdentity(date.getField());
287 }
288
289 // common ancestor to both frames in the frames tree
290 final Frame common = findCommon(this, destination);
291
292 // transform from common to instance
293 FieldTransform<T> commonToInstance = FieldTransform.getIdentity(date.getField());
294 for (Frame frame = this; frame != common; frame = frame.parent) {
295 commonToInstance =
296 new FieldTransform<>(date, frame.transformProvider.getTransform(date), commonToInstance);
297 }
298
299 // transform from destination up to common
300 FieldTransform<T> commonToDestination = FieldTransform.getIdentity(date.getField());
301 for (Frame frame = destination; frame != common; frame = frame.parent) {
302 commonToDestination =
303 new FieldTransform<>(date, frame.transformProvider.getTransform(date), commonToDestination);
304 }
305
306 // transform from instance to destination via common
307 return new FieldTransform<>(date, commonToInstance.getInverse(), commonToDestination);
308
309 }
310
311 /** Get the provider for transform from parent frame to instance.
312 * @return provider for transform from parent frame to instance
313 */
314 public TransformProvider getTransformProvider() {
315 return transformProvider;
316 }
317
318 /** Find the deepest common ancestor of two frames in the frames tree.
319 * @param from origin frame
320 * @param to destination frame
321 * @return an ancestor frame of both <code>from</code> and <code>to</code>
322 */
323 private static Frame findCommon(final Frame from, final Frame to) {
324
325 // select deepest frames that could be the common ancestor
326 Frame currentF = from.depth > to.depth ? from.getAncestor(from.depth - to.depth) : from;
327 Frame currentT = from.depth > to.depth ? to : to.getAncestor(to.depth - from.depth);
328
329 // go upward until we find a match
330 while (currentF != currentT) {
331 currentF = currentF.parent;
332 currentT = currentT.parent;
333 }
334
335 return currentF;
336
337 }
338
339 /** Determine if a Frame is a child of another one.
340 * @param potentialAncestor supposed ancestor frame
341 * @return true if the potentialAncestor belongs to the
342 * path from instance to the root frame, excluding itself
343 */
344 public boolean isChildOf(final Frame potentialAncestor) {
345 if (depth <= potentialAncestor.depth) {
346 return false;
347 }
348 return getAncestor(depth - potentialAncestor.depth) == potentialAncestor;
349 }
350
351 /** Get the unique root frame.
352 * @return the unique instance of the root frame
353 */
354 protected static Frame getRoot() {
355 return LazyRootHolder.INSTANCE;
356 }
357
358 /** Get a new version of the instance, frozen with respect to a reference frame.
359 * <p>
360 * Freezing a frame consist in computing its position and orientation with respect
361 * to another frame at some freezing date and fixing them so they do not depend
362 * on time anymore. This means the frozen frame is fixed with respect to the
363 * reference frame.
364 * </p>
365 * <p>
366 * One typical use of this method is to compute an inertial launch reference frame
367 * by freezing a {@link TopocentricFrame topocentric frame} at launch date
368 * with respect to an inertial frame. Another use is to freeze an equinox-related
369 * celestial frame at a reference epoch date.
370 * </p>
371 * <p>
372 * Only the frame returned by this method is frozen, the instance by itself
373 * is not affected by calling this method and still moves freely.
374 * </p>
375 * @param reference frame with respect to which the instance will be frozen
376 * @param freezingDate freezing date
377 * @param frozenName name of the frozen frame
378 * @return a frozen version of the instance
379 * @exception OrekitException if transform between reference frame and instance
380 * cannot be computed at freezing frame
381 */
382 public Frame getFrozenFrame(final Frame reference, final AbsoluteDate freezingDate,
383 final String frozenName) throws OrekitException {
384 return new Frame(reference, reference.getTransformTo(this, freezingDate).freeze(),
385 frozenName, reference.isPseudoInertial());
386 }
387
388 // We use the Initialization on demand holder idiom to store
389 // the singletons, as it is both thread-safe, efficient (no
390 // synchronization) and works with all versions of java.
391
392 /** Holder for the root frame singleton. */
393 private static class LazyRootHolder {
394
395 /** Unique instance. */
396 private static final Frame INSTANCE = new Frame("GCRF", true) {
397
398 /** Serializable UID. */
399 private static final long serialVersionUID = -2654403496396721543L;
400
401 /** Replace the instance with a data transfer object for serialization.
402 * <p>
403 * This intermediate class serializes nothing.
404 * </p>
405 * @return data transfer object that will be serialized
406 */
407 private Object writeReplace() {
408 return new DataTransferObject();
409 }
410
411 };
412
413 /** Private constructor.
414 * <p>This class is a utility class, it should neither have a public
415 * nor a default constructor. This private constructor prevents
416 * the compiler from generating one automatically.</p>
417 */
418 private LazyRootHolder() {
419 }
420
421 }
422
423 /** Internal class used only for serialization. */
424 private static class DataTransferObject implements Serializable {
425
426 /** Serializable UID. */
427 private static final long serialVersionUID = 4067764035816491212L;
428
429 /** Simple constructor.
430 */
431 private DataTransferObject() {
432 }
433
434 /** Replace the deserialized data transfer object with a {@link FactoryManagedFrame}.
435 * @return replacement {@link FactoryManagedFrame}
436 */
437 private Object readResolve() {
438 return getRoot();
439 }
440
441 }
442
443 }