orbitutils.h

/******************************************************************************
* Copyright (c) ATTX LLC 2024. All Rights Reserved.
*
* This software and associated documentation (the "Software") are the 
* proprietary and confidential information of ATTX, LLC. The Software is 
* furnished under a license agreement between ATTX and the user organization 
* and may be used or copied only in accordance with the terms of the agreement.
* Refer to 'license/attx_license.adoc' for standard license terms.
*
* EXPORT CONTROL NOTICE: THIS SOFTWARE MAY INCLUDE CONTENT CONTROLLED UNDER THE
* INTERNATIONAL TRAFFIC IN ARMS REGULATIONS (ITAR) OR THE EXPORT ADMINISTRATION 
* REGULATIONS (EAR99). No part of the Software may be used, reproduced, or 
* transmitted in any form or by any means, for any purpose, without the express 
* written permission of ATTX, LLC.
******************************************************************************/
/*
Orbit Utilities header file
---------------------------
This file contains orbit utilities for converting between "classical"
keplerian orbital elements and xyz cartesian position and velocity.
 
It also contains a number of utilities for calculating parameters associated
with keplerian orbits.
 
TODO: Protect edge cases in these files. Right now they only work for 
elliptical orbits
 
The converters in this file are based on those found in Vallado's 
Fundamentals of Astrodynamics and Applications, fourth edition, Chapter
2.5. The test cases are drawn from that text as well.
 
Author: Alex Reynolds
*/
#ifndef UTILS_ORBIT_UTILS_H
#define UTILS_ORBIT_UTILS_H
 
#include "core/macros.h"
#include "core/Matrix.hpp"
#include "core/CartesianVector.hpp"
#include "six_dof_dynamics/Frame.hpp"
#include "six_dof_dynamics/DCM.hpp"
 
namespace clockwerk {
    double true2eccentric(double true_anomaly);
 
    /// @brief Function to convert cartesian xyz pos/vel to orbital elements
    /// @param pos The x, y, z position of the reference object
    /// @param vel The x, y, z velocity of the reference object
    /// @param mu The gravitational parameter of the reference planet
    /// @param elements The orbital elements returned as {a, e, i, W, w, f} -- angles in radians
    /// @return Error code corresponding to success/failure
    /// @note Overloaded for float and double
    /// @note Automatically rounds 0 values for circular and zero-inclined orbits
    ///       to a minimum tolerance. Some values for orbits in circular and zero-inclined
    ///       orbits may not be valid.
    /// @note Automatically rounds 0 values for circular and zero-inclined orbits
    ///       to a minimum tolerance. Some values for orbits in circular and zero-inclined
    ///       orbits may not be valid.
    int rv2coe(const CartesianVector<double, 3> &pos,
            const CartesianVector<double, 3> &vel,
            double mu,
            CartesianVector<double, 6> &elements);
    /// @brief Function to convert cartesian xyz pos/vel to orbital elements
    /// @param pos The x, y, z position of the reference object
    /// @param vel The x, y, z velocity of the reference object
    /// @param mu The gravitational parameter of the reference planet
    /// @param elements The orbital elements returned as {a, e, i, W, w, f} -- angles in radians
    /// @return Error code corresponding to success/failure
    /// @note Overloaded for float and double
    /// @note Automatically rounds 0 values for circular and zero-inclined orbits
    ///       to a minimum tolerance. Some values for orbits in circular and zero-inclined
    ///       orbits may not be valid.
    int rv2coe(const CartesianVector<float, 3> &pos,
            const CartesianVector<float, 3> &vel,
            float mu,
            CartesianVector<float, 6> &elements);
 
    /// @brief Function to convert orbital elements to cartesian xyz
    /// @param elements The orbital elements as {a, e, i, W, w, f} -- angles in radians
    /// @param mu The gravitational parameter of the reference planet
    /// @param pos Return of the x, y, z position of the reference object
    /// @param vel Return of the x, y, z velocity of the reference object
    /// @return Error code corresponding to success/failure
    /// @note Overloaded for float and double
    /// @note Automatically rounds 0 values for circular and zero-inclined orbits
    ///       to a minimum tolerance. Some values for orbits in circular and zero-inclined
    ///       orbits may not be valid.
    /// @todo Update to handle parabolic orbits
    int coe2rv(CartesianVector<double, 6> &elements,
            double mu,
            CartesianVector<double, 3> &pos,
            CartesianVector<double, 3> &vel);
    /// @brief Function to convert orbital elements to cartesian xyz
    /// @param elements The orbital elements as {a, e, i, W, w, f} -- angles in radians
    /// @param mu The gravitational parameter of the reference planet
    /// @param pos Return of the x, y, z position of the reference object
    /// @param vel Return of the x, y, z velocity of the reference object
    /// @return Error code corresponding to success/failure
    /// @note Overloaded for float and double
    /// @todo Update to handle parabolic orbits
    int coe2rv(CartesianVector<float, 6> &elements,
            float mu,
            CartesianVector<float, 3> &pos,
            CartesianVector<float, 3> &vel);
 
    /// @brief Function to generate a 3-1-3 DCM to rotate from PQR to XYZ coordinates
    /// @param i Orbit inclination, in radians
    /// @param W RAAN, in radians
    /// @param w Argument of periapsis, in radians
    /// @return DCM defining the relationship
    /// @note   TODO: Make this function more efficient by pre-defining DCM
    DCM<double> dcmPqr2Xyz(double i, double W, double w);
    /// @brief Function to generate a 3-1-3 DCM to rotate from PQR to XYZ coordinates
    /// @param i Orbit inclination, in radians
    /// @param W RAAN, in radians
    /// @param w Argument of periapsis, in radians
    /// @return DCM defining the relationship
    /// @note   TODO: Make this function more efficient by pre-defining DCM
    DCM<float> dcmPqr2Xyz(float i, float W, float w);
 
    /// @brief Function to generate an LVLH frame attitude DCM from position and velocity
    /// @param pos Spacecraft position
    /// @param vel Spacecraft velocity
    /// @param lvlh_frame DCM describing the LVLH frame attitude
    /// @param lvlh_ang_vel__lvlh Cartesian vector to return angular velocity of LVLH frame in LVLH coordinates
    /// @return Error code corresponding to success/failure
    /// @note   This model creates and maintains the LVLH reference frame 
    ///         according to the NASA definition here:
    ///         https://ntrs.nasa.gov/api/citations/19780010162/downloads/19780010162.pdf
    ///         +Z axis directed toward the center of the Earth
    ///         +Y axis perpendicular to the orbit plane with direction opposite angular momentum
    ///         +X axis completes the right hand frame in the direction of orbit travel
    int lvlhFrame(const CartesianVector3D &pos, const CartesianVector3D &vel, DCMD &lvlh_frame, CartesianVector3D &lvlh_ang_vel__lvlh);
 
    /// @brief Function to generate an LVLH frame attitude DCM from position and velocity
    /// @param pos Spacecraft position
    /// @param vel Spacecraft velocity
    /// @param lvlh_frame DCM describing the LVLH frame attitude
    /// @param lvlh_ang_vel__lvlh Cartesian vector to return angular velocity of LVLH frame in LVLH coordinates
    /// @return Error code corresponding to success/failure
    /// @note   This model creates and maintains the LVLH reference frame 
    ///         according to the NASA definition here:
    ///         https://ntrs.nasa.gov/api/citations/19780010162/downloads/19780010162.pdf
    ///         +Z axis directed toward the center of the Earth
    ///         +Y axis perpendicular to the orbit plane with direction opposite angular momentum
    ///         +X axis completes the right hand frame in the direction of orbit travel
    int lvlhFrame(const CartesianVector3F &pos, const CartesianVector3F &vel, DCMF &lvlh_frame, CartesianVector3F &lvlh_ang_vel__lvlh);
 
}
 
#endif