Background

As we build up the ROS ecosystem we are working hard to keep standardization for as much code as possible. When we started using Bullet we provided many patches to bullet upstream for patches and consistency in the API. We have provided those patches to the ROS users of Bullet in the form of a patched library. Some of these patches have not been able to be accepted upstream. Although the patches make Bullet easier to use in robotics context, as ROS grows, we do not want to keep a divergent Bullet API in our repository. Unfortunately this sort of change is a painful one.

We have discussed this change at length as part of the fuerte Planning Thirdparty SIG http://wiki/fuerte/Planning/Thirdparty and could do a full tick-toc cycle and be done in 1.5 years, leave things significantly out of date, and also wouldn't prevent nasty bugs in unmigrated code. The following method will provide most users with compile errors, except for the people using significant amounts of bullet's API. We realize these changes are a pain, but we believe that the pain is worth it.

The change

The portion of the Bullet LinearMath library which was used by tf has been copied into the tf namespace and renamed to avoid collisions.

Requirements to port your code

Datatype copies:

btMatrix3x3 -> tf::Matrix  (previously a typedef)
btVector3 -> tf::Vector3  (previously a typedef)
btScalar  -> tf::Scalar
btQuaternion -> tf::Quaternion  (previously a typedef)
btMinMax -> tf::MinMax
btQuadWord -> tf::QuadWord

Include path changes:

LinearMath/bt*.h -> tf/LinearMath/*.h

Differences between the patched version and the unpatched version

If you have not made the above transition you will observe the following differences, note some of these cannot be caught by the compiler.

• btTransform.setEulerZYX and getEulerZYX ROS version (Yaw pitch roll about ZYX axes respectively, BT form are about respectively about XYZ) (marked as deprecated in ROS version)
• btQuaternion(yaw, pitch, roll) ROS version axes ZYX, BT version YXZ
• btMatrix3x3 loses setRPY and getRPY methods do not exist in Bullet version
• btQuaternion no longer has angleShortestPath method

Updates to code

Choose one of the following two sections

Packages not depending on bullet directly

If you are using the tf datatypes(previously typedefed) no changes are needed. If you are using the bullet datatypes listed above and no other bullet datatypes the following command is expected to fix most stacks.

In a package which you want to convert run the following:

rosrun tf bullet_migration_sed.py

This will attempt to fix all your include paths and type declarations to use the new data types in that directory recursively. If you make sure that bullet is not in your manifest and then errors should be caught by the compiler.

Packages using other bullet datatypes

If you are using more of the Bullet API you should not run this script. And you will need to audit all of your Euler angle methods to confirm their order. Please review every instance of the APIs listed above for usage.

All of these changes are avoided if you use the new tf types. For easier interoperability, the tf types have a method toBt() and assignment operators from the equivilant Bullet datatypes. The above referenced sed script can form a good basis for your own scripts if necessary.

If you have any questions about how to update any portion of your code for the API changes please ask with the snippet of code on answers.ros.org with bullet_migration as the tag.