org.orekit.utils
Class AngularCoordinates

java.lang.Object
  org.orekit.utils.AngularCoordinates

All Implemented Interfaces:

Serializable, TimeShiftable<AngularCoordinates>

Direct Known Subclasses:

TimeStampedAngularCoordinates

public class AngularCoordinates
extends Object
implements TimeShiftable<AngularCoordinates>, Serializable

Simple container for rotation/rotation rate/rotation acceleration triplet.

When applied to frames, the rotation here describes the orientation of the frame of interest in the reference frame. This means that defining X_ref=(1,0,0) in the reference frame, the vector X_interest (X axis of the frame of interest, still expressed in the reference frame) is obtained by : rotation.applyTo(X_ref).

The rotation rate (respectively the rotation acceleration) is the vector describing the rotation velocity (rotation acceleration) of the frame of interest relatively to the reference frame. This rotation rate (rotation acceleration) vector is always expressed in the frame of interest.

The state can be slightly shifted to close dates. This shift is based on an approximate solution of the fixed acceleration motion. It is not intended as a replacement for proper attitude propagation but should be sufficient for either small time shifts or coarse accuracy.

This class is the angular counterpart to PVCoordinates.

Instances of this class are guaranteed to be immutable.

Author:

Luc Maisonobe

See Also:

Serialized Form

Field Summary

static AngularCoordinates

IDENTITY Fixed orientation parallel with reference frame (identity rotation, zero rotation rate, zero rotation acceleration).

Constructor Summary

AngularCoordinates()
Simple constructor.

AngularCoordinates(PVCoordinates u1, PVCoordinates u2, PVCoordinates v1, PVCoordinates v2, double tolerance)
Build the rotation that transforms a pair of pv coordinates into another one.

AngularCoordinates(PVCoordinates u1, PVCoordinates u2, PVCoordinates v1, PVCoordinates v2, double tolerance, boolean spinDerivativesComputation)
Build the rotation that transforms a pair of pv coordinates into another one.

AngularCoordinates(Rotation rotation, Vector3D rotationRate)
Builds a rotation/rotation rate triplet (acceleration set to Vector3D.ZERO).

AngularCoordinates(Rotation rotation, Vector3D rotationRate, Vector3D rotationAcceleration)
Builds a rotation/rotation rate/rotation acceleration triplet.

Method Summary

AngularCoordinates	addOffset(AngularCoordinates offset) Add an offset from the instance.
AngularCoordinates	addOffset(AngularCoordinates offset, boolean computeSpinDerivatives) Add an offset from the instance.
PVCoordinates	applyTo(PVCoordinates pv) Apply the rotation to a pv coordinates.
TimeStampedPVCoordinates	applyTo(TimeStampedPVCoordinates pv) Apply the rotation to a pv coordinates.
static AngularCoordinates	createFromModifiedRodrigues(double[][] r) Convert a modified Rodrigues vector and derivatives to angular coordinates.
static AngularCoordinates	createFromModifiedRodrigues(double[][] r, boolean computeSpinDerivatives) Convert a modified Rodrigues vector and derivatives to angular coordinates.
static Vector3D	estimateRate(Rotation start, Rotation end, double dt) Estimate rotation rate between two orientations.
double[][]	getModifiedRodrigues(double sign) Convert rotation, rate and acceleration to modified Rodrigues vector and derivatives.
double[][]	getModifiedRodrigues(double sign, boolean computeSpinDerivative) Convert rotation, rate and acceleration to modified Rodrigues vector and derivatives.
Rotation	getRotation() Get the rotation.
Vector3D	getRotationAcceleration() Get the rotation acceleration.
Vector3D	getRotationRate() Get the rotation rate.
static AngularCoordinates	interpolate(AbsoluteDate date, boolean useRotationRates, Collection<Pair<AbsoluteDate,AngularCoordinates>> sample) Deprecated. since 3.1 replaced with TimeStampedAngularCoordinates.interpolate(AbsoluteDate, AngularDerivativesFilter, Collection)
static AngularCoordinates	interpolate(AbsoluteDate date, boolean useRotationRates, Collection<Pair<AbsoluteDate,AngularCoordinates>> sample, boolean computeSpinDerivative) Deprecated. since 3.1 replaced with TimeStampedAngularCoordinates.interpolate(AbsoluteDate, AngularDerivativesFilter, Collection, boolean)
AngularCoordinates	revert() Revert a rotation/rotation rate/rotation acceleration triplet.
AngularCoordinates	revert(boolean computeSpinDerivatives) Revert a rotation/rotation rate/rotation acceleration triplet.
AngularCoordinates	shiftedBy(double dt) Get a time-shifted state.
AngularCoordinates	shiftedBy(double dt, boolean computeSpinDerivatives) Get a time-shifted state.
AngularCoordinates	subtractOffset(AngularCoordinates offset) Subtract an offset from the instance.
AngularCoordinates	subtractOffset(AngularCoordinates offset, boolean computeSpinDerivatives) Subtract an offset from the instance.

Methods inherited from class java.lang.Object

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

Field Detail

IDENTITY

public static final AngularCoordinates IDENTITY

Fixed orientation parallel with reference frame (identity rotation, zero rotation rate, zero rotation acceleration).

Constructor Detail

AngularCoordinates

public AngularCoordinates()

Simple constructor.

Sets the rotation/rotation rate and acceleration to default : Identity (0 0 0).

AngularCoordinates

public AngularCoordinates(Rotation rotation,
                          Vector3D rotationRate)

Builds a rotation/rotation rate triplet (acceleration set to Vector3D.ZERO).

The rotation here describes the orientation of a frame of interest in a reference frame.

The rotation rate (rotation acceleration) is the vector describing the rotation velocity (rotation acceleration) of the frame of interest relatively to the reference frame. This rotation rate (rotation acceleration) vector is expressed in the frame of interest.

Parameters:

rotation - rotation

rotationRate - rotation rate (rad/s)

AngularCoordinates

public AngularCoordinates(Rotation rotation,
                          Vector3D rotationRate,
                          Vector3D rotationAcceleration)

Builds a rotation/rotation rate/rotation acceleration triplet.

Parameters:

rotation - rotation

rotationRate - rotation rate Ω (rad/s)

rotationAcceleration - rotation acceleration dΩ/dt (rad²/s²)

AngularCoordinates

public AngularCoordinates(PVCoordinates u1,
                          PVCoordinates u2,
                          PVCoordinates v1,
                          PVCoordinates v2,
                          double tolerance,
                          boolean spinDerivativesComputation)
                   throws OrekitException

Build the rotation that transforms a pair of pv coordinates into another one.

WARNING! This method requires much more stringent assumptions on its parameters than the similar constructor from the Rotation class. As a reminder, the rotation r describes the orientation of the frame of interest in the reference frame As far as the Rotation constructor is concerned, the v₂ vector from the second pair can be slightly misaligned. The Rotation constructor will compensate for this misalignment and create a rotation that ensure v₁ = r(u₁) and v₂ ∈ plane (r(u₁), r(u₂)). THIS IS NOT TRUE ANYMORE IN THIS CLASS! As derivatives are involved and must be preserved, this constructor works only if the two pairs are fully consistent, i.e. if a rotation exists that fulfill all the requirements: v₁ = r(u₁), v₂ = r(u₂), dv₁/dt = dr(u₁)/dt, dv₂/dt = dr(u₂)/dt, d²v₁/dt² = d²r(u₁)/dt², d²v₂/dt² = d²r(u₂)/dt².

Parameters:

u1 - first vector of the origin pair

u2 - second vector of the origin pair

v1 - desired image of u1 by the rotation

v2 - desired image of u2 by the rotation

tolerance - relative tolerance factor used to check singularities

spinDerivativesComputation - true if the spin derivative has to be computed. If not, spin derivative is set to null

Throws:

OrekitException - if the vectors are inconsistent for the rotation to be found (null, aligned, ...)

AngularCoordinates

public AngularCoordinates(PVCoordinates u1,
                          PVCoordinates u2,
                          PVCoordinates v1,
                          PVCoordinates v2,
                          double tolerance)
                   throws OrekitException

Build the rotation that transforms a pair of pv coordinates into another one.

WARNING! This method requires much more stringent assumptions on its parameters than the similar constructor from the Rotation class. As a reminder, the rotation r describes the orientation of the frame of interest in the reference frame As far as the Rotation constructor is concerned, the v₂ vector from the second pair can be slightly misaligned. The Rotation constructor will compensate for this misalignment and create a rotation that ensure v₁ = r(u₁) and v₂ ∈ plane (r(u₁), r(u₂)). THIS IS NOT TRUE ANYMORE IN THIS CLASS! As derivatives are involved and must be preserved, this constructor works only if the two pairs are fully consistent, i.e. if a rotation exists that fulfill all the requirements: v₁ = r(u₁), v₂ = r(u₂), dv₁/dt = dr(u₁)/dt, dv₂/dt = dr(u₂)/dt, d²v₁/dt² = d²r(u₁)/dt², d²v₂/dt² = d²r(u₂)/dt².

Warning: spin derivative is not computed.

Parameters:

u1 - first vector of the origin pair

u2 - second vector of the origin pair

v1 - desired image of u1 by the rotation

v2 - desired image of u2 by the rotation

tolerance - relative tolerance factor used to check singularities

Throws:

OrekitException - if the vectors are inconsistent for the rotation to be found (null, aligned, ...)

Method Detail

estimateRate

public static Vector3D estimateRate(Rotation start,
                                    Rotation end,
                                    double dt)

Estimate rotation rate between two orientations.

Estimation is based on a simple fixed rate rotation during the time interval between the two orientations.

Those two orientation must be expressed in the same frame.

Parameters:

start - start orientation

end - end orientation

dt - time elapsed between the dates of the two orientations

Returns:

rotation rate allowing to go from start to end orientations

revert

public AngularCoordinates revert(boolean computeSpinDerivatives)

Revert a rotation/rotation rate/rotation acceleration triplet. Build a triplet which reverse the effect of another triplet.

Parameters:

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

Returns:

a new triplet whose effect is the reverse of the effect of the instance

revert

public AngularCoordinates revert()

Revert a rotation/rotation rate/rotation acceleration triplet. Build a triplet which reverse the effect of another triplet.

Warning: spin derivative is not computed.

Returns:

a new triplet whose effect is the reverse of the effect of the instance

shiftedBy

public AngularCoordinates shiftedBy(double dt)

Get a time-shifted state.

The state can be slightly shifted to close dates. This shift is based on an approximate solution of the fixed acceleration motion. It is not intended as a replacement for proper attitude propagation but should be sufficient for either small time shifts or coarse accuracy.

Warning: spin derivative is not computed.

Specified by:

shiftedBy in interface TimeShiftable<AngularCoordinates>

Parameters:

dt - time shift in seconds

Returns:

a new state, shifted with respect to the instance (which is immutable)

shiftedBy

public AngularCoordinates shiftedBy(double dt,
                                    boolean computeSpinDerivatives)

Get a time-shifted state.

The state can be slightly shifted to close dates. This shift is based on an approximate solution of the fixed acceleration motion. It is not intended as a replacement for proper attitude propagation but should be sufficient for either small time shifts or coarse accuracy.

Parameters:

dt - time shift in seconds

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

Returns:

a new state, shifted with respect to the instance (which is immutable)

getRotation

public Rotation getRotation()

Get the rotation.

Returns:

the rotation.

getRotationRate

public Vector3D getRotationRate()

Get the rotation rate.

Returns:

the rotation rate vector (rad/s).

getRotationAcceleration

public Vector3D getRotationAcceleration()

Get the rotation acceleration.

Returns:

the rotation acceleration vector dΩ/dt (rad²/s²). May be null if not computed at some point

addOffset

public AngularCoordinates addOffset(AngularCoordinates offset,
                                    boolean computeSpinDerivatives)

Add an offset from the instance.

The instance rotation is applied first and the offset is applied afterward. Note that angular coordinates do not commute under this operation, i.e. a.addOffset(b) and b.addOffset(a) lead to different results in most cases.

The rotation of the angular coordinates returned here is a composition of R_instance first and then R_offset. But to compose them, we first have to express them in the same frame : R_offset has to be expressed in the reference frame of the instance. So it becomes : R_instance o R_offset o R_instance^-1. The total composed rotation is then : (R_instance o R_offset o R_instance^-1) o R_instance, wich can be simplified as R_instance o R_offset.

The two methods addOffset and subtractOffset are designed so that round trip applications are possible. This means that both ac1.subtractOffset(ac2).addOffset(ac2) and ac1.addOffset(ac2).subtractOffset(ac2) return angular coordinates equal to ac1.

Parameters:

offset - offset to subtract

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

Returns:

new instance, with offset subtracted

See Also:

subtractOffset(AngularCoordinates)

addOffset

public AngularCoordinates addOffset(AngularCoordinates offset)

Add an offset from the instance.

The instance rotation is applied first and the offset is applied afterward. Note that angular coordinates do not commute under this operation, i.e. a.addOffset(b) and b.addOffset(a) lead to different results in most cases.

The rotation of the angular coordinates returned here is a composition of R_instance first and then R_offset. But to compose them, we first have to express them in the same frame : R_offset has to be expressed in the reference frame of the instance. So it becomes : R_instance o R_offset o R_instance^-1. The total composed rotation is then : (R_instance o R_offset o R_instance^-1) o R_instance, wich can be simplified as R_instance o R_offset.

The two methods addOffset and subtractOffset are designed so that round trip applications are possible. This means that both ac1.subtractOffset(ac2).addOffset(ac2) and ac1.addOffset(ac2).subtractOffset(ac2) return angular coordinates equal to ac1.

Warning: spin derivative is not computed.

Parameters:

offset - offset to subtract

Returns:

new instance, with offset subtracted

See Also:

subtractOffset(AngularCoordinates)

subtractOffset

public AngularCoordinates subtractOffset(AngularCoordinates offset,
                                         boolean computeSpinDerivatives)

Subtract an offset from the instance.

The instance rotation is applied first and the offset is applied afterward. Note that angular coordinates do not commute under this operation, i.e. a.subtractOffset(b) and b.subtractOffset(a) lead to different results in most cases.

The two methods addOffset and subtractOffset are designed so that round trip applications are possible. This means that both ac1.subtractOffset(ac2).addOffset(ac2) and ac1.addOffset(ac2).subtractOffset(ac2) return angular coordinates equal to ac1.

Parameters:

offset - offset to subtract

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

Returns:

new instance, with offset subtracted

See Also:

addOffset(AngularCoordinates)

subtractOffset

public AngularCoordinates subtractOffset(AngularCoordinates offset)

Subtract an offset from the instance.

The instance rotation is applied first and the offset is applied afterward. Note that angular coordinates do not commute under this operation, i.e. a.subtractOffset(b) and b.subtractOffset(a) lead to different results in most cases.

The two methods addOffset and subtractOffset are designed so that round trip applications are possible. This means that both ac1.subtractOffset(ac2).addOffset(ac2) and ac1.addOffset(ac2).subtractOffset(ac2) return angular coordinates equal to ac1.

Warning: spin derivative is not computed.

Parameters:

offset - offset to subtract

Returns:

new instance, with offset subtracted

See Also:

addOffset(AngularCoordinates)

applyTo

public PVCoordinates applyTo(PVCoordinates pv)

Apply the rotation to a pv coordinates.

Parameters:

pv - vector to apply the rotation to

Returns:

a new pv coordinates which is the image of u by the rotation

applyTo

public TimeStampedPVCoordinates applyTo(TimeStampedPVCoordinates pv)

Apply the rotation to a pv coordinates.

Parameters:

pv - vector to apply the rotation to

Returns:

a new pv coordinates which is the image of u by the rotation

interpolate

@Deprecated
public static AngularCoordinates interpolate(AbsoluteDate date,
                                                        boolean useRotationRates,
                                                        Collection<Pair<AbsoluteDate,AngularCoordinates>> sample)
                                      throws OrekitException

Deprecated. since 3.1 replaced with TimeStampedAngularCoordinates.interpolate(AbsoluteDate, AngularDerivativesFilter, Collection)

Interpolate angular coordinates.

The interpolated instance is created by polynomial Hermite interpolation on Rodrigues vector ensuring rotation rate remains the exact derivative of rotation.

This method is based on Sergei Tanygin's paper Attitude Interpolation, changing the norm of the vector to match the modified Rodrigues vector as described in Malcolm D. Shuster's paper A Survey of Attitude Representations. This change avoids the singularity at π. There is still a singularity at 2π, which is handled by slightly offsetting all rotations when this singularity is detected.

Note that even if first time derivatives (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 rotations.

Warning: spin derivative is not computed.

Parameters:

date - interpolation date

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 position-velocity, interpolated at specified date

Throws:

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

interpolate

@Deprecated
public static AngularCoordinates interpolate(AbsoluteDate date,
                                                        boolean useRotationRates,
                                                        Collection<Pair<AbsoluteDate,AngularCoordinates>> sample,
                                                        boolean computeSpinDerivative)
                                      throws OrekitException

Deprecated. since 3.1 replaced with TimeStampedAngularCoordinates.interpolate(AbsoluteDate, AngularDerivativesFilter, Collection, boolean)

Interpolate angular coordinates.

The interpolated instance is created by polynomial Hermite interpolation on Rodrigues vector ensuring rotation rate remains the exact derivative of rotation.

This method is based on Sergei Tanygin's paper Attitude Interpolation, changing the norm of the vector to match the modified Rodrigues vector as described in Malcolm D. Shuster's paper A Survey of Attitude Representations. This change avoids the singularity at π. There is still a singularity at 2π, which is handled by slightly offsetting all rotations when this singularity is detected.

Note that even if first time derivatives (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 rotations.

Parameters:

date - interpolation date

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 position-velocity, interpolated at specified date

Throws:

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

getModifiedRodrigues

public double[][] getModifiedRodrigues(double sign)

Convert rotation, rate and acceleration to modified Rodrigues vector and derivatives.

The modified Rodrigues vector is tan(θ/4) u where θ and u are the rotation angle and axis respectively.

Warning: spin derivative is not computed.

Parameters:

sign - multiplicative sign for quaternion components

Returns:

modified Rodrigues vector and derivatives (vector on row 0, first derivative on row 1, second derivative on row 2)

See Also:

createFromModifiedRodrigues(double[][])

getModifiedRodrigues

public double[][] getModifiedRodrigues(double sign,
                                       boolean computeSpinDerivative)

Convert rotation, rate and acceleration to modified Rodrigues vector and derivatives.

The modified Rodrigues vector is tan(θ/4) u where θ and u are the rotation angle and axis respectively.

Parameters:

sign - multiplicative sign for quaternion components

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

Returns:

modified Rodrigues vector and derivatives (vector on row 0, first derivative on row 1, second derivative on row 2)

See Also:

createFromModifiedRodrigues(double[][])

createFromModifiedRodrigues

public static AngularCoordinates createFromModifiedRodrigues(double[][] r,
                                                             boolean computeSpinDerivatives)

Convert a modified Rodrigues vector and derivatives to angular coordinates.

Parameters:

r - modified Rodrigues vector (with first and second times derivatives)

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

Returns:

angular coordinates

See Also:

getModifiedRodrigues(double)

createFromModifiedRodrigues

public static AngularCoordinates createFromModifiedRodrigues(double[][] r)

Convert a modified Rodrigues vector and derivatives to angular coordinates.

Warning: spin derivative is not computed.

Parameters:

r - modified Rodrigues vector (with first and second times derivatives)

Returns:

angular coordinates

See Also:

getModifiedRodrigues(double)