org.orekit.frames
Class Frame

java.lang.Object
  org.orekit.frames.Frame

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

LocalOrbitalFrame, SpacecraftFrame, TopocentricFrame

public class Frame
extends java.lang.Object
implements java.io.Serializable

Tridimensional references frames class.

Frame Presentation

This class is the base class for all frames in OREKIT. The frames are linked together in a tree with some specific frame chosen as the root of the tree. Each frame is defined by transforms combining any number of translations and rotations from a reference frame which is its parent frame in the tree structure.

When we say a transform t is from frame_A to frame_B, we mean that if the coordinates of some absolute vector (say the direction of a distant star for example) has coordinates u_A in frame_A and u_B in frame_B, then u_B=t.transformVector(uA).

The transforms may be constant or varying. For simple fixed transforms, using this base class is sufficient. For varying transforms (time-dependent or telemetry-based for example), it may be useful to define specific subclasses that will implement updateFrame(AbsoluteDate) or that will add some specific updateFromTelemetry(telemetry) methods that will compute the transform and call internally the setTransform(Transform) method.

Version:

$Revision: 3174 $ $Date: 2010-03-17 17:34:41 +0100 (mer. 17 mars 2010) $

Author:

Guylaine Prat, Luc Maisonobe, Pascal Parraud

See Also:

Serialized Form

Constructor Summary

Frame(Frame parent, Transform transform, java.lang.String name)
Build a non-inertial frame from its transform with respect to its parent.

Frame(Frame parent, Transform transform, java.lang.String name, boolean quasiInertial)
Build a frame from its transform with respect to its parent.

Method Summary

static Frame	getCIRF2000() Deprecated. as of 4.1, replaced by FramesFactory.getCIRF2000()
static Frame	getEME2000() Deprecated. as of 4.1, replaced by FramesFactory.getEME2000()
static Frame	getITRF2005() Deprecated. as of 4.1, replaced by FramesFactory.getITRF2005()
static Frame	getJ2000() Deprecated. as of 4.0, replaced by FramesFactory.getEME2000()
java.lang.String	getName() Get the name.
Frame	getParent() Get the parent frame.
protected static Frame	getRoot() Get the unique root frame.
static Frame	getTIRF2000() Deprecated. as of 4.1, replaced by FramesFactory.getTIRF2000()
Transform	getTransformTo(Frame destination, AbsoluteDate date) Get the transform from the instance to another frame.
static Frame	getVeis1950() Deprecated. as of 4.1, replaced by FramesFactory.getVeis1950()
boolean	isChildOf(Frame potentialAncestor) Determine if a Frame is a child of another one.
boolean	isQuasiInertial() Check if the frame is quasi-inertial.
void	setTransform(Transform transform) Update the transform from the parent frame to the instance.
java.lang.String	toString() New definition of the java.util toString() method.
protected void	updateFrame(AbsoluteDate date) Update the frame to the given date.
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 java.lang.Object

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

Constructor Detail

Frame

public Frame(Frame parent,
             Transform transform,
             java.lang.String name)
      throws java.lang.IllegalArgumentException

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

calling this constructor is equivalent to call {link Frame(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:

java.lang.IllegalArgumentException - if the parent frame is null

Frame

public Frame(Frame parent,
             Transform transform,
             java.lang.String name,
             boolean quasiInertial)
      throws java.lang.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

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

Throws:

java.lang.IllegalArgumentException - if the parent frame is null

Method Detail

getName

public java.lang.String getName()

Get the name.

Returns:

the name

isQuasiInertial

public boolean isQuasiInertial()

Check if the frame is quasi-inertial.

Quasi-inertial frames are frames that do have a linear motion and either do not rotate or rotate at a very low rate resulting in neglectible inertial forces. This means they are suitable for orbit definition and propagation. Frames that are not quasi-inertial are not suitable for orbit definition and propagation.

Returns:

true if frame is quasi-inertial

toString

public java.lang.String toString()

New definition of the java.util toString() method.

Overrides:

toString in class java.lang.Object

Returns:

the name

getParent

public Frame getParent()

Get the parent frame.

Returns:

parent frame

setTransform

public void setTransform(Transform transform)

Update the transform from the parent frame to the instance.

Parameters:

transform - new transform from parent frame to instance

getTransformTo

public Transform getTransformTo(Frame destination,
                                AbsoluteDate date)
                         throws OrekitException

Get the transform from the instance to another frame.

Parameters:

destination - destination frame to which we want to transform vectors

date - the date (can be null if it is sure than no date dependent frame is used)

Returns:

transform from the instance to the destination frame

Throws:

OrekitException - if some frame specific error occurs

updateFrame

protected void updateFrame(AbsoluteDate date)
                    throws OrekitException

Update the frame to the given date.

This method is called each time getTransformTo(Frame, AbsoluteDate) is called. The base implementation in the Frame class does nothing. The proper way to build a date-dependent frame is to extend the Frame class and implement this method which will have to call setTransform(Transform) with the new transform

Parameters:

date - new value of the date

Throws:

OrekitException - if some frame specific error occurs

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 ones: 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 represent 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 solid sets linked 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

See Also:

setTransform(Transform)

isChildOf

public boolean isChildOf(Frame potentialAncestor)

Determine if a Frame is a child of another one.

Parameters:

potentialAncestor - supposed ancestor frame

Returns:

true if the potentialAncestor belongs to the path from instance to the root frame

getRoot

protected static Frame getRoot()

Get the unique root frame.

Returns:

the unique instance of the root frame

getJ2000

@Deprecated
public static Frame getJ2000()

Deprecated. as of 4.0, replaced by FramesFactory.getEME2000()

Get the unique J2000 frame.

The J2000 frame is also called the EME2000 frame. The latter denomination is preferred in Orekit.

Returns:

the unique instance of the J2000 frame

See Also:

FramesFactory.getEME2000()

getEME2000

@Deprecated
public static Frame getEME2000()

Deprecated. as of 4.1, replaced by FramesFactory.getEME2000()

Get the unique EME2000 frame.

The EME2000 frame is also called the J2000 frame. The former denomination is preferred in Orekit.

Returns:

the unique instance of the EME2000 frame

getITRF2005

@Deprecated
public static Frame getITRF2005()
                         throws OrekitException

Deprecated. as of 4.1, replaced by FramesFactory.getITRF2005()

Get the ITRF2005 reference frame.

Returns:

the selected reference frame singleton.

Throws:

OrekitException - if the precession-nutation model data embedded in the library cannot be read.

getTIRF2000

@Deprecated
public static Frame getTIRF2000()
                         throws OrekitException

Deprecated. as of 4.1, replaced by FramesFactory.getTIRF2000()

Get the TIRF2000 reference frame.

Returns:

the selected reference frame singleton.

Throws:

OrekitException - if the precession-nutation model data embedded in the library cannot be read.

getCIRF2000

@Deprecated
public static Frame getCIRF2000()
                         throws OrekitException

Deprecated. as of 4.1, replaced by FramesFactory.getCIRF2000()

Get the CIRF2000 reference frame.

Returns:

the selected reference frame singleton.

Throws:

OrekitException - if the precession-nutation model data embedded in the library cannot be read.

getVeis1950

@Deprecated
public static Frame getVeis1950()
                         throws OrekitException

Deprecated. as of 4.1, replaced by FramesFactory.getVeis1950()

Get the VEIS 1950 reference frame.

Returns:

the selected reference frame singleton.

Throws:

OrekitException - if data data embedded in the library cannot be read.