Change shape-shape intersection API to return multiple contacts

[jslee02]

This pull request enables FCL to return multiple contacts per primitive-primitive collision. This feature is essential when FCL is used in physics simulation. For example, if we want to stack a primitive shape on another primitive shape in presence of gravity, multiple contacts are required to support the upper object. Single contact will make it unstable.

As I known, the most low level collision object types in FCL are triangle and primitive shapes. Depending on the kind of primitive shape, FCL uses different collision algorithms. Here is the category of collision algorithms in FCL:

1. triangle-triangle algorithm
2. primitiveShape-triangle algorithms
3. general (convex) primitiveShape-primitiveShape algorithm using libccd
4. bunch of fast algorithms for specific primitiveShape-primitiveShape combination

All the collision algorithms returns single contact point. If a mesh and other collision object are colliding, multiple contacts can be detected because a mesh consists of many of triangles. The problem is the case that two primitive shapes are colliding. Although the algorithm for specific primitive shapes combination (e.g, box-box), it had to pick a single contact or average them because of the limitation of API. So I propose to change the API to be able to return multiple contacts as:

// Previous API
template<typename S1, typename S2>
bool shapeIntersect(const S1& s1, const Transform3f& tf1, const S2& s2, const Transform3f& tf2, Vec3f* contact_points, FCL_REAL* penetration_depth, Vec3f* normal*) const FCL_DEPRECATED;

// Proposing API
template<typename S1, typename S2>
bool shapeIntersect(const S1& s1, const Transform3f& tf1, const S2& s2, const Transform3f& tf2, std::vector<ContactPoint>* contacts) const;

As of now, box-box collision algorithm is the only one can detect multiple contacts. Other collision algorithm for different combination of primitive shapes needs to be implemented. This will be done in following pull requests.

Since the previous API, which is exposed to the user, is just marked as deprecated instead of removed, this PR doesn't hurt the backward compatibility. With this new API, all the unit tests (those were not broken as itself) are passing.

This pull request also fixes #15.

[mamoll]

A small comment: in the old API, you could ask for just the contact normals, or just the contact points, or just the distances. Now all of them are copied, whether you need all of them or just one of them. This makes the API a lot cleaner, though. It shouldn't affect users who only need to know whether there is a collision.

[jslee02]

in the old API, you could ask for just the contact normals, or just the contact points, or just the distances. Now all of them are copied, whether you need all of them or just one of them

I considered to make them can be asked separately in the first place but didn't. The reason was that it seemed there are only two cases: they are all null pointers or not null pointers. For example, GJKCollide assumes all of them are not null pointers if contact point is not null pointer. If FCL still want to make them separate parameters then I'm fine with that.

Even though they all go together, it still doesn't affect users who only need to know whether there is a collision. In that case, the user should pass null pointer at the place of contact list parameter as:

bool res = gjk_solver.shapeIntersect(shape1, tf1, shape2, tf2, NULL);

[mamoll]

Yes, I understand. I'll leave it to someone else to give more detailed feedback and accept/reject the PR, but this looks fine to me.

[jslee02]

Thanks! I welcome any feedback or questions.

[scpeters]

Is it better to pass contacts as a pointer or pass by reference? Never mind, it looks like you make it a pointer so that it can be treated as an optional output.

Does it make sense to assign a default value of contacts=NULL?

[jslee02]

It makes sense to me. I can see there are other functions we can pass default function parameters such as shapeTriangleIntersect, shapeDistance, and shapeTriangleDistance.

Especially, shapeDistance(const S1&, const Transform3f&, const S2&, const Transform3f&, FCL_REAL*) looks redundant once we have shapeDistance(const S1&, const Transform3f&, const S2&, const Transform3f&, FCL_REAL* = NULL, Vec3f* = NULL, Vec3f* = NULL).

[scpeters]

Looks like there's conflicts again

[jslee02]

Right, the most conflicts are in test/test_fcl_geometric_shapes.cpp. I'm working on it, and thinking it will be done by around tomorrow.

[jslee02]

In the recent commits, I improved shape-shape collision test suits for multiple contacts and updated all the tests in test_fcl_geometric_shapes. Now all the test should pass without any conflicts.

[hsu]

Excellent work JS, this is a great start on improve FCL versatility. +1

[jslee02]

Thanks John, I will wait another day for further feedback before merge this PR.