Rotational Path (Waypoints)

Description

This feature allows defining the orientation (pointing direction) of a platform over time using a series of time-tagged waypoints specified in the XML configuration. Each waypoint defines the desired elevation and azimuth angles (in radians) at a specific simulation time. The path supports several interpolation methods between these waypoints:

• Static: Holds the orientation from the last waypoint until the next one is reached.
• Linear: Performs simple linear interpolation independently on the elevation and azimuth angles between waypoints.
• Cubic Spline: Calculates a smooth curve through the waypoints using cubic spline interpolation, applied independently to elevation and azimuth.

Assumptions

• Waypoints provided in the XML configuration (<rotationwaypoint>) contain valid numerical values for time, elevation (radians), and azimuth (radians).
• Waypoints are sufficiently dense to allow the chosen interpolation method (Linear, Cubic) to accurately represent the intended smooth orientation changes.
• The chosen interpolation method (Static, Linear, Cubic) is appropriate for the desired platform motion behavior.
• The RotationPath::finalize() method is called internally after all waypoints are added and before getPosition() is called, particularly for cubic interpolation which requires pre-calculation of spline parameters.
• The overloaded arithmetic operators (+, -, * RealType) for the math::RotationCoord struct behave as expected by the generic interpolation algorithms (i.e., perform element-wise operations on elevation and azimuth).
• Waypoint times are monotonically increasing (this is ensured by sorting during the addCoord process).

Limitations

• Limited Interpolation Types: Only Static, Linear, and Cubic Spline interpolation are built-in. More complex or physically-based rotational dynamics (e.g., based on torque, momentum) are not directly supported via this waypoint method.
• Cubic Spline Overshoot: Cubic spline interpolation can potentially cause the interpolated angles to overshoot the range defined by adjacent waypoints, which might be non-physical depending on the scenario.
• No Direct Rate Control: There is no mechanism to directly specify or control angular velocity or acceleration profiles using this waypoint method. These must be implicitly defined by the spacing and values of the waypoints.
• Angle Wrapping: The interpolation relies on simple element-wise arithmetic operations on the RotationCoord's elevation and azimuth angles. It does not explicitly handle shortest-path angle wrapping (e.g., rotating from +170 deg to -170 deg via a 20-degree turn instead of a 340-degree turn). Large angle changes between waypoints might result in unexpected rotation paths due to interpolation occurring independently on each angle component across the potential discontinuity.
• Error Handling: The XML parser discards waypoints with invalid formats rather than halting the simulation, potentially leading to unexpected motion if configuration errors exist.
• Output Format: The RotationPath::getPosition() method returns the orientation as a math::SVec3 (a spherical coordinate vector with radius 1), representing a unit direction vector, not Euler angles or quaternions directly.

Related Components

• XML Parsing: xml_parser.cpp (specifically parseRotationPath function) is responsible for reading <rotationwaypoint> elements.
• Core Logic & Storage: rotation_path.h/.cpp defines the RotationPath class, which stores waypoints (_coords vector of math::RotationCoord), manages the interpolation type (_type enum), and stores cubic spline coefficients (_dd vector). Key methods include addCoord, finalize, and getPosition.
• Interpolation Implementation: path_utils.h provides generic interpolation function templates (e.g., interpolateLinear, interpolateCubic) used by RotationPath.
• Coordinate Representation: coord.h defines the math::RotationCoord struct (holding elevation, azimuth). geometry_ops.h defines math::SVec3 used for the output direction vector.
• Platform Class: The Platform class contains a RotationPath member to manage its orientation over time.

Validation Status

• Needs Verification: The accuracy and behavior of rotational path interpolation, especially concerning angle wrapping and cubic spline behavior, require specific validation.
• Key Areas for Validation:
  • Verify the correctness of Linear and Cubic interpolation implementations for angle pairs representing orientation.
  • Test scenarios involving large angle changes between waypoints (e.g., crossing the +/- PI radian boundary for azimuth) to assess the impact of element-wise interpolation and the lack of explicit shortest-path wrapping logic.
  • Characterize or test conditions under which Cubic Spline interpolation might lead to significant, potentially non-physical, angle overshoots.
  • Confirm that Static interpolation correctly holds the last specified orientation between waypoints.
  • Ensure the returned SVec3 direction vector accurately reflects the interpolated elevation and azimuth according to standard spherical coordinate conventions.
• Priority: Medium (Represents core platform functionality, but has known interpolation limitations and potential edge cases requiring checks).