org.orekit.frames

Class UpdatableFrame

java.lang.Object

org.orekit.frames.Frame

org.orekit.frames.UpdatableFrame

All Implemented Interfaces:

Serializable

public class UpdatableFrame
extends Frame

Frame whose transform from its parent can be updated.

This class allows to control the relative position of two parts of the global frames tree using any two frames in each part as control handles. Consider the following simplified frames tree as an example:

              GCRF
                |
  --------------------------------
  |             |                |
 Sun        satellite          Earth
                |                |
        on-board antenna   ground station
                                 |
                          tracking antenna
 

Tracking measurements really correspond to the link between the ground and on-board antennas. This is tightly linked to the transform between these two frames, however neither frame is the direct parent frame of the other one: the path involves four intermediate frames. When we process a measurement, what we really want to update is the transform that defines the satellite frame with respect to its parent GCRF frame.

In order to implement the above case, the satellite frame is defined as an instance of this class and its updateTransform would be called each time we want to adjust the frame, i.e. each time we get a new measurement between the two antennas.

Author:

Luc Maisonobe

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
UpdatableFrame(Frame parent, Transform transform, String name) Build a non-inertial frame from its transform with respect to its parent.
UpdatableFrame(Frame parent, Transform transform, String name, boolean pseudoInertial) Build a frame from its transform with respect to its parent.

Method Summary

Modifier and Type	Method and Description
void	updateTransform(Frame f1, Frame f2, Transform f1Tof2, AbsoluteDate date) Update the transform from parent frame implicitly according to two other frames.

Methods inherited from class org.orekit.frames.Frame

getAncestor, getDepth, getFrozenFrame, getName, getParent, getRoot, getTransformProvider, getTransformTo, getTransformTo, isChildOf, isPseudoInertial, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

UpdatableFrame

public UpdatableFrame(Frame parent,
                      Transform transform,
                      String name)
               throws IllegalArgumentException

Build a non-inertial frame from its transform with respect to its parent.

calling this constructor is equivalent to call UpdatableFrame(parent, transform, name, false).

Parameters:

parent - parent frame (must be non-null)

transform - transform from parent frame to instance

name - name of the frame

Throws:

IllegalArgumentException - if the parent frame is null

UpdatableFrame

public UpdatableFrame(Frame parent,
                      Transform transform,
                      String name,
                      boolean pseudoInertial)
               throws IllegalArgumentException

Build a frame from its transform with respect to its parent.

The convention for the transform is that it is from parent frame to instance. This means that the two following frames are similar:

 Frame frame1 = new Frame(FramesFactory.getGCRF(), new Transform(t1, t2));
 Frame frame2 = new Frame(new Frame(FramesFactory.getGCRF(), t1), t2);
 

Parameters:

parent - parent frame (must be non-null)

transform - transform from parent frame to instance

name - name of the frame

pseudoInertial - true if frame is considered pseudo-inertial (i.e. suitable for propagating orbit)

Throws:

IllegalArgumentException - if the parent frame is null

Method Detail

updateTransform

public void updateTransform(Frame f1,
                            Frame f2,
                            Transform f1Tof2,
                            AbsoluteDate date)
                     throws OrekitException

Update the transform from parent frame implicitly according to two other frames.

This method allows to control the relative position of two parts of the global frames tree using any two frames in each part as control handles. Consider the following simplified frames tree as an example:

              GCRF
                |
  --------------------------------
  |             |                |
 Sun        satellite          Earth
                |                |
        on-board antenna   ground station
                                 |
                          tracking antenna
 

Tracking measurements really correspond to the link between the ground and on-board antennas. This is tightly linked to the transform between these two frames, however neither frame is the direct parent frame of the other one: the path involves four intermediate frames. When we process a measurement, what we really want to update is the transform that defines the satellite frame with respect to its parent GCRF frame. This is the purpose of this method. This update is done by the following call, where measurementTransform represents the measurement as a simple translation transform between the two antenna frames:

 satellite.updateTransform(onBoardAntenna, trackingAntenna,
                           measurementTransform, date);
 

One way to represent the behavior of the method is to consider the sub-tree rooted at the instance on one hand (satellite and on-board antenna in the example above) and the tree containing all the other frames on the other hand (GCRF, Sun, Earth, ground station, tracking antenna). Both tree are considered as two solid sets linked together by a flexible spring, which is the transform we want to update. The method stretches the spring to make sure the transform between the two specified frames (one in each tree part) matches the specified transform.

Parameters:

f1 - first control frame (may be the instance itself)

f2 - second control frame (may be the instance itself)

f1Tof2 - desired transform from first to second control frame

date - date of the transform

Throws:

OrekitException - if the path between the two control frames does not cross the link between instance and its parent frame or if some intermediate transform fails