Gazebo Math : Math classes and functions for robot applications

Maintainer: scpeters AT openrobotics DOT org

GitHub open issues GitHub open pull requests Discourse topics



Test coverage


Ubuntu Jammy

Build Status


Build Status


Build Status

Gazebo Math, a component of Gazebo, provides general purpose math classes and functions designed for robotic applications.

Table of Contents




Folder Structure

Code of Conduct





Gazebo Math provides a wide range of functionality, including:

  • Type-templated pose, matrix, vector, and quaternion classes.

  • Shape representations along with operators to compute volume, density, size and other properties.

  • Classes for material properties, mass, inertial, temperature, PID, kmeans, spherical coordinates, and filtering.

  • Optional Eigen component that converts between a few Eigen and Gazebo Math types.


See the installation tutorial.


Please refer to the examples directory.

Folder Structure

Refer to the following table for information about important directories and files in this repository.

├── examples                 Example programs.
├── include/gz/math          Header files.
├── src                      Source files and unit tests.
│   └── graph                Source files for the graph classes.
│   └── python_pybind11      Pybind11 Python interfaces.
│   └── ruby                 SWIG Ruby interfaces.
├── eigen3                   Files for Eigen component.
├── test
│    ├── integration         Integration tests.
│    ├── performance         Performance tests.
│    └── regression          Regression tests.
├── tutorials                Tutorials, written in markdown.
├──             Changelog.
└── CMakeLists.txt           CMake build script.


Please see the contributing guide.

Code of Conduct

Please see


This library uses Semantic Versioning. Additionally, this library is part of the Gazebo project which periodically releases a versioned set of compatible and complimentary libraries. See the Gazebo website for version and release information.


This library is licensed under Apache 2.0. See also the LICENSE file.

Gazebo Math 7.x

Gazebo Math 7.5.0 (2024-06-18)

  1. Backport: Adding cone primitives.

  2. Enable 24.04 CI on harmonic

  3. Add package.xml

  4. bazel: correctly export license

  5. Add missing eigen3.hh header for bazel build

  6. Expose non-const reference to edges

Gazebo Math 7.4.0 (2024-03-14)

  1. Added MecanumDriveOdometry Python wrapper

  2. Update CI badges in README

  3. Infrastructure

  4. Suppress warnings on MSVC

  5. Remove the use of numeric_limits in appendToStream test

  6. Replace CMake Python variables with new ones from FindPython3 module

  7. Fix on Windows with conda-forge dependencies

  8. Fix small typo

  9. Update Ubuntu Binary installation since apt-key is deprecated

  10. Update file tree in README to point out pybind11

  11. Update tutorial/

  12. ign->gz in

  13. Update

Gazebo Math 7.3.0 (2023-08-29)

  1. Adds a validity check for Sessions created using the TimeVaryingVolumetricGrid

  2. Fixes for testing in non standard architectures

  3. MecanumDriveOdometry to handle odometry estimation of Mecanum wheeled models

  4. Fix documentation on Plane.hh

  5. Infrastructure

  6. Build examples from CMake rather than executable

  7. Added std::optional MassMatrix() functions for Box, Cylinder & Sphere

Gazebo Math 7.2.0 (2023-06-14)

  1. Add tests to increase test coverage

  2. Forward ports

  3. Disable pybind11 on windows by default

  4. Add option to skip pybind11 and SWIG

  5. Custom PID error rate

  6. Garden bazel support

  7. Rename COPYING to LICENSE

  8. Infrastructure

  9. Fix link of installation tutorial to point to 7.1 version

Gazebo Math 7.1.0 (2022-11-15)

  1. Adds bounds retrieval for TimeVarying grid class.

Gazebo Math 7.0.2 (2022-09-26)

  1. Update to disable tests failing on arm64

Gazebo Math 7.0.1 (2022-09-23)

  1. Disable tests failing on arm64

Gazebo Math 7.0.0 (2022-09-22)

  1. Deprecated Angle::Degree(double) and Angle::Radian(double). Use Angle::SetDegree(double) and Angle::SetRadian(double) instead.

  2. Added Equal functions with a tolerance parameter to Pose3 and Quaternion.

  3. Updates per issue #101.

  4. Removed deprecations.

  5. Updated Temperature class documentation, script interface, and added examples.

  6. Prevent -0 with out stream operator

  7. Use <ostream> and <istream> narrower includes, not <iostream>

  8. Evict large function definitions from the Helpers.hh header file.

  9. Defer regex construction to avoid static initialization.

  10. Defer Material::Predefined construction to avoid static initialization.

  11. Resolve cppcheck errors by adding explicit constructors and consts.

  12. Remove virtual from destructors of copyable classes.

  13. Use constexpr for simple static constants.

  14. Fix output stream operator

  15. Tutorial updates

  16. Fixed quaternion from euler example

  17. Rename the python library as gz.math7

  18. Add option to skip pybind11 and SWIG

  19. Python bindings

  20. Add a Time Interpolation API

  21. Add fluid added mass to inertial

  22. VolumetricGridLookupField: generalize index type, add constructor

  23. Drop unnecessary moving window filter pimpl

  24. Migrate ign -> gz

  25. Fix output stream operator

  26. Compute distance between points on a general celestial body

  27. Update GoogleTest to latest version

  28. Reduce compilation time

  29. Pose3: deprecate +, -, and -= operators

  30. Document Pose::operator*()

  31. Subtraction operator for Inertial class

  32. Add linear interpolation methods.

  33. Infrastructure

  34. Add PiecewiseScalarField3 class

  35. Add AdditivelySeparableScalarField3 class

  36. Add Polynomial3 class

  37. Add Interval and Region3 classes

  38. Add missing headers

  39. [math7] Tidy up unused variables

  40. Use ImplPtr from ign-utils where relevant

  41. Modified cmake target name for Ruby interfaces

  42. Make API / naming consistent for Frustum, Edge, Angle

  43. Reduce Stopwatch test sleep times

  44. Speed up Helpers::Pair test

  45. Make Vector2 API more consistent with Vector3

  46. Clean up a few new GCC9 warnings

Gazebo Math 6.x

Gazebo Math 6.15.1 (2024-01-05)

  1. Replace CMake Python variables with new ones from FindPython3 module

  2. Suppress warnings on MSVC

  3. Infrastructure

Gazebo Math 6.15.0 (2023-09-01)

  1. Fixes for testing in non standard architectures

  2. MecanumDriveOdometry to handle odometry estimation of Mecanum wheeled models

  3. Infrastructure

Gazebo Math 6.14.0 (2023-04-14)

  1. Disable pybind11 on windows by default

  2. Add option to skip pybind11 and SWIG

  3. Custom PID error rate

  4. Infrastructure

Gazebo Math 6.13.0 (2022-08-31)

  1. Support migration and migrate headers

  2. Remove redundant namespace references

Gazebo Math 6.12.0 (2022-07-27)

  1. Added Helper function isTimeString to Python

  2. Ignition -> Gazebo

  3. Added *.pyc to .gitignore

  4. Alphabetize examples

  5. Add PiecewiseScalarField3 class

  6. Add AdditivelySeparableScalarField3 class

  7. Add Polynomial3 class

  8. Add Region3 class

  9. Add Interval class

  10. Add Matrix6 class

  11. Backport newest appendToStream functions

  12. Use pytest to generate junit xml files for python tests

  13. Add Aditya as codeowner

Gazebo Math 6.11.0 (2022-05-11)

  1. MassMatrix3: fix bug in PrincipalAxesOffset tolerances

  2. Fix return policies for some member functions

  3. Added Ellipsoid Python interface

  4. Added Capsule Python interface

  5. Fixes for tests on i386: relax SphericalCoordinates and workaround for negative zero

  6. Added helper function to check if a string represents a time

  7. Reduce pybind11 compilation memory

Gazebo Math 6.10.0 (2022-01-26)

  1. Use const instead of constexpr in Ellipsoid constructor

  2. Refactor finding pybind11

  3. Fix Focal on Jenkins

  4. kmeans example in C++ and Python

  5. Small fixed in doxygen

  6. Added Python Getting started tutorial

  7. Move SWIG interfaces from Python to Ruby

  8. Added pybind11 interfaces for various classes

    1. SphericalCoordinates

    2. Vector3Stats

    3. SignalStats

    4. Sphere

    5. Frustum

    6. Plane

    7. Cylinder

    8. OrientedBox

    9. Inertial

    10. Matrix4

    11. PID

    12. Temperature

    13. DiffDriveOdometry (with examples)

    14. MassMatrix3

    15. AxisAlignedBox

    16. GaussMarkovProcess (with examples)

    17. RotationSpline

    18. Material

    19. Kmeans

    20. Triangle3

    21. Pose3

    22. Triangle

    23. Spline

    24. Filter

    25. SemanticVersion

    26. Matrix3

    27. MovingWindowFilter

    28. Line3

    29. Quaternion

    30. StopWatch

    31. RollingMean

    32. Line2

    33. Color

    34. Helpers

    35. Rand (with examples)

    36. Angle

    37. Vector2, Vector3 and Vector4

  9. Fix Color::HSV() incorrect hue output

  10. Add example and modify document for class Color

  11. Document that euler angles should be in radians for quaternion constructor

  12. Fix windows warnings in Vector2, 3 and 4

  13. Modified cmake target name for Ruby interfaces

  14. Frustrum Python interface

  15. quaternion_from_euler example: input degrees

  16. Internal URL fixed (paragraph 266)

  17. Added tutorials for vector, angle, triangle and rotation

  18. Inertial Python interface

  19. Box Python interfaces

  20. DiffDriveOdometry Python interface

  21. Sphere Python interface

  22. Plane Python interfaces

  23. Cylinder Python interface

  24. Added SphericalCoordinates Python interface

  25. MassMatrix3 Python interface

  26. AxisAlignedBox Python interface

  27. AxisAlignedBox: deprecate unimplemented methods

Gazebo Math 6.9.2 (2021-10-14)

  1. Added StopWatch Python Interface

  2. Fix clang warnings.

  3. Fixed Helpers Python templates

  4. Add Helpers Python interface

  5. Add Python interface to Triangle3

  6. Adds python interface to MaterialType and Material.

  7. Remove Cylinder::SetLength const method

Gazebo Math 6.9.1 (2021-09-30)

  1. Avoid assertAlmostEqual for python strings

  2. use 0.01 (not 0) in string test

Gazebo Math 6.9.0 (2021-09-28)

  1. Volume below a plane for spheres and boxes

  2. 🌐 Spherical coordinates: bug fix, docs and sanity checks

  3. Add Vector(2|3|4)::NaN to easily create invalid vectors

  4. Add options to install python/ruby in system standard paths

  5. Add eigen utils to convert mesh 3d vertices to oriented box

  6. Python interface

    1. Adds python interface to RollingMean, Color and Spline

    2. Adds python interface for Kmeans and Vector3Stats

    3. Adds python interface to PID and SemanticVersion.

    4. Adds python interface to triangle.

    5. Adds Line2, Line3, SignalStats, Temperature python interface

    6. Python interface: Renames methods to match PEP8 style

    7. Adds python interface to Filter, MovingWindowFilter, RotationSpline.

    8. Adds python interface to Quaternion, Pose3, Matrix3 and Matrix4

    9. Basic setup for Python interface using SWIG

  7. 👩‍🌾 Don’t use std::pow with integers in Vectors and handle sqrt

  8. Relax expectations about zero in SpeedLimiter_TEST to make ARM happy

  9. Infrastructure

Gazebo Math 6.8.0 (2021-03-30)

  1. Add speed limiter class

  2. Bazel Updates for math6

  3. Add Equal tolerance method to Quaternion

  4. Fix broken link in MassMatrix3.hh

  5. Add instructions to build and run examples

  6. Infrastructure and documentation

  7. Remove unnecessary copy constructor declaration from Box

  8. Windows installation via conda-forge

  9. Add rule-of-five members for Angle

  10. Ellipsoid: new shape class with inertia calculation method

  11. Avoid moving a return value, it might prevent (N)RVO

  12. Properly handle stream errors when reading math objects

Gazebo Math 6.7.0 (2020-11-23)

  1. Capsule: new shape class with inertia calculation method

  2. Add missing header to Color.hh

  3. Improve tests of Vector2, Vector3, Vector4, Quaternion, and Pose3

  4. Pose3: document operator*

  5. Quaternion: add Normalized() method

  6. Vector2: add Round(), Rounded() methods

  7. Add test for printing inf Vector3

Gazebo Math 6.6.0 (2020-09-16)

  1. Add chrono duration helper functions

Gazebo Math 6.5.0 (2020-09-04)

  1. Add string to time function

  2. Added functions to convert between time_point and secNsec


  4. Add Max and Min function to Vector2.hh

  5. Round, Rounded, Correct, Distance(x, y, z, w) and operator< addition to Vector 4

  6. Sum and normalized functions for Vector4

  7. Vector4 Ruby tests - Vector4.i and Vector4_TEST.rb

  8. Vector3 to vector4 functions

  9. Update vector2 fuctions from vector3

  10. Add Abs, Dot and AbsDot and respective tests to Vector4

  11. Create abs, absDot and Correct functions for Vector2d

  12. Document Ruby tests

  13. Add header for numeric_limits allowing build on ubuntu 16.04

  14. Add setter/getter for Pose’s each element

  15. Implement AxisAlignedBox Volume function

  16. Add operator + for AxisAlignedBox and Vector3.

  17. Make alpha optional when parsing a Color from an input stream.

  18. GitHub actions CI and workflow updates

  19. Added a Gauss-Markov Process class.

  20. Fix bug in Inertial addition of off-diagonal moment of inertia terms with pose offsets.

  21. Create FAKE_INSTALL target so example compilation can be tested without doing a real install.

  22. Updating documentation.

  23. GraphAlgorithms: add ToUndirected(DirectedGraph) that copies to an UndirectedGraph.

  24. Doxygen fixes for graph classes

Gazebo Math 6.4.0

  1. Added a function that rounds up a number to the nearest multiple of another number.

Gazebo Math 6.3.0

  1. Added Odometry class that computes odometry for a two wheeled vehicle.

  2. Added RollingMean class.

Gazebo Math 6.2.0

  1. eigen3: Use linear() instead of rotation() to prevent computation of SVD

  2. Change definition of Pose3 * operator to fix multiplication order

Gazebo Math 6.1.0

  1. eigen3: add conversion functions for Eigen::AlignedBox3d <=> gz::math::AxisAlignedBox

Gazebo Math 6.0.0

  1. Helper function that converts from std::chrono::steady_clock::duration to {seconds, nanoseconds}.

  2. Upgrade to c++17.

Gazebo Math 5.x

Gazebo Math 5.x.x

Gazebo Math 5.1.0 (2019-09-11)

  1. GraphAlgorithms: add ToUndirected(DirectedGraph) that copies to an UndirectedGraph.

  2. Doxygen fixes for graph classes

  3. eigen3: Use linear() instead of rotation() to prevent computation of SVD

  4. Change definition of Pose3 * operator to fix multiplication order

  5. eigen3: add conversion functions for Eigen::AlignedBox3d <=> gz::math::AxisAlignedBox

Gazebo Math 5.0.0 (2018-12-12)

  1. Added a Stopwatch class

  2. Added material properties to OrientedBox

  3. Added a Cylinder class.

  4. The Box class has been changed to a templatized class that is not axis-aligned. The previous Box functionality is now in the AxisAlignedBox class.

  5. Added eigen3 component with functions for converting between Eigen and gz-math types.

  6. Added a MassMatrix3::SetFromCylinder function that uses a Material to specify a density.

  7. Added a Sphere class.

  8. Added a MassMatrix3::SetFromSphere function that uses a Material to specify a density.

  9. Added a MassMatrix3::SetFromBox function that uses a Material to specify a density.

  10. Deprecated mutator functions in MassMatrix3 that lacked a Set prefix.

  11. Updated the MassMatrix3::ValidMoments(), MassMatrix3::IsValid(), MassMatrix3::IsPositive(), and Inertial::SetMassMatrix functions to accept a tolerance parameter.

  12. Add MassMatrix3::IsNearPositive and use it in MassMatrix3::IsValid, use >= instead of > in MassMatrix3::ValidMoments

Gazebo Math 4.x

Gazebo Math 4.x.x

  1. Add Graph::EdgeFromVertices function that return an edge, if one exists, between two vertices.

  2. Added multiply assign operator to Matrix4.

  3. Add Plane copy constructor and fix cppcheck on artful

  4. Added MovingWindowFilter, a copy from Gazebo Common. This version will replace the version found in Gazebo Common.

  5. Added a Material class, which holds information about materials like wood, steel, and iron.

Gazebo Math 4.0.0 (2017-12-26)

  1. Use std::stoi and std::stod in math::parse* functions to reduce code

  2. Fixing const-correctness for operator* of Pose3

  3. Deprecate Matrix4::Translate and replace by Matrix4::SetTranslation

  4. Use ignition-cmake to simplify build scripts

  5. Make constructor SemanticVersion(string) explicit

  6. Switch to C++14

  7. Removed the box ‘extent’ field. The default constructor now sets a box’s corners to extrema in order to indicate an uninitialized box.

  8. Added graph utilites:

    1. Added a Vertex class:

    1. Added an Edge class:

    1. Added a Graph class:

    1. Added a GraphAlgorithms class:

    1. Added a function to calculate connected components in undirected graphs:

    1. Improved the performance of graph::InDegree() and graph::IncidentsTo().

  9. Added Inline Versioned Namespace

Gazebo Math 3.x

Gazebo Math 3.x.x

Gazebo Math 3.3.0 (2017-11-27)

  1. Fixed frustum falsely saying it contained AABB in some cases

  2. Create consistent bracket operators across all Vector# types

  3. Change name to the generic BUILDING_DLL macro to avoid conflicts

  4. Fix some compiler warnings

  5. Suppress gtest warnings

  6. Move private headers to src folder

  7. Update configure.bat

Gazebo Math 3.2.0 (2017-05-15)

  1. Construct on first use in Rand class

  2. Extended Spline API: derivative interpolation, arc length calculation and tangent forcing.

Gazebo Math 3.1.0 (2017-04-11)

  1. Added signum functions to Helpers.hh.

Gazebo Math 3.0.0 (2017-01-05)

  1. Deprecate many IGN_* macros in favor of static const variables in Helpers.hh

  2. Removed exceptions. Return values should be evaluated to determine if errors have occured.

  3. Added operator=(const Quaternion<T> &_q) to Matrix3.

  4. Fix xenial cppcheck

  5. Require cmake 2.8.12

  6. Migrate to relocatable CMake package. Contribution from Silvio Traversaro.

  7. Fix logic of installation of CMake configuration files in Windows. Contribution from Silvio Traversaro.

Gazebo Math 2.x

Gazebo Math 2.9 (2017-11-22)

  1. Fixed frustum falsely saying it contained AABB in some cases

  2. Added Color

  3. Backport updated configure.bat to gz-math2 and fix cppcheck warnings

Gazebo Math 2.8

Gazebo Math 2.8.0

  1. Added OrientedBox

  2. Added an assignment operator to the Frustum class.

Gazebo Math 2.7

Gazebo Math 2.7.0

  1. Add static const variables as alternative to macros in Helpers.hh

  2. Add new methods for floating numbers: lessOrEqual and greaterOrEqual

Gazebo Math 2.6

Gazebo Math 2.6.0

  1. Added copy constructor, equality operators and assignment operators to SphericalCoordinates class.

  2. Fix Euler angle conversion of quaternions near singularities

  3. Backport triangle3, helper functions, equality helper to work with 387 fp unit (Contribution from Rich Mattes).

  4. Added Matrix4::LookAt

  5. Set Inertial Rotations

  6. Added SemanticVersion class

Gazebo Math 2.5

Gazebo Math 2.5.0

  1. Added PID class

  2. Added SphericalCoordinate class

Gazebo Math 2.4

Gazebo Math 2.4.1

  1. Combine inertial properties of different objects, returning the equivalent inertial properties as if the objects were welded together.

Gazebo Math 2.4.0

  1. New MassMatrix3 class

  2. MassMatrix3 helper functions

  3. Added Temperature class

Gazebo Math 2.3.0

  1. Added simple volumes formulas

  2. Add Length and SquaredLength for Vector2 with test

  3. Add Equal function with numerical tolerance argument

  4. First part of MassMatrix3 class, mostly accessors and modifiers

  5. Add Transpose methods for Matrix3,4 with test

  6. Multiplication improvements for Vector/Matrix classes

  7. Scalar +,- operators for Vector[234]

  8. Add Determinant method for Matrix[34]

  9. Fixes for compiling and running tests on Windows 7/Visual Studio 2013 Contribution from Silvio Traversaro.