Package org.orekit.frames

Class Frame

java.lang.Object

org.orekit.frames.Frame

Direct Known Subclasses:

CR3BPRotatingFrame, ExtendedPositionProviderAdapter, FactoryManagedFrame, L1Frame, L2Frame, LocalOrbitalFrame, ModifiedFrame, TopocentricFrame, TwoBodiesBaryFrame, UpdatableFrame, VersionedITRF

public class Frame
extends Object

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

Constructor Summary

Constructors

Constructor	Description
Frame(Frame parent, TransformProvider transformProvider, String name)	Build a non-inertial frame from its transform with respect to its parent.
Frame(Frame parent, TransformProvider transformProvider, String name, boolean pseudoInertial)	Build a frame from its transform with respect to its parent.
Frame(Frame parent, Transform transform, String name)	Build a non-inertial frame from its transform with respect to its parent.
Frame(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	Description
Frame	getAncestor(int n)	Get the nth ancestor of the frame.
int	getDepth()	Get the depth of the frame.
Frame	getFrozenFrame(Frame reference, AbsoluteDate freezingDate, String frozenName)	Get a new version of the instance, frozen with respect to a reference frame.
KinematicTransform	getKinematicTransformTo(Frame destination, AbsoluteDate date)	Get the kinematic portion of the transform from the instance to another frame.
<T extends CalculusFieldElement<T>> FieldKinematicTransform<T>	getKinematicTransformTo(Frame destination, FieldAbsoluteDate<T> date)	Get the kinematic portion of the transform from the instance to another frame.
String	getName()	Get the name.
Frame	getParent()	Get the parent frame.
Frame	getPeer()	Get the peer associated to this frame.
static Frame	getRoot()	Get the unique root frame.
StaticTransform	getStaticTransformTo(Frame destination, AbsoluteDate date)	Get the static portion of the transform from the instance to another frame.
<T extends CalculusFieldElement<T>> FieldStaticTransform<T>	getStaticTransformTo(Frame destination, FieldAbsoluteDate<T> date)	Get the static portion of the transform from the instance to another frame.
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.
<T extends CalculusFieldElement<T>> FieldTransform<T>	getTransformTo(Frame destination, FieldAbsoluteDate<T> date)	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	setPeerCaching(Frame peer, int cacheSize)	Associate this frame to a peer, caching transforms.
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 Details

Frame

public Frame(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 {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:

IllegalArgumentException - if the parent frame is null

Frame

public Frame(Frame parent,
 TransformProvider transformProvider,
 String name)
      throws 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)

transformProvider - provider for transform from parent frame to instance

name - name of the frame

Throws:

IllegalArgumentException - if the parent frame is null

Frame

public Frame(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

Frame

public Frame(Frame parent,
 TransformProvider transformProvider,
 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)

transformProvider - provider for 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 Details

getName

public String getName()

Get the name.

Returns:

the name

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.

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

getDepth

public 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

public Frame getAncestor(int n)
                  throws IllegalArgumentException

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

setPeerCaching

public void setPeerCaching(Frame peer,
 int cacheSize)

Associate this frame to a peer, caching transforms.

The cache is a LRU cache (Least Recently Used), so entries remain in the cache if they are used frequently, and only older entries that have not been accessed for a while will be expunged.

Setting up a peer is mainly intended when there is a real need to speed up conversions in a context when the same frames (origin and destination) are used over and over again at the same date. One typical use case is to peer topocentric frames to the inertial frame when dealing with ground links as the conversion between a ground station (topocentric frame) and inertial frame will be needed for relative position computation, tropospheric effect computation, ionospheric effect computation, on all signal types and for all observables (code, phase, Doppler, signal strength…).

Setting up peer caching does not change the result of the various getTransformTo methods, it just speeds up the computation in the case the same date is used over and over again between the instance and its peer. The computation is just fully performed the first time a date is used and the result is put in the cache before being returned. If a later call uses the same date again and there is a cache hit, then it will return the cached transform without any computation.

The peer frame doesn't need to be close to the initial frame in the hierarchical frames tree, and there is no transitivity involved: peering is a point-to-point relationship. It is for example possible to peer a topocentric frame to the EME2000 frame despite there are several intermediate frames involved when computing the transform (topocentric → ITRF → TIRF → CIRF → GCRF → EME2000), the link will be a direct one and what will be cached at each date is the transform resulting from the combination of all transforms between the intermediate frames at this date. We could have at the same time the intermediate ITRF frame peered to another frame not belonging to this list, it won't have any influence, peering is really point-to-point.

Peering is unidirectional, i.e. if frameA is peered to frameB, it means the transforms that will be cached are the transforms from frameA (the instance when this method or the getTransformTo method are called) to frameB (the argument when this method or the getTransformTo method are called). It is therefore possible to have frameA peered to frameB and frameB peered to another frameC or no frames at all. This allows several frames to be peered to a shared pivot one (typically Earth frame and many topocentric frames all peered to one inertial frame). The side effect of this choice is that peering improves efficiency only in one direction, i.e. if frameA is peered to frameB, then computing the transform from frameB to frameA should be done by computing transform from frameA to frameB and then inverting rather than directly computing the transform from frameB to frameA. It is of course possible to peer frameA to frameB and also frameB to frameA, but this prevents using a shared pivot frame.

Peering is generally set up at the start of the application and kept unchanged throughout its operation, but nothing prevents to change it on the fly, even from different threads. Peering is thread-safe, but shared among all threads (there are internal locks to ensure thread safety), so peering is often set up on a main thread and then used on several other threads, like for example in parallel propagation contexts.

Peering is optional; when a frame is first created, it is not peered to any other frames.

When peering has been set up, caching is enabled for all transforms computed from the instance to its peer, i.e. regular transforms, field transforms, regular kinematic transforms, field kinematic transforms, regular static transforms, field static transforms. It is not possible to set different cached for different transforms types.

If a peer was already associated to this frame, it will be overridden. This can be used to clear peering by setting the peer to null and avoid keeping a reference to a frame that is not used anymore, hence allowing it to be garbage collected.

Parameters:

peer - peer frame (null to clear the cache)

cacheSize - number of transforms kept in the date-based cache

Since:

13.0.3

getPeer

public Frame getPeer()

Get the peer associated to this frame.

Returns:

peer associated with this frame, null if not peered at all

Since:

13.0.3

getTransformTo

public Transform getTransformTo(Frame destination,
 AbsoluteDate date)

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 certain that no date dependent frame is used)

Returns:

transform from the instance to the destination frame

getTransformTo

public <T extends CalculusFieldElement<T>>
FieldTransform<T> getTransformTo(Frame destination,
 FieldAbsoluteDate<T> date)

Get the transform from the instance to another frame.

Type Parameters:

T - the type of the field elements

Parameters:

destination - destination frame to which we want to transform vectors

date - the date (must be non-null, which is a more stringent condition than in getTransformTo(Frame, FieldAbsoluteDate))

Returns:

transform from the instance to the destination frame

getKinematicTransformTo

public KinematicTransform getKinematicTransformTo(Frame destination,
 AbsoluteDate date)

Get the kinematic portion of the transform from the instance to another frame. The returned transform is kinematic in the sense that it includes translations and rotations, with rates, but cannot transform an acceleration vector.

This method is often more performant than getTransformTo(Frame, AbsoluteDate) when accelerations are not needed.

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:

kinematic transform from the instance to the destination frame

Since:

12.1

getStaticTransformTo

public StaticTransform getStaticTransformTo(Frame destination,
 AbsoluteDate date)

Get the static portion of the transform from the instance to another frame. The returned transform is static in the sense that it includes translations and rotations, but not rates.

This method is often more performant than getTransformTo(Frame, AbsoluteDate) when rates are not needed.

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:

static transform from the instance to the destination frame

Since:

11.2

getStaticTransformTo

public <T extends CalculusFieldElement<T>>
FieldStaticTransform<T> getStaticTransformTo(Frame destination,
 FieldAbsoluteDate<T> date)

Get the static portion of the transform from the instance to another frame. The returned transform is static in the sense that it includes translations and rotations, but not rates.

This method is often more performant than getTransformTo(Frame, FieldAbsoluteDate) when rates are not needed.

A first check is made on the FieldAbsoluteDate because "fielded" transforms have low-performance.
The date field is checked with FieldElement.isZero().
If true, the un-fielded version of the transform computation is used.

Type Parameters:

T - type of the elements

Parameters:

destination - destination frame to which we want to transform vectors

date - the date (must be non-null, which is a more stringent condition than in getStaticTransformTo(Frame, AbsoluteDate))

Returns:

static transform from the instance to the destination frame

Since:

12.0

getKinematicTransformTo

public <T extends CalculusFieldElement<T>>
FieldKinematicTransform<T> getKinematicTransformTo(Frame destination,
 FieldAbsoluteDate<T> date)

Get the kinematic portion of the transform from the instance to another frame. The returned transform is kinematic in the sense that it includes translations and rotations, with rates, but cannot transform an acceleration vector.

This method is often more performant than getTransformTo(Frame, AbsoluteDate) when accelerations are not needed.

Type Parameters:

T - Type of transform returned.

Parameters:

destination - destination frame to which we want to transform vectors

date - the date (must be non-null, which is a more stringent condition * than in getKinematicTransformTo(Frame, AbsoluteDate))

Returns:

kinematic transform from the instance to the destination frame

Since:

12.1

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, excluding itself

getRoot

public static Frame getRoot()

Get the unique root frame.

Returns:

the unique instance of the root frame

getFrozenFrame

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

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