orientation.fbs

/*
 * ANISE Toolkit
 * Copyright (C) 2021 Christopher Rabotin <christopher.rabotin@gmail.com> et al. (cf. AUTHORS.md)
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at https://mozilla.org/MPL/2.0/.
 */

include "common.fbs";
include "time.fbs";

namespace Anise.Orientation;

/*
 * Spline defines all of the coefficients to interpolate any of the values of this quaternion, body rates, and associated covariance.
 * If the array is empty, it means the data for that parameter is non existent (this does NOT mean it is zero).
 */
table Spline {
    /*
     * Interpolation validity start and end epochs.
     *
     * NOTE: that if the spline was generated backward, the duration may be negative.
     * Compute the usable duration of this spline as follows:
     * duration_in_seconds = spline.usable_end_epoch - spline.usable_start_epoch
     *
     * NOTE: this spline is defined without referencing its index in the ephemeris. In practice,
     * this allows it to be generated on a separate threads and subsequently added to the binary treee
     * representing the unequal time step ephemeris.
     *
     * NOTE: to determine the polynomial degree, peak at the length of each coordinate.
     */
    usable_start_epoch: Time.Epoch (required);
    usable_end_epoch: Time.Epoch (required);
    // State information
    quat_w: [double];
    quat_x: [double];
    quat_y: [double];
    quat_z: [double];
    rate_x: [double];
    rate_y: [double];
    rate_z: [double];
    // Covariance information
    cov_quat_w_quat_w: [double];

    cov_quat_x_quat_w: [double];
    cov_quat_x_quat_x: [double];
    
    cov_quat_y_quat_w: [double];
    cov_quat_y_quat_x: [double];
    cov_quat_y_quat_y: [double];
    
    cov_quat_z_quat_w: [double];
    cov_quat_z_quat_x: [double];
    cov_quat_z_quat_y: [double];
    cov_quat_z_quat_z: [double];
    
    cov_rate_x_quat_w: [double];
    cov_rate_x_quat_x: [double];
    cov_rate_x_quat_y: [double];
    cov_rate_x_quat_z: [double];
    cov_rate_x_rate_x: [double];

    cov_rate_y_quat_w: [double];
    cov_rate_y_quat_x: [double];
    cov_rate_y_quat_y: [double];
    cov_rate_y_quat_z: [double];
    cov_rate_y_rate_x: [double];
    cov_rate_y_rate_y: [double];

    cov_rate_z_quat_w: [double];
    cov_rate_z_quat_x: [double];
    cov_rate_z_quat_y: [double];
    cov_rate_z_quat_z: [double];
    cov_rate_z_rate_x: [double];
    cov_rate_z_rate_y: [double];
    cov_rate_z_rate_z: [double];
}

/*
 * EqualTimeSteps defines an interpolated trajectory where each spline has the same duration, specified in seconds.
 * This method allows for O(1) access to any set of coefficients, thereby O(1) access to compute the position, and
 * optional velocity, of any ephemeris data.
 * This approach is commonly used to interpolate the position of slow moving objects like celestial objects.
 */
table EqualTimeSteps {
    /*
     * The duration of this spline in seconds, used to compute the offset of the vectors to fetch.
     * To retrieve the appropriate index in the coefficient data, apply the following algorithm.
     * 0. Let _epoch_ be the desired epoch, and _start_epoch_ the start epoch of the parent structure.
     * 1. Compute the offset between the desired epoch and the start_epoch: ephem_offset <- desired_epoch - start_epoch
     * 2. Compute the index in splines as: index <- floor( ephem_offset / spline_duration_s)
     * 3. Compute the time offset, in seconds, within that window: t_prime <- ephem_offset - index * spline_duration_s
     * 4. Retrieve the coefficient data at key `index`.
     * 5. Initialize the proper interpolation scheme with t_prime as the requested interpolation time.
     */
    spline_duration_s: double;
    splines: [Spline];
}

/*
 * UnequalTimeSteps defines an interpolated trajectory where each spline has its own duration.
 * This is common for spacecraft trajectories as the dynamics may vary greatly throughout the mission.
 * For example, an Earth orbiter's trajectory needs smaller splines to interpolate its Cartesian position over 1h30min
 * than a spacecraft in deep space between Jupiter and Saturn.
 *
 * This structure provides a pre-sorted index of time offsets enabling an implementor to perform a binary search
 * for the desired coefficients. Hence, UnequalTimeSteps provides O(log(n)) access to any state data.
 *
 * # Primer on building an interpolated trajectory
 * 1. Determine the interpolation scheme, which will determine the number of values (states) needed for the interpolation
 * 2. Determine the interpolation degree, which will determine the number of coefficients to calculate
 * 3. Assume N states are needed. Bucket N states and their associated epoch in a vector of size N.
 * 4. Set the start of the interpolation spline to the epoch of the first state.
 * 5. Normalize all state epochs between -1.0 and +1.0 (i.e. the first state's epoch is now -1.0 and the last is +1.0)
 * 6. Find the interpolation coefficients (ANISE will provide these algorithms).
 * 7. Optionally, verify that querying the interpolation at the initial epochs returns the original state data (x, y, z,... cov_vz_vz).
 */
table UnequalTimeSteps {
   /*
    * A pre-sorted list of all of the offsets from the start_epoch of the Ephemeris
    * available in the list of coefficient data.
    * These time entries are centiseconds (10 milliseconds) past the start_epoch (defined
    * in the parent Ephemeris object). Perform a binary search in this index to retrieve
    * index for the desired epoch. Then, retrieve the Spline for that key.
    * Ensure that the desired epoch is within the usable start and end time offsets.
    * If the desired epoch is prior to that time, select the previous key and check again.
    * If the desired epoch is after that time, select the next key and check again.
    * If within usable time, call the appropriate interpolation function (using the parent's
    * interpolation_kind attribute) with each of the coefficients as the polynominal weights.
    *
    * NOTE: The index is a signed integer of 64 bits because floating point values do not
    * have the total order property, therefore we cannot guarantee an order thereby preventing
    * a binary search of said vector. Further, it's as a signed integer to trivially support trajectories
    * created with a forward and a backward propagation.
    *
    * NOTE: The index points to the start of the window. In theory, this should prevent the binary search
    * from having to seek to the previous set of data compared to a method where the index points to the middle of the window.
    *
    * NOTE: We store the data in centiseconds because experience has shown that, in some high fidelity scenarios,
    * a variable-duration spline may last less than one second (even for only 8 states). In practice, this leads to
    * a collision in the indexing if it were to be in seconds. Therefore, a LIMITATION of this structure is that
    * a variable-duration spline may only be up to 497 days long. If your trajectory is longer than that, you should
    * convert it to an equal-time-step trajectory.
    */
    spline_time_index_cs: [int64];
    splines: [Spline];
    /*
     * The minimum value of the time input to the interpolation function (often -1).
     */
    time_normalization_min: double = -1.0;
    /*
     * The maxmum value of the time input to the interpolation function (often +1)
     */
    time_normalization_max: double = 1.0;
}

/*
 * An Interpolator stores one of two different interpolation methods, each with different access times.
 */
union Interpolator {
    equal_time_steps: EqualTimeSteps,
    unequal_time_steps: UnequalTimeSteps,
}

/* 
 * Orientation stores orientation parameters (quaternion, body rates, covariance) with respect to its parent.
 * In other words, _rotating_ a vector defined in the parent frame by the quaternion represented in this
 * orientation structure will rotate that vector from the parent frame INTO this frame.
 */
table Orientation {
    /*
     * The name is used to generate the (almost) unique hash of this orientation.
     */
    name: string (required);
    /*
     * The reference epoch of this orientation and associated time system (e.g. TDB, UTC, etc.).
     * The reference epoch is used to compute the index in the index in the spline.
     *
     * NOTE: if the orientation table was built backward (cf. backward flag), then the ref_epoch is actually the ending epoch of this
     * table, and you should navigate the interpolation splines to determine the actual start epoch.
     *
     * NOTE: _All_ splines must also be expressed in the same time system as the reference time system.
     */
    ref_epoch: Time.Epoch;
    ref_system: Time.System;
    /*
     * A flag used to tell whether the trajectory was built backward, and if some, some logic is modified.
     */
    backward: bool = false;
    /* 
     * The kind of interpolation used, determines how to evaluate a parameter at a given time.
     */
    interpolation_kind: Common.InterpolationKind;
    /*
     * An Orientation interpolation table which stores the actual data.
     */
    interpolator: Interpolator (required);
    /* 
     * Hash of the parent orientation, e.g. if this object is defined with respect to object A,
     * then the parent_hash will store the hash of object A.
     */
    parent_hash: uint32;
    /*
     * A map of constants. 
     */
    constants: Common.ConstantMap;
}