Axes, Points, and Vectors

DME Component Libraries contains a full-featured geometry engine for modeling vectors, axes, points, and reference frames. This geometry engine is able to model each of these objects as static geometrical concepts or dynamic ones that may vary in time. For example, a Point might represent the position of a satellite as computed by a propagator. A set of Axes might represent Earth fixed axes. If you are familiar with STK Desktop, the geometry engine in DME Component Libraries is modeled after STK Desktop's Vector Geometry Tool.

Axes, points, and vectors all depend upon the coordinate system used to represent them. In this topic, the most commonly used types of these objects are described and a code example is presented. For additional examples showing how to perform frame transformations, see the Reference Frames and Transformations topic.

Axes

A set of axes provides a method to express coordinates of geometrical objects like points and vectors. They can be used, for example, to express an object's position relative to the Earth fixed frame or a vehicle's moving body frame. Axes can be defined independently of other axes or in terms of other axes, points, and vectors. To create a custom set of axes, refer to the example in the reference documentation for Axes.

Some commonly used types of axes:

Axes	Description
AxesInAxes	A set of axes which takes two input axes and defines a transformation from InAxes (get / set) to AxesToObserve (get / set). This is useful for observing vectors defined in one set of axes in another set of axes.
AxesAlignedConstrained	A set of axes with one axis aligned with the principal direction vector and another axis constrained to keep the angular separation minimal between itself and a supplied reference vector. The unspecified axis is described by the right-hand rule. This set of axes is useful for creating axes defined on the body of a moving platform.
AxesTargetingLink	A set of axes which has the third axis aligned along the link direction between two platforms. The first axis is constrained toward an input reference vector. The second axis is described by the right-hand rule. This class is useful for pointing sensors and their antennas toward their intended targets. This type of axes is very similar to AxesAlignedConstrained.
AxesNorthEastDown	A set of axes which is defined as local north and local east at a specified location point on a given CentralBody. The third primary axis, down, points in the direction of the inverted local normal at that point. This is useful for modeling axes attached to an aircraft. For a diagram illustrating this set of axes, see the reference documentation for AxesNorthEastDown.
AxesAlongTerrain	A set of axes which defines the third axis along the inverted local terrain surface normal of a Point on a given CentralBody. The first axis is aligned with velocity of this point and the second axis is parallel to the surface. This is useful for modeling a ground vehicle.
AxesFixedOffset	A set of axes whose orientation does not change in time with respect to the axes with which it is defined. This can be used to create a fixed axes based upon a simple rotation from another set of axes.
AxesInterpolator	A set of axes which is computed by interpolating a collection of times and rotations from a given reference axes. The samples are specified by a DateMotionCollection2<UnitQuaternion, Cartesian>, which describes at each time a rotation (UnitQuaternion) and an angular velocity (Cartesian) relative to the reference axes. See the inheritance hierarchy in the reference documentation for InterpolationAlgorithm for the types of interpolation available.
CompositeAxes	A set of axes that is defined by a TimeIntervalCollection1<Axes>, where each interval contains a set of axes representing the orientation for that interval.

For a complete listing of the axes included in DME Component Libraries, see the inheritance hierarchy in the reference documentation for Axes.

Points

Points represent a location of interest, like the center of mass of a central body, the location of the center of a vehicle, or the location of a sensor on an object. When Point are used with an appropriate reference frame, you can find the precise location of an object, define a vector, or perform other geometric calculations. For an example of creating a custom point type, see the code in the reference documentation for Point.

Some commonly used types of points:

Point	Description
PointCartographic	A point that represents a fixed planetodetic location on a CentralBody, specified using Cartographic coordinates. This point is useful for specifying a facility location on Earth, for example.
PointFixedOffset	A point whose position does not change in time with respect to the reference frame in which it is defined. This is a useful type of point for cases such as modeling a sensor's location on the body of an aircraft.
PointInPointsFrame	A point that observes a given point (ObservedPoint (get / set)) in the reference frame of another point (FrameOwner (get / set)). This point is useful for observing the Moon's center of mass point from a moving vehicle, for example.
PointInReferenceFrame	A point defined in the specified reference frame. This is a very useful type of point, suitable when the appropriate frame for the point is known in advance. It is possible, for example, to define a point on the Earth, in its fixed frame, and then later observe this point in another frame that has relative motion, like the ICRF.
PointVectorToPoint	A point created by displacing an input point by an input vector. This type of point is useful, for example, in creating a cluster of ships at sea where subordinate ship location points are defined as displacements from a central ship's location point.
PointInterpolator	A point which is computed by interpolating a collection of times and positions. The samples are specified by a DateMotionCollection1<Cartesian>. This type of point is useful, for example, to create a continuously moving point from a set of discrete position measurements of an object, like radar readings of the position of an aircraft. See the inheritance hierarchy in the reference documentation for InterpolationAlgorithm for the types of interpolation available.
CompositePoint	A point defined by a TimeIntervalCollection1<Point>, where each interval contains a Point representing the position for that interval. This is useful for modeling an object that has changes in its motion at discrete times.
PointDifferentiator	A point with higher-order derivatives obtained by numerical derivative calculation via the method of finite-differences on the input point.

For additional information about the types of points available in DME Component Libraries, see the inheritance hierarchy in the reference documentation for Point.

Vectors

Vectors in DME Component Libraries are specified relative to a set of axes. These objects support the usual set of scalar operations: (both in time-varying form and fixed) multiply, divide, add, subtract, and magnitude. Vectors also support the usual vector operations: cross product, dot product, addition, subtraction, and vector derivative. To create a custom type of vector, refer to the example in the reference documentation for Vector.

Some commonly used types of vectors:

Vector	Description
VectorTrueDisplacement	A vector that represents the true geometrical displacement between an initial and final point, even as these points move in time. This vector is useful for computing the time-varying distance between two moving objects, like two aircraft.
VectorApparentDisplacement	A vector that represents the displacement between initial and final points, as in VectorTrueDisplacement, with the addition of modeling light time travel delay between the points and, optionally, astronomical aberration. This type of vector is particularly useful for modeling communication links.
VectorInVectorsAxes	A vector that takes an input vector and expresses it in the second vector's axes, thus observing the first vector in a new set of axes.
VectorInAxes	A vector which takes a vector and reexpresses it in the new supplied axes. This is similar to VectorInVectorsAxes, and is used as a way to translate a vector to new axes.
VectorNormalized	A vector which normalizes a given input vector.
VectorCrossProduct	A vector which takes two supplied input vectors and performs the vector cross product operation.
VectorFixed	A vector whose components do not change in time with respect to the axes with which it is defined. This is useful for defining a displacement vector on a rigid object, for example.
VectorSum	A vector that represents the addition of a number of given Vectors, summed together and observed in a common set of Axes. The axes can be configured, or if not supplied, will be the axes of the first input vector.

For additional information about the types of vectors available in DME Component Libraries, see Vector.

Illustrative Example

The following code sample utilizes several of the key concepts described in this help page. The vector displacement between two objects and the angle between their velocity vectors is computed. The use of a custom reference frame, comprised of a set of axes and a point, is also illustrated.

Java

Copy

// Define the time to evaluate at, and an epoch time for the propagators.
// We define, in the helper methods, the propagators to be valid from epoch to epoch plus one hour.
JulianDate epoch = JulianDate.getNow();
JulianDate timeToEvaluateAt = epoch.addMinutes(30);

// Get the Earth central body.
EarthCentralBody earth = CentralBodiesFacet.getFromContext().getEarth();

// Define an aircraft via a helper method and return the propagator that represents its motion.
WaypointPropagator aircraftPropagator = getAircraftPropagator(epoch);
Point aircraftPoint = aircraftPropagator.createPoint();

// Define a ground vehicle via a helper method and return the propagator that represents its motion.
WaypointPropagator groundVehiclePropagator = getGroundVehiclePropagator(epoch);
Point groundVehiclePoint = groundVehiclePropagator.createPoint();

// Create a custom reference frame that is a rotation about the Earth fixed frame's axes.
ElementaryRotation rotation = new ElementaryRotation(AxisIndicator.FIRST, Constants.HalfPi);
UnitQuaternion quaternion = new UnitQuaternion(rotation);
ReferenceFrame rotatedEarthFixed = new ReferenceFrame(earth.getCenterOfMassPoint(),
                                                      new AxesFixedOffset(earth.getFixedFrame().getAxes(), quaternion));

// Get the velocity vectors.
Vector aircraftVelocity = aircraftPoint.createVectorVelocity(rotatedEarthFixed);
Vector groundVehicleVelocity = groundVehiclePoint.createVectorVelocity(earth.getFixedFrame());

// Compute the angle between the aircraft and ground vehicle's velocity vectors. 
// This scalar will make sure that both velocity vectors are observed in the same frame.
// Get the scalar evaluator for the angle and evaluate at the present time.
ScalarAngleBetweenVectors angleBetweenVelocityVectors = 
        new ScalarAngleBetweenVectors(groundVehicleVelocity, aircraftVelocity);
ScalarEvaluator angleEvaluator = angleBetweenVelocityVectors.getEvaluator();
double angle = angleEvaluator.evaluate(timeToEvaluateAt);

// Compute the displacement vector and the scalar distance between the two vehicles.
VectorTrueDisplacement displacement = new VectorTrueDisplacement(aircraftPoint, groundVehiclePoint);
VectorEvaluator displacementEvaluator = displacement.getEvaluator();
Cartesian displacementVector = displacementEvaluator.evaluate(timeToEvaluateAt);
double distance = displacementVector.getMagnitude();