fr.cnes.sirius.patrius.frames

Class Frame

java.lang.Object

fr.cnes.sirius.patrius.frames.Frame

All Implemented Interfaces:

PVCoordinatesProvider, Serializable

Direct Known Subclasses:

AttitudeFrame, CelestialBodyFrame, FrozenFrame, H0MinusNFrame, LocalOrbitalFrame, OrientationFrame, SynodicFrame, TopocentricFrame, TranslatedFrame, UpdatableFrame

public class Frame
extends Object
implements PVCoordinatesProvider

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, depending on the implementation of the transform provider used to define the frame. For simple fixed transforms, using FixedTransformProvider is sufficient. For varying transforms (time-dependent or telemetry-based for example), it may be useful to define specific implementations of transform provider.

Author:

Guylaine Prat, Luc Maisonobe, Pascal Parraud

See Also:

Serialized Form

Constructor Summary

Constructors

Modifier	Constructor and Description
	Frame(Frame parentIn, TransformProvider transformProviderIn, String nameIn) Build a non-inertial frame from its transform with respect to its parent.
	Frame(Frame parentIn, TransformProvider transformProviderIn, String nameIn, boolean pseudoInertialIn) Build a frame from its transform with respect to its parent.
	Frame(Frame parentIn, Transform transformIn, String nameIn) Build a non-inertial frame from its transform with respect to its parent.
	Frame(Frame parentIn, Transform transformIn, String nameIn, boolean pseudoInertialIn) Build a frame from its transform with respect to its parent.
protected	Frame(String nameIn, boolean pseudoInertialIn) Private constructor used only for the root frame.

Method Summary

Modifier and Type	Method and Description
protected Frame	getAncestor(int n) Get the nth ancestor of the frame.
protected int	getDepth() Get the depth of the frame.
Frame	getFirstCommonPseudoInertialAncestor(Frame frame) Returns the first pseudo-inertial common ancestor between this and provided frame.
Frame	getFirstPseudoInertialAncestor() Returns the first pseudo-inertial ancestor in the frame tree.
Frame	getFrozenFrame(Frame reference, AbsoluteDate freezingDate, String frozenName) Get a new version of the instance, frozen with respect to a reference frame.
String	getName() Get the name.
Frame	getNativeFrame(AbsoluteDate date) Get the native frame, i.e.
Frame	getParent() Get the parent frame.
PVCoordinates	getPVCoordinates(AbsoluteDate date, Frame frame) Get the PVCoordinates of the frame origin in the selected frame.
protected static CelestialBodyFrame	getRoot() Get the unique root frame.
RealMatrix	getTransformJacobian(Frame to, AbsoluteDate date) Compute the Jacobian from current frame to target frame at provided date.
TransformProvider	getTransformProvider() Get the provider for transform from parent frame to instance.
Transform	getTransformTo(Frame destination, AbsoluteDate date) Get the transform from the instance to another frame.
Transform	getTransformTo(Frame destination, AbsoluteDate date, boolean computeSpinDerivatives) Get the transform from the instance to another frame.
Transform	getTransformTo(Frame destination, AbsoluteDate date, FramesConfiguration config) Get the transform from the instance to another frame.
Transform	getTransformTo(Frame destination, AbsoluteDate date, FramesConfiguration config, boolean computeSpinDerivatives) Get the transform from the instance to another frame.
boolean	isChildOf(Frame potentialAncestor) Determine if a Frame is a child of another one.
boolean	isPseudoInertial() Check if the frame is pseudo-inertial.
void	setName(String name) Set frame name.
void	setReferential(Frame referentialIn) Set the referential of the frame.
String	toString() New definition of the java.util toString() method.

Methods inherited from class java.lang.Object

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

Constructor Detail

Frame

protected Frame(String nameIn,
                boolean pseudoInertialIn)

Private constructor used only for the root frame.

Parameters:

nameIn - name of the frame.

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

Frame

public Frame(Frame parentIn,
             Transform transformIn,
             String nameIn)

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:

parentIn - parent frame (must be non-null)

transformIn - transform from parent frame to instance

nameIn - name of the frame. Must be unique!

Throws:

IllegalArgumentException - if the parent frame is null

Frame

public Frame(Frame parentIn,
             TransformProvider transformProviderIn,
             String nameIn)

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:

parentIn - parent frame (must be non-null)

transformProviderIn - provider for transform from parent frame to instance

nameIn - name of the frame. Must be unique!

Throws:

IllegalArgumentException - if the parent frame is null

Frame

public Frame(Frame parentIn,
             Transform transformIn,
             String nameIn,
             boolean pseudoInertialIn)

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:

parentIn - parent frame (must be non-null)

transformIn - transform from parent frame to instance

nameIn - name of the frame. Must be unique!

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

Throws:

IllegalArgumentException - if the parent frame is null

Frame

public Frame(Frame parentIn,
             TransformProvider transformProviderIn,
             String nameIn,
             boolean pseudoInertialIn)

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:

parentIn - parent frame (must be non-null)

transformProviderIn - provider for transform from parent frame to instance

nameIn - name of the frame. Must be unique!

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

Throws:

IllegalArgumentException - if the parent frame is null

Method Detail

getName

public String getName()

Get the name.

Returns:

the name

getDepth

protected int getDepth()

Get the depth of the frame.

The depth of a frame is the number of parents frame between it and the frames tree root. It is 0 for the root frame, and the depth of a frame is the depth of its parent frame plus one.

Returns:

depth of the frame

getAncestor

protected Frame getAncestor(int n)

Get the n^th ancestor of the frame.

Parameters:

n - index of the ancestor (0 is the instance, 1 is its parent, 2 is the parent of its parent...)

Returns:

n^th ancestor of the frame (must be between 0 and the depth of the frame)

Throws:

IllegalArgumentException - if n is larger than the depth of the instance

isPseudoInertial

public boolean isPseudoInertial()

Check if the frame is pseudo-inertial.

Pseudo-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 using Newtonian mechanics. Frames that are not pseudo-inertial are not suitable for orbit definition and propagation.

Warning: this notion depends on the horizon of propagation and the "level of inertiality of the frame". As a rule of thumb, precession/nutation effects of Earth frames such as CIRF/MOD are considered small enough on a horizon of a day to consider them pseudo-inertial.

Returns:

true if frame is pseudo-inertial

toString

public String toString()

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

Overrides:

toString in class Object

Returns:

the name

getParent

public Frame getParent()

Get the parent frame.

Returns:

parent frame

getTransformTo

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

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:

PatriusException - if some frame specific error occurs

getTransformTo

public Transform getTransformTo(Frame destination,
                                AbsoluteDate date,
                                boolean computeSpinDerivatives)
                         throws PatriusException

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)

computeSpinDerivatives - spin derivatives are computed : true, or not : false

Returns:

transform from the instance to the destination frame

Throws:

PatriusException - if some frame specific error occurs

getTransformTo

public Transform getTransformTo(Frame destination,
                                AbsoluteDate date,
                                FramesConfiguration config)
                         throws PatriusException

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)

config - frames configuration to use

Returns:

transform from the instance to the destination frame

Throws:

PatriusException - if some frame specific error occurs

getTransformTo

public Transform getTransformTo(Frame destination,
                                AbsoluteDate date,
                                FramesConfiguration config,
                                boolean computeSpinDerivatives)
                         throws PatriusException

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)

config - frames configuration to use

computeSpinDerivatives - spin derivatives are computed : true, or not : false

Returns:

transform from the instance to the destination frame

Throws:

PatriusException - if some frame specific error occurs

getTransformProvider

public TransformProvider getTransformProvider()

Get the provider for transform from parent frame to instance.

Returns:

provider for transform from parent frame to instance

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 CelestialBodyFrame getRoot()

Get the unique root frame.

Returns:

the unique instance of the root frame

getFrozenFrame

public Frame getFrozenFrame(Frame reference,
                            AbsoluteDate freezingDate,
                            String frozenName)
                     throws PatriusException

Get a new version of the instance, frozen with respect to a reference frame.

Freezing a frame consist in computing its position and orientation with respect to another frame at some freezing date and fixing them so they do not depend on time anymore. This means the frozen frame is fixed with respect to the reference frame.

One typical use of this method is to compute an inertial launch reference frame by freezing a topocentric frame at launch date with respect to an inertial frame. Another use is to freeze an equinox-related celestial frame at a reference epoch date.

Only the frame returned by this method is frozen, the instance by itself is not affected by calling this method and still moves freely.

Parameters:

reference - frame with respect to which the instance will be frozen

freezingDate - freezing date

frozenName - name of the frozen frame

Returns:

a frozen version of the instance

Throws:

PatriusException - if transform between reference frame and instance cannot be computed at freezing frame

getTransformJacobian

public RealMatrix getTransformJacobian(Frame to,
                                       AbsoluteDate date)
                                throws PatriusException

Compute the Jacobian from current frame to target frame at provided date.

Parameters:

to - target frame

date - date

Returns:

transform Jacobian from current frame to target frame

Throws:

PatriusException - Failed to compute frame transformation

getPVCoordinates

public PVCoordinates getPVCoordinates(AbsoluteDate date,
                                      Frame frame)
                               throws PatriusException

Get the PVCoordinates of the frame origin in the selected frame.

Specified by:

getPVCoordinates in interface PVCoordinatesProvider

Parameters:

date - current date

frame - the frame where to define the position

Returns:

position/velocity of the topocentric frame origin (m and m/s)

Throws:

PatriusException - if position cannot be computed in given frame

getNativeFrame

public Frame getNativeFrame(AbsoluteDate date)
                     throws PatriusException

Get the native frame, i.e. the raw frame in which PVCoordinates are expressed before transformation to user output frame.

Specified by:

getNativeFrame in interface PVCoordinatesProvider

Parameters:

date - a date

Returns:

the native frame

Throws:

PatriusException - thrown if native frame is undefined or unknown

setName

public final void setName(String name)

Set frame name.

Parameters:

name - frame name

setReferential

public void setReferential(Frame referentialIn)

Set the referential of the frame.

Parameters:

referentialIn - referential of the frame to set

getFirstPseudoInertialAncestor

public Frame getFirstPseudoInertialAncestor()

Returns the first pseudo-inertial ancestor in the frame tree. Except for OrphanFrame, it cannot be null since root frame is ICRF which is inertial.

Returns:

the first pseudo-inertial ancestor, this if this is pseudo-inertial

getFirstCommonPseudoInertialAncestor

public Frame getFirstCommonPseudoInertialAncestor(Frame frame)

Returns the first pseudo-inertial common ancestor between this and provided frame. Except for OrphanFrame, it cannot be null since root frame is ICRF which is inertial.

Parameters:

frame - a frame

Returns:

the first pseudo-inertial common ancestor between this and provided frame