Package org.orekit.frames

Class FieldTransform<T extends CalculusFieldElement<T>>

  • Type Parameters:
    T - the type of the field elements
    All Implemented Interfaces:
    FieldStaticTransform<T>, FieldTimeShiftable<FieldTransform<T>,​T>, TimeShiftable<FieldTransform<T>>, TimeStamped
    public class FieldTransform<T extends CalculusFieldElement<T>>
extends Object
implements FieldTimeShiftable<FieldTransform<T>,​T>, FieldStaticTransform<T>
    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.

    The convention used in OREKIT is vectorial transformation. It means that a transformation is defined as a transform to apply to the coordinates of a vector expressed in the old frame to obtain the same vector expressed in the new frame.

    Instances of this class are guaranteed to be immutable.

    Examples

    Example of translation from RA to RB

    We want to transform the FieldPVCoordinates PVA to PVB with :

    PVA = ({1, 0, 0}, {2, 0, 0}, {3, 0, 0});
    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(-2, 0, 0);
 Vector3D acceleration = new Vector3D(-3, 0, 0);

 Transform R1toR2 = new Transform(date, translation, velocity, acceleration);

 PVB = R1toR2.transformPVCoordinate(PVA);

    Example of rotation from RA to RB

    We want to transform the FieldPVCoordinates PVA to PVB with

    PVA = ({1, 0, 0}, { 1, 0, 0});
    PVB = ({0, 1, 0}, {-2, 1, 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(rotation, rotationRate);

 PVB = R1toR2.transformPVCoordinates(PVA);
    Since:
    9.0
    Author:
    Luc Maisonobe, Fabien Maussion

    • Constructor Detail

      • FieldTransform

        public FieldTransform​(Field<T> field,
                      Transform transform)
        Build a transform from a regular transform.
        Parameters:
        field - field of the elements
        transform - regular transform to convert

      • FieldTransform

        public FieldTransform​(FieldAbsoluteDate<T> date,
                      FieldVector3D<T> translation)
        Build a translation transform.
        Parameters:
        date - date of the transform
        translation - translation to apply (i.e. coordinates of the transformed origin, or coordinates of the origin of the old frame in the new frame)

      • FieldTransform

        public FieldTransform​(FieldAbsoluteDate<T> date,
                      FieldRotation<T> rotation)
        Build a rotation transform.
        Parameters:
        date - date of the transform
        rotation - rotation to apply ( i.e. rotation to apply to the coordinates of a vector expressed in the old frame to obtain the same vector expressed in the new frame )

      • FieldTransform

        public FieldTransform​(FieldAbsoluteDate<T> date,
                      FieldVector3D<T> translation,
                      FieldVector3D<T> velocity)
        Build a translation transform, with its first time derivative.
        Parameters:
        date - date of the transform
        translation - translation to apply (i.e. coordinates of the transformed origin, or coordinates of the origin of the old frame in the new frame)
        velocity - the velocity of the translation (i.e. origin of the old frame velocity in the new frame)

      • FieldTransform

        public FieldTransform​(FieldAbsoluteDate<T> date,
                      FieldVector3D<T> translation,
                      FieldVector3D<T> velocity,
                      FieldVector3D<T> acceleration)
        Build a translation transform, with its first and second time derivatives.
        Parameters:
        date - date of the transform
        translation - translation to apply (i.e. coordinates of the transformed origin, or coordinates of the origin of the old frame in the new frame)
        velocity - the velocity of the translation (i.e. origin of the old frame velocity in the new frame)
        acceleration - the acceleration of the translation (i.e. origin of the old frame acceleration in the new frame)

      • FieldTransform

        public FieldTransform​(FieldAbsoluteDate<T> date,
                      FieldPVCoordinates<T> cartesian)
        Build a translation transform, with its first time derivative.
        Parameters:
        date - date of the transform
        cartesian - Cartesian part of the transformation to apply (i.e. coordinates of the transformed origin, or coordinates of the origin of the old frame in the new frame, with their derivatives)

      • FieldTransform

        public FieldTransform​(FieldAbsoluteDate<T> date,
                      FieldRotation<T> rotation,
                      FieldVector3D<T> rotationRate)
        Build a rotation transform.
        Parameters:
        date - date of the transform
        rotation - rotation to apply ( i.e. rotation to apply to the coordinates of a vector expressed in the old frame to obtain the same vector expressed in the new frame )
        rotationRate - the axis of the instant rotation expressed in the new frame. (norm representing angular rate)

      • FieldTransform

        public FieldTransform​(FieldAbsoluteDate<T> date,
                      FieldRotation<T> rotation,
                      FieldVector3D<T> rotationRate,
                      FieldVector3D<T> rotationAcceleration)
        Build a rotation transform.
        Parameters:
        date - date of the transform
        rotation - rotation to apply ( i.e. rotation to apply to the coordinates of a vector expressed in the old frame to obtain the same vector expressed in the new frame )
        rotationRate - the axis of the instant rotation
        rotationAcceleration - the axis of the instant rotation expressed in the new frame. (norm representing angular rate)

      • FieldTransform

        public FieldTransform​(FieldAbsoluteDate<T> date,
                      FieldAngularCoordinates<T> angular)
        Build a rotation transform.
        Parameters:
        date - date of the transform
        angular - angular part of the transformation to apply (i.e. rotation to apply to the coordinates of a vector expressed in the old frame to obtain the same vector expressed in the new frame, with its rotation rate)

      • FieldTransform

        public FieldTransform​(FieldAbsoluteDate<T> date,
                      FieldTransform<T> first,
                      FieldTransform<T> second)
        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

    • Method Detail

      • getIdentity

        public static <T extends CalculusFieldElement<T>> FieldTransform<T> getIdentity​(Field<T> field)
        Get the identity transform.
        Type Parameters:
        T - the type of the field elements
        Parameters:
        field - field for the components
        Returns:
        identity transform

      • getFieldDate

        public FieldAbsoluteDate<T> getFieldDate()
        Get the date.
        Returns:
        date attached to the object

      • shiftedBy

        public FieldTransform<T> shiftedBy​(double dt)
        Get a time-shifted instance.
        Specified by:
        shiftedBy in interface TimeShiftable<T extends CalculusFieldElement<T>>
        Parameters:
        dt - time shift in seconds
        Returns:
        a new instance, shifted with respect to instance (which is not changed)

      • staticShiftedBy

        public FieldStaticTransform<T> staticShiftedBy​(T dt)
        Shift the transform in time considering all rates, then return only the translation and rotation portion of the transform.
        Parameters:
        dt - time shift in seconds.
        Returns:
        shifted transform as a static transform. It is static in the sense that it can only be used to transform directions and positions, but not velocities or accelerations.
        See Also:
        shiftedBy(double)

      • toStaticTransform

        public FieldStaticTransform<T> toStaticTransform()
        Create a so-called static transform from the instance.
        Returns:
        static part of the transform. It is static in the sense that it can only be used to transform directions and positions, but not velocities or accelerations.
        See Also:
        FieldStaticTransform

      • interpolate

        public static <T extends CalculusFieldElement<T>> FieldTransform<T> interpolate​(FieldAbsoluteDate<T> date,
                                                                                CartesianDerivativesFilter cFilter,
                                                                                AngularDerivativesFilter aFilter,
                                                                                Collection<FieldTransform<T>> sample)
        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.

        As this implementation of interpolation is polynomial, it should be used only with small samples (about 10-20 points) in order to avoid Runge's phenomenon and numerical problems (including NaN appearing).

        Type Parameters:
        T - the type of the field elements
        Parameters:
        date - interpolation date
        cFilter - filter for derivatives from the sample to use in interpolation
        aFilter - filter for derivatives from the sample to use in interpolation
        sample - sample points on which interpolation should be done
        Returns:
        a new instance, interpolated at specified date

      • interpolate

        public static <T extends CalculusFieldElement<T>> FieldTransform<T> interpolate​(FieldAbsoluteDate<T> date,
                                                                                CartesianDerivativesFilter cFilter,
                                                                                AngularDerivativesFilter aFilter,
                                                                                Stream<FieldTransform<T>> sample)
        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.

        As this implementation of interpolation is polynomial, it should be used only with small samples (about 10-20 points) in order to avoid Runge's phenomenon and numerical problems (including NaN appearing).

        Type Parameters:
        T - the type of the field elements
        Parameters:
        date - interpolation date
        cFilter - filter for derivatives from the sample to use in interpolation
        aFilter - filter for derivatives from the sample to use in interpolation
        sample - sample points on which interpolation should be done
        Returns:
        a new instance, interpolated at specified date

      • freeze

        public FieldTransform<T> freeze()
        Get a frozen transform.

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

        Returns:
        a new transform, without any time-dependent parts

      • transformPVCoordinates

        public FieldPVCoordinates<T> transformPVCoordinates​(PVCoordinates 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

      • transformPVCoordinates

        public TimeStampedFieldPVCoordinates<T> 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

      • transformPVCoordinates

        public FieldPVCoordinates<T> transformPVCoordinates​(FieldPVCoordinates<T> pv)
        Transform TimeStampedFieldPVCoordinates including kinematic effects.

        BEWARE! This method does explicit computation of velocity and acceleration by combining the transform velocity, acceleration, rotation rate and rotation acceleration with the velocity and acceleration from the argument. This implies that this method should not be used when derivatives are contained in the field elements (typically when using DerivativeStructure elements where time is one of the differentiation parameter), otherwise the time derivatives would be computed twice, once explicitly in this method and once implicitly in the field operations. If time derivatives are contained in the field elements themselves, then rather than this method the transformPosition method should be used, so the derivatives are computed once, as part of the field. This method is rather expected to be used when the field elements are DerivativeStructure instances where the differentiation parameters are not time (they can typically be initial state for computing state transition matrices or force models parameters, or ground stations positions, ...).

        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

      • transformPVCoordinates

        public TimeStampedFieldPVCoordinates<T> transformPVCoordinates​(TimeStampedFieldPVCoordinates<T> pv)
        Transform TimeStampedFieldPVCoordinates including kinematic effects.

        BEWARE! This method does explicit computation of velocity and acceleration by combining the transform velocity, acceleration, rotation rate and rotation acceleration with the velocity and acceleration from the argument. This implies that this method should not be used when derivatives are contained in the field elements (typically when using DerivativeStructure elements where time is one of the differentiation parameter), otherwise the time derivatives would be computed twice, once explicitly in this method and once implicitly in the field operations. If time derivatives are contained in the field elements themselves, then rather than this method the transformPosition method should be used, so the derivatives are computed once, as part of the field. This method is rather expected to be used when the field elements are DerivativeStructure instances where the differentiation parameters are not time (they can typically be initial state for computing state transition matrices or force models parameters, or ground stations positions, ...).

        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

      • getJacobian

        public void getJacobian​(CartesianDerivativesFilter selector,
                        T[][] jacobian)
        Compute the Jacobian of the transformPVCoordinates(FieldPVCoordinates) method of the transform.

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

        This definition implies that if we define position-velocity coordinates 

        PV₁ = transform.transformPVCoordinates(PV₀)
        then their differentials dPV₁ and dPV₀ will obey the following relation where J is the matrix computed by this method: 
        dPV₁ = J × dPV₀
        Parameters:
        selector - selector specifying the size of the upper left corner that must be filled (either 3x3 for positions only, 6x6 for positions and velocities, 9x9 for positions, velocities and accelerations)
        jacobian - placeholder matrix whose upper-left corner is to be filled with the Jacobian, the rest of the matrix remaining untouched

      • getCartesian

        public FieldPVCoordinates<T> getCartesian()
        Get the underlying elementary Cartesian part.

        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:
        underlying elementary Cartesian part
        See Also:
        getTranslation(), getVelocity()

      • getAngular

        public FieldAngularCoordinates<T> getAngular()
        Get the underlying elementary angular part.

        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:
        underlying elementary angular part
        See Also:
        getRotation(), getRotationRate(), getRotationAcceleration()