Program Listing for File RotationVector.h#
↰ Return to documentation for file (include/Karana/Math/RotationVector.h)
/*
* Copyright (c) 2024-2026 Karana Dynamics Pty Ltd. All rights reserved.
*
* NOTICE TO USER:
*
* This source code and/or documentation (the "Licensed Materials") is
* the confidential and proprietary information of Karana Dynamics Inc.
* Use of these Licensed Materials is governed by the terms and conditions
* of a separate software license agreement between Karana Dynamics and the
* Licensee ("License Agreement"). Unless expressly permitted under that
* agreement, any reproduction, modification, distribution, or disclosure
* of the Licensed Materials, in whole or in part, to any third party
* without the prior written consent of Karana Dynamics is strictly prohibited.
*
* THE LICENSED MATERIALS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.
* KARANA DYNAMICS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
* BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, AND
* FITNESS FOR A PARTICULAR PURPOSE.
*
* IN NO EVENT SHALL KARANA DYNAMICS BE LIABLE FOR ANY DAMAGES WHATSOEVER,
* INCLUDING BUT NOT LIMITED TO LOSS OF PROFITS, DATA, OR USE, EVEN IF
* ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, WHETHER IN CONTRACT, TORT,
* OR OTHERWISE ARISING OUT OF OR IN CONNECTION WITH THE LICENSED MATERIALS.
*
* U.S. Government End Users: The Licensed Materials are a "commercial item"
* as defined at 48 C.F.R. 2.101, and are provided to the U.S. Government
* only as a commercial end item under the terms of this license.
*
* Any use of the Licensed Materials in individual or commercial software must
* include, in the user documentation and internal source code comments,
* this Notice, Disclaimer, and U.S. Government Use Provision.
*/
/**
* @file
* @brief Contains the declarations for the RotationVector class.
*/
#pragma once
#include "Karana/Math/Defs.h"
namespace Karana::Math {
using namespace Eigen;
/**
* @class RotationVector
* @brief The (n * theta) Rotation Vector attitude representation
* minimal coordinate representation for orientations, where n is a
* unit vector, and theta is an angle. See \sref{attitude_sec} section
* for more discussion on attitude representations.
*
* It is recommended that the angle be in [0, PI] range to preserve
* 1-1 mapping in the space of orientations, and to stay from
* singularities at multiples of 2*PI. There is however no angle
* range restriction imposed in this class. This is the
* representation used for exponential map representations of
* orientation.
*/
class RotationVector {
// Constructors
public:
/** Default constructor */
RotationVector();
/**
* @brief Constructor from 3 vector.
*
* @param vec the 3-vector of coefficients
*
*/
RotationVector(const Vec3 &vec);
// Copy constructor, move constructor, and assignment operators
public:
/**
* @brief Copy constructor.
* @param rv Other RotationVector to copy from.
*/
RotationVector(const RotationVector &rv);
/**
* @brief Copy assignment operator.
* @param other Other RotationVector to copy from.
* @return Reference to this object.
*/
RotationVector &operator=(const RotationVector &other);
/**
* @brief Move constructor.
* @param rv RotationVector to move from.
*/
RotationVector(RotationVector &&rv) noexcept;
/**
* @brief Move assignment operator.
* @param other RotationVector to move from.
* @return Reference to this object.
*/
RotationVector &operator=(RotationVector &&other) noexcept;
public:
/**
* @brief Equality operator.
*
* @param other RotationVector to compare with.
* @return True if equal, false otherwise.
*/
bool operator==(const RotationVector &other) const;
/**
* @brief Approximate equality check.
*
* @param other RotationVector to compare with.
* @param prec Precision threshold.
* @return True if approximately equal, false otherwise.
*/
bool isApprox(const RotationVector &other, double prec = MATH_EPSILON);
/**
* @brief Get the type string of this class.
* @return "RotationVector"
*/
std::string_view typeString() const;
/**
* @brief Return rotation angle.
*
* @return The rotation angle.
*
*/
double angle() const;
/**
* @brief Return the unit axis of rotation.
*
* @return The unit axis of rotation.
*/
Vec3 unitAxis() const;
/**
* @brief Return the RotationVector as a Vec3.
*
* @return This RotationVector as a Vec3.
*/
const Vec3 &toVec3() const;
/**
* @brief Mark this RotationVector as not ready.
*/
void makeNotReady();
/**
* @brief Check whether this RotationVector is initialized.
* @return True if initialized, false otherwise.
*/
bool isReady() const;
public:
/**
* @brief Compute the angular velocity from coeff rates
*
* @param rates The 3-vector with coefficient rates.
* @param oframe If true, the angular velocity is in the 'from' frame, else in the 'to'
* frame.
*
* @return The angular velocity that corresponds to the rates.
*/
Vec3 ratesToOmega(const Vec3 &rates, bool oframe) const;
/**
* @brief Compute the coeff rates from the angular velocity
*
* @param omega The 3-vector angular velocity.
* @param oframe If true, the angular velocity is in the 'from' frame, else in the 'to'
* frame.
*
* @return The coefficient rates from the omega angular velocity
*
*/
Vec3 omegaToRates(const Vec3 &omega, bool oframe) const;
/**
* @brief The 3x3 matrix that maps the coefficient rates to the angular velocity
*
* @param oframe If true, the angular velocity is in the 'from' frame, else the 'to' frame.
* @return The 3x3 matrix map
*/
Mat33 ratesToOmegaMap(bool oframe) const;
/**
* @brief The 3x3 matrix that maps the angular velocity to the coefficient rates
*
* @param oframe If true, the angular velocity is in the 'from' frame, else the 'to' frame
* @return The 3x3 matrix map
*/
Mat33 omegaToRatesMap(bool oframe) const;
/**
* @brief The 4x3 matrix that maps the rotation vector rates to quaternion rates.
*
* @return The 4x3 matrix map.
*/
Mat ratesToQuatRatesMap() const;
/**
* @brief Get a string representation of the RotationVector.
* @param prefix String prefix for each line.
* @param precision Number of digits to use for floating point values.
* @param format_type The format type to use.
* @return String with information about this RotationVector.
*/
std::string dumpString(std::string_view prefix = "",
unsigned int precision = 10,
DumpFormatType format_type = DumpFormatType::DEFAULT_FLOAT) const;
private:
Vec3 _coeffs; /// the actual coefficients
};
} // namespace Karana::Math