Angle.h

Go to the documentation of this file.

/*--------------------------------------------------------------------------------------------
Copyright (c) 2019, NDEVR LLC
tyler.parke@ndevr.org
  __    __   ____     _____ __     __  _______
 |  \  |  | |  __ \  |  ___|\ \   / / |   __  \
 |   \ |  | | |  \ \ | |___  \ \ / /  |  |__)  |
 |  . \|  | | |__/ / | |___   \ V /   |   _   /
 |  |\    |_|_____/__|_____|___\_/____|  | \  \
 |__| \__________________________________|  \__\
 
Subject to the terms of the Enterprise+ Agreement, NDEVR hereby grants
Licensee a limited, non-exclusive, non-transferable, royalty-free license
(without the right to sublicense) to use the API solely for the purpose of
Licensee's internal development efforts to develop applications for which
the API was provided.
 
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
 
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
 
Library: Base
File: Angle
Included in API: True
Author(s): Tyler Parke
 *-----------------------------------------------------------------------------------------**/
#pragma once
#include <NDEVR/BaseValues.h>
#include <NDEVR/ObjectInfo.h>
#include <cmath>
 
namespace NDEVR
{
    /**--------------------------------------------------------------------------------------------------
    Enum: EulerPosition
 
    \brief Values that represent euler angles. 
    These are typically used in Vector<3, Angle> to classify an orientation of an object.
     *-----------------------------------------------------------------------------------------------**/
    enum EulerPosition : uint01
    {
          ROLL
        , PITCH
        , YAW
    };
 
    /**--------------------------------------------------------------------------------------------------
    \brief The possible units that can be used by the angle class. 
    
    These are returned and used for real world angle representation. 
    
    INTERNAL_ANGLE is the angle internally used by the angle class.
     *-----------------------------------------------------------------------------------------------**/
    enum AngleType
    {
          RADIANS
        , DEGREES
        , INTERNAL_ANGLE
        , PERCENT
    };
 
    /**--------------------------------------------------------------------------------------------------
    \brief Values that represent angle format modes.
    Used in classes for printing angle in a given format
     *-----------------------------------------------------------------------------------------------**/
    enum AngleFormatMode
    {
          MODE_DECIMAL_DEGREES
        , MODE_DEGREES_MINUTES_SECONDS
        , MODE_GRADIANS
        , MODE_RADIANS
        , MODE_SURVEYOR_UNITS
    };
    /**--------------------------------------------------------------------------------------------------
    \brief Returns the value of PI to a given precision.
    \return The value of PI (~3.1415...).
    *-----------------------------------------------------------------------------------------------**/
    template<class t_float_type>
    static constexpr t_float_type PI()
    {
        return cast<t_float_type>(3.14159265358979323846264338327950288419716939937510);
    }
    /**--------------------------------------------------------------------------------------------------
    \brief The primary angle storage class for this API. Stores an angle in an optimized format. 
 
    Since all angles are from 0-360 degrees it is possible to make certain optimizations that 
        make use of defined overflow that traditional floating point angles would not be able to achieve. 
        In addition space can be saved and expensive sin, cos, tan functions can be precomputed.
     *-----------------------------------------------------------------------------------------------**/
    template<class t_type = fltp08>
    class Angle
    {
    public:
 
        /**--------------------------------------------------------------------------------------------------
        \brief Default constructor, creates an angle with 0 degrees.
         *-----------------------------------------------------------------------------------------------**/
        constexpr Angle()
            : m_index_angle(0)
        {}
 
        /**--------------------------------------------------------------------------------------------------
        \brief Default copy constructor
         *-----------------------------------------------------------------------------------------------**/
        constexpr Angle(const Angle& angle)
            : m_index_angle(angle.m_index_angle)
        {}
 
        /**--------------------------------------------------------------------------------------------------
        \brief Explicit conversion of an angle from one container type to another.
         *-----------------------------------------------------------------------------------------------**/
        template<class t_other_type>
        explicit constexpr Angle(const Angle<t_other_type>& angle)
            : m_index_angle(cast<t_type>(angle.template internal<false>()))
        {}
 
        /**--------------------------------------------------------------------------------------------------
        \brief Angle Constructor.
        \param[in] type The type of the angle given (Example: radians, degrees, percent)
        \param[in] value The value of the angle in the units specified by type.
         *-----------------------------------------------------------------------------------------------**/
        constexpr explicit Angle(AngleType type, fltp04 value)
            : m_index_angle(0)
        {
            switch (type)
            {
            case INTERNAL_ANGLE: break;
            case RADIANS: value = (value / PI<fltp04>()) * INDEX_PI; break;
            case DEGREES: value = (value / 180.0f) * INDEX_PI; break;
            case PERCENT: value = value * 2.0f * INDEX_PI; break;
            }
            m_index_angle = cast<t_type>(value);
        }
 
        /**--------------------------------------------------------------------------------------------------
        \brief Angle Constructor.
        \param[in] type The type of the angle given (Example: radians, degrees, percent)
        \param[in] value The value of the angle in the units specified by type.
         *-----------------------------------------------------------------------------------------------**/
        constexpr explicit Angle(AngleType type, fltp08 value)
            : m_index_angle(0)
        {
            switch (type)
            {
            case INTERNAL_ANGLE: break;
            case RADIANS: value = (value / PI<fltp08>()) * INDEX_PI; break;
            case DEGREES: value = (value / 180.0) * INDEX_PI; break;
            case PERCENT: value = value * 2.0 * INDEX_PI; break;
            }
            m_index_angle = cast<t_type>(value);
        }
 
        /**--------------------------------------------------------------------------------------------------
        \brief Constructor.
        \param[in] value - the optimized input where INDEX_PI is 180 degrees
         *-----------------------------------------------------------------------------------------------**/
        constexpr explicit Angle(t_type value)
            : m_index_angle(value)
        {}
 
        /**--------------------------------------------------------------------------------------------------
        \brief Returns a form of this angle as a given type (Radian, Degree, Percent, etc)
        \param[in] t_type The type of the angle to return (Example: radians, degrees, percent)
        \param[in] t_is_signed Whether the given type should be signed or not (-180 - 180 vs 0 to 360)
        \return A fltp08 representing this angle as the given type.
         *-----------------------------------------------------------------------------------------------**/
        template<AngleType t_angle_type>
        [[nodiscard]] constexpr fltp08 as() const
        {
            switch (t_angle_type)
            {
            case INTERNAL_ANGLE:
                if (IsInvalid(m_index_angle))
                    return Constant<fltp08>::Invalid;
                else
                    return cast<fltp08>(internal<false>());
            case DEGREES:
                return as<INTERNAL_ANGLE>() * INV_INDEX_PI * 180.0;
            case RADIANS:
                return as<INTERNAL_ANGLE>() * INV_INDEX_PI * PI<fltp08>();
            case PERCENT:
                return as<INTERNAL_ANGLE>() * INV_INDEX_PI * 0.5;
            }
            return Constant<fltp08>::Invalid;
        }
 
        /**--------------------------------------------------------------------------------------------------
        \brief Returns a form of this angle as a given type (Radian, Degree, Percent, etc)
        \param[in] type -  The type of the angle to return (Example: radians, degrees, percent).
        \return A fltp04 representing this angle as the given type.
         *-----------------------------------------------------------------------------------------------**/
        [[nodiscard]] constexpr fltp08 as(AngleType type) const
        {
            switch (type)
            {
            case DEGREES: return as<DEGREES>();
            case RADIANS: return as<RADIANS>();
            case PERCENT: return as<PERCENT>();
            case INTERNAL_ANGLE: return as<INTERNAL_ANGLE>();
            }
            return Constant<fltp08>::Invalid;
        }
    public:
        /**--------------------------------------------------------------------------------------------------
        \brief Gets the internal index angle which is the default storage unit for the angle data.
        \return The internal index angle, or the angle represented by 0 - Constant<t_type>::Max representing
            0 to 2 PI radians
         *-----------------------------------------------------------------------------------------------**/
        template<bool t_normalized>
        [[nodiscard]] constexpr t_type internal() const
        {
            if constexpr(t_normalized)
            {
                return Angle<t_type>::template NormalizeInternal<t_type>(m_index_angle);
            }
            else
            {
                return m_index_angle;
            }
        }
        /**--------------------------------------------------------------------------------------------------
        \brief Explicit conversion of an angle from one container type to another.
         *-----------------------------------------------------------------------------------------------**/
        template<class t_new_type>
        constexpr Angle<t_new_type> toTypeAngle() const
        {
            Angle<t_new_type> angle(cast<t_new_type>(m_index_angle));
            return angle;
        }
        /**--------------------------------------------------------------------------------------------------
        \brief returns the normalized angle which lies from 0 to 360 degrees.
         *-----------------------------------------------------------------------------------------------**/
        [[nodiscard]] constexpr Angle normalized() const
        {
            return Angle(internal<true>());
        }
        /**--------------------------------------------------------------------------------------------------
        \brief returns the normalized angle which lies from -180 to 180 degrees.
         *-----------------------------------------------------------------------------------------------**/
        [[nodiscard]] constexpr Angle normalizedOffset() const
        {
            Angle value = normalized();
            if (value > Angle(DEGREES, 180.0))
                value -= Angle(DEGREES, 360.0);
            return value;
        }
        /**--------------------------------------------------------------------------------------------------
        \param[in] angle -  The value to assign.
        \return A shallow copy of this object.
         *-----------------------------------------------------------------------------------------------**/
        constexpr Angle& operator=(const Angle& angle)
        {
            m_index_angle = angle.m_index_angle;
            return (*this);
        }
 
        /**--------------------------------------------------------------------------------------------------
        \brief Equality operator.
        \param[in] angle -  The value to check comparison.
        \return true if the left and right are considered equivalent.
         *-----------------------------------------------------------------------------------------------**/
        constexpr bool operator==(const Angle& angle) const
        {
            return internal<false>() == angle.internal<false>();
        }
 
        /**--------------------------------------------------------------------------------------------------
        \brief Inequality operator.
        \param[in] angle The value to check inequality against.
        \return true if the left and right are not considered equivalent.
         *-----------------------------------------------------------------------------------------------**/
        constexpr bool operator!=(const Angle& angle) const
        {
            return internal<false>() != angle.internal<false>();
        }
 
        /**--------------------------------------------------------------------------------------------------
        \brief negates the angle
        \return The result of the operation.
         *-----------------------------------------------------------------------------------------------**/
        Angle operator-() const
        {
            return Angle(-m_index_angle);
        }
    public:
 
        /**--------------------------------------------------------------------------------------------------
        \brief Computes the principal value of the arc cosine of the given value
        \param[in] value -  The value to perform arc cos.
        \return the arc cosine of the given value as an Angle.
         *-----------------------------------------------------------------------------------------------**/
        template<class t_value_type>
        static Angle acos(t_value_type value)
        {
            return Angle(RADIANS, ::acos(value));
        }
 
        /**--------------------------------------------------------------------------------------------------
        \brief Computes the principal value of the arc sine of the given value
        \param[in] value -  The value to perform arc sine.
        \return the arc sine of the given value as an Angle.
         *-----------------------------------------------------------------------------------------------**/
        template<class t_value_type>
        static Angle asin(t_value_type value)
        {
            return Angle(RADIANS, ::asin(value));
        }
        
        /**--------------------------------------------------------------------------------------------------
        \brief Computes the principal value of the arc tangent of the given value
        \param[in] value -  The value to perform arc tangent.
        \return the arc tangent of the given value as an Angle.
         *-----------------------------------------------------------------------------------------------**/
        template<class t_value_type>
        static Angle atan(t_value_type value)
        {
            return Angle(RADIANS, ::atan(value));
        }
 
        /**--------------------------------------------------------------------------------------------------
        \brief measures the counterclockwise angle between the positive x-axis and the point (x, y)
        \param[in] x - the numerator or x value of atan
        \param[in] y - the denomenator or y value of atan
        \return the arc tangent of the given value as an Angle.
         *-----------------------------------------------------------------------------------------------**/
        template<class t_value_type>
        static Angle atan2(t_value_type x, t_value_type y)
        {
            return Angle(RADIANS, ::atan2(x, y));
        }
    public:
        static constexpr sint04 INDEX_PI = 32768;//optimized angle that allows integers to store angles to some degree of accuracy
        static constexpr fltp08 INV_INDEX_PI = { 1.0 / Angle<t_type>::INDEX_PI };
    private:
        template<class t_normal_type>
        static constexpr typename std::enable_if<!ObjectInfo<t_normal_type>::Float, t_normal_type>::type NormalizeInternal(t_normal_type value)
        {
            const t_normal_type angle = (value >= 0 ? value : -value) % (2 * INDEX_PI);
            if (value >= 0)
                return angle;
            else
                return (2 * INDEX_PI) - angle;
        }
 
        template<class t_normal_type>
        static constexpr typename std::enable_if<ObjectInfo<t_normal_type>::Float, t_normal_type>::type NormalizeInternal(t_normal_type value)
        {
            const t_normal_type angle = fmod(std::abs(value), (2 * INDEX_PI));
            if (value >= 0)
                return angle;
            else
                return 2 * cast<t_normal_type>(INDEX_PI) - angle;
        }
 
    protected:
        /** The index angle. */
        t_type m_index_angle;
    };
    template<> constexpr const Angle<sint04> Constant<Angle<sint04>>::Invalid = Angle<sint04>(Constant<sint04>::Invalid);
    template<> constexpr const Angle<sint04> Constant<Angle<sint04>>::Max = Angle<sint04>(Constant<sint04>::Max);
    template<> constexpr const Angle<sint04> Constant<Angle<sint04>>::Min = Angle<sint04>(Constant<sint04>::Min);
 
    template<> constexpr const Angle<fltp08> Constant<Angle<fltp08>>::Invalid = Angle<fltp08>(Constant<fltp08>::Invalid);
    template<> constexpr const Angle<fltp08> Constant<Angle<fltp08>>::Max = Angle<fltp08>(Constant<fltp08>::Max);
    template<> constexpr const Angle<fltp08> Constant<Angle<fltp08>>::Min = Angle<fltp08>(Constant<fltp08>::Min);
 
    template<class t_type>
    static constexpr bool IsInvalid(const Angle<t_type>& value)
    {
        return IsInvalid(value.template internal<false>());
    }
 
    template<class t_to, class t_from>
    constexpr t_to cast(const Angle<t_from>& value)
    {
        return t_to(INTERNAL_ANGLE, cast<fltp08>(value.template internal<false>()));
    }
    /**--------------------------------------------------------------------------------------------------
    \brief Information about an Angle object backed by a signed 4 byte integer.
     *-----------------------------------------------------------------------------------------------**/
    template<>
    struct ObjectInfo<Angle<sint04>, false, false>
    {
        static const uint01 Dimensions = 0;
        static const bool Vector = false;
        static const bool Primitive = true;
        static const bool Pointer = false;
        static const bool Unsigned = false;
        static const bool Float = true;
        static const bool Integer = false;
        static const bool Number = true;
        static const bool String = false;
        static const bool Color = false;
        static const bool Buffer = false;
        static const bool Boolean = false;
        static constexpr ObjectInfo<Angle<sint04>, false, false> VectorSub() { return ObjectInfo<Angle<sint04>, false, false>(); }
    };
    /**--------------------------------------------------------------------------------------------------
    \brief Information about an Angle object backed by a 8 byte floating point number.
     *-----------------------------------------------------------------------------------------------**/
    template<>
    struct ObjectInfo<Angle<fltp08>, false, false>
    {
        static const uint01 Dimensions = 0;
        static const bool Vector = false;
        static const bool Primitive = true;
        static const bool Pointer = false;
        static const bool Unsigned = false;
        static const bool Float = true;
        static const bool Integer = false;
        static const bool Number = true;
        static const bool String = false;
        static const bool Color = false;
        static const bool Buffer = false;
        static const bool Boolean = false;
        static constexpr ObjectInfo<Angle<fltp08>, false, false> VectorSub() { return ObjectInfo<Angle<fltp08>, false, false>(); }
    };
    /**--------------------------------------------------------------------------------------------------
    \brief Information about an Angle object backed by a 4 byte floating point number.
     *-----------------------------------------------------------------------------------------------**/
    template<>
    struct ObjectInfo<Angle<fltp04>, false, false>
    {
        static const uint01 Dimensions = 0;
        static const bool Vector = false;
        static const bool Primitive = true;
        static const bool Pointer = false;
        static const bool Unsigned = false;
        static const bool Float = true;
        static const bool Integer = false;
        static const bool Number = true;
        static const bool String = false;
        static const bool Color = false;
        static const bool Buffer = false;
        static const bool Boolean = false;
        static constexpr ObjectInfo<Angle<fltp04>, false, false> VectorSub() { return ObjectInfo<Angle<fltp04>, false, false>(); }
    };
};