Merged in issue_101_quaternion (pull request gazebosim#327)

5. Updating documentation, scripts, and examples for the Quaternion class

Approved-by: Steve Peters <[email protected]>

Changelog.md

@@ -10,6 +10,10 @@
 1. Added Equal functions with a tolerance parameter to Pose3 and Quaternion.
     * [Pull request 319](https://bitbucket.org/ignitionrobotics/ign-math/pull-requests/319)
 
+1. Updates per issue #101.
+    * Quaternion: [Pull request 327](https://bitbucket.org/ignitionrobotics/ign-math/pull-requests/327)
+    * Matrix3: [Pull request 328](https://bitbucket.org/ignitionrobotics/ign-math/pull-requests/328)
+
 1. Removed deprecations.
     * [Pull request 320](https://bitbucket.org/ignitionrobotics/ign-math/pull-requests/320)
 

Migration.md

@@ -7,12 +7,52 @@ release will remove the deprecated code.
 
 ## Ignition Math 6.X to 7.X
 
+### Breaking Changes
+
+  1. Removed the Quaternion integer template `Quaternioni`.
+
+
 ### Deprecations
 
 1. **Angle.hh**
     + All mutator functions that lacked a `Set` prefix have been deprecated
     and replaced by version with a `Set` prefix.
 
+1. **Matrix3.hh**
+    + ***Deprecation:*** public: void Axes(const Vector3<T> &, const Vector3<T> &, const Vector3<T> &)
+    + ***Replacement:*** public: void SetAxes(const Vector3<T> &, const Vector3<T> &, const Vector3<T> &)
+
+    + ***Deprecation:*** public: void Axis(const Vector3<T> &, T)
+    + ***Replacement:*** public: void SetFromAxisAngle(const Vector3<T> &, T)
+    + ***Deprecation:*** public: void From2Axes(const Vector3<T> &, const Vector3<T> &)
+    + ***Replacement:*** public: void SetFrom2Axes(const Vector3<T> &, const Vector3<T> &)
+    + ***Deprecation:*** public: void Col(unsigned int, const Vector3<T> &)
+    + ***Replacement:*** public: void SetCol(unsigned int, const Vector3<T> &)
+
+1. **Quaternion.hh**
+    + ***Deprecation:*** public: void Axis(T, T, T, T)
+    + ***Replacement:*** public: void SetFromAxisAngle(T, T, T, T)
+    + ***Deprecation:*** public: void Axis(const Vector3<T>&, T)
+    + ***Replacement:*** public: void SetFromAxisAngle(const Vector3<T>&, T)
+    + ***Deprecation:*** public: void Euler(const Vector3<T> &)
+    + ***Replacement:*** public: void SetFromEuler(const Vector3<T> &)
+    + ***Deprecation:*** public: void Euler(T, T, T)
+    + ***Replacement:*** public: void SetFromEuler(T, T, T)
+    + ***Deprecation:*** public: void ToAxis(Vector3<T> &, T &) const
+    + ***Replacement:*** public: void void AxisAngle(Vector3<T> &, T &) const
+    + ***Deprecation:*** public: void Matrix(const Matrix3<T> &)
+    + ***Replacement:*** public: void SetFromMatrix(const Matrix3<T> &)
+    + ***Deprecation:*** public: void From2Axes(const Vector3<T> &, const Vector3<T> &)
+    + ***Replacement:*** public: void SetFrom2Axes(const Vector3<T> &, const Vector3<T> &)
+    + ***Deprecation:*** public: void X(T)
+    + ***Replacement:*** public: void SetX(T)
+    + ***Deprecation:*** public: void Y(T)
+    + ***Replacement:*** public: void SetY(T)
+    + ***Deprecation:*** public: void Z(T)
+    + ***Replacement:*** public: void SetZ(T)
+    + ***Deprecation:*** public: void W(T)
+    + ***Replacement:*** public: void SetW(T)
+
 ## Ignition Math 4.X to 5.X
 
 ### Additions

examples/CMakeLists.txt

@@ -10,17 +10,23 @@ target_link_libraries(angle_example ignition-math${IGN_MATH_VER}::ignition-math$
 add_executable(gauss_markov_process gauss_markov_process_example.cc)
 target_link_libraries(gauss_markov_process ignition-math${IGN_MATH_VER}::ignition-math${IGN_MATH_VER})
 
-add_executable(vector2_example vector2_example.cc)
-target_link_libraries(vector2_example ignition-math${IGN_MATH_VER}::ignition-math${IGN_MATH_VER})
+add_executable(graph_example graph_example.cc)
+target_link_libraries(graph_example ignition-math${IGN_MATH_VER}::ignition-math${IGN_MATH_VER})
 
-add_executable(triangle_example triangle_example.cc)
-target_link_libraries(triangle_example ignition-math${IGN_MATH_VER}::ignition-math${IGN_MATH_VER})
+add_executable(matrix3_example matrix3_example.cc)
+target_link_libraries(matrix3_example ignition-math${IGN_MATH_VER}::ignition-math${IGN_MATH_VER})
 
-add_executable(quaternion_to_euler quaternion_to_euler.cc)
-target_link_libraries(quaternion_to_euler ignition-math${IGN_MATH_VER}::ignition-math${IGN_MATH_VER})
+add_executable(quaternion_example quaternion_example.cc)
+target_link_libraries(quaternion_example ignition-math${IGN_MATH_VER}::ignition-math${IGN_MATH_VER})
 
 add_executable(quaternion_from_euler quaternion_from_euler.cc)
 target_link_libraries(quaternion_from_euler ignition-math${IGN_MATH_VER}::ignition-math${IGN_MATH_VER})
 
-add_executable(graph_example graph_example.cc)
-target_link_libraries(graph_example ignition-math${IGN_MATH_VER}::ignition-math${IGN_MATH_VER})
+add_executable(quaternion_to_euler quaternion_to_euler.cc)
+target_link_libraries(quaternion_to_euler ignition-math${IGN_MATH_VER}::ignition-math${IGN_MATH_VER})
+
+add_executable(triangle_example triangle_example.cc)
+target_link_libraries(triangle_example ignition-math${IGN_MATH_VER}::ignition-math${IGN_MATH_VER})
+
+add_executable(vector2_example vector2_example.cc)
+target_link_libraries(vector2_example ignition-math${IGN_MATH_VER}::ignition-math${IGN_MATH_VER})

examples/matrix3_example.cc

@@ -0,0 +1,41 @@
+/*
+ * Copyright (C) 2019 Open Source Robotics Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+*/
+//! [complete]
+#include <iostream>
+#include <ignition/math/Matrix3.hh>
+
+int main(int argc, char **argv)
+{
+  // Construct a default matrix3.
+  ignition::math::Matrix3d m;
+  std::cout << "The default constructed matrix m has the following values.\n\t"
+    << m << std::endl;
+
+  // Set the first column of the matrix.
+  m.SetCol(0, ignition::math::Vector3d(3, 4, 5));
+  std::cout << "Setting the first column of the matrix m to 3, 4, 5.\n\t"
+    << m << std::endl;
+
+  // Transpose the matrix.
+  ignition::math::Matrix3d t = m.Transposed();
+  std::cout << "The transposed matrix t has the values.\n\t"
+    << t << std::endl;
+
+  // Multiply the two matrices.
+  std::cout << "m * t = " << m * t << std::endl;
+}
+//! [complete]

examples/matrix3_example.rb

@@ -0,0 +1,55 @@
+# Copyright (C) 2019 Open Source Robotics Foundation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# This example will only work if the Ruby interface library was compiled and
+# installed.
+#
+# Modify the RUBYLIB environment variable to include the ignition math
+# library install path. For example, if you install to /user:
+#
+# $ export RUBYLIB=/usr/lib/ruby:$RUBYLIB
+#
+require 'ignition/math'
+
+# Construct a default matrix3.
+m = Ignition::Math::Matrix3d.new
+printf("The default constructed matrix m has the following values.\n\t" +
+       "%2.1f %2.1f %2.1f %2.1f %2.1f %2.1f %2.1f %2.1f %2.1f\n",
+       m.(0, 0), m.(0, 1), m.(0, 2),
+       m.(1, 0), m.(1, 1), m.(1, 2),
+       m.(2, 0), m.(2, 1), m.(2, 2))
+
+# Set the first column of the matrix.
+m.SetCol(0, Ignition::Math::Vector3d.new(3, 4, 5))
+printf("Setting the first column of the matrix m to 3, 4, 5.\n\t" +
+       "%2.1f %2.1f %2.1f %2.1f %2.1f %2.1f %2.1f %2.1f %2.1f\n",
+       m.(0, 0), m.(0, 1), m.(0, 2),
+       m.(1, 0), m.(1, 1), m.(1, 2),
+       m.(2, 0), m.(2, 1), m.(2, 2))
+
+# Transpose the matrix.
+t = m.Transposed()
+printf("The transposed matrix t has the values.\n\t"+
+       "%2.1f %2.1f %2.1f %2.1f %2.1f %2.1f %2.1f %2.1f %2.1f\n",
+       t.(0, 0), t.(0, 1), t.(0, 2),
+       t.(1, 0), t.(1, 1), t.(1, 2),
+       t.(2, 0), t.(2, 1), t.(2, 2))
+
+# Multiply the two matrices.
+m = m * t
+printf("m * t = " +
+       "%2.1f %2.1f %2.1f %2.1f %2.1f %2.1f %2.1f %2.1f %2.1f\n",
+       m.(0, 0), m.(0, 1), m.(0, 2),
+       m.(1, 0), m.(1, 1), m.(1, 2),
+       m.(2, 0), m.(2, 1), m.(2, 2))

examples/quaternion_example.cc

@@ -0,0 +1,44 @@
+/*
+ * Copyright (C) 2019 Open Source Robotics Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+*/
+//! [complete]
+#include <stdio.h>
+#include <ignition/math/Quaternion.hh>
+
+int main(int argc, char **argv)
+{
+  // Construct a default quaternion.
+  ignition::math::Quaterniond q;
+  printf("A default quaternion has the following values\n" \
+       "\tW=%f X=%f Y=%f Z=%f\n", q.W(), q.X(), q.Y(), q.Z());
+
+  // Set the quaternion to [1, 0, 0, 0], the identity.
+  q = ignition::math::Quaterniond::Identity;
+  printf("The identity quaternion has the following values\n" \
+       "\tW=%f X=%f Y=%f Z=%f\n", q.W(), q.X(), q.Y(), q.Z());
+
+  // Create a new quaternion using Euler angles.
+  ignition::math::Quaterniond q2(0, 0, 3.14);
+  printf("A quaternion initialized from roll=0, pitch=0, and yaw=3.14 has"\
+         "the following values\n" \
+         "\tW=%f X=%f Y=%f Z=%f\n", q2.W(), q2.X(), q2.Y(), q2.Z());
+
+  // Get the Euler angles back from the quaternion.
+  ignition::math::Vector3d euler = q2.Euler();
+  printf("Getting back the euler angles from the quaternion\n"\
+         "\troll=%f pitch=%f yaw=%f\n", euler.X(), euler.Y(), euler.Z());
+}
+//! [complete]

examples/quaternion_example.rb

@@ -0,0 +1,45 @@
+# Copyright (C) 2019 Open Source Robotics Foundation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# This example will only work if the Ruby interface library was compiled and
+# installed.
+#
+# Modify the RUBYLIB environment variable to include the ignition math
+# library install path. For example, if you install to /user:
+#
+# $ export RUBYLIB=/usr/lib/ruby:$RUBYLIB
+#
+require 'ignition/math'
+
+# Construct a default quaternion.
+q = Ignition::Math::Quaterniond.new
+printf("A default quaternion has the following values\n"+
+       "\tW=%f X=%f Y=%f Z=%f\n", q.W(), q.X(), q.Y(), q.Z())
+
+# Set the quaternion to [1, 0, 0, 0], the identity.
+q = Ignition::Math::Quaterniond.Identity
+printf("The identity quaternion has the following values\n" +
+       "\tW=%f X=%f Y=%f Z=%f\n", q.W(), q.X(), q.Y(), q.Z())
+
+# Create a new quaternion using Euler angles.
+q2 = Ignition::Math::Quaterniond.new(0, 0, 3.14)
+printf("A quaternion initialized from roll=0, pitch=0, and yaw=3.14 " +
+       "has the following values\n" +
+       "\tW=%f X=%f Y=%f Z=%f\n", q2.W(), q2.X(), q2.Y(), q2.Z())
+
+# Get the Euler angles back from the quaternion.
+euler = q2.Euler()
+printf("Getting back the euler angles from the quaternion\n" +
+       "\troll=%f pitch=%f yaw=%f\n", euler.X(), euler.Y(), euler.Z())
+