[backport ign-math6] Added examples to tutorials.md.in

examples/angle_example.cc

@@ -20,21 +20,31 @@
 
 int main(int argc, char **argv)
 {
-  // Create an angle.
+
+//! [Create an angle]
   ignition::math::Angle a;
+//! [Create an angle]
 
   // A default constructed angle should be zero.
   std::cout << "The angle 'a' should be zero: " << a << std::endl;
+//! [constant pi]
+  a = ignition::math::Angle::HalfPi;
   a = ignition::math::Angle::Pi;
+//! [constant pi]
 
-  // Output the angle in radians and degrees.
+//! [Output the angle in radians and degrees.]
   std::cout << "Pi in radians: " << a << std::endl;
   std::cout << "Pi in degrees: " << a.Degree() << std::endl;
+//! [Output the angle in radians and degrees.]
 
-  // The Angle class overloads the +=, and many other, math operators.
+//! [The Angle class overloads the +=, and many other, math operators.]
   a += ignition::math::Angle::HalfPi;
+//! [The Angle class overloads the +=, and many other, math operators.]
   std::cout << "Pi + PI/2 in radians: " << a << std::endl;
+//! [normalized]
   std::cout << "Normalized to the range -Pi and Pi: "
     << a.Normalized() << std::endl;
+//! [normalized]
+
 }
 //! [complete]

examples/angle_example.rb

@@ -22,7 +22,9 @@
 #
 require 'ignition/math'
 
+#! [constant]
 printf("PI in degrees = %f\n", Ignition::Math::Angle.Pi.Degree)
+#! [constant]
 
 a1 = Ignition::Math::Angle.new(1.5707)
 a2 = Ignition::Math::Angle.new(0.7854)

examples/quaternion_from_euler.cc

@@ -69,18 +69,24 @@ int main(int argc, char **argv)
           IGN_RTOD(pitch),
           IGN_RTOD(yaw));
 
+//![constructor]
   ignition::math::Quaterniond q(roll, pitch, yaw);
   ignition::math::Matrix3d m(q);
+//![constructor]
 
   std::cout << "\nto Quaternion\n";
+//! [access quaterion]
   printf(" W % .6f\n X % .6f\n Y % .6f\n Z % .6f\n",
         q.W(), q.X(), q.Y(), q.Z());
+//! [access quaterion]
 
+//! [rotation matrix]
   std::cout << "\nto Rotation matrix\n";
   printf("   % .6f  % .6f  % .6f\n"
          "   % .6f  % .6f  % .6f\n"
          "   % .6f  % .6f  % .6f\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));
+//! [rotation matrix]
 }

examples/quaternion_to_euler.cc

@@ -75,7 +75,9 @@ int main(int argc, char **argv)
             << std::endl;
 
   ignition::math::Matrix3d m(q);
+//![constructor]
   ignition::math::Vector3d euler(q.Euler());
+//![constructor]
 
   std::cout << "\nConverting to Euler angles\n";
   printf(" roll  % .6f radians\n"

examples/triangle_example.cc

@@ -24,43 +24,59 @@ int main(int argc, char **argv)
   // 1: x = -1, y = 0
   // 2: x = 0, y = 1
   // 3: x = 1, y = 0
+//! [constructor]
   ignition::math::Triangled tri(
       ignition::math::Vector2d(-1, 0),
       ignition::math::Vector2d(0, 1),
       ignition::math::Vector2d(1, 0));
+//! [constructor]
 
   // The individual vertices are accessible through the [] operator
+
+//! [access1]
   std::cout << "Vertex 1: " << tri[0] << "\n"
             << "Vertex 2: " << tri[1] << "\n"
             << "Vertex 3: " << tri[2] << "\n";
+//! [access1]
 
   // Each side of the triangle is also accessible via the Side function
+//! [access2]
   std::cout << "Side 1: " << tri.Side(0) << "\n"
             << "Side 2: " << tri.Side(1) << "\n"
             << "Side 3: " << tri.Side(2) << "\n";
+//! [access2]
 
   // It's also possible to set each vertex individually.
+//! [vertex1]
   tri.Set(0, ignition::math::Vector2d(-10, 0));
   tri.Set(1, ignition::math::Vector2d(0, 20));
   tri.Set(2, ignition::math::Vector2d(10, 2));
+//! [vertex1]
 
   // Or set all the vertices at once.
+//! [vertex2]
   tri.Set(ignition::math::Vector2d(-1, 0),
           ignition::math::Vector2d(0, 1),
           ignition::math::Vector2d(1, 0));
+//! [vertex2]
 
   // You can get the perimeter length and area of the triangle
+//! [perimeter and area]
   std::cout << "Perimeter=" << tri.Perimeter()
             << " Area=" << tri.Area() << "\n";
+//! [perimeter and area]
 
   // The Contains functions check if a line or point is inside the triangle
+//! [contains]
   if (tri.Contains(ignition::math::Vector2d(0, 0.5)))
     std::cout << "Triangle contains the point 0, 0.5\n";
   else
     std::cout << "Triangle does not contain the point 0, 0.5\n";
+//! [contains]
 
   // The Intersect function check if a line segment intersects the triangle.
   // It also returns the points of intersection
+//! [intersect]
   ignition::math::Vector2d pt1, pt2;
   if (tri.Intersects(ignition::math::Line2d(-2, 0.5, 2, 0.5), pt1, pt2))
   {
@@ -74,6 +90,7 @@ int main(int argc, char **argv)
     std::cout << "A line from (-2, 0.5) to (2, 0.5) does not intersect "
               << "the triangle\n";
   }
+//! [intersect]
 
   // There are more functions in Triangle. Take a look at the API;
   // http://ignitionrobotics.org/libraries/ign_mat/api

examples/vector2_example.cc

@@ -22,44 +22,57 @@ int main(int argc, char **argv)
 {
   // Create a Vector2 called vec2 of doubles using the typedef Vector2d.
   // The initial x any y values are zero.\n\n";
-  ignition::math::Vector2d vec2;
-
   // The x and y component of vec2 can be set at anytime.
+//! [constructor]
+  ignition::math::Vector2d vec2;
   vec2.Set(2.0, 4.0);
+//! [constructor]
 
   // The Vector2 class is a template, so you can also create a Vector2 using
   // ignition::math::Vector2<double>
+  //! [constructor2]
   ignition::math::Vector2<double> vec2a;
 
   vec2a.Set(1.0, 2.0);
+  //! [constructor2]
 
   // It's also possible to set initial values. This time we are using
   // a Vector2 of floats
+  //! [constructor3]
   ignition::math::Vector2f vec2b(1.2f, 3.4f);
+  //! [constructor3]
 
   // We can output the contents of each vector using std::cout
+//! [stdout]
   std::cout << "Vec2: " << vec2 << "\n"
             << "Vec2a: " << vec2a << "\n"
             << "Vec2b: " << vec2b << "\n";
+//! [stdout]
 
   // You can also get access to each component in the vector using the
   // X(), Y() accessors or the [] operator.
+  //! [access]
   std::cout << "Vec2: x=" << vec2.X() << " y=" << vec2.Y() << "\n";
   std::cout << "Vec2a: x=" << vec2a[0] << " y=" << vec2a[1] << "\n";
   std::cout << "Vec2b: x=" << vec2b.X() << " y=" << vec2b[1] << "\n";
+  //! [access]
 
   // The [] operator is clamped to the range [0, 1]
   std::cout << vec2[3] << std::endl;
 
   // The Vector2 class overloads many common operators
+//! [operators]
   std::cout << vec2 * vec2a << "\n"
             << vec2 + vec2a << "\n"
             << vec2 - vec2a << "\n"
             << vec2 / vec2a << "\n";
+//! [operators]
 
   // There are also many useful function such as finding the distance
   // between two vectors
+//! [distance]
   std::cout << vec2.Distance(vec2a) << std::endl;
+//! [distance]
 
   // There are more functions in Vector2. Take a look at the API:
   // https://ignitionrobotics.org/libs/math

tutorials.md.in

@@ -9,6 +9,10 @@ Ignition @IGN_DESIGNATION_CAP@ library and how to use the library effectively.
 
 1. \subpage install "Installation"
 2. \subpage cppgetstarted "C++ Get Started"
+3. \subpage vector "Vector example"
+4. \subpage angle "Angle example"
+5. \subpage triangle "Triangle example"
+6. \subpage rotation "Rotation example"
 
 ## License
 

tutorials/angle.md

@@ -0,0 +1,109 @@
+\page angle Angle example
+
+This tutorial explains how to use the `Angle` class from Ignition Math library.
+
+## C++ example
+
+### Compile the code
+
+Go to `ign-math/examples` and use `cmake` to compile the code:
+
+```{.sh}
+git clone https://github.com/ignitionrobotics/ign-math/ -b ign-math6
+cd ign-math/examples
+mkdir build
+cd build
+cmake ..
+make
+```
+
+When the code is compiled, run:
+
+```{.sh}
+./angle_example
+```
+
+The ouput of the program:
+
+```{.sh}
+The angle 'a' should be zero: 0
+Pi in radians: 3.14159
+Pi in degrees: 180
+Pi + PI/2 in radians: 4.71239
+Normalized to the range -Pi and Pi: -1.5708
+```
+
+### Code
+
+The code instantiates an angle class. The default constructed angle should be zero.
+
+\snippet examples/angle_example.cc Create an angle
+
+There are some predefined angles, such as:
+
+\snippet examples/angle_example.cc constant pi
+
+By default, all values are in radians, but you can use the method `Degree` to convert to degrees.
+
+\snippet examples/angle_example.cc Output the angle in radians and degrees.
+
+The `Angle` class overloads the `+=`, and many other, math operators.
+
+\snippet examples/angle_example.cc The Angle class overloads the +=, and many other, math operators.
+
+Use the method `Normalized` to bound the value between `-PI` and `PI`.
+
+\snippet examples/angle_example.cc normalized
+
+## Ruby example
+
+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 `/usr`:
+
+```{.sh}
+export RUBYLIB=/usr/lib/ruby:$RUBYLIB
+```
+
+Execute the code:
+
+```{.sh}
+ruby angle_example.rb
+```
+
+### Code
+
+There are some predefined values:
+
+```{.rb}
+printf("PI in degrees = %f\n", Ignition::Math::Angle.Pi.Degree)
+```
+
+Create new objects:
+
+```{.rb}
+a1 = Ignition::Math::Angle.new(1.5707)
+a2 = Ignition::Math::Angle.new(0.7854)
+```
+
+Use the values in radians or degrees:
+
+```{.rb}
+printf("a1 = %f radians, %f degrees\n", a1.Radian, a1.Degree)
+printf("a2 = %f radians, %f degrees\n", a2.Radian, a2.Degree)
+```
+
+The `Angle` class overloads math operators.
+
+```{.rb}
+printf("a1 * a2 = %f radians, %f degrees\n", (a1 * a2).Radian, (a1 * a2).Degree)
+printf("a1 + a2 = %f radians, %f degrees\n", (a1 + a2).Radian, (a1 + a2).Degree)
+printf("a1 - a2 = %f radians, %f degrees\n", (a1 - a2).Radian, (a1 - a2).Degree)
+```
+
+Normalize the value between `-PI` and `PI`.
+
+```{.rb}
+a3 = Ignition::Math::Angle.new(15.707)
+printf("a3 = %f radians, %f degrees\n", a3.Radian, a3.Degree)
+a3.Normalize
+printf("a3.Normalize = %f radians, %f degrees\n", a3.Radian, a3.Degree)
+```