Frame.java

  1. /* Copyright 2002-2016 CS Systèmes d'Information
  2.  * Licensed to CS Systèmes d'Information (CS) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * CS licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *   http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.orekit.frames;

  19. import java.io.Serializable;

  21. import org.orekit.errors.OrekitIllegalArgumentException;
  22. import org.orekit.errors.OrekitException;
  23. import org.orekit.errors.OrekitMessages;
  24. import org.orekit.time.AbsoluteDate;


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

  54.     /** Serializable UID. */
  55.     private static final long serialVersionUID = -6981146543760234087L;

  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.      * @exception OrekitException if some frame specific error occurs
  241.      */
  242.     public Transform getTransformTo(final Frame destination, final AbsoluteDate date)
  243.         throws OrekitException {

  245.         if (this == destination) {
  246.             // shortcut for special case that may be frequent
  247.             return Transform.IDENTITY;
  248.         }

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

  253.         // transform from common to instance
  254.         Transform commonToInstance = Transform.IDENTITY;
  255.         for (Frame frame = this; frame != common; frame = frame.parent) {
  256.             commonToInstance =
  257.                 new Transform(date, frame.transformProvider.getTransform(date), commonToInstance);
  258.         }

  260.         // transform from destination up to common
  261.         Transform commonToDestination = Transform.IDENTITY;
  262.         for (Frame frame = destination; frame != common; frame = frame.parent) {
  263.             commonToDestination =
  264.                 new Transform(date, frame.transformProvider.getTransform(date), commonToDestination);
  265.         }

  267.         // transform from instance to destination via common
  268.         return new Transform(date, commonToInstance.getInverse(), commonToDestination);

  270.     }

  272.     /** Get the provider for transform from parent frame to instance.
  273.      * @return provider for transform from parent frame to instance
  274.      */
  275.     public TransformProvider getTransformProvider() {
  276.         return transformProvider;
  277.     }

  279.     /** Find the deepest common ancestor of two frames in the frames tree.
  280.      * @param from origin frame
  281.      * @param to destination frame
  282.      * @return an ancestor frame of both <code>from</code> and <code>to</code>
  283.      */
  284.     private static Frame findCommon(final Frame from, final Frame to) {

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

  290.         // go upward until we find a match
  291.         while (currentF != currentT) {
  292.             currentF = currentF.parent;
  293.             currentT = currentT.parent;
  294.         }

  296.         return currentF;

  298.     }

  300.     /** Determine if a Frame is a child of another one.
  301.      * @param potentialAncestor supposed ancestor frame
  302.      * @return true if the potentialAncestor belongs to the
  303.      * path from instance to the root frame, excluding itself
  304.      */
  305.     public boolean isChildOf(final Frame potentialAncestor) {
  306.         if (depth <= potentialAncestor.depth) {
  307.             return false;
  308.         }
  309.         return getAncestor(depth - potentialAncestor.depth) == potentialAncestor;
  310.     }

  312.     /** Get the unique root frame.
  313.      * @return the unique instance of the root frame
  314.      */
  315.     protected static Frame getRoot() {
  316.         return LazyRootHolder.INSTANCE;
  317.     }

  319.     /** Get a new version of the instance, frozen with respect to a reference frame.
  320.      * <p>
  321.      * Freezing a frame consist in computing its position and orientation with respect
  322.      * to another frame at some freezing date and fixing them so they do not depend
  323.      * on time anymore. This means the frozen frame is fixed with respect to the
  324.      * reference frame.
  325.      * </p>
  326.      * <p>
  327.      * One typical use of this method is to compute an inertial launch reference frame
  328.      * by freezing a {@link TopocentricFrame topocentric frame} at launch date
  329.      * with respect to an inertial frame. Another use is to freeze an equinox-related
  330.      * celestial frame at a reference epoch date.
  331.      * </p>
  332.      * <p>
  333.      * Only the frame returned by this method is frozen, the instance by itself
  334.      * is not affected by calling this method and still moves freely.
  335.      * </p>
  336.      * @param reference frame with respect to which the instance will be frozen
  337.      * @param freezingDate freezing date
  338.      * @param frozenName name of the frozen frame
  339.      * @return a frozen version of the instance
  340.      * @exception OrekitException if transform between reference frame and instance
  341.      * cannot be computed at freezing frame
  342.      */
  343.     public Frame getFrozenFrame(final Frame reference, final AbsoluteDate freezingDate,
  344.                                 final String frozenName) throws OrekitException {
  345.         return new Frame(reference, reference.getTransformTo(this, freezingDate).freeze(),
  346.                          frozenName, reference.isPseudoInertial());
  347.     }

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

  353.     /** Holder for the root frame singleton. */
  354.     private static class LazyRootHolder {

  356.         /** Unique instance. */
  357.         private static final Frame INSTANCE = new Frame("GCRF", true) {

  359.             /** Serializable UID. */
  360.             private static final long serialVersionUID = -2654403496396721543L;

  362.             /** Replace the instance with a data transfer object for serialization.
  363.              * <p>
  364.              * This intermediate class serializes nothing.
  365.              * </p>
  366.              * @return data transfer object that will be serialized
  367.              */
  368.             private Object writeReplace() {
  369.                 return new DataTransferObject();
  370.             }

  372.         };

  374.         /** Private constructor.
  375.          * <p>This class is a utility class, it should neither have a public
  376.          * nor a default constructor. This private constructor prevents
  377.          * the compiler from generating one automatically.</p>
  378.          */
  379.         private LazyRootHolder() {
  380.         }

  382.     }

  384.     /** Internal class used only for serialization. */
  385.     private static class DataTransferObject implements Serializable {

  387.         /** Serializable UID. */
  388.         private static final long serialVersionUID = 4067764035816491212L;

  390.         /** Simple constructor.
  391.          */
  392.         private DataTransferObject() {
  393.         }

  395.         /** Replace the deserialized data transfer object with a {@link FactoryManagedFrame}.
  396.          * @return replacement {@link FactoryManagedFrame}
  397.          */
  398.         private Object readResolve() {
  399.             return getRoot();
  400.         }

  402.     }

  404. }
Created with JaCoCo 0.7.7.201606060606