Ocean
Loading...
Searching...
No Matches
SphericalExponentialMap.h
Go to the documentation of this file.
1/*
2 * Copyright (c) Meta Platforms, Inc. and affiliates.
3 *
4 * This source code is licensed under the MIT license found in the
5 * LICENSE file in the root directory of this source tree.
6 */
7
8#ifndef META_OCEAN_MATH_SPHERICAL_EXPONENTIAL_MAP_H
9#define META_OCEAN_MATH_SPHERICAL_EXPONENTIAL_MAP_H
10
11#include "ocean/math/Math.h"
13#include "ocean/math/Rotation.h"
14
15namespace Ocean
16{
17
18/**
19 * This class implements an exponential map representing a 2-DOF rotation.
20 * Thus, this class allows to define a rotation between two 3D coordinates located on a sphere (with 2 degrees of freedom).<br>
21 * The rotation is defined by two scalar parameters defining a 3D vector located in the xz-plane (having zero as value for the y-axis).<br>
22 * The 3D vector defines the rotation axis and the length of the vector defined the rotation angle.<br>
23 * This class can be used to store the 3D position of a point lying on a sphere by two scalar parameters.<br>
24 * Further, this class can be used to rotate a 3D point lying on a sphere to any other position on that sphere.<br>
25 * Compared to an Euler rotation (3-DOF), the SphericalExponentialMap (2-DOF) holds/provides/stores a yaw-angle and a pitch-angle, but not roll-angle.<br>
26 * The SphericalExponentialMap class can be seen as a specialization of the ExponentialMap.<br>
27 * @see ExponentialMap, Rotation, Quaternion, Euler.
28 * @ingroup math
29 */
30class OCEAN_MATH_EXPORT SphericalExponentialMap
31{
32 public:
33
34 /**
35 * Creates a new exponential map object with default (no) rotation.
36 */
38
39 /**
40 * Creates an exponential map object by a given 3D rotation axis (lying in the xz-plane) with axis length defining the rotation angle in radian.
41 * @param wx X component of the rotation axis
42 * @param wz Z component of the rotation axis
43 */
44 inline SphericalExponentialMap(const Scalar wx, const Scalar wz);
45
46 /**
47 * Creates a new exponential map object that rotates a given offset vector to a given reference vector both lying on the same unit sphere in 3D space.
48 * The following equation holds: offset = SphericalExponentialMap(reference, offset).rotation() * reference.<br>
49 * @param reference The reference vector, with unit length
50 * @param offset The offset vector, with unit length
51 */
52 SphericalExponentialMap(const Vector3& reference, const Vector3& offset);
53
54 /**
55 * Returns the (non-normalized) rotation axis of this object.
56 * Beware: This axis has a length equal to the rotation angle.
57 * @return Non normalized rotation axis (in 3D space lying in the xz-plane)
58 */
59 inline const Vector3 axis() const;
60
61 /**
62 * Returns the angle of this rotation object.
63 * @return Rotation angle, in radian
64 */
65 inline Scalar angle() const;
66
67 /**
68 * Returns this rotation representation as quaternion object.
69 * @return Equivalent quaternion rotation
70 */
71 inline Quaternion quaternion() const;
72
73 /**
74 * Returns this rotation representation as angle-axis object.
75 * @return Equivalent rotation
76 */
77 inline Rotation rotation() const;
78
79 /**
80 * Returns a pointer to the two rotation values of this object (for the x-axis and z-axis).
81 * @return Pointer to the rotation values, with order [wx, wz]
82 */
83 inline const Scalar* data() const;
84
85 /**
86 * Returns a pointer to the two rotation values of this object (for the x-axis and z-axis).
87 * @return Pointer to the rotation values, with order [wx, wz]
88 */
89 inline Scalar* data();
90
91 /**
92 * Element access operator.
93 * @param index The index of the element to access, with range [0, 1]
94 * @return The requested element
95 */
96 inline const Scalar& operator[](const unsigned int index) const;
97
98 /**
99 * Element access operator.
100 * @param index The index of the element to access, with range [0, 1]
101 * @return The requested element
102 */
103 inline Scalar& operator[](const unsigned int index);
104
105 protected:
106
107 /// The 2-DOF orientation values with order [wx, wz]
109};
110
112 mapRotationAxis(0, 0)
113{
114 // nothing to do here
115}
116
118 mapRotationAxis(wx, wz)
119{
120 // nothing to do here
121}
122
124{
125 return Vector3(mapRotationAxis[0], 0, mapRotationAxis[1]);
126}
127
129{
130 return mapRotationAxis.length();
131}
132
137
139{
140 const Scalar length = mapRotationAxis.length();
141
142 if (Numeric::isEqualEps(length))
143 {
144 return Rotation();
145 }
146
147 return Rotation(Vector3(mapRotationAxis[0], 0, mapRotationAxis[1]) / length, length);
148}
149
151{
152 return mapRotationAxis.data();
153}
154
159
160inline const Scalar& SphericalExponentialMap::operator[](const unsigned int index) const
161{
162 ocean_assert(index <= 1u);
163
164 return mapRotationAxis[index];
165}
166
167inline Scalar& SphericalExponentialMap::operator[](const unsigned int index)
168{
169 ocean_assert(index <= 1u);
170
171 return mapRotationAxis[index];
172}
173
174}
175
176#endif // META_OCEAN_MATH_SPHERICAL_EXPONENTIAL_MAP_H
static constexpr bool isEqualEps(const T value)
Returns whether a value is smaller than or equal to a small epsilon.
Definition Numeric.h:2087
This class implements a axis-angle rotation using floating point values.
Definition Rotation.h:79
This class implements an exponential map representing a 2-DOF rotation.
Definition SphericalExponentialMap.h:31
SphericalExponentialMap(const Vector3 &reference, const Vector3 &offset)
Creates a new exponential map object that rotates a given offset vector to a given reference vector b...
const Scalar & operator[](const unsigned int index) const
Element access operator.
Definition SphericalExponentialMap.h:160
Scalar angle() const
Returns the angle of this rotation object.
Definition SphericalExponentialMap.h:128
Rotation rotation() const
Returns this rotation representation as angle-axis object.
Definition SphericalExponentialMap.h:138
const Vector3 axis() const
Returns the (non-normalized) rotation axis of this object.
Definition SphericalExponentialMap.h:123
SphericalExponentialMap()
Creates a new exponential map object with default (no) rotation.
Definition SphericalExponentialMap.h:111
Vector2 mapRotationAxis
The 2-DOF orientation values with order [wx, wz].
Definition SphericalExponentialMap.h:108
Quaternion quaternion() const
Returns this rotation representation as quaternion object.
Definition SphericalExponentialMap.h:133
const Scalar * data() const
Returns a pointer to the two rotation values of this object (for the x-axis and z-axis).
Definition SphericalExponentialMap.h:150
const T * data() const noexcept
Returns an pointer to the vector elements.
Definition Vector2.h:734
T length() const
Returns the length of the vector.
Definition Vector2.h:627
QuaternionT< Scalar > Quaternion
Definition of the Quaternion object, depending on the OCEAN_MATH_USE_SINGLE_PRECISION either with sin...
Definition Quaternion.h:40
RotationT< Scalar > Rotation
Definition of the Rotation object, depending on the OCEAN_MATH_USE_SINGLE_PRECISION flag either with ...
Definition Rotation.h:38
float Scalar
Definition of a scalar type.
Definition Math.h:129
VectorT3< Scalar > Vector3
Definition of a 3D vector.
Definition Vector3.h:29
The namespace covering the entire Ocean framework.
Definition Accessor.h:15