35. MergeSplit (deprecated)

This feature is deprecated and will be removed in the next major release of AGX Dynamics. We recommend that you use the new Merge functionality described in Section 34. It is more general and support added masses, constrained systems etc.

MergeSplit is a method that can be used to increase the performance in a scene with a medium number of simple/non-constrained bodies. A typical scenario is a tractor shuffling around rocks on a height field. Having all rocks/bodies dynamically simulated the whole time would generate a large number of contact constraints, which in turn would affect the performance negatively. MergeSplit will consider bodies which are in contact and analyze if bodies can be merged into one body containing multiple geometries, or have to be split into smaller parts again.

MergeSplit has the advantage over AutoSleep that it can be used for reducing complexity in scenes where bodies are in contact with a dynamic object. Assume you are simulating a truck. A wheel loader is loading rocks on the bed of the truck, now even if the truck moves, bodies can still be merged with the bed of the truck. This means that instead of having hundreds or thousands of bodies simulated on the bed, there are only a few, as they are merged into one body. The mass, inertia and center of mass will still be accurate.

The criteria for a merge are:

  • One or more of body A’s geometries are in contact with one or more of body B’s geometries.

  • AND |A.velocity – B.velocity|2 < velocity threshold

  • AND |A.acceleration – B.acceleration|2 < acceleration threshold

  • One of the bodies is not attached to an enabled constraint (Hinge, LockJoint etc…)

In other words when the two bodies A and B can be considered moving as one rigid body, they are merged into one single rigid body. If Body1 is STATIC, it will become the “parent” of Body2. If Body1 is constrained (has a constraint associated to it) it will become the parent of Body2 and vice versa. A constrained body can never become a “child” of another body.

This means that if a dynamic body falls onto a static ground, the dynamic body will be part of the static ground.

When a body A is merged into another body B, A will still get its transformation updated when B moves. Body A will however be disabled (not part of the dynamic simulation).

MergeSplit is enabled by a call to:

agxSDK::SimulationRef simulation = new agxSDK::Simulation;
agx::MergeSplit *mergeSplit = simulation->getDynamicsSystem()->getMergeSplit();
// Enable MergeSplit functionality
mergeSplit->setEnable(true);

MergeSplit also has to be enabled for each body:

agx::RigidBodyRef body = new agx::RigidBody
// Tell this body it is allowed to be merged with other bodies
body->getMergeSplitProperties()->setEnableMerge(true);

If the scenario is that bodies are falling onto a static ground, it is more efficient to only allow the bodies to be merged with the static ground, instead of with each other. So to build a large pile of bodies on a static ground, we can do the following call for each body:

// We can also tell a body ONLY to merge with STATIC bodies
body->getMergeSplitProperties()->setMergeOnlyWithStatic(true);

Bodies can also be explicitly merged/split:

// Merge body1 into body2
bool wasMerged = mergeSplit->merge(body1, body2);

// Split body1 from its parent
bool was Split = mergeSplit->split(body1);

It is important to remember that MergeSplit is modifying relations for geometries. Whenever a body is merged into a parent, geometries are transferred to the parent. Whenever a body is split, it will get its original geometries restored. Given a geometry, it is possible to ask which its original body was (before it was merged):

// If this geometry belongs to a merged body, the original body will be returned
// Otherwise NULL.
agx::RigidBodyRef originalBody = merged_geometry->getOriginalBody();

35.1. Merging

Merging two bodies from Body1 -> Body2 means the following:

Body A has the mass properties: [ma, Ia(inertia tensor), and CmA (center of mass)] and the geometry Ga. Body B has respectively the mass properties: [mB, IB, and CmsB] and geometry GB.

After merging A into B we have: Body A with the mass properties: mA+mB, IA+IB and CmA+CmB. Body B will now be disabled which will save CPU. The geometry GA will be transferred over to body A which will now in all senses act as the union between body A and body B.

35.2. Splitting

Splitting can occur when:

  • a separation between geometries occur

  • an impact between a the geometries of merged body and another geometry occur

  • An explicit split using the MergeSplit API.

35.3. Known limitations

  • Body attributes such as damping, Properties are not merged