Documentation issue with respect to object size and timestep

[GoogleCodeExporter]

Chapter 14 of the manual says that the minimum object size is about 0.1 units 
for a gravity of 9.8. Unfortunately, it doesn't work at the default timestep of 
60Hz, whatever mass, friction, restitution, damping, and so on, when colliding 
boxes with a static plane. See 
http://bulletphysics.org/Bullet/phpBB3/viewtopic.php?f=9&t=7249 for symptoms 
and suggested solutions.

Therefore, it would greatly help new users if the manual was changed to use 
"0.2 units" and "20 centimeters" as the minimum size. And even at this size, 
there still is some instability for box/plane collision, so it would be better 
to use "0.3" and "30 cm". In fact, someone on the forums even suggested to go 
as far as "0.5" to avoid any instability.

Even better, there should be a few sentences explaining the relation between 
size, gravity, and timestep. Something like the following for the first 
paragraph of Chapter 14: "...don't create objects smaller than 30 centimeters 
for Earth gravity. If smaller objects or bigger gravity are manipulated, reduce 
the simulation timestep accordingly. For instance, simulating a dice throw 
(1cm-wide box with a gravity of 987cm/s2) requires a frequency of at least 
300Hz. It is recommended to keep the maximum size of moving..."

By the way, this is with version 2.78 of the manual.

Original issue reported on code.google.com by guillaum...@gmail.com on 14 Aug 2011 at 10:14

• Merged into: #541

[GoogleCodeExporter]

I just created a demo that shows boxes of 5cm (0.05) units colliding and 
resting fine on a plane.

Can you modify the BasicDemo that shows the instability?

http://code.google.com/p/bullet/issues/detail?id=541#c5

Original comment by erwin.coumans on 15 Sep 2011 at 1:22

• Changed state: Duplicate

[GoogleCodeExporter]

Here is a modification of BasicDemo with boxes of half-width 0.025, gravity of 
9.8, timestep of 60Hz, restitution of 0.1, friction of 1.0, linear damping of 
0.1, and angular damping of 0.3. With version 2.78 of Bullet, the boxes don't 
come to rest. You can play with the SCALE factor (e.g. setting it to 100, so 
that the collision margin becomes negligible with respect to the size of the 
objects) and notice that it doesn't change the behavior.

Original comment by guillaum...@gmail.com on 15 Sep 2011 at 5:27

Attachments:

• BasicDemo.cpp

[GoogleCodeExporter]

Using the latest trunk, you need to make two changes to make your demo with 
0.025 size boxes stable:

set the collision margin to be an order of magnitude smaller than the size, for 
example
        colShape->setMargin(0.001);
and use a smaller timestep:
        m_dynamicsWorld->stepSimulation(ms / 1000000.f, 100, 1/240.);

At 60 hertz it is best to use 10 centimeter/0.1 units boxes.

Original comment by erwin.coumans on 15 Sep 2011 at 5:38

[GoogleCodeExporter]

Improving the documentation is a good point though. The instability is a 
complex function related to object size, gravity, timestep, collision margin, 
friction and more.

I cannot reproduce the instability for 0.1 sized objects at default gravity at 
60 hertz using the latest trunk. It might be a bug on your side?

Original comment by erwin.coumans on 15 Sep 2011 at 5:46

[GoogleCodeExporter]

I know that you have to increase the frequency. Perhaps you missed the point of 
my report. I was not saying there is a bug in the implementation. I was just 
suggesting to add a sentence to the documentation saying to increase it for 
small objects (and I even provided the sentence).

By the way, if you take the file I posted and change line 143 so that it uses 
0.05 (10 centimeter boxes), you will see that there is still too much jitter at 
this size for the simulation to be useful.

Original comment by guillaum...@gmail.com on 15 Sep 2011 at 5:46

[GoogleCodeExporter]

Some better documentation that explains the complex relationship between object 
size, gravity, timestep, friction, collision margin, restitution and contact 
generation would be nice indeed.

Using 0.05 works OK in your demo if you enable this line:
    m_collisionConfiguration->setPlaneConvexMultipointIterations();

This allows the btStaticPlaneShape to compute multiple contact points at once, 
which improves stability.

I'll make sure to improve the section in the documentation for upcoming release.

Original comment by erwin.coumans on 15 Sep 2011 at 6:05

[GoogleCodeExporter]

I have been trying to emulate your patch in 2.78 with

    btConvexPlaneCollisionAlgorithm::CreateFunc* planeCreateFunc = (btConvexPlaneCollisionAlgorithm::CreateFunc*)m_collisionConfiguration->getCollisionAlgorithmCreateFunc(BOX_SHAPE_PROXYTYPE, STATIC_PLANE_PROXYTYPE);
    planeCreateFunc->m_numPerturbationIterations = 3;
    planeCreateFunc->m_minimumPointsPerturbationThreshold = 3;

and it didn't help at all. Perhaps I did misunderstand your change. Or perhaps 
there has been some additional changes to stability of plane/box collisions in 
SVN, and I shouldn't expect this change alone to help. So for now I will keep 
using the increased frequency.

Anyway, thanks for your time on this matter. I will be sure to test the next 
release once it is out.

Original comment by guillaum...@gmail.com on 15 Sep 2011 at 6:38

[GoogleCodeExporter]

Updated manual

http://code.google.com/p/bullet/source/detail?r=2440

Thanks for the feedback!
Erwin

Original comment by erwin.coumans on 17 Sep 2011 at 12:28