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.function.BiFunction;
  20. import java.util.function.Function;

  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;


  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 {

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

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

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

  66.     /** Instance name. */
  67.     private final String name;

  69.     /** Indicator for pseudo-inertial frames. */
  70.     private final boolean pseudoInertial;

  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.     }

  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.     }

  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.     }

  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.     }

  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 {

  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;

  162.     }

  164.     /** Get the name.
  165.      * @return the name
  166.      */
  167.     public String getName() {
  168.         return this.name;
  169.     }

  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.     }

  184.     /** New definition of the java.util toString() method.
  185.      * @return the name
  186.      */
  187.     public String toString() {
  188.         return this.name;
  189.     }

  191.     /** Get the parent frame.
  192.      * @return parent frame
  193.      */
  194.     public Frame getParent() {
  195.         return parent;
  196.     }

  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.     }

  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 {

  220.         // safety check
  221.         if (n > depth) {
  222.             throw new OrekitIllegalArgumentException(OrekitMessages.FRAME_NO_NTH_ANCESTOR,
  223.                                                      name, depth, n);
  224.         }

  226.         // go upward to find ancestor
  227.         Frame current = this;
  228.         for (int i = 0; i < n; ++i) {
  229.             current = current.parent;
  230.         }

  232.         return current;

  234.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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()));

  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.     }

  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);

  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.     }

  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) {

  405.         if (this == destination) {
  406.             // shortcut for special case that may be frequent
  407.             return identity;
  408.         }

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

  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.         }

  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.         }

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

  428.     }

  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.     }

  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) {

  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);

  448.         // go upward until we find a match
  449.         while (currentF != currentT) {
  450.             currentF = currentF.parent;
  451.             currentT = currentT.parent;
  452.         }

  454.         return currentF;

  456.     }

  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.     }

  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.     }

  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.     }

  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.

  509.     /** Holder for the root frame singleton. */
  510.     private static class LazyRootHolder {

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

  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.         }

  523.     }

  525. }
Created with JaCoCo 0.8.12.202403310830