Description

This PR adds the ability to visualize entity PathGraphics relative to one another.

This is done by adding a new experimental relativeTo property to the PathGraphics class. This property can have the following values:

• Missing property: default to current behavior, which is showing the entity's path polyline points in the same reference frame as the entity's Position.ReferenceFrame
• "FIXED": path polyline points are transformed to a fixed frame regardless of Position.ReferenceFrame
• "INERTIAL": path polyline points are transformed to an inertial frame regardless of Position.ReferenceFrame
• The ID of an entity that has a position
  • If this entity has an orientation: path polyline points are transformed to the "body" frame of that entity
  • Without orientation: path polyline points are transformed to a vehicle velocity, local horizontal (VVLH) frame based on the entity's position and velocity as specified by Position.ReferenceFrame

This new property will also be reflected in the CZML spec following its support in CesiumJS.

Example

Here are the two entities and their paths from the TwoSats.czml example with their path.relativeTo properties set to undefined, defaulting to their Position.ReferenceFrame values, which are both "INERTIAL". Observe how the paths appear straight because we are zoomed in, but if you zoom out, they circle the Earth following an Earth-centered inertial frame.

Now, here are their paths where satellite 2's path.relativeTo is set to the ID of satellite 1. Observe that satellite 1's path appears the same, but satellite 2's path now shows its orbit relative to satellite 1's positon instead of the Earth.

Testing plan

Added a new developer Sandcastle demonstrating this feature. It has the following buttons:

• "Satellite 1" - Displays satellite 2 entity's path relative to satellite 1
• "Satellite 2" - Displays satellite 1's path relative to satellite 2
• "Both" - Displays both satellites with a default undefined path.relativeTo property
• "Earth" - Displays both satellites with a default undefined path.relativeTo, but zoomed out to view their path around the Earth
• "Satellite 2 - fixed frame path" - Displays satellite 1 with a default undefined path.relativeTo property, and satellite 2 with its path relative to a fixed frame
• "Satellite 2 - orientation" - Displays satellite 1 with a default undefined path.relativeTo property, and two versions of satellite 2's path
  • One satellite 2 path, in orange, is relative to satellite 1 where satellite 1 does not have an orientation property set
  • The second satellite 2 path, in yellow, is relative to satellite 1 where satellite 1 does have an orientation property set to "velocityReference":"#position"

There's also a 3rd file TwoSatsRelativeReferenceEnds.czml that isn't included as a UI option. In this file, satellite 1 displays as before, but satellite 2's availability and position data end at an earlier time. This is for testing the case where an entity's path.relativeTo references an entity which no longer has position data. In that case, the path graphic does not continue when its relativeTo entity is gone.

For testing the spec itself, the property has been added to Specs/Data/CZML/ValidationDocument.czml and the test CzmlDataSourceSpec.js.

Author checklist

• I have submitted a Contributor License Agreement
• I have added my name to CONTRIBUTORS.md
• I have updated CHANGES.md with a short summary of my change
• I have added or updated unit tests to ensure consistent code coverage
• I have updated the inline documentation, and included code examples where relevant
• I have performed a self-review of my code
• Awaiting to hear back about possible schema change (about property capitalization/spelling)