agi.foundation.propagators

(agi.foundation.models-2024r3.jar)

Class WaypointPropagator

java.lang.Object

agi.foundation.infrastructure.DefinitionalObject

agi.foundation.propagators.CartesianOnePointPropagator

agi.foundation.propagators.WaypointPropagator

All Implemented Interfaces:

ICloneWithContext, IEnumerateDependencies, IEquatableDefinition, IFreezable

public class WaypointPropagator
extends CartesianOnePointPropagator

Propagates a path connecting waypoints relative to an ellipsoid.

The following example shows how to use the WaypointPropagator to move between waypoints at a constant velocity:

EarthCentralBody earth = CentralBodiesFacet.getFromContext().getEarth();
final double constantVelocity = 80.0;

JulianDate startDate = new JulianDate(new GregorianDate(2007, 12, 6, 12, 0, 0.0));

// Create the start point of our route with a particular date, location, and velocity.
Cartographic point1 = new Cartographic(Trig.degreesToRadians(-77.28), Trig.degreesToRadians(39.94), 3000.0);
Waypoint waypoint1 = new Waypoint(startDate, point1, constantVelocity, 0.0);

// Create the next two waypoints from a location, the same velocity, and the previous waypoint.
Cartographic point2 = new Cartographic(Trig.degreesToRadians(-79.59), Trig.degreesToRadians(38.81), 3000.0);
Waypoint waypoint2 = new Waypoint(waypoint1, earth.getShape(), point2, constantVelocity);

Cartographic point3 = new Cartographic(Trig.degreesToRadians(-81.44), Trig.degreesToRadians(39.69), 3000.0);
Waypoint waypoint3 = new Waypoint(waypoint2, earth.getShape(), point3, constantVelocity);

// Construct the waypoint propagator with all of the waypoints
ArrayList<Waypoint> waypoints = new ArrayList<>();
waypoints.add(waypoint1);
waypoints.add(waypoint2);
waypoints.add(waypoint3);
WaypointPropagator propagator = new WaypointPropagator(earth, waypoints);

// The propagator can then be used to create a Point that represents the position and velocity of the
// vehicle moving between the waypoints.
Point propagatedPoint = propagator.createPoint();

// Or an entire set of ephemeris can be computed at a specified time step.
DateMotionCollection1<Cartesian> ephemeris = propagator.propagate(waypoint1.getDate(), waypoint3.getDate(), Duration.fromSeconds(60.0), 1,
        propagator.getReferenceFrame());

Constructor Summary

Constructors

Modifier	Constructor and Description
	WaypointPropagator(CentralBody centralBody, Collection<Waypoint> waypoints) Initializes a waypoint propagator.
	WaypointPropagator(CentralBody centralBody, Waypoint... waypoints) Initializes a waypoint propagator.
protected	WaypointPropagator(WaypointPropagator existingInstance, CopyContext context) Initializes a new instance as a copy of an existing instance.

Method Summary

Modifier and Type	Method and Description
protected boolean	checkForSameDefinition(CartesianOnePointPropagator other) Checks to determine if another instance has the same definition as this instance and returns true if it does.
protected boolean	checkForSameDefinition(WaypointPropagator other) Checks to determine if another instance has the same definition as this instance and returns true if it does.
Object	clone(CopyContext context) Clones this object using the specified context.
protected int	computeCurrentDefinitionHashCode() Computes a hash code based on the current properties of this object.
static WaypointPropagator	constructConstantVelocityWaypointPropagator(CentralBody centralBody, List<JulianDate> times, List<Cartographic> positions) Creates a waypoint propagator from a list of times and locations.
static double	determineDuration(double displacement, double initialVelocity, double finalVelocity) Assuming constant acceleration, determines the duration from the provided parameters.
static double	determineFinalVelocity(double displacement, double duration, double initialVelocity) Assuming constant acceleration, determines the final velocity from the provided parameters.
static double	determineInitialVelocity(double displacement, double duration, double finalVelocity) Assuming constant acceleration, determines the initial velocity from the provided parameters.
void	enumerateDependencies(DependencyEnumerator enumerator) Enumerates the dependencies of this object by calling DependencyEnumerator#enumerate(T) for each object that this object directly depends upon.
TimeIntervalCollection	getAvailabilityIntervals() Gets a TimeIntervalCollection over which data is available.
Ellipsoid	getEllipsoid() Gets the reference ellipsoid.
MotionEvaluator1<Cartesian>	getEvaluator(EvaluatorGroup group) Gets an evaluator that can propagate the position of the path of a platform over time as it traverses the given collection of Waypoints (get) using great arcs across the reference Ellipsoid (get) shape model.
protected ReferenceFrame	getMotionReferenceFrame() Gets the reference frame in which the motion is defined.
ReferenceFrame	getReferenceFrame() Gets the reference frame in which ephemeris information is produced.
TimeInterval	getTimeInterval() Gets the time interval over which the propagator can supply ephemeris.
List<Waypoint>	getWaypoints() Gets the list of waypoints.
boolean	isAvailable(JulianDate date) Determines if valid data is available for the given JulianDate.

Methods inherited from class agi.foundation.propagators.CartesianOnePointPropagator

checkForSameDefinition, createPoint, getEvaluator, propagate, propagate

Methods inherited from class agi.foundation.infrastructure.DefinitionalObject

areSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, collectionItemsAreSameDefinition, collectionItemsAreSameDefinition, collectionItemsAreSameDefinition, dictionaryItemsAreSameDefinition, freeze, freezeAggregatedObjects, getCollectionHashCode, getCollectionHashCode, getCollectionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDictionaryHashCode, getIsFrozen, isSameDefinition, throwIfFrozen

Methods inherited from class java.lang.Object

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

Constructor Detail

WaypointPropagator

public WaypointPropagator(@Nonnull
                          CentralBody centralBody,
                          @Nonnull
                          Collection<Waypoint> waypoints)

Initializes a waypoint propagator.

Parameters:

centralBody - The reference central body.

waypoints - The list of waypoints that define the path and motion.

Throws:

ArgumentNullException - Thrown when centralBody or waypoints is null.

ArgumentException - Thrown when waypoints does not contain at least two items.

ArithmeticException - Thrown when the waypoint collection does not model constant accelerations between the waypoints.

WaypointPropagator

public WaypointPropagator(@Nonnull
                          CentralBody centralBody,
                          @Nonnull
                          Waypoint... waypoints)

Initializes a waypoint propagator.

Parameters:

centralBody - The reference central body.

waypoints - The list of waypoints that define the path and motion.

Throws:

ArgumentNullException - Thrown when centralBody or waypoints is null.

ArgumentException - Thrown when waypoints does not contain at least two items.

ArithmeticException - Thrown when the waypoint collection does not model constant accelerations between the waypoints.

WaypointPropagator

protected WaypointPropagator(@Nonnull
                             WaypointPropagator existingInstance,
                             @Nonnull
                             CopyContext context)

Initializes a new instance as a copy of an existing instance.

See ICloneWithContext.clone(CopyContext) for more information about how to implement this constructor in a derived class.

Parameters:

existingInstance - The existing instance to copy.

context - A CopyContext that controls the depth of the copy.

Throws:

ArgumentNullException - Thrown when existingInstance or context is null.

Method Detail

clone

public Object clone(CopyContext context)

Clones this object using the specified context.

This method should be implemented to call a copy constructor on the class of the object being cloned. The copy constructor should take the CopyContext as a parameter in addition to the existing instance to copy. The copy constructor should first call CopyContext.addObjectMapping(T, T) to identify the newly constructed instance as a copy of the existing instance. It should then copy all fields, using CopyContext.updateReference(T) to copy any reference fields.

A typical implementation of ICloneWithContext:

public static class MyClass implements ICloneWithContext {
    public MyClass(MyClass existingInstance, CopyContext context) {
        context.addObjectMapping(existingInstance, this);
        someReference = context.updateReference(existingInstance.someReference);
    }

    @Override
    public final Object clone(CopyContext context) {
        return new MyClass(this, context);
    }

    private Object someReference;
}

In general, all fields that are reference types should be copied with a call to CopyContext.updateReference(T). There are a couple of exceptions:

1. Fields that are aggregate parts of the object should always be copied. A referenced object is an aggregate if properties or methods on the object being copied can modify the externally-visible value of the referenced object.
2. If the semantics of the referenced object require that it have a single parent, owner, context, etc., and the object being copied is that parent, owner, or context, then the referenced object should always be copied.

If one of these exceptions applies, the CopyContext should be given an opportunity to update the reference before the reference is copied explicitly. Use CopyContext.updateReference(T) to update the reference. If CopyContext.updateReference(T) returns the original object, indicating that the context does not have a replacement registered, then copy the object manually by invoking a Clone method, a copy constructor, or by manually constructing a new instance and copying the values.

alwaysCopy = context.updateReference(existingInstance.alwaysCopy);
if (existingInstance.alwaysCopy != null && alwaysCopy == existingInstance.alwaysCopy) {
    alwaysCopy = (AlwaysCopy) existingInstance.alwaysCopy.clone(context);
}

If you are implementing an evaluator (a class that implements IEvaluator), the IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) method shares some responsibilities with the copy context constructor. Code duplication can be avoided by doing the following:

1. For references to other evaluators ONLY, simply assign the reference in the constructor instead of calling CopyContext.updateReference(T). You should still call CopyContext.updateReference(T) on any references to non-evaluators.
2. Call IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) as the last line in the constructor and pass it the same CopyContext passed to the constructor.
3. Implement IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) as normal. See the reference documentation for IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) for more information on implementing that method.

public MyClass(MyClass existingInstance, CopyContext context) {
    super(existingInstance, context);
    someReference = context.updateReference(existingInstance.someReference);
    evaluatorReference = existingInstance.evaluatorReference;
    updateEvaluatorReferences(context);
}

@Override
public void updateEvaluatorReferences(CopyContext context) {
    evaluatorReference = context.updateReference(evaluatorReference);
}

@Override
public Object clone(CopyContext context) {
    return new MyClass(this, context);
}

private Object someReference;
private IEvaluator evaluatorReference;

Specified by:

clone in interface ICloneWithContext

Specified by:

clone in class DefinitionalObject

Parameters:

context - The context to use to perform the copy.

Returns:

A new instance which is a copy of this object.

checkForSameDefinition

protected final boolean checkForSameDefinition(CartesianOnePointPropagator other)

Checks to determine if another instance has the same definition as this instance and returns true if it does. Derived classes MUST override this method and check all new fields introduced by the derived class for definitional equivalence. It is NOT necessary to check base class fields because the base class will already have done that. When overriding this method, you should NOT call the base implementation because it will return false for all derived-class instances. Derived classes should check the type of other to preserve the symmetric nature of IEquatableDefinition.isSameDefinition(java.lang.Object).

Specified by:

checkForSameDefinition in class CartesianOnePointPropagator

Parameters:

other - The other instance to compare to this one.

Returns:

true if the two objects are defined equivalently; otherwise false.

checkForSameDefinition

protected boolean checkForSameDefinition(WaypointPropagator other)

Checks to determine if another instance has the same definition as this instance and returns true if it does. Derived classes MUST override this method and check all new fields introduced by the derived class for definitional equivalence. It is NOT necessary to check base class fields because the base class will already have done that. When overriding this method, you should NOT call the base implementation because it will return false for all derived-class instances. Derived classes should check the type of other to preserve the symmetric nature of IEquatableDefinition.isSameDefinition(java.lang.Object).

Parameters:

other - The other instance to compare to this one.

Returns:

true if the two objects are defined equivalently; otherwise false.

computeCurrentDefinitionHashCode

protected int computeCurrentDefinitionHashCode()

Computes a hash code based on the current properties of this object. Derived classes MUST override this method and compute a hash code that combines: a unique hash code seed, the base implementation result, and the hash codes of all new fields introduced by the derived class which are used in the WaypointPropagator.checkForSameDefinition(agi.foundation.propagators.CartesianOnePointPropagator) method.

Overrides:

computeCurrentDefinitionHashCode in class CartesianOnePointPropagator

Returns:

The computed hash code.

enumerateDependencies

public void enumerateDependencies(DependencyEnumerator enumerator)

Enumerates the dependencies of this object by calling DependencyEnumerator#enumerate(T) for each object that this object directly depends upon. Derived classes which contain additional dependencies MUST override this method, call the base implementation, and enumerate dependencies introduced by the derived class.

Specified by:

enumerateDependencies in interface IEnumerateDependencies

Overrides:

enumerateDependencies in class DefinitionalObject

Parameters:

enumerator - The enumerator that is informed of the dependencies of this object.

isAvailable

public final boolean isAvailable(@Nonnull
                                 JulianDate date)

Determines if valid data is available for the given JulianDate.

Parameters:

date - The date for which to check availability.

Returns:

true if valid data is available for this date; otherwise false.

determineFinalVelocity

public static double determineFinalVelocity(double displacement,
                                            double duration,
                                            double initialVelocity)

Assuming constant acceleration, determines the final velocity from the provided parameters.

• The displacement should not be zero.
• The duration should be positively valued.
• The displacement and initial velocity should have the same sign.
• The initial velocity may be zero.

Parameters:

displacement - The total displacement between the initial and final points (distance).

duration - The total duration between the initial and final points (time).

initialVelocity - The velocity at the initial point (distance per time).

Returns:

The velocity at the final point (distance per time).

determineInitialVelocity

public static double determineInitialVelocity(double displacement,
                                              double duration,
                                              double finalVelocity)

Assuming constant acceleration, determines the initial velocity from the provided parameters.

• The displacement should not be zero.
• The duration should be positively valued.
• The displacement and final velocity should have the same sign.
• The final velocity may be zero.

Parameters:

displacement - The total displacement between the initial and final points (distance).

duration - The total duration between the initial and final points (time).

finalVelocity - The velocity at the final point (distance per time).

Returns:

The velocity at the initial point (distance per time).

determineDuration

public static double determineDuration(double displacement,
                                       double initialVelocity,
                                       double finalVelocity)

Assuming constant acceleration, determines the duration from the provided parameters.

• The displacement should not be zero.
• The initial and final velocities should have the same sign.
• Either the initial or the final velocity may be zero.

Parameters:

displacement - The total displacement between the initial and final points (distance).

initialVelocity - The velocity at the initial point (distance per time).

finalVelocity - The velocity at the final point (distance per time).

Returns:

The total duration between the initial and final points (time).

constructConstantVelocityWaypointPropagator

@Nonnull
public static WaypointPropagator constructConstantVelocityWaypointPropagator(@Nonnull
                                                                                       CentralBody centralBody,
                                                                                       @Nonnull
                                                                                       List<JulianDate> times,
                                                                                       @Nonnull
                                                                                       List<Cartographic> positions)

Creates a waypoint propagator from a list of times and locations. The object will travel from point to point at a constant ground speed and rate of climb, with discontinuous jumps in those parameters at the waypoints.

Parameters:

centralBody - The reference central body.

times - The list of times the point will be at the given positions.

positions - The list of positions the point will be at the given times.

Returns:

A waypoint propagator where each coordinate is visited at the specified time, while traveling at constant speed between coordinates.

Throws:

ArgumentNullException - Thrown when centralBody, times, or positions is null.

ArgumentException - Thrown when the times and positions lists have different numbers of elements, or do not contain at least two items each.

getEvaluator

public MotionEvaluator1<Cartesian> getEvaluator(EvaluatorGroup group)

Gets an evaluator that can propagate the position of the path of a platform over time as it traverses the given collection of Waypoints (get) using great arcs across the reference Ellipsoid (get) shape model. The resulting evaluator will produce the Cartesian position for a given JulianDate within the range of the waypoint data represented by TimeInterval (get).

The evaluator will throw a DataUnavailableException when evaluated at dates before the initial waypoint and after the final waypoint.

Specified by:

getEvaluator in class CartesianOnePointPropagator

Parameters:

group - The group with which to associate the new evaluator. By grouping evaluators that are often evaluated at the same Julian dates, common computations can be performed only once for the entire group instead of multiple times for each evaluator.

Returns:

The evaluator.

Throws:

ArgumentNullException - Thrown when group is null.

See Also:

CartesianOnePointPropagator.createPoint()

getTimeInterval

@Nonnull
public final TimeInterval getTimeInterval()

Gets the time interval over which the propagator can supply ephemeris.

getReferenceFrame

public final ReferenceFrame getReferenceFrame()

Gets the reference frame in which ephemeris information is produced.

getMotionReferenceFrame

protected ReferenceFrame getMotionReferenceFrame()

Gets the reference frame in which the motion is defined.

Specified by:

getMotionReferenceFrame in class CartesianOnePointPropagator

Returns:

The reference frame.

getEllipsoid

public final Ellipsoid getEllipsoid()

Gets the reference ellipsoid.

getWaypoints

@Nonnull
public final List<Waypoint> getWaypoints()

Gets the list of waypoints.

getAvailabilityIntervals

public final TimeIntervalCollection getAvailabilityIntervals()

Gets a TimeIntervalCollection over which data is available. If the availability interval is infinite, this returns Infinite (get).

It is recommended that you call WaypointPropagator.isAvailable(agi.foundation.time.JulianDate) to determine availability instead of calling this method and checking for yourself.

Returns:

The collection of availability intervals.