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 /** Private constructor used only for the root frame.
73 * @param name name of the frame
74 * @param pseudoInertial true if frame is considered pseudo-inertial
75 * (i.e. suitable for propagating orbit)
76 */
77 private Frame(final String name, final boolean pseudoInertial) {
78 parent = null;
79 depth = 0;
80 transformProvider = new FixedTransformProvider(Transform.IDENTITY);
81 this.name = name;
82 this.pseudoInertial = pseudoInertial;
83 }
84
85 /** Build a non-inertial frame from its transform with respect to its parent.
86 * <p>calling this constructor is equivalent to call
87 * <code>{link {@link #Frame(Frame, Transform, String, boolean)
88 * Frame(parent, transform, name, false)}</code>.</p>
89 * @param parent parent frame (must be non-null)
90 * @param transform transform from parent frame to instance
91 * @param name name of the frame
92 * @exception IllegalArgumentException if the parent frame is null
93 */
94 public Frame(final Frame parent, final Transform transform, final String name)
95 throws IllegalArgumentException {
96 this(parent, transform, name, false);
97 }
98
99 /** Build a non-inertial frame from its transform with respect to its parent.
100 * <p>calling this constructor is equivalent to call
101 * <code>{link {@link #Frame(Frame, Transform, String, boolean)
102 * Frame(parent, transform, name, false)}</code>.</p>
103 * @param parent parent frame (must be non-null)
104 * @param transformProvider provider for transform from parent frame to instance
105 * @param name name of the frame
106 * @exception IllegalArgumentException if the parent frame is null
107 */
108 public Frame(final Frame parent, final TransformProvider transformProvider, final String name)
109 throws IllegalArgumentException {
110 this(parent, transformProvider, name, false);
111 }
112
113 /** Build a frame from its transform with respect to its parent.
114 * <p>The convention for the transform is that it is from parent
115 * frame to instance. This means that the two following frames
116 * are similar:</p>
117 * <pre>
118 * Frame frame1 = new Frame(FramesFactory.getGCRF(), new Transform(t1, t2));
119 * Frame frame2 = new Frame(new Frame(FramesFactory.getGCRF(), t1), t2);
120 * </pre>
121 * @param parent parent frame (must be non-null)
122 * @param transform transform from parent frame to instance
123 * @param name name of the frame
124 * @param pseudoInertial true if frame is considered pseudo-inertial
125 * (i.e. suitable for propagating orbit)
126 * @exception IllegalArgumentException if the parent frame is null
127 */
128 public Frame(final Frame parent, final Transform transform, final String name,
129 final boolean pseudoInertial)
130 throws IllegalArgumentException {
131 this(parent, new FixedTransformProvider(transform), name, pseudoInertial);
132 }
133
134 /** Build a frame from its transform with respect to its parent.
135 * <p>The convention for the transform is that it is from parent
136 * frame to instance. This means that the two following frames
137 * are similar:</p>
138 * <pre>
139 * Frame frame1 = new Frame(FramesFactory.getGCRF(), new Transform(t1, t2));
140 * Frame frame2 = new Frame(new Frame(FramesFactory.getGCRF(), t1), t2);
141 * </pre>
142 * @param parent parent frame (must be non-null)
143 * @param transformProvider provider for transform from parent frame to instance
144 * @param name name of the frame
145 * @param pseudoInertial true if frame is considered pseudo-inertial
146 * (i.e. suitable for propagating orbit)
147 * @exception IllegalArgumentException if the parent frame is null
148 */
149 public Frame(final Frame parent, final TransformProvider transformProvider, final String name,
150 final boolean pseudoInertial)
151 throws IllegalArgumentException {
152
153 if (parent == null) {
154 throw new OrekitIllegalArgumentException(OrekitMessages.NULL_PARENT_FOR_FRAME, name);
155 }
156 this.parent = parent;
157 this.depth = parent.depth + 1;
158 this.transformProvider = transformProvider;
159 this.name = name;
160 this.pseudoInertial = pseudoInertial;
161
162 }
163
164 /** Get the name.
165 * @return the name
166 */
167 public String getName() {
168 return this.name;
169 }
170
171 /** Check if the frame is pseudo-inertial.
172 * <p>Pseudo-inertial frames are frames that do have a linear motion and
173 * either do not rotate or rotate at a very low rate resulting in
174 * neglectible inertial forces. This means they are suitable for orbit
175 * definition and propagation using Newtonian mechanics. Frames that are
176 * <em>not</em> pseudo-inertial are <em>not</em> suitable for orbit
177 * definition and propagation.</p>
178 * @return true if frame is pseudo-inertial
179 */
180 public boolean isPseudoInertial() {
181 return pseudoInertial;
182 }
183
184 /** New definition of the java.util toString() method.
185 * @return the name
186 */
187 public String toString() {
188 return this.name;
189 }
190
191 /** Get the parent frame.
192 * @return parent frame
193 */
194 public Frame getParent() {
195 return parent;
196 }
197
198 /** Get the depth of the frame.
199 * <p>
200 * The depth of a frame is the number of parents frame between
201 * it and the frames tree root. It is 0 for the root frame, and
202 * the depth of a frame is the depth of its parent frame plus one.
203 * </p>
204 * @return depth of the frame
205 */
206 public int getDepth() {
207 return depth;
208 }
209
210 /** Get the n<sup>th</sup> ancestor of the frame.
211 * @param n index of the ancestor (0 is the instance, 1 is its parent,
212 * 2 is the parent of its parent...)
213 * @return n<sup>th</sup> ancestor of the frame (must be between 0
214 * and the depth of the frame)
215 * @exception IllegalArgumentException if n is larger than the depth
216 * of the instance
217 */
218 public Frame getAncestor(final int n) throws IllegalArgumentException {
219
220 // safety check
221 if (n > depth) {
222 throw new OrekitIllegalArgumentException(OrekitMessages.FRAME_NO_NTH_ANCESTOR,
223 name, depth, n);
224 }
225
226 // go upward to find ancestor
227 Frame current = this;
228 for (int i = 0; i < n; ++i) {
229 current = current.parent;
230 }
231
232 return current;
233
234 }
235
236 /** Get the transform from the instance to another frame.
237 * @param destination destination frame to which we want to transform vectors
238 * @param date the date (can be null if it is sure than no date dependent frame is used)
239 * @return transform from the instance to the destination frame
240 */
241 public Transform getTransformTo(final Frame destination, final AbsoluteDate date) {
242 return getTransformTo(
243 destination,
244 Transform.IDENTITY,
245 frame -> frame.getTransformProvider().getTransform(date),
246 (t1, t2) -> new Transform(date, t1, t2),
247 Transform::getInverse);
248 }
249
250 /** Get the transform from the instance to another frame.
251 * @param destination destination frame to which we want to transform vectors
252 * @param date the date (<em>must</em> be non-null, which is a more stringent condition
253 * * than in {@link #getTransformTo(Frame, FieldAbsoluteDate)})
254 * @param <T> the type of the field elements
255 * @return transform from the instance to the destination frame
256 */
257 public <T extends CalculusFieldElement<T>> FieldTransform<T> getTransformTo(final Frame destination,
258 final FieldAbsoluteDate<T> date) {
259 if (date.hasZeroField()) {
260 return new FieldTransform<>(date.getField(), getTransformTo(destination, date.toAbsoluteDate()));
261 }
262 return getTransformTo(destination,
263 FieldTransform.getIdentity(date.getField()),
264 frame -> frame.getTransformProvider().getTransform(date),
265 (t1, t2) -> new FieldTransform<>(date, t1, t2),
266 FieldTransform::getInverse);
267 }
268
269 /**
270 * Get the kinematic portion of the transform from the instance to another
271 * frame. The returned transform is kinematic in the sense that it includes
272 * translations and rotations, with rates, but cannot transform an acceleration vector.
273 *
274 * <p>This method is often more performant than {@link
275 * #getTransformTo(Frame, AbsoluteDate)} when accelerations are not needed.
276 *
277 * @param destination destination frame to which we want to transform
278 * vectors
279 * @param date the date (can be null if it is sure than no date
280 * dependent frame is used)
281 * @return kinematic transform from the instance to the destination frame
282 * @since 12.1
283 */
284 public KinematicTransform getKinematicTransformTo(final Frame destination, final AbsoluteDate date) {
285 return getTransformTo(
286 destination,
287 KinematicTransform.getIdentity(),
288 frame -> frame.getTransformProvider().getKinematicTransform(date),
289 (t1, t2) -> KinematicTransform.compose(date, t1, t2),
290 KinematicTransform::getInverse);
291 }
292
293 /**
294 * Get the static portion of the transform from the instance to another
295 * frame. The returned transform is static in the sense that it includes
296 * translations and rotations, but not rates.
297 *
298 * <p>This method is often more performant than {@link
299 * #getTransformTo(Frame, AbsoluteDate)} when rates are not needed.
300 *
301 * @param destination destination frame to which we want to transform
302 * vectors
303 * @param date the date (can be null if it is sure than no date
304 * dependent frame is used)
305 * @return static transform from the instance to the destination frame
306 * @since 11.2
307 */
308 public StaticTransform getStaticTransformTo(final Frame destination,
309 final AbsoluteDate date) {
310 return getTransformTo(
311 destination,
312 StaticTransform.getIdentity(),
313 frame -> frame.getTransformProvider().getStaticTransform(date),
314 (t1, t2) -> StaticTransform.compose(date, t1, t2),
315 StaticTransform::getInverse);
316 }
317
318 /**
319 * Get the static portion of the transform from the instance to another
320 * frame. The returned transform is static in the sense that it includes
321 * translations and rotations, but not rates.
322 *
323 * <p>This method is often more performant than {@link
324 * #getTransformTo(Frame, FieldAbsoluteDate)} when rates are not needed.
325 *
326 * <p>A first check is made on the FieldAbsoluteDate because "fielded" transforms have low-performance.<br>
327 * The date field is checked with {@link FieldElement#isZero()}.<br>
328 * If true, the un-fielded version of the transform computation is used.
329 *
330 * @param <T> type of the elements
331 * @param destination destination frame to which we want to transform
332 * vectors
333 * @param date the date (<em>must</em> be non-null, which is a more stringent condition
334 * than in {@link #getStaticTransformTo(Frame, AbsoluteDate)})
335 * @return static transform from the instance to the destination frame
336 * @since 12.0
337 */
338 public <T extends CalculusFieldElement<T>> FieldStaticTransform<T> getStaticTransformTo(final Frame destination,
339 final FieldAbsoluteDate<T> date) {
340 if (date.hasZeroField()) {
341 // If date field is Zero, then use the un-fielded version for performances
342 return FieldStaticTransform.of(date, getStaticTransformTo(destination, date.toAbsoluteDate()));
343
344 } else {
345 // Use classic fielded function
346 return getTransformTo(destination,
347 FieldStaticTransform.getIdentity(date.getField()),
348 frame -> frame.getTransformProvider().getStaticTransform(date),
349 (t1, t2) -> FieldStaticTransform.compose(date, t1, t2),
350 FieldStaticTransform::getInverse);
351 }
352 }
353
354 /**
355 * Get the kinematic portion of the transform from the instance to another
356 * frame. The returned transform is kinematic in the sense that it includes
357 * translations and rotations, with rates, but cannot transform an acceleration vector.
358 *
359 * <p>This method is often more performant than {@link
360 * #getTransformTo(Frame, AbsoluteDate)} when accelerations are not needed.
361 * @param <T> Type of transform returned.
362 * @param destination destination frame to which we want to transform
363 * vectors
364 * @param date the date (<em>must</em> be non-null, which is a more stringent condition
365 * * than in {@link #getKinematicTransformTo(Frame, AbsoluteDate)})
366 * @return kinematic transform from the instance to the destination frame
367 * @since 12.1
368 */
369 public <T extends CalculusFieldElement<T>> FieldKinematicTransform<T> getKinematicTransformTo(final Frame destination,
370 final FieldAbsoluteDate<T> date) {
371 if (date.hasZeroField()) {
372 // If date field is Zero, then use the un-fielded version for performances
373 final KinematicTransform kinematicTransform = getKinematicTransformTo(destination, date.toAbsoluteDate());
374 return FieldKinematicTransform.of(date.getField(), kinematicTransform);
375
376 } else {
377 // Use classic fielded function
378 return getTransformTo(destination,
379 FieldKinematicTransform.getIdentity(date.getField()),
380 frame -> frame.getTransformProvider().getKinematicTransform(date),
381 (t1, t2) -> FieldKinematicTransform.compose(date, t1, t2),
382 FieldKinematicTransform::getInverse);
383 }
384 }
385
386 /**
387 * Generic get transform method that builds the transform from {@code this}
388 * to {@code destination}.
389 *
390 * @param destination destination frame to which we want to transform
391 * vectors
392 * @param identity transform of the given type.
393 * @param getTransform method to get a transform from a frame.
394 * @param compose method to combine two transforms.
395 * @param inverse method to invert a transform.
396 * @param <T> Type of transform returned.
397 * @return composite transform.
398 */
399 private <T> T getTransformTo(final Frame destination,
400 final T identity,
401 final Function<Frame, T> getTransform,
402 final BiFunction<T, T, T> compose,
403 final Function<T, T> inverse) {
404
405 if (this == destination) {
406 // shortcut for special case that may be frequent
407 return identity;
408 }
409
410 // common ancestor to both frames in the frames tree
411 final Frame common = findCommon(this, destination);
412
413 // transform from common to instance
414 T commonToInstance = identity;
415 for (Frame frame = this; frame != common; frame = frame.parent) {
416 commonToInstance = compose.apply(getTransform.apply(frame), commonToInstance);
417 }
418
419 // transform from destination up to common
420 T commonToDestination = identity;
421 for (Frame frame = destination; frame != common; frame = frame.parent) {
422 commonToDestination = compose.apply(getTransform.apply(frame), commonToDestination);
423 }
424
425 // transform from instance to destination via common
426 return compose.apply(inverse.apply(commonToInstance), commonToDestination);
427
428 }
429
430 /** Get the provider for transform from parent frame to instance.
431 * @return provider for transform from parent frame to instance
432 */
433 public TransformProvider getTransformProvider() {
434 return transformProvider;
435 }
436
437 /** Find the deepest common ancestor of two frames in the frames tree.
438 * @param from origin frame
439 * @param to destination frame
440 * @return an ancestor frame of both <code>from</code> and <code>to</code>
441 */
442 private static Frame findCommon(final Frame from, final Frame to) {
443
444 // select deepest frames that could be the common ancestor
445 Frame currentF = from.depth > to.depth ? from.getAncestor(from.depth - to.depth) : from;
446 Frame currentT = from.depth > to.depth ? to : to.getAncestor(to.depth - from.depth);
447
448 // go upward until we find a match
449 while (currentF != currentT) {
450 currentF = currentF.parent;
451 currentT = currentT.parent;
452 }
453
454 return currentF;
455
456 }
457
458 /** Determine if a Frame is a child of another one.
459 * @param potentialAncestor supposed ancestor frame
460 * @return true if the potentialAncestor belongs to the
461 * path from instance to the root frame, excluding itself
462 */
463 public boolean isChildOf(final Frame potentialAncestor) {
464 if (depth <= potentialAncestor.depth) {
465 return false;
466 }
467 return getAncestor(depth - potentialAncestor.depth) == potentialAncestor;
468 }
469
470 /** Get the unique root frame.
471 * @return the unique instance of the root frame
472 */
473 public static Frame getRoot() {
474 return LazyRootHolder.INSTANCE;
475 }
476
477 /** Get a new version of the instance, frozen with respect to a reference frame.
478 * <p>
479 * Freezing a frame consist in computing its position and orientation with respect
480 * to another frame at some freezing date and fixing them so they do not depend
481 * on time anymore. This means the frozen frame is fixed with respect to the
482 * reference frame.
483 * </p>
484 * <p>
485 * One typical use of this method is to compute an inertial launch reference frame
486 * by freezing a {@link TopocentricFrame topocentric frame} at launch date
487 * with respect to an inertial frame. Another use is to freeze an equinox-related
488 * celestial frame at a reference epoch date.
489 * </p>
490 * <p>
491 * Only the frame returned by this method is frozen, the instance by itself
492 * is not affected by calling this method and still moves freely.
493 * </p>
494 * @param reference frame with respect to which the instance will be frozen
495 * @param freezingDate freezing date
496 * @param frozenName name of the frozen frame
497 * @return a frozen version of the instance
498 */
499 public Frame getFrozenFrame(final Frame reference, final AbsoluteDate freezingDate,
500 final String frozenName) {
501 return new Frame(reference, reference.getTransformTo(this, freezingDate).freeze(),
502 frozenName, reference.isPseudoInertial());
503 }
504
505 // We use the Initialization on demand holder idiom to store
506 // the singletons, as it is both thread-safe, efficient (no
507 // synchronization) and works with all versions of java.
508
509 /** Holder for the root frame singleton. */
510 private static class LazyRootHolder {
511
512 /** Unique instance. */
513 private static final Frame INSTANCE = new Frame(Predefined.GCRF.getName(), true) { };
514
515 /** Private constructor.
516 * <p>This class is a utility class, it should neither have a public
517 * nor a default constructor. This private constructor prevents
518 * the compiler from generating one automatically.</p>
519 */
520 private LazyRootHolder() {
521 }
522
523 }
524
525 }