C++ Get Started

Previous Tutorial: Installation

Overview

This tutorial describes how to get started using Ignition Math with C++.

We will run through an example that determines the distance between two points in 3D space. Start by creating a bare-bones main file using the editor of your choice.

int main()
{
  return 0;
}

The easiest way to include Ignition Math is through the ignition/math.hh header file. Alternatively, you can include only the header files you need. For this example, we'll take the short and easy approach.

At this point your main file should look like

#include <gz/math.hh>
 
int main()
{
  return 0;
}

Now let's create to 3D points with arbitrary values. We will use the ignition::math::Vector3 class to represent these points. Ignition Math provides a handy ignition::math::Vector3d type which is a typedef of Vector3<double>. The result of this addition will be a main file similar to the following.

#include <gz/math.hh>
 
int main()
{
  ignition::math::Vector3d point1(1, 3, 5);
  ignition::math::Vector3d point2(2, 4, 6);
 
  return 0;
}

Finally, we can compute the distance between point1 and point2 using the ignition::math::Vector3::Distance() function and output the distance value.

#include <gz/math.hh>
 
int main()
{
  ignition::math::Vector3d point1(1, 3, 5);
  ignition::math::Vector3d point2(2, 4, 6);
 
  double distance = point1.Distance(point2);
  std::cout << "Distance from " << point1 << " to " << point2 << " is " <<
    distance << std::endl;
  return 0;
}

Bonus: Vector2 Example

The following is an example program that uses Vector2 to perform some simple computation.

#include <iostream>
#include <gz/math.hh>
 
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";
  // The x and y component of vec2 can be set at anytime.
  gz::math::Vector2d vec2;
  vec2.Set(2.0, 4.0);
 
  // The Vector2 class is a template, so you can also create a Vector2 using
  // gz::math::Vector2<double>
  gz::math::Vector2<double> vec2a;
 
  vec2a.Set(1.0, 2.0);
 
  // It's also possible to set initial values. This time we are using
  // a Vector2 of floats
  gz::math::Vector2f vec2b(1.2f, 3.4f);
 
  // We can output the contents of each vector using std::cout
  std::cout << "Vec2: " << vec2 << "\n"
            << "Vec2a: " << vec2a << "\n"
            << "Vec2b: " << vec2b << "\n";
 
  // You can also get access to each component in the vector using the
  // X(), Y() accessors or the [] operator.
  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";
 
  // The [] operator is clamped to the range [0, 1]
  std::cout << vec2[3] << std::endl;
 
  // The Vector2 class overloads many common operators
  std::cout << vec2 * vec2a << "\n"
            << vec2 + vec2a << "\n"
            << vec2 - vec2a << "\n"
            << vec2 / vec2a << "\n";
 
  // There are also many useful function such as finding the distance
  // between two vectors
  std::cout << vec2.Distance(vec2a) << std::endl;
 
  // There are more functions in Vector2. Take a look at the API:
  // https://ignitionrobotics.org/libs/math
}