/** @mainpage BulletCollisionDetection - a plugin using Bullet collision pipeline within Sofa

This plugin contains the Bullet collision pipeline itself named
BulletCollisionDetection, where broad phase and narrow phase are performed. So
in the Sofa scene, you must place the element BulletCollisionDetection instead
of any broad or narrow phase. An important thing to know is that this plugin
works well with constraints (LMConstraintSolver for example) and no with
penalty contacts because it is not robust to collision models penetration. But
some improvement has been done with the collision model margin to allow this for
most of the primitives (if the primitives don't penetrate).


It also contains the element BulletIntersection which must replace any kind of
Sofa intersection method. So it has also to be placed in the Sofa scene.

It contains models already existing in Sofa and inheriting from them:
- BulletTriangleModel
- BulletSphereModel
- BulletCapsuleModel BulletRigidCapsuleModel
- BulletOBBModel
- BulletCylinderModel

There are also a collision model that doesn't derive from any of the Sofa
collision models:
- BulletConvexHullModel

Note that BulletConvexHullModel is special because its parameterization can
completely change its behaviour:

- It contains the parameter called computeConvexHullDecomposition, if set to
  true, the convex hull is decomposed in convex parts.
- The parameter concavityThreeshold is a real that parameterizes the convex hull
  decomposition, the more this parameter will be high, the more the
  decomposition will be gross.
- You can visualize the decomposition by setting the parameter
  drawConvexHullDecomposition to true.
- Another important thing is that its loading is similar to a triangle model
  because it needs a mesh but it is templated by a rigid mechanical object which
  position and orientation define also the position and orientation of the
  BulletConvexHull if positionDefined is set to true and if it is not, the
  mechanical must be of size 0 and its position/orientation will be computed at
  runtime as the barycenter of the entry points.

All collision models have the field called margin. It enlarges the primitives
(only in bullet, not in sofa) using the value of margin.

For a box, its extents are enlarged, for a sphere or a capsule, their radius are
enlarged.  Only the BulletConvexHullModel and the BulletTriangleModel use a real
margin, meaning that the primitives are not enlarged, and the collision closer
than the value margin are detected.

You can find some examples in the folder examples:
- BulletConvexHullDemo.scn which decomposes two objects show the decomposition:

@image html BulletConvexHullDemo.png

- GlobalBulletCollision.scn is an example of all primitives falling into a salad
  bowl, it is using sofa python:

@image html GlobalBulletCollision.png

- BulletSphere.scn is a very simple scene:

@image html BulletSphere.png

<h3>Dependencies</h3>

This plugin depends on Bullet 2.82, with the following peculiarities:
- you must compile with the BULLET_TRIANGLE_COLLISION definition;
- under Linux, you need to compile with the -fPIC option;
- you should compile it as shared libraries to avoid undefined references
  when loading the plugin (CMake option: BUILD_SHARED_LIBS)
- you need to install the "extra" libraries (CMake option:
  INSTALL_EXTRA_LIBS).

If you choose to install Bullet in a non-standard location, then in order to
build this plugin you should either add the installation prefix of Bullet to
CMAKE_PREFIX_PATH or set Bullet_DIR to the directory containing
BulletConfig.cmake (<prefix>/lib/cmake/bullet).

For reference, the following snippet downloads Bullet 2.82, compiles it with
the appropriate options, and installs it in ~/bullet.  One would then pass
"-DBullet_DIR=~/bullet/lib/cmake/bullet" as an argument to cmake to compile
this plugin:

@code
BULLET_INSTALL_PREFIX=~/bullet
wget https://bullet.googlecode.com/files/bullet-2.82-r2704.tgz
rm -rf bullet-2.82-r2704
tar -xzf bullet-2.82-r2704.tgz
cd bullet-2.82-r2704
patch CMakeLists.txt <<EOF
13a14
> add_definitions(-DBULLET_TRIANGLE_COLLISION)
EOF
cmake -DBUILD_SHARED_LIBS=ON -DINSTALL_EXTRA_LIBS=ON -DCMAKE_CXX_FLAGS=-fPIC -DCMAKE_INSTALL_PREFIX="$BULLET_INSTALL_PREFIX" .
make
make install
@endcode

<h3>Issues</h3>

- Currently, the plugin doesn't work well with CompliantContacts
- Some improvements to static meshes could be done by using another Bullet mesh
  class in this case

*/
