Frame.java

  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;

  19. import java.util.Map;
  20. import java.util.concurrent.ConcurrentHashMap;
  21. import java.util.function.BiFunction;
  22. import java.util.function.Function;

  24. import org.hipparchus.CalculusFieldElement;
  25. import org.hipparchus.Field;
  26. import org.hipparchus.FieldElement;
  27. import org.orekit.errors.OrekitIllegalArgumentException;
  28. import org.orekit.errors.OrekitMessages;
  29. import org.orekit.time.AbsoluteDate;
  30. import org.orekit.time.FieldAbsoluteDate;


  33. /** Tridimensional references frames class.
  34.  *
  35.  * <h2> Frame Presentation </h2>
  36.  * <p>This class is the base class for all frames in OREKIT. The frames are
  37.  * linked together in a tree with some specific frame chosen as the root of the tree.
  38.  * Each frame is defined by {@link Transform transforms} combining any number
  39.  * of translations and rotations from a reference frame which is its
  40.  * parent frame in the tree structure.</p>
  41.  * <p>When we say a {@link Transform transform} t is <em>from frame<sub>A</sub>
  42.  * to frame<sub>B</sub></em>, we mean that if the coordinates of some absolute
  43.  * vector (say the direction of a distant star for example) has coordinates
  44.  * u<sub>A</sub> in frame<sub>A</sub> and u<sub>B</sub> in frame<sub>B</sub>,
  45.  * then u<sub>B</sub>={@link
  46.  * Transform#transformVector(org.hipparchus.geometry.euclidean.threed.Vector3D)
  47.  * t.transformVector(u<sub>A</sub>)}.
  48.  * <p>The transforms may be constant or varying, depending on the implementation of
  49.  * the {@link TransformProvider transform provider} used to define the frame. For simple
  50.  * fixed transforms, using {@link FixedTransformProvider} is sufficient. For varying
  51.  * transforms (time-dependent or telemetry-based for example), it may be useful to define
  52.  * specific implementations of {@link TransformProvider transform provider}.</p>
  53.  *
  54.  * @author Guylaine Prat
  55.  * @author Luc Maisonobe
  56.  * @author Pascal Parraud
  57.  */
  58. public class Frame {

  60.     /** Parent frame (only the root frame doesn't have a parent). */
  61.     private final Frame parent;

  63.     /** Depth of the frame with respect to tree root. */
  64.     private final int depth;

  66.     /** Provider for transform from parent frame to instance. */
  67.     private final TransformProvider transformProvider;

  69.     /** Instance name. */
  70.     private final String name;

  72.     /** Indicator for pseudo-inertial frames. */
  73.     private final boolean pseudoInertial;

  75.     /** Cache for transforms with peer frame.
  76.      * @since 13.0.3
  77.      */
  78.     private CachedTransformProvider peerCache;

  80.     /** Cache for transforms with peer frame.
  81.      * @since 13.0.3
  82.      */
  83.     private Map<Field<? extends CalculusFieldElement<?>>, FieldCachedTransformProvider<?>> peerFieldCache;

  85.     /** Private constructor used only for the root frame.
  86.      * @param name name of the frame
  87.      * @param pseudoInertial true if frame is considered pseudo-inertial
  88.      * (i.e. suitable for propagating orbit)
  89.      */
  90.     private Frame(final String name, final boolean pseudoInertial) {
  91.         parent              = null;
  92.         depth               = 0;
  93.         transformProvider   = new FixedTransformProvider(Transform.IDENTITY);
  94.         this.name           = name;
  95.         this.pseudoInertial = pseudoInertial;
  96.         this.peerCache      = null;
  97.         this.peerFieldCache = null;
  98.     }

  100.     /** Build a non-inertial frame from its transform with respect to its parent.
  101.      * <p>calling this constructor is equivalent to call
  102.      * <code>{link {@link #Frame(Frame, Transform, String, boolean)
  103.      * Frame(parent, transform, name, false)}</code>.</p>
  104.      * @param parent parent frame (must be non-null)
  105.      * @param transform transform from parent frame to instance
  106.      * @param name name of the frame
  107.      * @exception IllegalArgumentException if the parent frame is null
  108.      */
  109.     public Frame(final Frame parent, final Transform transform, final String name)
  110.         throws IllegalArgumentException {
  111.         this(parent, transform, name, false);
  112.     }

  114.     /** Build a non-inertial frame from its transform with respect to its parent.
  115.      * <p>calling this constructor is equivalent to call
  116.      * <code>{link {@link #Frame(Frame, Transform, String, boolean)
  117.      * Frame(parent, transform, name, false)}</code>.</p>
  118.      * @param parent parent frame (must be non-null)
  119.      * @param transformProvider provider for transform from parent frame to instance
  120.      * @param name name of the frame
  121.      * @exception IllegalArgumentException if the parent frame is null
  122.      */
  123.     public Frame(final Frame parent, final TransformProvider transformProvider, final String name)
  124.         throws IllegalArgumentException {
  125.         this(parent, transformProvider, name, false);
  126.     }

  128.     /** Build a frame from its transform with respect to its parent.
  129.      * <p>The convention for the transform is that it is from parent
  130.      * frame to instance. This means that the two following frames
  131.      * are similar:</p>
  132.      * <pre>
  133.      * Frame frame1 = new Frame(FramesFactory.getGCRF(), new Transform(t1, t2));
  134.      * Frame frame2 = new Frame(new Frame(FramesFactory.getGCRF(), t1), t2);
  135.      * </pre>
  136.      * @param parent parent frame (must be non-null)
  137.      * @param transform transform from parent frame to instance
  138.      * @param name name of the frame
  139.      * @param pseudoInertial true if frame is considered pseudo-inertial
  140.      * (i.e. suitable for propagating orbit)
  141.      * @exception IllegalArgumentException if the parent frame is null
  142.      */
  143.     public Frame(final Frame parent, final Transform transform, final String name,
  144.                  final boolean pseudoInertial)
  145.         throws IllegalArgumentException {
  146.         this(parent, new FixedTransformProvider(transform), name, pseudoInertial);
  147.     }

  149.     /** Build a frame from its transform with respect to its parent.
  150.      * <p>The convention for the transform is that it is from parent
  151.      * frame to instance. This means that the two following frames
  152.      * are similar:</p>
  153.      * <pre>
  154.      * Frame frame1 = new Frame(FramesFactory.getGCRF(), new Transform(t1, t2));
  155.      * Frame frame2 = new Frame(new Frame(FramesFactory.getGCRF(), t1), t2);
  156.      * </pre>
  157.      * @param parent parent frame (must be non-null)
  158.      * @param transformProvider provider for transform from parent frame to instance
  159.      * @param name name of the frame
  160.      * @param pseudoInertial true if frame is considered pseudo-inertial
  161.      * (i.e. suitable for propagating orbit)
  162.      * @exception IllegalArgumentException if the parent frame is null
  163.      */
  164.     public Frame(final Frame parent, final TransformProvider transformProvider, final String name,
  165.                  final boolean pseudoInertial)
  166.         throws IllegalArgumentException {

  168.         if (parent == null) {
  169.             throw new OrekitIllegalArgumentException(OrekitMessages.NULL_PARENT_FOR_FRAME, name);
  170.         }
  171.         this.parent            = parent;
  172.         this.depth             = parent.depth + 1;
  173.         this.transformProvider = transformProvider;
  174.         this.name              = name;
  175.         this.pseudoInertial    = pseudoInertial;

  177.     }

  179.     /** Get the name.
  180.      * @return the name
  181.      */
  182.     public String getName() {
  183.         return this.name;
  184.     }

  186.     /** Check if the frame is pseudo-inertial.
  187.      * <p>Pseudo-inertial frames are frames that do have a linear motion and
  188.      * either do not rotate or rotate at a very low rate resulting in
  189.      * neglectible inertial forces. This means they are suitable for orbit
  190.      * definition and propagation using Newtonian mechanics. Frames that are
  191.      * <em>not</em> pseudo-inertial are <em>not</em> suitable for orbit
  192.      * definition and propagation.</p>
  193.      * @return true if frame is pseudo-inertial
  194.      */
  195.     public boolean isPseudoInertial() {
  196.         return pseudoInertial;
  197.     }

  199.     /** New definition of the java.util toString() method.
  200.      * @return the name
  201.      */
  202.     public String toString() {
  203.         return this.name;
  204.     }

  206.     /** Get the parent frame.
  207.      * @return parent frame
  208.      */
  209.     public Frame getParent() {
  210.         return parent;
  211.     }

  213.     /** Get the depth of the frame.
  214.      * <p>
  215.      * The depth of a frame is the number of parents frame between
  216.      * it and the frames tree root. It is 0 for the root frame, and
  217.      * the depth of a frame is the depth of its parent frame plus one.
  218.      * </p>
  219.      * @return depth of the frame
  220.      */
  221.     public int getDepth() {
  222.         return depth;
  223.     }

  225.     /** Get the n<sup>th</sup> ancestor of the frame.
  226.      * @param n index of the ancestor (0 is the instance, 1 is its parent,
  227.      * 2 is the parent of its parent...)
  228.      * @return n<sup>th</sup> ancestor of the frame (must be between 0
  229.      * and the depth of the frame)
  230.      * @exception IllegalArgumentException if n is larger than the depth
  231.      * of the instance
  232.      */
  233.     public Frame getAncestor(final int n) throws IllegalArgumentException {

  235.         // safety check
  236.         if (n > depth) {
  237.             throw new OrekitIllegalArgumentException(OrekitMessages.FRAME_NO_NTH_ANCESTOR,
  238.                                                      name, depth, n);
  239.         }

  241.         // go upward to find ancestor
  242.         Frame current = this;
  243.         for (int i = 0; i < n; ++i) {
  244.             current = current.parent;
  245.         }

  247.         return current;

  249.     }

  251.     /** Associate this frame with a peer, caching transforms.
  252.      * <p>
  253.      * The cache is a LRU cache (Least Recently Used), so entries remain in
  254.      * the cache if they are used frequently, and only older entries
  255.      * that have not been accessed for a while will be expunged.
  256.      * </p>
  257.      * <p>
  258.      * If a peer was already associated with this frame, it will be overridden.
  259.      * </p>
  260.      * <p>
  261.      * Peering is unidirectional, i.e. if frameA is peered with frameB,
  262.      * then frameB may be peered with another frameC or no frame at all.
  263.      * This allows several frames to be peered with a pivot one (typically
  264.      * Earth frame and many topocentric frames all peered with one inertial frame).
  265.      * </p>
  266.      * @param peer peer frame
  267.      * @param cacheSize number of transforms kept in the date-based cache
  268.      * @since 13.0.3
  269.      */
  270.     public void setPeerCaching(final Frame peer, final int cacheSize) {

  272.         // caching for regular dates
  273.         peerCache = createCache(peer, cacheSize);

  275.         // caching for field dates
  276.         peerFieldCache = new ConcurrentHashMap<>();

  278.     }

  280.     /** Get the peer associated to this frame.
  281.      * @return peer associated with this frame, null if not peered at all
  282.      * @since 13.0.3
  283.      */
  284.     public Frame getPeer() {
  285.         return peerCache == null ? null : peerCache.getDestination();
  286.     }

  288.     /** Create cache.
  289.      * @param peer peer frame
  290.      * @param cacheSize number of transforms kept in the date-based cache
  291.      * @return built cache
  292.      * @since 13.0.3
  293.      */
  294.     private CachedTransformProvider createCache(final Frame peer, final int cacheSize) {
  295.         final Function<AbsoluteDate, Transform> fullGenerator =
  296.                 date -> getTransformTo(peer,
  297.                                        Transform.IDENTITY,
  298.                                        frame -> frame.getTransformProvider().getTransform(date),
  299.                                        (t1, t2) -> new Transform(date, t1, t2),
  300.                                        Transform::getInverse);
  301.         final Function<AbsoluteDate, KinematicTransform> kinematicGenerator =
  302.                 date -> getTransformTo(peer,
  303.                                        KinematicTransform.getIdentity(),
  304.                                        frame -> frame.getTransformProvider().getTransform(date),
  305.                                        (t1, t2) -> KinematicTransform.compose(date, t1, t2),
  306.                                        KinematicTransform::getInverse);
  307.         final Function<AbsoluteDate, StaticTransform> staticGenerator =
  308.                 date -> getTransformTo(peer,
  309.                                        StaticTransform.getIdentity(),
  310.                                        frame -> frame.getTransformProvider().getTransform(date),
  311.                                        (t1, t2) -> StaticTransform.compose(date, t1, t2),
  312.                                        StaticTransform::getInverse);
  313.         return new CachedTransformProvider(this, peer,
  314.                                            fullGenerator, kinematicGenerator, staticGenerator,
  315.                                            cacheSize);
  316.     }

  318.     /** Create field cache.
  319.      * @param <T> type of the field elements
  320.      * @param peer peer frame
  321.      * @param field field elements belong to
  322.      * @return built cache
  323.      * @since 13.0.3
  324.      */
  325.     private <T extends CalculusFieldElement<T>> FieldCachedTransformProvider<T>
  326.         createCache(final Frame peer, final Field<T> field) {
  327.         final Function<FieldAbsoluteDate<T>, FieldTransform<T>> fullGenerator =
  328.                 d -> getTransformTo(peer,
  329.                                     FieldTransform.getIdentity(field),
  330.                                     frame -> frame.getTransformProvider().getTransform(d),
  331.                                     (FieldTransform<T> t1, FieldTransform<T> t2) -> new FieldTransform<>(d, t1, t2),
  332.                                     FieldTransform::getInverse);
  333.         final Function<FieldAbsoluteDate<T>, FieldKinematicTransform<T>> kinematicGenerator =
  334.                 d -> getTransformTo(peer,
  335.                                     FieldKinematicTransform.getIdentity(field),
  336.                                     frame -> frame.getTransformProvider().getTransform(d),
  337.                                     (t1, t2) -> FieldKinematicTransform.compose(d, t1, t2),
  338.                                     FieldKinematicTransform::getInverse);
  339.         final Function<FieldAbsoluteDate<T>, FieldStaticTransform<T>> staticGenerator =
  340.                 d -> getTransformTo(peer,
  341.                                     FieldStaticTransform.getIdentity(field),
  342.                                     frame -> frame.getTransformProvider().getTransform(d),
  343.                                     (t1, t2) -> FieldStaticTransform.compose(d, t1, t2),
  344.                                     FieldStaticTransform::getInverse);
  345.         return new FieldCachedTransformProvider<>(this, peer,
  346.                                                   fullGenerator, kinematicGenerator, staticGenerator,
  347.                                                   peerCache.getCacheSize());
  348.     }

  350.     /** Get the transform from the instance to another frame.
  351.      * @param destination destination frame to which we want to transform vectors
  352.      * @param date the date (can be null if it is certain that no date dependent frame is used)
  353.      * @return transform from the instance to the destination frame
  354.      */
  355.     public Transform getTransformTo(final Frame destination, final AbsoluteDate date) {
  356.         if (peerCache != null && peerCache.getDestination() == destination) {
  357.             // this is our peer, we must cache the transform
  358.             return peerCache.getTransform(date);
  359.         } else {
  360.             // not our peer, just compute the transform and forget about it
  361.             return getTransformTo(
  362.                     destination,
  363.                     Transform.IDENTITY,
  364.                     frame -> frame.getTransformProvider().getTransform(date),
  365.                     (t1, t2) -> new Transform(date, t1, t2),
  366.                     Transform::getInverse);
  367.         }
  368.     }

  370.     /** Get the transform from the instance to another frame.
  371.      * @param destination destination frame to which we want to transform vectors
  372.      * @param date        the date (<em>must</em> be non-null, which is a more stringent condition
  373.      *                    than in {@link #getTransformTo(Frame, FieldAbsoluteDate)})
  374.      * @param <T> the type of the field elements
  375.      * @return transform from the instance to the destination frame
  376.      */
  377.     public <T extends CalculusFieldElement<T>> FieldTransform<T> getTransformTo(final Frame destination,
  378.                                                                                 final FieldAbsoluteDate<T> date) {
  379.         if (peerCache != null && peerCache.getDestination() == destination) {
  380.             // this is our peer, we must cache the transform
  381.             @SuppressWarnings("unchedked")
  382.             final FieldCachedTransformProvider<T> cache =
  383.                     (FieldCachedTransformProvider<T>) peerFieldCache.computeIfAbsent(date.getField(),
  384.                                                                                      field -> createCache(destination, date.getField()));
  385.             return cache.getTransform(date);
  386.         } else {
  387.             // not our peer, just compute the transform and forget about it
  388.             if (date.hasZeroField()) {
  389.                 return new FieldTransform<>(date.getField(), getTransformTo(destination, date.toAbsoluteDate()));
  390.             }

  392.             return getTransformTo(destination,
  393.                                   FieldTransform.getIdentity(date.getField()),
  394.                                   frame -> frame.getTransformProvider().getTransform(date),
  395.                                   (t1, t2) -> new FieldTransform<>(date, t1, t2),
  396.                                   FieldTransform::getInverse);
  397.         }
  398.     }

  400.     /**
  401.      * Get the kinematic portion of the transform from the instance to another
  402.      * frame. The returned transform is kinematic in the sense that it includes
  403.      * translations and rotations, with rates, but cannot transform an acceleration vector.
  404.      *
  405.      * <p>This method is often more performant than {@link
  406.      * #getTransformTo(Frame, AbsoluteDate)} when accelerations are not needed.
  407.      *
  408.      * @param destination destination frame to which we want to transform
  409.      *                    vectors
  410.      * @param date        the date (can be null if it is sure than no date
  411.      *                    dependent frame is used)
  412.      * @return kinematic transform from the instance to the destination frame
  413.      * @since 12.1
  414.      */
  415.     public KinematicTransform getKinematicTransformTo(final Frame destination, final AbsoluteDate date) {
  416.         if (peerCache != null && peerCache.getDestination() == destination) {
  417.             // this is our peer, we must cache the transform
  418.             return peerCache.getKinematicTransform(date);
  419.         } else {
  420.             // not our peer, just compute the transform and forget about it
  421.             return getTransformTo(
  422.                     destination,
  423.                     KinematicTransform.getIdentity(),
  424.                     frame -> frame.getTransformProvider().getKinematicTransform(date),
  425.                     (t1, t2) -> KinematicTransform.compose(date, t1, t2),
  426.                     KinematicTransform::getInverse);
  427.         }
  428.     }

  430.     /**
  431.      * Get the static portion of the transform from the instance to another
  432.      * frame. The returned transform is static in the sense that it includes
  433.      * translations and rotations, but not rates.
  434.      *
  435.      * <p>This method is often more performant than {@link
  436.      * #getTransformTo(Frame, AbsoluteDate)} when rates are not needed.
  437.      *
  438.      * @param destination destination frame to which we want to transform
  439.      *                    vectors
  440.      * @param date        the date (can be null if it is sure than no date
  441.      *                    dependent frame is used)
  442.      * @return static transform from the instance to the destination frame
  443.      * @since 11.2
  444.      */
  445.     public StaticTransform getStaticTransformTo(final Frame destination,
  446.                                                 final AbsoluteDate date) {
  447.         if (peerCache != null && peerCache.getDestination() == destination) {
  448.             // this is our peer, we must cache the transform
  449.             return peerCache.getStaticTransform(date);
  450.         }
  451.         else {
  452.             // not our peer, just compute the transform and forget about it
  453.             return getTransformTo(
  454.                     destination,
  455.                     StaticTransform.getIdentity(),
  456.                     frame -> frame.getTransformProvider().getStaticTransform(date),
  457.                     (t1, t2) -> StaticTransform.compose(date, t1, t2),
  458.                     StaticTransform::getInverse);
  459.         }
  460.     }

  462.     /**
  463.      * Get the static portion of the transform from the instance to another
  464.      * frame. The returned transform is static in the sense that it includes
  465.      * translations and rotations, but not rates.
  466.      *
  467.      * <p>This method is often more performant than {@link
  468.      * #getTransformTo(Frame, FieldAbsoluteDate)} when rates are not needed.
  469.      *
  470.      * <p>A first check is made on the FieldAbsoluteDate because "fielded" transforms have low-performance.<br>
  471.      * The date field is checked with {@link FieldElement#isZero()}.<br>
  472.      * If true, the un-fielded version of the transform computation is used.
  473.      *
  474.      * @param <T>         type of the elements
  475.      * @param destination destination frame to which we want to transform
  476.      *                    vectors
  477.      * @param date        the date (<em>must</em> be non-null, which is a more stringent condition
  478.      *                    than in {@link #getStaticTransformTo(Frame, AbsoluteDate)})
  479.      * @return static transform from the instance to the destination frame
  480.      * @since 12.0
  481.      */
  482.     public <T extends CalculusFieldElement<T>> FieldStaticTransform<T> getStaticTransformTo(final Frame destination,
  483.                                                 final FieldAbsoluteDate<T> date) {
  484.         if (peerCache != null && peerCache.getDestination() == destination) {
  485.             // this is our peer, we must cache the transform
  486.             @SuppressWarnings("unchedked")
  487.             final FieldCachedTransformProvider<T> cache =
  488.                     (FieldCachedTransformProvider<T>) peerFieldCache.computeIfAbsent(date.getField(),
  489.                                                                                      field -> createCache(destination, date.getField()));
  490.             return cache.getStaticTransform(date);
  491.         } else {
  492.             // not our peer, just compute the transform and forget about it
  493.             if (date.hasZeroField()) {
  494.                 // If date field is Zero, then use the un-fielded version for performances
  495.                 return FieldStaticTransform.of(date, getStaticTransformTo(destination, date.toAbsoluteDate()));

  497.             }
  498.             else {
  499.                 // Use classic fielded function
  500.                 return getTransformTo(destination,
  501.                                       FieldStaticTransform.getIdentity(date.getField()),
  502.                                       frame -> frame.getTransformProvider().getStaticTransform(date),
  503.                                       (t1, t2) -> FieldStaticTransform.compose(date, t1, t2),
  504.                                       FieldStaticTransform::getInverse);
  505.             }
  506.         }
  507.     }

  509.     /**
  510.      * Get the kinematic portion of the transform from the instance to another
  511.      * frame. The returned transform is kinematic in the sense that it includes
  512.      * translations and rotations, with rates, but cannot transform an acceleration vector.
  513.      *
  514.      * <p>This method is often more performant than {@link
  515.      * #getTransformTo(Frame, AbsoluteDate)} when accelerations are not needed.
  516.      * @param <T>          Type of transform returned.
  517.      * @param destination destination frame to which we want to transform
  518.      *                    vectors
  519.      * @param date        the date (<em>must</em> be non-null, which is a more stringent condition
  520.      *      *                    than in {@link #getKinematicTransformTo(Frame, AbsoluteDate)})
  521.      * @return kinematic transform from the instance to the destination frame
  522.      * @since 12.1
  523.      */
  524.     public <T extends CalculusFieldElement<T>> FieldKinematicTransform<T> getKinematicTransformTo(final Frame destination,
  525.                                                                                                   final FieldAbsoluteDate<T> date) {
  526.         if (peerCache != null && peerCache.getDestination() == destination) {
  527.             // this is our peer, we must cache the transform
  528.             @SuppressWarnings("unchedked")
  529.             final FieldCachedTransformProvider<T> cache =
  530.                     (FieldCachedTransformProvider<T>) peerFieldCache.computeIfAbsent(date.getField(),
  531.                                                                                      field -> createCache(destination, date.getField()));
  532.             return cache.getKinematicTransform(date);
  533.         }
  534.         else {
  535.             // not our peer, just compute the transform and forget about it
  536.             if (date.hasZeroField()) {
  537.                 // If date field is Zero, then use the un-fielded version for performances
  538.                 final KinematicTransform kinematicTransform = getKinematicTransformTo(destination, date.toAbsoluteDate());
  539.                 return FieldKinematicTransform.of(date.getField(), kinematicTransform);

  541.             }
  542.             else {
  543.                 // Use classic fielded function
  544.                 return getTransformTo(destination,
  545.                                       FieldKinematicTransform.getIdentity(date.getField()),
  546.                                       frame -> frame.getTransformProvider().getKinematicTransform(date),
  547.                                       (t1, t2) -> FieldKinematicTransform.compose(date, t1, t2),
  548.                                       FieldKinematicTransform::getInverse);
  549.             }
  550.         }
  551.     }

  553.     /**
  554.      * Generic get transform method that builds the transform from {@code this}
  555.      * to {@code destination}.
  556.      *
  557.      * @param destination  destination frame to which we want to transform
  558.      *                     vectors
  559.      * @param identity     transform of the given type.
  560.      * @param getTransform method to get a transform from a frame.
  561.      * @param compose      method to combine two transforms.
  562.      * @param inverse      method to invert a transform.
  563.      * @param <T>          Type of transform returned.
  564.      * @return composite transform.
  565.      */
  566.     private <T> T getTransformTo(final Frame destination,
  567.                                  final T identity,
  568.                                  final Function<Frame, T> getTransform,
  569.                                  final BiFunction<T, T, T> compose,
  570.                                  final Function<T, T> inverse) {

  572.         if (this == destination) {
  573.             // shortcut for special case that may be frequent
  574.             return identity;
  575.         }

  577.         // common ancestor to both frames in the frames tree
  578.         final Frame common = findCommon(this, destination);

  580.         // transform from common to instance
  581.         T commonToInstance = identity;
  582.         for (Frame frame = this; frame != common; frame = frame.parent) {
  583.             commonToInstance = compose.apply(getTransform.apply(frame), commonToInstance);
  584.         }

  586.         // transform from destination up to common
  587.         T commonToDestination = identity;
  588.         for (Frame frame = destination; frame != common; frame = frame.parent) {
  589.             commonToDestination = compose.apply(getTransform.apply(frame), commonToDestination);
  590.         }

  592.         // transform from instance to destination via common
  593.         return compose.apply(inverse.apply(commonToInstance), commonToDestination);

  595.     }

  597.     /** Get the provider for transform from parent frame to instance.
  598.      * @return provider for transform from parent frame to instance
  599.      */
  600.     public TransformProvider getTransformProvider() {
  601.         return transformProvider;
  602.     }

  604.     /** Find the deepest common ancestor of two frames in the frames tree.
  605.      * @param from origin frame
  606.      * @param to destination frame
  607.      * @return an ancestor frame of both <code>from</code> and <code>to</code>
  608.      */
  609.     private static Frame findCommon(final Frame from, final Frame to) {

  611.         // select deepest frames that could be the common ancestor
  612.         Frame currentF = from.depth > to.depth ? from.getAncestor(from.depth - to.depth) : from;
  613.         Frame currentT = from.depth > to.depth ? to : to.getAncestor(to.depth - from.depth);

  615.         // go upward until we find a match
  616.         while (currentF != currentT) {
  617.             currentF = currentF.parent;
  618.             currentT = currentT.parent;
  619.         }

  621.         return currentF;

  623.     }

  625.     /** Determine if a Frame is a child of another one.
  626.      * @param potentialAncestor supposed ancestor frame
  627.      * @return true if the potentialAncestor belongs to the
  628.      * path from instance to the root frame, excluding itself
  629.      */
  630.     public boolean isChildOf(final Frame potentialAncestor) {
  631.         if (depth <= potentialAncestor.depth) {
  632.             return false;
  633.         }
  634.         return getAncestor(depth - potentialAncestor.depth) == potentialAncestor;
  635.     }

  637.     /** Get the unique root frame.
  638.      * @return the unique instance of the root frame
  639.      */
  640.     public static Frame getRoot() {
  641.         return LazyRootHolder.INSTANCE;
  642.     }

  644.     /** Get a new version of the instance, frozen with respect to a reference frame.
  645.      * <p>
  646.      * Freezing a frame consist in computing its position and orientation with respect
  647.      * to another frame at some freezing date and fixing them so they do not depend
  648.      * on time anymore. This means the frozen frame is fixed with respect to the
  649.      * reference frame.
  650.      * </p>
  651.      * <p>
  652.      * One typical use of this method is to compute an inertial launch reference frame
  653.      * by freezing a {@link TopocentricFrame topocentric frame} at launch date
  654.      * with respect to an inertial frame. Another use is to freeze an equinox-related
  655.      * celestial frame at a reference epoch date.
  656.      * </p>
  657.      * <p>
  658.      * Only the frame returned by this method is frozen, the instance by itself
  659.      * is not affected by calling this method and still moves freely.
  660.      * </p>
  661.      * @param reference frame with respect to which the instance will be frozen
  662.      * @param freezingDate freezing date
  663.      * @param frozenName name of the frozen frame
  664.      * @return a frozen version of the instance
  665.      */
  666.     public Frame getFrozenFrame(final Frame reference, final AbsoluteDate freezingDate,
  667.                                 final String frozenName) {
  668.         return new Frame(reference, reference.getTransformTo(this, freezingDate).freeze(),
  669.                          frozenName, reference.isPseudoInertial());
  670.     }

  672.     // We use the Initialization on demand holder idiom to store
  673.     // the singletons, as it is both thread-safe, efficient (no
  674.     // synchronization) and works with all versions of java.

  676.     /** Holder for the root frame singleton. */
  677.     private static class LazyRootHolder {

  679.         /** Unique instance. */
  680.         private static final Frame INSTANCE = new Frame(Predefined.GCRF.getName(), true) { };

  682.         /** Private constructor.
  683.          * <p>This class is a utility class, it should neither have a public
  684.          * nor a default constructor. This private constructor prevents
  685.          * the compiler from generating one automatically.</p>
  686.          */
  687.         private LazyRootHolder() {
  688.         }

  690.     }

  692. }
Created with JaCoCo 0.8.12.202403310830