[ros-users] Bullet change in unstable for Fuerte -- EFFECTS ALL PACAKGES USING Bullet and tf

[Tully Foote]

Hi everyone,

If you are using Bullet datatypes this effects you! As we are approaching
the release of ROS Fuerte, please read!

If you want the quick version jump to the = Updates to code = section
below.

= 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://www.ros.org/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.

The script is also attached.  The script has been used to successfully
completely convert several test packages so far.  If there are improvements
which can be made please ticket them and we will rerelease it such that
others can get the improvements quickly.

Tully


-- 
Tully Foote
Systems Engineer
Willow Garage, Inc.
tfoote at willowgarage.com
(650) 475-2827
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osuosl.org/pipermail/ros-users/attachments/20111128/82259e9f/attachment-0003.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: bullet_migration_sed.py
Type: text/x-python
Size: 3250 bytes
Desc: not available
URL: <http://lists.osuosl.org/pipermail/ros-users/attachments/20111128/82259e9f/attachment-0003.py>