Intro

A simple, analytical inverse kinematic library for industrial robots with parallel bases and spherical wrists. Based on the paper An Analytical Solution of the Inverse Kinematics Problem of Industrial Serial Manipulators with an Ortho-parallel Basis and a Spherical Wrist by Mathias Brandstötter, Arthur Angerer, and Michael Hofbaur.

Purpose

This package is meant to provide a simpler alternative to IK-Fast based solutions in situations where one has an industrial robot with a parallel base and spherical wrist. This configuration is extremely common in industrial robots.

The kinematics are parameterized by 7 primary values taken directly from the robot’s spec sheet and a set of joint-zero offsets. Given this structure, no other setup is required.

Build Status

Platform	CI Status
Linux (Focal)
Linux (Bionic)
Linux (Xenial)
Windows
Lint (Clang-Format)
Lint (CodeCov)

Parameters

This library makes use of 7 kinematic parameters (a1, a2, b, c1, c2, c3, and c4) defined in the paper An Analytical Solution of the Inverse Kinematics Problem of Industrial Serial Manipulators with an Ortho-parallel Basis and a Spherical Wrist. See the paper for details.

This paper assumes that the arm is at zero when all joints are sticking straight up in the air as seen in the image below. It also assumes that all rotations are positive about the base axis of the robot.

To use the library, fill out an opw_kinematics::Parameters<T> data structure with the appropriate values for the 7 kinematic parameters and any joint offsets required to bring the paper’s zero position (arm up in Z) to the manufacturers position. Additionally, there are 6 “sign correction” parameters (-1 or 1) that should be specified if your robot’s axes do not match the convention in the paper.

For example, the ABB IRB2400 has the following values:

  Parameters<T> p;
  p.a1 = T(0.100);
  p.a2 = T(-0.135);
  p.b =  T(0.000);
  p.c1 = T(0.615);
  p.c2 = T(0.705);
  p.c3 = T(0.755);
  p.c4 = T(0.085);

  p.offsets[2] = -M_PI / 2.0;

  p.sign_corrections[0] = 1; // Already 1 by default; just an example

Note that the offset of the third joint is -90 degrees, bringing the joint from the upright position to parallel with the ground at “zero”.

You can find other examples (many un-tested) taken from the source paper in include/opw_kinematics/opw_parameters_examples.h.

Create Debian Package (Linux) or NuGet Package (Windows)

The following process will generate a Debian or NuGet package leveraging cmake and cpack based on the OS.

The package should be located in the current directory.

cd <workspace directory>
catkin build -DOPW_PACKAGE=ON
./src/opw_kinematics/.run-cpack

Example

#include "opw_kinematics/opw_kinematics.h"
#include "opw_kinematics/opw_parameters_examples.h" // for makeIrb2400_10<double>()
#include "opw_kinematics/opw_utilities.h" // for optional checking
#include <array>

int main()
{
  const auto abb2400 = opw_kinematics::makeIrb2400_10<double>();

  // Inverse kinematics
  auto pose = opw_kinematics::Transform<double>::Identity();
  pose.translation() = Eigen::Vector3d(1.3, 0.2, 0);

  // Up to 8 solutions exist
  // NaN indicates a solution did not exist
  std::array<double, 6 * 8> sols; // You could also use a std::vector or c-array of the appropriate size (6*8)
  opw_kinematics::inverse(abb2400, pose, sols.data());

  // Forward kinematics
  Eigen::Isometry3d forward_pose = opw_kinematics::forward(abb2400, &sols[6 * 0]);

  // Optionally, check for validity (this just makes sure there are no Nans in a solution)
  bool second_sol_is_valid = opw_kinematics::isValid(&sols[6 * 1]);

  // Optionally, harmonize the result toward zero in place
  // So if a joint is greater than PI or less than -PI, we add -2PI or +2PI respectively to move the joint solution closer to zero.
  opw_kinematics::harmonizeTowardZero(&sols[6 * 2]); // Harmonizes the third solution.

  return 0;
}

Notes

The library returns the 8 kinematically unique solutions for a given pose. Note that:

1. These solutions ARE NOT the ONLY solutions. For each joint that can rotate more than 2 * Pi, there exists redundant solutions. For example, if joint 6 can rotate -2Pi to 2Pi then a solution with joint 6 at 4.0 radians also has a solution with joint 6 at -2.28 radians and all other values the same.
2. This library has no concept of LIMITS! Check your own limits. Be sure to check the redundant solutions to see if they are in limits. Consider calling opw_kinematics::harmonizeTowardZero(T* qs) in opw_kinematics/opw_utilities.h to help check these.

Changelog for package opw_kinematics

0.5.0 (2022-07-05)

• remove xenial CI build
• Update to ros_industrial_cmake_boilerplate 0.3.0
• Contributors: Levi Armstrong

0.4.6 (2022-06-26)

• Update cpack CI to use colcon
• Use find_gtest macro
• Updated CPack
• Fix windows CI branch
• Update windows CI (#64)
• Contributors: Levi Armstrong, Michael Ripperger

0.4.5 (2022-03-24)

• Upgrade to latest cmake boilerplate and add cmake formater
• Contributors: Levi Armstrong

0.4.4 (2021-11-11)

• Fix numerical issue in inverse function
• Contributors: Levi-Armstrong

0.4.3 (2021-04-23)

• Do not add compiler option -mno-avx if processor is uknown
• Contributors: Levi Armstrong

0.4.2 (2021-04-15)

• Do not add compiler option -mno-avx for arm
• Contributors: Levi Armstrong

0.4.1 (2021-04-09)

• Only enable initialize_code_coverage if code coverage is enabled
• Add cpack archive package
• Add package debian github action leveraging cpack
• Add CONTRIBUTING.md
• Contributors: Levi Armstrong

0.4.0 (2021-02-19)

• Vectorize using Eigen::Array and Eigen::Map
• Add code coverage CI build
• Clean CMakeLists.txt
• Switch to using std::array versus raw pointer to array
• Contributors: Levi Armstrong

0.3.1 (2021-01-06)

• Update to use initialize_code_coverage() macro
• Contributors: Levi Armstrong

0.3.0 (2021-01-06)

• Extract package name and version from package.xml
• Update CI build and add badges to readme
• Remove -std=c++11 compile option. This causes problems in downstream packages that add cxx_std_14 to compile features.
• Increase version to 0.2.0
• Add github actions
• Add code coverage to targets
• Add ros_industrial_cmake_boilerplate
• Contributors: Levi Armstrong, Matthew Powelson

0.1.0 (2020-02-06)

• Change build tool depend from catkin to cmake
• Change Affine3d to Isometry3d in readme
• Address compiler warnings
• Export targets with namespace to build directory
• Fix gtest target names
• Use new source_bat.bash command to set env variables (#34)
  • Use source_bat to configure env variables
  • Update source_bat in travis.yml
  • Update source_bat in travis.yml
  • Remove comments and set build type to Release in travis.yml
• Add windows build to ci
• Add package specific gtest subdirectory
• Initialize Forward return value to identity
• Fix unit tests method for including gtest to work if exists
• Pure cmake (#25)
  • Make opw_kinematics a pure cmake package
  • Set cmake version to 3.8.0
  • Add support for cmake versions on xenial
  • Replace cxx property with compiler option
  • Add namespace to exported targets
  • Add ExternalProject_add for GTest if not found
• force evaluation of Vector u in forward, fixes #21 using auto here allowed the compiler to create some sort of computation-object that was later handled incorrectly. Not sure if this is a bug in Eigen or g++. It also fixes a warning about uninitialized values being used and makes the tests succeed on our systems.
• switch to industrial_ci, add eigen dependency
• accept warnings as they stem from ikfast mostly
• Add travis config based on moveit_ci
• Fix printing of joint sign corrections. Print the sign correction as [-1]{.title-ref} or [1]{.title-ref} instead of the raw character.
• Replaced Affine with Isometry in Readme.md
• Changed license to Apache 2.0
• Replaced Affine with Isometry to better reflect what the solver is working toward
• Added image with positive rotations marked on it
• Added note about the default rotational axis
• Added noexcept to IK & FK calls. Casted all real number literals to the appropriate type. This prevents us from converting doubles to floats all the time and increases speed by quite a bit when you want to use floats.
• Swapped the short int to a signed char. We're just using it for -1 or 1 so it shouldn't matter.
• Made updates to the attribution for the idea behind the test: thanks jeroen demaeyer!
• Added a 'throughput' test for FK/IK for three different robots. No assertions but its nice to have something easy to re-run.
• Added a new set of tests based on JeroenDM's kuka tests that compute FK, solve the IK, and then make sure a new FK matches the original
• Renames abb2400_tests to abb2400_ikfast_tests to better capture the intent of the tests
• Moved the gtests inside a CATKIN_ENABLE_TESTING if-clause in the main cmake file
• Add joint sign corrections to parameters
• add ik test for using a single forward kinematics solution
• add simple fk test using a known solution for KukaKR6_R700_sixx
• Update KukaKR6_R700_sixx to match description kuka_experimental package
• add joint sign corrections to parameters and update io function
• Create LICENSE GPLv3
• Moved some includes around
• Added a doc string pointing to the examples
• Added a few more example robot configurations.
• Documentation - noted that you can store the results in many different formats.
• Added diagram from paper; expanded examples
• Converted all the fixed double math over to templatized code.
• Added some utility headers for harmonization and validity checking.
• Added some documentation
• Added some basic unit tests to compare the OPW and IKFast solutions for the same abb 2400
• Contributors: CraigLin, G.A. vd. Hoorn, Jeroen, John Wason, Jonathan Meyer, Levi Armstrong, Matthew Powelson, Michael Ripperger, Simon Schmeisser, jeroendm