1 /* Copyright 2002-2025 CS GROUP
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.function.BiFunction;
20 import java.util.function.Function;
21
22 import org.hipparchus.CalculusFieldElement;
23 import org.hipparchus.FieldElement;
24 import org.orekit.errors.OrekitIllegalArgumentException;
25 import org.orekit.errors.OrekitMessages;
26 import org.orekit.time.AbsoluteDate;
27 import org.orekit.time.FieldAbsoluteDate;
28
29
30 /** Tridimensional references frames class.
31 *
32 * <h2> Frame Presentation </h2>
33 * <p>This class is the base class for all frames in OREKIT. The frames are
34 * linked together in a tree with some specific frame chosen as the root of the tree.
35 * Each frame is defined by {@link Transform transforms} combining any number
36 * of translations and rotations from a reference frame which is its
37 * parent frame in the tree structure.</p>
38 * <p>When we say a {@link Transform transform} t is <em>from frame<sub>A</sub>
39 * to frame<sub>B</sub></em>, we mean that if the coordinates of some absolute
40 * vector (say the direction of a distant star for example) has coordinates
41 * u<sub>A</sub> in frame<sub>A</sub> and u<sub>B</sub> in frame<sub>B</sub>,
42 * then u<sub>B</sub>={@link
43 * Transform#transformVector(org.hipparchus.geometry.euclidean.threed.Vector3D)
44 * t.transformVector(u<sub>A</sub>)}.
45 * <p>The transforms may be constant or varying, depending on the implementation of
46 * the {@link TransformProvider transform provider} used to define the frame. For simple
47 * fixed transforms, using {@link FixedTransformProvider} is sufficient. For varying
48 * transforms (time-dependent or telemetry-based for example), it may be useful to define
49 * specific implementations of {@link TransformProvider transform provider}.</p>
50 *
51 * @author Guylaine Prat
52 * @author Luc Maisonobe
53 * @author Pascal Parraud
54 */
55 public class Frame {
56
57 /** Parent frame (only the root frame doesn't have a parent). */
58 private final Frame parent;
59
60 /** Depth of the frame with respect to tree root. */
61 private final int depth;
62
63 /** Provider for transform from parent frame to instance. */
64 private final TransformProvider transformProvider;
65
66 /** Instance name. */
67 private final String name;
68
69 /** Indicator for pseudo-inertial frames. */
70 private final boolean pseudoInertial;
71
72 /** Cache for transforms with peer frame.
73 * @since 13.1
74 */
75 private final PeerCache peerCache;
76
77 /** Private constructor used only for the root frame.
78 * @param name name of the frame
79 * @param pseudoInertial true if frame is considered pseudo-inertial
80 * (i.e. suitable for propagating orbit)
81 */
82 private Frame(final String name, final boolean pseudoInertial) {
83 parent = null;
84 depth = 0;
85 transformProvider = new FixedTransformProvider(Transform.IDENTITY);
86 this.name = name;
87 this.pseudoInertial = pseudoInertial;
88 this.peerCache = new PeerCache(this);
89 }
90
91 /** Build a non-inertial frame from its transform with respect to its parent.
92 * <p>calling this constructor is equivalent to call
93 * <code>{link {@link #Frame(Frame, Transform, String, boolean)
94 * Frame(parent, transform, name, false)}</code>.</p>
95 * @param parent parent frame (must be non-null)
96 * @param transform transform from parent frame to instance
97 * @param name name of the frame
98 * @exception IllegalArgumentException if the parent frame is null
99 */
100 public Frame(final Frame parent, final Transform transform, final String name)
101 throws IllegalArgumentException {
102 this(parent, transform, name, false);
103 }
104
105 /** Build a non-inertial frame from its transform with respect to its parent.
106 * <p>calling this constructor is equivalent to call
107 * <code>{link {@link #Frame(Frame, Transform, String, boolean)
108 * Frame(parent, transform, name, false)}</code>.</p>
109 * @param parent parent frame (must be non-null)
110 * @param transformProvider provider for transform from parent frame to instance
111 * @param name name of the frame
112 * @exception IllegalArgumentException if the parent frame is null
113 */
114 public Frame(final Frame parent, final TransformProvider transformProvider, final String name)
115 throws IllegalArgumentException {
116 this(parent, transformProvider, name, false);
117 }
118
119 /** Build a frame from its transform with respect to its parent.
120 * <p>The convention for the transform is that it is from parent
121 * frame to instance. This means that the two following frames
122 * are similar:</p>
123 * <pre>
124 * Frame frame1 = new Frame(FramesFactory.getGCRF(), new Transform(t1, t2));
125 * Frame frame2 = new Frame(new Frame(FramesFactory.getGCRF(), t1), t2);
126 * </pre>
127 * @param parent parent frame (must be non-null)
128 * @param transform transform from parent frame to instance
129 * @param name name of the frame
130 * @param pseudoInertial true if frame is considered pseudo-inertial
131 * (i.e. suitable for propagating orbit)
132 * @exception IllegalArgumentException if the parent frame is null
133 */
134 public Frame(final Frame parent, final Transform transform, final String name,
135 final boolean pseudoInertial)
136 throws IllegalArgumentException {
137 this(parent, new FixedTransformProvider(transform), name, pseudoInertial);
138 }
139
140 /** Build a frame from its transform with respect to its parent.
141 * <p>The convention for the transform is that it is from parent
142 * frame to instance. This means that the two following frames
143 * are similar:</p>
144 * <pre>
145 * Frame frame1 = new Frame(FramesFactory.getGCRF(), new Transform(t1, t2));
146 * Frame frame2 = new Frame(new Frame(FramesFactory.getGCRF(), t1), t2);
147 * </pre>
148 * @param parent parent frame (must be non-null)
149 * @param transformProvider provider for transform from parent frame to instance
150 * @param name name of the frame
151 * @param pseudoInertial true if frame is considered pseudo-inertial
152 * (i.e. suitable for propagating orbit)
153 * @exception IllegalArgumentException if the parent frame is null
154 */
155 public Frame(final Frame parent, final TransformProvider transformProvider, final String name,
156 final boolean pseudoInertial)
157 throws IllegalArgumentException {
158
159 if (parent == null) {
160 throw new OrekitIllegalArgumentException(OrekitMessages.NULL_PARENT_FOR_FRAME, name);
161 }
162 this.parent = parent;
163 this.depth = parent.depth + 1;
164 this.transformProvider = transformProvider;
165 this.name = name;
166 this.pseudoInertial = pseudoInertial;
167 this.peerCache = new PeerCache(this);
168 }
169
170 /** Get the name.
171 * @return the name
172 */
173 public String getName() {
174 return this.name;
175 }
176
177 /** Check if the frame is pseudo-inertial.
178 * <p>Pseudo-inertial frames are frames that do have a linear motion and
179 * either do not rotate or rotate at a very low rate resulting in
180 * neglectible inertial forces. This means they are suitable for orbit
181 * definition and propagation using Newtonian mechanics. Frames that are
182 * <em>not</em> pseudo-inertial are <em>not</em> suitable for orbit
183 * definition and propagation.</p>
184 * @return true if frame is pseudo-inertial
185 */
186 public boolean isPseudoInertial() {
187 return pseudoInertial;
188 }
189
190 /** New definition of the java.util toString() method.
191 * @return the name
192 */
193 public String toString() {
194 return this.name;
195 }
196
197 /** Get the parent frame.
198 * @return parent frame
199 */
200 public Frame getParent() {
201 return parent;
202 }
203
204 /** Get the depth of the frame.
205 * <p>
206 * The depth of a frame is the number of parents frame between
207 * it and the frames tree root. It is 0 for the root frame, and
208 * the depth of a frame is the depth of its parent frame plus one.
209 * </p>
210 * @return depth of the frame
211 */
212 public int getDepth() {
213 return depth;
214 }
215
216 /** Get the n<sup>th</sup> ancestor of the frame.
217 * @param n index of the ancestor (0 is the instance, 1 is its parent,
218 * 2 is the parent of its parent...)
219 * @return n<sup>th</sup> ancestor of the frame (must be between 0
220 * and the depth of the frame)
221 * @exception IllegalArgumentException if n is larger than the depth
222 * of the instance
223 */
224 public Frame getAncestor(final int n) throws IllegalArgumentException {
225
226 // safety check
227 if (n > depth) {
228 throw new OrekitIllegalArgumentException(OrekitMessages.FRAME_NO_NTH_ANCESTOR,
229 name, depth, n);
230 }
231
232 // go upward to find ancestor
233 Frame current = this;
234 for (int i = 0; i < n; ++i) {
235 current = current.parent;
236 }
237
238 return current;
239
240 }
241
242 /** Associate this frame to a peer, caching transforms.
243 * <p>
244 * The cache is a LRU cache (Least Recently Used), so entries remain in
245 * the cache if they are used frequently, and only older entries
246 * that have not been accessed for a while will be expunged.
247 * </p>
248 * <p>
249 * Setting up a peer is mainly intended when there is a real need to speed up
250 * conversions in a context when the same frames (origin and destination) are
251 * used over and over again at the same date. One typical use case is to peer
252 * topocentric frames to the inertial frame when dealing with ground links
253 * as the conversion between a ground station (topocentric frame) and inertial
254 * frame will be needed for relative position computation, tropospheric effect
255 * computation, ionospheric effect computation, on all signal types and for
256 * all observables (code, phase, Doppler, signal strength…).
257 * </p>
258 * <p>
259 * Setting up peer caching does not change the result of the various
260 * {@code getTransformTo} methods, it just speeds up the computation in the
261 * case the same date is used over and over again between the instance and its
262 * peer. The computation is just fully performed the first time a date is used
263 * and the result is put in the cache before being returned. If a later call
264 * uses the same date again and there is a cache hit, then it will return the
265 * cached transform without any computation.
266 * </p>
267 * <p>
268 * The peer frame doesn't need to be close to the initial frame in the hierarchical
269 * frames tree, and there is no transitivity involved: peering is a point-to-point
270 * relationship. It is for example possible to peer a topocentric frame to the
271 * EME2000 frame despite there are several intermediate frames involved when
272 * computing the transform (topocentric → ITRF → TIRF → CIRF → GCRF → EME2000), the
273 * link will be a direct one and what will be cached at each date is the transform
274 * resulting from the combination of all transforms between the intermediate frames
275 * at this date. We could have at the same time the intermediate ITRF frame peered
276 * to another frame not belonging to this list, it won't have any influence,
277 * peering is really point-to-point.
278 * </p>
279 * <p>
280 * Peering is unidirectional, i.e. if {@code frameA} is peered to {@code frameB},
281 * it means the transforms that will be cached are the transforms from {@code frameA}
282 * (the instance when this method or the {@link #getTransformTo(Frame, AbsoluteDate)
283 * getTransformTo} method are called) to {@code frameB} (the argument when this
284 * method or the {@link #getTransformTo(Frame, AbsoluteDate) getTransformTo} method
285 * are called). It is therefore possible to have {@code frameA} peered to {@code frameB}
286 * and {@code frameB} peered to another {@code frameC} or no frames at all.
287 * This allows several frames to be peered to a shared pivot one (typically Earth
288 * frame and many topocentric frames all peered to one inertial frame). The side
289 * effect of this choice is that peering improves efficiency only in one direction,
290 * i.e. if {@code frameA} is peered to {@code frameB}, then computing the transform
291 * from {@code frameB} to {@code frameA} should be done by computing transform from
292 * {@code frameA} to {@code frameB} and then inverting rather than directly computing
293 * the transform from {@code frameB} to {@code frameA}. It is of course possible to
294 * peer {@code frameA} to {@code frameB} and also {@code frameB} to {@code frameA},
295 * but this prevents using a shared pivot frame.
296 * </p>
297 * <p>
298 * Peering is generally set up at the start of the application and kept unchanged
299 * throughout its operation, but nothing prevents to change it on the fly, even
300 * from different threads. Peering is thread-safe, but shared among all threads
301 * (there are internal locks to ensure thread safety), so peering is often set up
302 * on a main thread and then used on several other threads, like for example in
303 * parallel propagation contexts.
304 * </p>
305 * <p>
306 * Peering is optional; when a frame is first created, it is not peered to any
307 * other frames.
308 * </p>
309 * <p>
310 * When peering has been set up, caching is enabled for all transforms computed
311 * from the instance to its peer, i.e. {@link #getTransformTo(Frame, AbsoluteDate)
312 * regular transforms}, {@link #getTransformTo(Frame, FieldAbsoluteDate) field transforms},
313 * {@link #getKinematicTransformTo(Frame, AbsoluteDate) regular kinematic transforms},
314 * {@link #getKinematicTransformTo(Frame, FieldAbsoluteDate) field kinematic transforms},
315 * {@link #getStaticTransformTo(Frame, AbsoluteDate) regular static transforms},
316 * {@link #getStaticTransformTo(Frame, FieldAbsoluteDate) field static transforms}.
317 * It is not possible to set different cached for different transforms types.
318 * </p>
319 * <p>
320 * If a peer was already associated to this frame, it will be overridden. This
321 * can be used to clear peering by setting the peer to {@code null} and avoid
322 * keeping a reference to a frame that is not used anymore, hence allowing it to
323 * be garbage collected.
324 * </p>
325 * @param peer peer frame (null to clear the cache)
326 * @param cacheSize number of transforms kept in the date-based cache
327 * @since 13.0.3
328 */
329 public void setPeerCaching(final Frame peer, final int cacheSize) {
330 peerCache.setPeerCaching(peer, cacheSize);
331 }
332
333 /** Get the peer associated to this frame.
334 * @return peer associated with this frame, null if not peered at all
335 * @since 13.0.3
336 */
337 public Frame getPeer() {
338 return peerCache.getPeer();
339 }
340
341 /** Get the transform from the instance to another frame.
342 * @param destination destination frame to which we want to transform vectors
343 * @param date the date (can be null if it is certain that no date dependent frame is used)
344 * @return transform from the instance to the destination frame
345 */
346 public Transform getTransformTo(final Frame destination, final AbsoluteDate date) {
347 final CachedTransformProvider cachedProvider = peerCache.getCachedTransformProvider(destination);
348 if (cachedProvider != null) {
349 // this is our peer, we must cache the transform
350 return cachedProvider.getTransform(date);
351 } else {
352 // not our peer, just compute the transform and forget about it
353 return getTransformTo(
354 destination,
355 Transform.IDENTITY,
356 frame -> frame.getTransformProvider().getTransform(date),
357 (t1, t2) -> new Transform(date, t1, t2),
358 Transform::getInverse);
359 }
360 }
361
362 /** Get the transform from the instance to another frame.
363 * @param destination destination frame to which we want to transform vectors
364 * @param date the date (<em>must</em> be non-null, which is a more stringent condition
365 * than in {@link #getTransformTo(Frame, FieldAbsoluteDate)})
366 * @param <T> the type of the field elements
367 * @return transform from the instance to the destination frame
368 */
369 public <T extends CalculusFieldElement<T>> FieldTransform<T> getTransformTo(final Frame destination,
370 final FieldAbsoluteDate<T> date) {
371 final FieldCachedTransformProvider<T> cachedProvider = peerCache.getCachedTransformProvider(destination, date.getField());
372 if (cachedProvider != null) {
373 // this is our peer, we must cache the transform
374 return cachedProvider.getTransform(date);
375 } else {
376 // not our peer, just compute the transform and forget about it
377 if (date.hasZeroField()) {
378 return new FieldTransform<>(date.getField(), getTransformTo(destination, date.toAbsoluteDate()));
379 }
380
381 return getTransformTo(destination,
382 FieldTransform.getIdentity(date.getField()),
383 frame -> frame.getTransformProvider().getTransform(date),
384 (t1, t2) -> new FieldTransform<>(date, t1, t2),
385 FieldTransform::getInverse);
386 }
387 }
388
389 /**
390 * Get the kinematic portion of the transform from the instance to another
391 * frame. The returned transform is kinematic in the sense that it includes
392 * translations and rotations, with rates, but cannot transform an acceleration vector.
393 *
394 * <p>This method is often more performant than {@link
395 * #getTransformTo(Frame, AbsoluteDate)} when accelerations are not needed.
396 *
397 * @param destination destination frame to which we want to transform
398 * vectors
399 * @param date the date (can be null if it is sure than no date
400 * dependent frame is used)
401 * @return kinematic transform from the instance to the destination frame
402 * @since 12.1
403 */
404 public KinematicTransform getKinematicTransformTo(final Frame destination, final AbsoluteDate date) {
405 final CachedTransformProvider cachedProvider = peerCache.getCachedTransformProvider(destination);
406 if (cachedProvider != null) {
407 // this is our peer, we must cache the transform
408 return cachedProvider.getKinematicTransform(date);
409 } else {
410 // not our peer, just compute the transform and forget about it
411 return getTransformTo(
412 destination,
413 KinematicTransform.getIdentity(),
414 frame -> frame.getTransformProvider().getKinematicTransform(date),
415 (t1, t2) -> KinematicTransform.compose(date, t1, t2),
416 KinematicTransform::getInverse);
417 }
418 }
419
420 /**
421 * Get the static portion of the transform from the instance to another
422 * frame. The returned transform is static in the sense that it includes
423 * translations and rotations, but not rates.
424 *
425 * <p>This method is often more performant than {@link
426 * #getTransformTo(Frame, AbsoluteDate)} when rates are not needed.
427 *
428 * @param destination destination frame to which we want to transform
429 * vectors
430 * @param date the date (can be null if it is sure than no date
431 * dependent frame is used)
432 * @return static transform from the instance to the destination frame
433 * @since 11.2
434 */
435 public StaticTransform getStaticTransformTo(final Frame destination,
436 final AbsoluteDate date) {
437 final CachedTransformProvider cachedProvider = peerCache.getCachedTransformProvider(destination);
438 if (cachedProvider != null) {
439 // this is our peer, we must cache the transform
440 return cachedProvider.getStaticTransform(date);
441 }
442 else {
443 // not our peer, just compute the transform and forget about it
444 return getTransformTo(
445 destination,
446 StaticTransform.getIdentity(),
447 frame -> frame.getTransformProvider().getStaticTransform(date),
448 (t1, t2) -> StaticTransform.compose(date, t1, t2),
449 StaticTransform::getInverse);
450 }
451 }
452
453 /**
454 * Get the static portion of the transform from the instance to another
455 * frame. The returned transform is static in the sense that it includes
456 * translations and rotations, but not rates.
457 *
458 * <p>This method is often more performant than {@link
459 * #getTransformTo(Frame, FieldAbsoluteDate)} when rates are not needed.
460 *
461 * <p>A first check is made on the FieldAbsoluteDate because "fielded" transforms have low-performance.<br>
462 * The date field is checked with {@link FieldElement#isZero()}.<br>
463 * If true, the un-fielded version of the transform computation is used.
464 *
465 * @param <T> type of the elements
466 * @param destination destination frame to which we want to transform
467 * vectors
468 * @param date the date (<em>must</em> be non-null, which is a more stringent condition
469 * than in {@link #getStaticTransformTo(Frame, AbsoluteDate)})
470 * @return static transform from the instance to the destination frame
471 * @since 12.0
472 */
473 public <T extends CalculusFieldElement<T>> FieldStaticTransform<T> getStaticTransformTo(final Frame destination,
474 final FieldAbsoluteDate<T> date) {
475 final FieldCachedTransformProvider<T> cachedProvider = peerCache.getCachedTransformProvider(destination, date.getField());
476 if (cachedProvider != null) {
477 return cachedProvider.getStaticTransform(date);
478 } else {
479 // not our peer, just compute the transform and forget about it
480 if (date.hasZeroField()) {
481 // If date field is Zero, then use the un-fielded version for performances
482 return FieldStaticTransform.of(date, getStaticTransformTo(destination, date.toAbsoluteDate()));
483
484 }
485 else {
486 // Use classic fielded function
487 return getTransformTo(destination,
488 FieldStaticTransform.getIdentity(date.getField()),
489 frame -> frame.getTransformProvider().getStaticTransform(date),
490 (t1, t2) -> FieldStaticTransform.compose(date, t1, t2),
491 FieldStaticTransform::getInverse);
492 }
493 }
494 }
495
496 /**
497 * Get the kinematic portion of the transform from the instance to another
498 * frame. The returned transform is kinematic in the sense that it includes
499 * translations and rotations, with rates, but cannot transform an acceleration vector.
500 *
501 * <p>This method is often more performant than {@link
502 * #getTransformTo(Frame, AbsoluteDate)} when accelerations are not needed.
503 * @param <T> Type of transform returned.
504 * @param destination destination frame to which we want to transform
505 * vectors
506 * @param date the date (<em>must</em> be non-null, which is a more stringent condition
507 * * than in {@link #getKinematicTransformTo(Frame, AbsoluteDate)})
508 * @return kinematic transform from the instance to the destination frame
509 * @since 12.1
510 */
511 public <T extends CalculusFieldElement<T>> FieldKinematicTransform<T> getKinematicTransformTo(final Frame destination,
512 final FieldAbsoluteDate<T> date) {
513 final FieldCachedTransformProvider<T> cachedProvider = peerCache.getCachedTransformProvider(destination, date.getField());
514 if (cachedProvider != null) {
515 return cachedProvider.getKinematicTransform(date);
516 }
517 else {
518 // not our peer, just compute the transform and forget about it
519 if (date.hasZeroField()) {
520 // If date field is Zero, then use the un-fielded version for performances
521 final KinematicTransform kinematicTransform = getKinematicTransformTo(destination, date.toAbsoluteDate());
522 return FieldKinematicTransform.of(date.getField(), kinematicTransform);
523
524 }
525 else {
526 // Use classic fielded function
527 return getTransformTo(destination,
528 FieldKinematicTransform.getIdentity(date.getField()),
529 frame -> frame.getTransformProvider().getKinematicTransform(date),
530 (t1, t2) -> FieldKinematicTransform.compose(date, t1, t2),
531 FieldKinematicTransform::getInverse);
532 }
533 }
534 }
535
536 /**
537 * Generic get transform method that builds the transform from {@code this}
538 * to {@code destination}.
539 *
540 * @param destination destination frame to which we want to transform
541 * vectors
542 * @param identity transform of the given type.
543 * @param getTransform method to get a transform from a frame.
544 * @param compose method to combine two transforms.
545 * @param inverse method to invert a transform.
546 * @param <T> Type of transform returned.
547 * @return composite transform.
548 */
549 <T> T getTransformTo(final Frame destination,
550 final T identity,
551 final Function<Frame, T> getTransform,
552 final BiFunction<T, T, T> compose,
553 final Function<T, T> inverse) {
554
555 if (this == destination) {
556 // shortcut for special case that may be frequent
557 return identity;
558 }
559
560 // common ancestor to both frames in the frames tree
561 final Frame common = findCommon(this, destination);
562
563 // transform from common to instance
564 T commonToInstance = identity;
565 for (Frame frame = this; frame != common; frame = frame.parent) {
566 commonToInstance = compose.apply(getTransform.apply(frame), commonToInstance);
567 }
568
569 // transform from destination up to common
570 T commonToDestination = identity;
571 for (Frame frame = destination; frame != common; frame = frame.parent) {
572 commonToDestination = compose.apply(getTransform.apply(frame), commonToDestination);
573 }
574
575 // transform from instance to destination via common
576 return compose.apply(inverse.apply(commonToInstance), commonToDestination);
577
578 }
579
580 /** Get the provider for transform from parent frame to instance.
581 * @return provider for transform from parent frame to instance
582 */
583 public TransformProvider getTransformProvider() {
584 return transformProvider;
585 }
586
587 /** Find the deepest common ancestor of two frames in the frames tree.
588 * @param from origin frame
589 * @param to destination frame
590 * @return an ancestor frame of both <code>from</code> and <code>to</code>
591 */
592 private static Frame findCommon(final Frame from, final Frame to) {
593
594 // select deepest frames that could be the common ancestor
595 Frame currentF = from.depth > to.depth ? from.getAncestor(from.depth - to.depth) : from;
596 Frame currentT = from.depth > to.depth ? to : to.getAncestor(to.depth - from.depth);
597
598 // go upward until we find a match
599 while (currentF != currentT) {
600 currentF = currentF.parent;
601 currentT = currentT.parent;
602 }
603
604 return currentF;
605
606 }
607
608 /** Determine if a Frame is a child of another one.
609 * @param potentialAncestor supposed ancestor frame
610 * @return true if the potentialAncestor belongs to the
611 * path from instance to the root frame, excluding itself
612 */
613 public boolean isChildOf(final Frame potentialAncestor) {
614 if (depth <= potentialAncestor.depth) {
615 return false;
616 }
617 return getAncestor(depth - potentialAncestor.depth) == potentialAncestor;
618 }
619
620 /** Get the unique root frame.
621 * @return the unique instance of the root frame
622 */
623 public static Frame getRoot() {
624 return LazyRootHolder.INSTANCE;
625 }
626
627 /** Get a new version of the instance, frozen with respect to a reference frame.
628 * <p>
629 * Freezing a frame consist in computing its position and orientation with respect
630 * to another frame at some freezing date and fixing them so they do not depend
631 * on time anymore. This means the frozen frame is fixed with respect to the
632 * reference frame.
633 * </p>
634 * <p>
635 * One typical use of this method is to compute an inertial launch reference frame
636 * by freezing a {@link TopocentricFrame topocentric frame} at launch date
637 * with respect to an inertial frame. Another use is to freeze an equinox-related
638 * celestial frame at a reference epoch date.
639 * </p>
640 * <p>
641 * Only the frame returned by this method is frozen, the instance by itself
642 * is not affected by calling this method and still moves freely.
643 * </p>
644 * @param reference frame with respect to which the instance will be frozen
645 * @param freezingDate freezing date
646 * @param frozenName name of the frozen frame
647 * @return a frozen version of the instance
648 */
649 public Frame getFrozenFrame(final Frame reference, final AbsoluteDate freezingDate,
650 final String frozenName) {
651 return new Frame(reference, reference.getTransformTo(this, freezingDate).freeze(),
652 frozenName, reference.isPseudoInertial());
653 }
654
655 // We use the Initialization on demand holder idiom to store
656 // the singletons, as it is both thread-safe, efficient (no
657 // synchronization) and works with all versions of java.
658
659 /** Holder for the root frame singleton. */
660 private static class LazyRootHolder {
661
662 /** Unique instance. */
663 private static final Frame INSTANCE = new Frame(Predefined.GCRF.getName(), true) { };
664
665 /** Private constructor.
666 * <p>This class is a utility class, it should neither have a public
667 * nor a default constructor. This private constructor prevents
668 * the compiler from generating one automatically.</p>
669 */
670 private LazyRootHolder() {
671 }
672
673 }
674
675 }