org.orekit.frames.transformations
Class Transform

java.lang.Object
  org.orekit.frames.transformations.Transform

All Implemented Interfaces:

Serializable, TimeInterpolable<Transform>, TimeShiftable<Transform>, TimeStamped

public class Transform
extends Object
implements TimeStamped, TimeShiftable<Transform>, TimeInterpolable<Transform>, Serializable

Transformation class in three dimensional space.

This class represents the transformation engine between frames. It is used both to define the relationship between each frame and its parent frame and to gather all individual transforms into one operation when converting between frames far away from each other.

A Transform object contain the position, velocity and orientation vectors that describe the "destination" frames in the "origin" one. This means that, defining X_ref=(1,0,0) in the origin frame, the vector X_destination (X axis of the destination frame, still expressed in the reference frame) is obtained by : rotation.applyTo(X_ref).

Instances of this class are guaranteed to be immutable.

Example

 1 ) Example of translation from RA to RB:
 We want to transform the PVCoordinates PVA to PVB.

 With :  PVA = ({1, 0, 0} , {1, 0, 0} , {1, 0, 0});
 and  :  PVB = ({0, 0, 0} , {0, 0, 0} , {0, 0, 0});

 The transform to apply then is defined as follows :

 Vector3D translation = new Vector3D(1,0,0);
 Vector3D velocity = new Vector3D(1,0,0);
 Vector3D acc = new Vector3D(1,0,0);

 Transform R1toR2 = new Transform(date, translation, Velocity, acc);

 PVB = R1toR2.transformPVCoordinates(PVA);


 2 ) Example of rotation from RA to RB:
 We want to transform the PVCoordinates PVA to PVB.

 With :  PVA = ({0, 1, 0}, {-2, 1, 0});
 and  :  PVB = ({1, 0, 0}, {1, 0, 0});

 The transform to apply then is defined as follows :

 Rotation rotation = new Rotation(Vector3D.PLUS_K, FastMath.PI / 2);
 Vector3D rotationRate = new Vector3D(0, 0, 2);

 Transform R1toR2 = new Transform(date, rotation, rotationRate);

 PVB = R1toR2.transformPVCoordinates(PVA);

 

Author:

Luc Maisonobe, Fabien Maussion

See Also:

Serialized Form

Field Summary

static Transform

IDENTITY Identity transform.

Constructor Summary

Transform(AbsoluteDate date, AngularCoordinates angular)
Build a rotation transform.

Transform(AbsoluteDate date, PVCoordinates cartesian)
Build a translation transform, with its first time derivative.

Transform(AbsoluteDate date, PVCoordinates cartesian, AngularCoordinates angular)
Build a transform from its primitive operations.

Transform(AbsoluteDate date, Rotation rotation)
Build a rotation transform.

Transform(AbsoluteDate date, Rotation rotation, Vector3D rotationRate)
Build a rotation transform.

Transform(AbsoluteDate date, Rotation rotation, Vector3D rotationRate, Vector3D rotationAcceleration)
Build a rotation transform.

Transform(AbsoluteDate date, Transform first, Transform second)
Build a transform by combining two existing ones without computing spin derivatives.

Transform(AbsoluteDate date, Transform first, Transform second, boolean computeSpinDerivatives)
Build a transform by combining two existing ones.

Transform(AbsoluteDate date, Vector3D translation)
Build a translation transform.

Transform(AbsoluteDate date, Vector3D translation, Vector3D velocity)
Build a translation transform, with its first time derivative.

Transform(AbsoluteDate date, Vector3D translation, Vector3D velocity, Vector3D acceleration)
Build a translation transform, with its first and second time derivatives.

Method Summary

Transform	freeze() Get a freezed transform.
Vector3D	getAcceleration() Get the second time derivative of the translation.
AngularCoordinates	getAngular() Get the orientation and rotation rate of the "destination" frame in the "origin" one.
PVCoordinates	getCartesian() Get the position and velocity of the "destination" frame in the "origin" one.
AbsoluteDate	getDate() Get the date.
Transform	getInverse() Get the inverse transform of the instance.
Transform	getInverse(boolean computeSpinDerivatives) Get the inverse transform of the instance.
void	getJacobian(double[][] jacobian) Compute the Jacobian of the transformPVCoordinates(PVCoordinates) method of the transform.
Rotation	getRotation() Get the orientation of the "destination" frame in the "origin" one.
Vector3D	getRotationAcceleration() Get the second time derivative of the rotation.
Vector3D	getRotationRate() Get the rotation rate of the "destination" frame in the "origin" one.
Vector3D	getTranslation() Get the position of the "destination" frame in the "origin" one.
Vector3D	getVelocity() Get the velocity of the "destination" frame in the "origin" one.
static Transform	interpolate(AbsoluteDate date, boolean useVelocities, boolean useRotationRates, Collection<Transform> sample) Interpolate a transform from a sample set of existing transforms.
static Transform	interpolate(AbsoluteDate date, boolean useVelocities, boolean useRotationRates, Collection<Transform> sample, boolean computeSpinDerivative) Interpolate a transform from a sample set of existing transforms.
Transform	interpolate(AbsoluteDate interpolationDate, Collection<Transform> sample) Get an interpolated instance.
Transform	interpolate(AbsoluteDate interpolationDate, Collection<Transform> sample, boolean computeSpinDerivative) Get an interpolated instance.
Transform	shiftedBy(double dt) Get a time-shifted instance.
Transform	shiftedBy(double dt, boolean computeSpinDerivative) Get a time-shifted instance.
Line	transformLine(Line line) Transform a line from an algebraic point of view.
Vector3D	transformPosition(Vector3D position) Transform a position vector (including translation effects).
PVCoordinates	transformPVCoordinates(PVCoordinates pv) Transform PVCoordinates including kinematic effects from an algebraic point of view.
TimeStampedPVCoordinates	transformPVCoordinates(TimeStampedPVCoordinates pv) Transform TimeStampedPVCoordinates including kinematic effects.
Vector3D	transformVector(Vector3D vector) Transform a vector (ignoring translation effects).
Wrench	transformWrench(Wrench wrench) Transform a wrench (ignoring translation effects).

Methods inherited from class java.lang.Object

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

Field Detail

IDENTITY

public static final Transform IDENTITY

Identity transform.

Constructor Detail

Transform

public Transform(AbsoluteDate date,
                 Vector3D translation)

Build a translation transform.

Parameters:

date - date of the transform

translation - the position of the "destination" frame expressed in the "origin" one

Transform

public Transform(AbsoluteDate date,
                 Rotation rotation)

Build a rotation transform.

Parameters:

date - date of the transform

rotation - the orientation of the "destination" frame expressed in the "origin" one

Transform

public Transform(AbsoluteDate date,
                 Vector3D translation,
                 Vector3D velocity)

Build a translation transform, with its first time derivative.

Parameters:

date - date of the transform

translation - the position of the "destination" frame expressed in the "origin" one

velocity - the velocity of the "destination" frame expressed in the "origin" one

Transform

public Transform(AbsoluteDate date,
                 Vector3D translation,
                 Vector3D velocity,
                 Vector3D acceleration)

Build a translation transform, with its first and second time derivatives.

Parameters:

date - date of the transform

translation - the position of the "destination" frame expressed in the "origin" one

velocity - the velocity of the "destination" frame expressed in the "origin" one

acceleration - the acceleration of the "destination" frame expressed in the "origin" one

Transform

public Transform(AbsoluteDate date,
                 PVCoordinates cartesian)

Build a translation transform, with its first time derivative.

Parameters:

date - date of the transform

cartesian - position and velocity of the "destination" frame expressed in the "origin" one

Transform

public Transform(AbsoluteDate date,
                 Rotation rotation,
                 Vector3D rotationRate)

Build a rotation transform.

Parameters:

date - date of the transform

rotation - the orientation of the "destination" frame expressed in the "origin" one

rotationRate - the rotation rate of the "destination" frame in the "origin" one, expressed in the "destination" frame

Transform

public Transform(AbsoluteDate date,
                 Rotation rotation,
                 Vector3D rotationRate,
                 Vector3D rotationAcceleration)

Build a rotation transform.

Parameters:

date - date of the transform

rotation - the orientation of the "destination" frame expressed in the "origin" one

rotationRate - the rotation rate of the "destination" frame in the "origin" one, expressed in the "destination" frame

rotationAcceleration - the axis of the instant rotation expressed in the new frame. (norm representing angular rate)

Transform

public Transform(AbsoluteDate date,
                 AngularCoordinates angular)

Build a rotation transform.

Parameters:

date - date of the transform

angular - AngularCoordinates of the "destination" frame in the "origin" one

Transform

public Transform(AbsoluteDate date,
                 Transform first,
                 Transform second)

Build a transform by combining two existing ones without computing spin derivatives.

Warning: spin derivative is not computed.

Parameters:

date - date of the transform

first - first transform applied

second - second transform applied

Transform

public Transform(AbsoluteDate date,
                 Transform first,
                 Transform second,
                 boolean computeSpinDerivatives)

Build a transform by combining two existing ones.

Note that the dates of the two existing transformed are ignored, and the combined transform date is set to the date supplied in this constructor without any attempt to shift the raw transforms. This is a design choice allowing user full control of the combination.

Parameters:

date - date of the transform

first - first transform applied

second - second transform applied

computeSpinDerivatives - true if spin derivatives should be computed. If not, spin derivative is set to null

Transform

public Transform(AbsoluteDate date,
                 PVCoordinates cartesian,
                 AngularCoordinates angular)

Build a transform from its primitive operations.

Parameters:

date - date of the transform

cartesian - position and velocity of the "destination" frame expressed in the "origin" one

angular - AngularCoordinates of the "destination" frame in the "origin" one

Method Detail

getDate

public AbsoluteDate getDate()

Get the date.

Specified by:

getDate in interface TimeStamped

Returns:

date attached to the object

shiftedBy

public Transform shiftedBy(double dt)

Get a time-shifted instance.

Warning: spin derivative is not computed.

Specified by:

shiftedBy in interface TimeShiftable<Transform>

Parameters:

dt - time shift in seconds

Returns:

a new instance, shifted with respect to instance (which is not changed)

shiftedBy

public Transform shiftedBy(double dt,
                           boolean computeSpinDerivative)

Get a time-shifted instance.

Parameters:

dt - time shift in seconds

computeSpinDerivative - true if spin derivatives should be computed. If not, spin derivative is set to null

Returns:

a new instance, shifted with respect to instance (which is not changed)

interpolate

public Transform interpolate(AbsoluteDate interpolationDate,
                             Collection<Transform> sample)
                      throws OrekitException

Get an interpolated instance.

Note that the state of the current instance may not be used in the interpolation process, only its type and non interpolable fields are used (for example central attraction coefficient or frame when interpolating orbits). The interpolable fields taken into account are taken only from the states of the sample points. So if the state of the instance must be used, the instance should be included in the sample points.

Calling this method is equivalent to call interpolate(AbsoluteDate, boolean, boolean, Collection) with both useVelocities and useRotationRates set to true.

Warning: spin derivative is not computed.

Specified by:

interpolate in interface TimeInterpolable<Transform>

Parameters:

interpolationDate - interpolation date

sample - sample points on which interpolation should be done

Returns:

a new instance, interpolated at specified date

Throws:

OrekitException - if the sample points are inconsistent

interpolate

public Transform interpolate(AbsoluteDate interpolationDate,
                             Collection<Transform> sample,
                             boolean computeSpinDerivative)
                      throws OrekitException

Get an interpolated instance.

Note that the state of the current instance may not be used in the interpolation process, only its type and non interpolable fields are used (for example central attraction coefficient or frame when interpolating orbits). The interpolable fields taken into account are taken only from the states of the sample points. So if the state of the instance must be used, the instance should be included in the sample points.

Calling this method is equivalent to call interpolate(AbsoluteDate, boolean, boolean, Collection) with both useVelocities and useRotationRates set to true.

Parameters:

interpolationDate - interpolation date

sample - sample points on which interpolation should be done

computeSpinDerivative - true if spin derivatives should be computed. If not, spin derivative is set to null

Returns:

a new instance, interpolated at specified date

Throws:

OrekitException - if the sample points are inconsistent

interpolate

public static Transform interpolate(AbsoluteDate date,
                                    boolean useVelocities,
                                    boolean useRotationRates,
                                    Collection<Transform> sample)
                             throws OrekitException

Interpolate a transform from a sample set of existing transforms.

Note that even if first time derivatives (velocities and rotation rates) from sample can be ignored, the interpolated instance always includes interpolated derivatives. This feature can be used explicitly to compute these derivatives when it would be too complex to compute them from an analytical formula: just compute a few sample points from the explicit formula and set the derivatives to zero in these sample points, then use interpolation to add derivatives consistent with the positions and rotations.

Warning: spin derivative is not computed.

Parameters:

date - interpolation date

useVelocities - if true, use sample transforms velocities, otherwise ignore them and use only positions

useRotationRates - if true, use sample points rotation rates, otherwise ignore them and use only rotations

sample - sample points on which interpolation should be done

Returns:

a new instance, interpolated at specified date

Throws:

OrekitException - OrekitException if the number of point is too small for interpolating

interpolate

public static Transform interpolate(AbsoluteDate date,
                                    boolean useVelocities,
                                    boolean useRotationRates,
                                    Collection<Transform> sample,
                                    boolean computeSpinDerivative)
                             throws OrekitException

Interpolate a transform from a sample set of existing transforms.

Note that even if first time derivatives (velocities and rotation rates) from sample can be ignored, the interpolated instance always includes interpolated derivatives. This feature can be used explicitly to compute these derivatives when it would be too complex to compute them from an analytical formula: just compute a few sample points from the explicit formula and set the derivatives to zero in these sample points, then use interpolation to add derivatives consistent with the positions and rotations.

Parameters:

date - interpolation date

useVelocities - if true, use sample transforms velocities, otherwise ignore them and use only positions

useRotationRates - if true, use sample points rotation rates, otherwise ignore them and use only rotations

sample - sample points on which interpolation should be done

computeSpinDerivative - true if spin derivatives should be computed. If not, spin derivative is set to null

Returns:

a new instance, interpolated at specified date

Throws:

OrekitException - OrekitException if the number of point is too small for interpolating

getInverse

public Transform getInverse(boolean computeSpinDerivatives)

Get the inverse transform of the instance.

Parameters:

computeSpinDerivatives - true if spin derivatives should be computed. If not, spin derivative is set to null

Returns:

inverse transform of the instance

getInverse

public Transform getInverse()

Get the inverse transform of the instance.

Warning: spin derivative is not computed.

Returns:

inverse transform of the instance

freeze

public Transform freeze()

Get a freezed transform.

This method creates a copy of the instance but frozen in time, i.e. with velocity, rotation rate, acceleration and rotation acceleration set to zero.

Returns:

a new transform, without any time-dependent parts

transformPosition

public Vector3D transformPosition(Vector3D position)

Transform a position vector (including translation effects).

Parameters:

position - vector to transform

Returns:

transformed position

transformVector

public Vector3D transformVector(Vector3D vector)

Transform a vector (ignoring translation effects).

Parameters:

vector - vector to transform

Returns:

transformed vector

transformWrench

public Wrench transformWrench(Wrench wrench)

Transform a wrench (ignoring translation effects).

Parameters:

wrench - wrench to transform

Returns:

transformed wrench

transformLine

public Line transformLine(Line line)

Transform a line from an algebraic point of view.

Parameters:

line - to transform

Returns:

transformed line

transformPVCoordinates

public PVCoordinates transformPVCoordinates(PVCoordinates pv)

Transform PVCoordinates including kinematic effects from an algebraic point of view.

Parameters:

pv - the couple position-velocity to transform.

Returns:

transformed position/velocity

transformPVCoordinates

public TimeStampedPVCoordinates transformPVCoordinates(TimeStampedPVCoordinates pv)

Transform TimeStampedPVCoordinates including kinematic effects.

In order to allow the user more flexibility, this method does not check for consistency between the transform date and the time-stamped position-velocity date. The returned value will always have the same date as the input argument, regardless of the instance date.

Parameters:

pv - time-stamped position-velocity to transform.

Returns:

transformed time-stamped position-velocity

Since:

7.0

getJacobian

public void getJacobian(double[][] jacobian)

Compute the Jacobian of the transformPVCoordinates(PVCoordinates) method of the transform.

Element jacobian[i][j] is the derivative of Cartesian coordinate i of the transformed PVCoordinates with respect to Cartesian coordinate j of the input PVCoordinates in method transformPVCoordinates(PVCoordinates).

This definition implies that if we define position-velocity coordinates

 PV1 = transform.transformPVCoordinates(PV0), then
 

their differentials dPV₁ and dPV₀ will obey the following relation where J is the matrix computed by this method:

 dPV1 = J × dPV0
 

Parameters:

jacobian - placeholder 6x6 (or larger) matrix to be filled with the Jacobian, if matrix is larger than 6x6, only the 6x6 upper left corner will be modified

getCartesian

public PVCoordinates getCartesian()

Get the position and velocity of the "destination" frame in the "origin" one.

NB : A transform can be uniquely represented as an elementary translation followed by an elementary rotation. This method returns this unique elementary translation with its derivative.

Returns:

elementary cartesian part

See Also:

getTranslation(), getVelocity()

getTranslation

public Vector3D getTranslation()

Get the position of the "destination" frame in the "origin" one.

NB : A transform can be uniquely represented as an elementary translation followed by an elementary rotation. This method returns this unique elementary translation.

Returns:

elementary translation

See Also:

getCartesian(), getVelocity()

getVelocity

public Vector3D getVelocity()

Get the velocity of the "destination" frame in the "origin" one.

Returns:

first time derivative of the translation

See Also:

getCartesian(), getTranslation()

getAcceleration

public Vector3D getAcceleration()

Get the second time derivative of the translation.

Returns:

second time derivative of the translation

See Also:

getCartesian(), getTranslation(), getVelocity()

getAngular

public AngularCoordinates getAngular()

Get the orientation and rotation rate of the "destination" frame in the "origin" one.

NB : A transform can be uniquely represented as an elementary translation followed by an elementary rotation. This method returns this unique elementary rotation with its derivative.

Returns:

elementary angular coordinates

See Also:

getRotation(), getRotationRate()

getRotation

public Rotation getRotation()

Get the orientation of the "destination" frame in the "origin" one.

NB : A transform can be uniquely represented as an elementary translation followed by an elementary rotation. This method returns this unique elementary rotation.

Returns:

underlying elementary rotation

See Also:

getAngular(), getRotationRate()

getRotationRate

public Vector3D getRotationRate()

Get the rotation rate of the "destination" frame in the "origin" one.

The norm represents the angular rate.

Returns:

First time derivative of the rotation

See Also:

getAngular(), getRotation()

getRotationAcceleration

public Vector3D getRotationAcceleration()

Get the second time derivative of the rotation. May be null

Returns:

Second time derivative of the rotation

See Also:

getAngular(), getRotation(), getRotationRate()