CollisionModel
The CollisionModel is an abstract base class in SOFA (Simulation Open Framework Architecture) used to represent collision geometry for physics simulations. It serves as the foundation for various types of collision models such as TriangleSetTopologyContainer, LineSetTopologyContainer etc.
- abstract
- The CollisionModel abstract class in SOFA manages collision geometry for physics simulations, handling proximity detection, contact response parameters, and hierarchical bounding volume structures.
- sheet
- # CollisionModel ## Overview The CollisionModel is an abstract base class that represents collision geometry within the SOFA simulation framework. It handles various aspects of collision detection and response, including proximity thresholds, contact stiffness, friction, and restitution coefficients. The component supports a hierarchy of models through pointers to previous (coarser) and next (finer) levels in bounding volume hierarchies. ## Parameters and Data The CollisionModel exposes several significant data fields that control its behavior: - `bActive`: A boolean flag indicating if this collision model is active and should be included in default collision detections. - `bMoving`: A boolean flag indicating if the object's position changes between iterations. - `bSimulated`: A boolean flag indicating if the object is controlled by a simulation. - `bSelfCollision`: A boolean flag indicating if the object can self-collide. - `proximity`: The proximity threshold for collision detection. - `d_contactDistance`: Additional distance along the normal of the collision element to apply 'skinning' effect for collision. - `contactStiffness`: Contact stiffness coefficient (\(k\)). - `contactFriction`: Contact friction coefficient (dry or viscous). - `contactRestitution`: Coefficient of restitution for contact response. - `color`: RGBA color used to display the collision model if requested. ## Dependencies and Connections The CollisionModel typically requires connections with other SOFA components such as: - **Previous**: A pointer to the previous (coarser / upper / parent level) CollisionModel in the hierarchy. - **Next**: A pointer to the next (finer / lower / child level) CollisionModel in the hierarchy. - **CollisionElementActiver**: A component that activates or deactivates collision elements during execution. ## Practical Notes - Ensure proper setting of `bActive`, `bMoving`, and `bSimulated` flags to control simulation behavior accurately. - Adjust proximity thresholds (`proximity`) and contact response parameters (stiffness, friction, restitution) based on the physical properties of the objects being simulated. - For efficient collision detection, manage the hierarchy levels appropriately using `previous` and `next` pointers.
- name
- CollisionModel
- description
- The CollisionModel is an abstract base class in SOFA (Simulation Open Framework Architecture) used to represent collision geometry for physics simulations. It serves as the foundation for various types of collision models such as TriangleSetTopologyContainer, LineSetTopologyContainer etc.
- attributes
-
- {'name': 'bActive', 'description': 'A boolean flag indicating whether this collision model is active and should be included in default collision detections.'}
- {'name': 'bMoving', 'description': 'A boolean flag indicating if the object represented by this collision model is changing position between iterations, which may affect how collisions are detected or handled.'}
- {'name': 'bSimulated', 'description': "A boolean flag indicating whether the object controlled by this collision model is simulated. If false, it implies that the object's motion might be driven by other means than physics simulation (e.g., animation)."}
- {'name': 'bSelfCollision', 'description': 'A boolean flag indicating if the object can collide with itself or not.'}
- {'name': 'd_contactDistance', 'description': 'The distance to the actual (visual) surface, used for collision detection purposes. This can be thought of as a padding around the collision geometry.'}
- {'name': 'contactStiffness', 'description': 'A default contact stiffness value that defines how stiff the response should be when collisions occur between objects.'}
- {'name': 'contactFriction', 'description': 'The friction (damping) coefficient for contacts. This affects how much tangential force is applied to prevent sliding along collision surfaces.'}
- {'name': 'contactRestitution', 'description': 'The coefficient of restitution that defines the elasticity of collisions. A value of 0 indicates perfectly inelastic collisions, while a value close to 1 represents highly elastic collisions.'}
- {'name': 'contactResponse', 'description': 'Indicates which contact response algorithm should be used for this collision model. This is indicative and might not always be honored if the colliding models specify different algorithms.'}
- {'name': 'color', 'description': 'A color value that can be used to visually represent the collision geometry during simulations or debugging sessions.'}
- {'name': 'group', 'description': 'A set of group IDs. No collisions will occur between models included in a common group (i.e., sharing a common ID).'}
- {'name': 'size', 'description': 'The number of collision elements in this model, such as triangles or lines.'}
- {'name': 'd_numberOfContacts', 'description': 'A data field representing the number of contacts attached to the collision model.'}
- {'name': 'previous', 'description': 'A link to the previous (coarser / upper / parent level) CollisionModel in a hierarchy, if any.'}
- {'name': 'next', 'description': 'A link to the next (finer / lower / child level) CollisionModel in a hierarchy, if any.'}
- {'name': 'enum_type', 'description': 'An integer value corresponding to the type of collision model. Useful for optimizations involving static_casts or identifying specific types of collision models at runtime.'}
- methods
-
- {'name': 'canCollideWith', 'parameters': ['CollisionModel* model'], 'returns': 'bool', 'description': 'Tests whether this CollisionModel can collide with another provided CollisionModel. This is based on the self-collision flag and group IDs, among other factors.'}
- {'name': 'createPrevious', 'parameters': [''], 'returns': 'DerivedModel*', 'description': 'A template method used to create or get a previous model in the hierarchy of collision models.'}
- maths
- The CollisionModel class in SOFA is an abstract base class designed to represent collision geometry for objects within the simulation environment. This class serves as a blueprint for more specific collision models, such as TriangleSetTopologyContainer and LineSetTopologyContainer, each tailored to particular types of geometric primitives (e.g., triangles or lines). The primary role of CollisionModel is to manage collision detection between different entities in a physics-based simulation. 1. **Collision Detection**: - **Proximity Handling**: The class provides attributes such as `d_contactDistance` and `proximity`, which define the distance threshold for collision detection. This is mathematically represented as a function that measures the minimum distance between geometric primitives (e.g., vertices, edges) of different models. - **Contact Response Parameters**: Additional parameters include `contactStiffness`, `contactFriction`, and `contactRestitution`. These are mathematical coefficients used in force calculations when collisions occur. The contact stiffness (\(k ext{ or } \eta ext{-stiffness} ext{)}) models the elastic response, while friction and restitution control the dissipation of energy during collisions. 2. **Hierarchy Management**: - `previous` and `next`: These links manage a hierarchy of CollisionModels, enabling multi-level collision detection structures. For example, in hierarchical BVH (Bounding Volume Hierarchy) trees, these pointers link to coarser or finer levels of the tree, allowing efficient traversal for proximity checks. 3. **Topology Association**: - `getCollisionTopology()`: This method links CollisionModel with a topology object (`BaseMeshTopology`). The association is crucial as it maps collision geometry to mesh structures, enabling detailed spatial queries (e.g., vertex-to-face tests). 4. **Visualization and Debugging**: - Color and Drawing: The `draw` methods allow for visualization of the collision model, which can be useful for debugging or visualizing the simulation setup. 5. **Self-Collision Handling**: - Attributes like `bSelfCollision` control whether a given object should perform self-collisions (i.e., parts of an object colliding with itself). This is crucial in simulations involving deformable objects, where internal collisions are necessary to maintain structural integrity. 6. **Group Management and Collision Pruning**: - `group`: The set of group IDs associated with the collision model can be used for collision pruning by avoiding unnecessary pairwise tests between models within the same group. 7. **User Data Handling**: - `SetUserData` and `GetUserData`: These methods allow users to attach custom data to a CollisionModel, enabling additional flexibility in application-specific scenarios. 8. **Contact Response Configuration**: - The `contactResponse` attribute allows the user to specify which contact response algorithm should be used for this model, providing control over how collisions are resolved physically.
{
"name": "CollisionModel",
"main": {
"name": "CollisionModel",
"namespace": "sofa::core",
"module": "Sofa.framework.Core",
"include": "sofa/core/CollisionModel.h",
"doc": "Abstract CollisionModel interface.\n A CollisionModel contains a list of same-type elements. It can be part of a\n list of CollisionModels, each describing a level in a bounding-volume\n hierarchy.\n Each CollisionModel stores a pointer to the next model in the hierarchy\n (i.e. finer / lower / child level) as well as the previous model (i.e.\n coarser / upper / parent level). The first CollisionModel in this list is\n the root of the hierarchy and contains only one element. The last\n CollisionModel contains the leaves of the hierarchy which are the real\n elements of the object.\n Each element inside CollisionModels except for the last one can have a list\n of children. There are 2 types of child elements:\n \\li internal children: child elements of the same type as their parent (often\n corresponding to non-final elements)\n \\li external children: child elements of a different type (often corresponding\n to the final elements)",
"inherits": [
"BaseObject"
],
"templates": [],
"data_fields": [
{
"name": "bActive",
"type": "bool",
"xmlname": "active",
"help": "flag indicating if this collision model is active and should be included in default collision detections"
},
{
"name": "bMoving",
"type": "bool",
"xmlname": "moving",
"help": "flag indicating if this object is changing position between iterations"
},
{
"name": "bSimulated",
"type": "bool",
"xmlname": "simulated",
"help": "flag indicating if this object is controlled by a simulation"
},
{
"name": "bSelfCollision",
"type": "bool",
"xmlname": "selfCollision",
"help": "flag indication if the object can self collide"
},
{
"name": "proximity",
"type": "SReal"
},
{
"name": "d_contactDistance",
"type": "SReal",
"xmlname": "contactDistance",
"help": "This distance is added along the normal of the collision element to apply 'skinning' effect for collision. The contact arise at this distance of the element."
},
{
"name": "contactStiffness",
"type": "SReal",
"xmlname": "contactStiffness",
"help": "Contact stiffness"
},
{
"name": "contactFriction",
"type": "SReal",
"xmlname": "contactFriction",
"help": "Contact friction coefficient (dry or viscous or unused depending on the contact method)"
},
{
"name": "contactRestitution",
"type": "SReal",
"xmlname": "contactRestitution",
"help": "Contact coefficient of restitution"
},
{
"name": "color",
"type": "sofa::type::RGBAColor",
"xmlname": "color",
"help": "color used to display the collision model if requested"
}
],
"links": [
{
"name": "previous",
"target": "CollisionModel",
"kind": "single",
"xmlname": "previous",
"help": "Previous (coarser / upper / parent level) CollisionModel in the hierarchy."
},
{
"name": "next",
"target": "CollisionModel",
"kind": "single",
"xmlname": "next",
"help": "Next (finer / lower / child level) CollisionModel in the hierarchy."
},
{
"name": "l_collElemActiver",
"target": "BaseObject",
"kind": "single",
"xmlname": "collisionElementActiver",
"help": "CollisionElementActiver component that activates or deactivates collision element(s) during execution"
}
],
"methods": [
{
"name": "toCollisionModel",
"return_type": "const CollisionModel *",
"params": [],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "bwdInit",
"return_type": "void",
"params": [],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "empty",
"return_type": "bool",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getSize",
"return_type": "int",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getSelfCollision",
"return_type": "bool",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "setSelfCollision",
"return_type": "void",
"params": [
{
"name": "_bSelfCollision",
"type": "bool"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getNumberOfContacts",
"return_type": "int",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "setNumberOfContacts",
"return_type": "void",
"params": [
{
"name": "i",
"type": "int"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "resize",
"return_type": "void",
"params": [
{
"name": "s",
"type": "int"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "begin",
"return_type": "Iterator",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "end",
"return_type": "Iterator",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getNext",
"return_type": "CollisionModel *",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getPrevious",
"return_type": "CollisionModel *",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "setPrevious",
"return_type": "void",
"params": [
{
"name": "val",
"type": "int"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "isActive",
"return_type": "bool",
"params": [],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "setActive",
"return_type": "void",
"params": [
{
"name": "val",
"type": "bool"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "isMoving",
"return_type": "bool",
"params": [],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "setMoving",
"return_type": "void",
"params": [
{
"name": "val",
"type": "bool"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "isSimulated",
"return_type": "bool",
"params": [],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "setSimulated",
"return_type": "void",
"params": [
{
"name": "val",
"type": "bool"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "computeBoundingTree",
"return_type": "void",
"params": [
{
"name": "maxDepth",
"type": "int"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "computeContinuousBoundingTree",
"return_type": "void",
"params": [
{
"name": "",
"type": "SReal"
},
{
"name": "continuousIntersectionFlag",
"type": "ContinuousIntersectionTypeFlag"
},
{
"name": "maxDepth",
"type": "int"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getInternalChildren",
"return_type": "std::pair<CollisionElementIterator, CollisionElementIterator>",
"params": [
{
"name": "",
"type": "int"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getExternalChildren",
"return_type": "std::pair<CollisionElementIterator, CollisionElementIterator>",
"params": [
{
"name": "",
"type": "int"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "isLeaf",
"return_type": "bool",
"params": [
{
"name": "",
"type": "int"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "canCollideWith",
"return_type": "bool",
"params": [
{
"name": "model",
"type": "CollisionModel *"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "canCollideWithElement",
"return_type": "bool",
"params": [
{
"name": "",
"type": "int"
},
{
"name": "",
"type": "CollisionModel *"
},
{
"name": "",
"type": "int"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "draw",
"return_type": "void",
"params": [
{
"name": "",
"type": "const core::visual::VisualParams *"
},
{
"name": "",
"type": "int"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "draw",
"return_type": "void",
"params": [
{
"name": "vparams",
"type": "const core::visual::VisualParams *"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getFirst",
"return_type": "CollisionModel *",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getLast",
"return_type": "CollisionModel *",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "createPrevious",
"return_type": "DerivedModel *",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getProximity",
"return_type": "SReal",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getContactDistance",
"return_type": "SReal",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getContactStiffness",
"return_type": "SReal",
"params": [
{
"name": "",
"type": "int"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "setContactStiffness",
"return_type": "void",
"params": [
{
"name": "stiffness",
"type": "SReal"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "isContactStiffnessSet",
"return_type": "bool",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getContactFriction",
"return_type": "SReal",
"params": [
{
"name": "",
"type": "int"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "setContactFriction",
"return_type": "void",
"params": [
{
"name": "friction",
"type": "SReal"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getContactRestitution",
"return_type": "SReal",
"params": [
{
"name": "",
"type": "int"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "setContactRestitution",
"return_type": "void",
"params": [
{
"name": "restitution",
"type": "SReal"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getContactResponse",
"return_type": "int",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getGroups",
"return_type": "const int &",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "addGroup",
"return_type": "void",
"params": [
{
"name": "groupId",
"type": "const int"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "setGroups",
"return_type": "void",
"params": [
{
"name": "ids",
"type": "const int &"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getCollisionTopology",
"return_type": "sofa::core::topology::BaseMeshTopology *",
"params": [],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getColor4f",
"return_type": "const float *",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "setColor4f",
"return_type": "void",
"params": [
{
"name": "c",
"type": "const float *"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "setContactDistance",
"return_type": "void",
"params": [
{
"name": "a",
"type": "const SReal"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "setProximity",
"return_type": "void",
"params": [
{
"name": "a",
"type": "const SReal"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "setContactResponse",
"return_type": "void",
"params": [
{
"name": "a",
"type": "const int &"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getEnumType",
"return_type": "int",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "SetUserData",
"return_type": "void",
"params": [
{
"name": "pUserData",
"type": "void *"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "GetUserData",
"return_type": "void *",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "drawCollisionModel",
"return_type": "void",
"params": [
{
"name": "vparams",
"type": "const core::visual::VisualParams *"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "protected"
},
{
"name": "insertInNode",
"return_type": "bool",
"params": [
{
"name": "node",
"type": "objectmodel::BaseNode *"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "removeInNode",
"return_type": "bool",
"params": [
{
"name": "node",
"type": "objectmodel::BaseNode *"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
}
]
},
"desc": {
"name": "CollisionModel",
"description": "The CollisionModel is an abstract base class in SOFA (Simulation Open Framework Architecture) used to represent collision geometry for physics simulations. It serves as the foundation for various types of collision models such as TriangleSetTopologyContainer, LineSetTopologyContainer etc.",
"attributes": [
{
"name": "bActive",
"description": "A boolean flag indicating whether this collision model is active and should be included in default collision detections."
},
{
"name": "bMoving",
"description": "A boolean flag indicating if the object represented by this collision model is changing position between iterations, which may affect how collisions are detected or handled."
},
{
"name": "bSimulated",
"description": "A boolean flag indicating whether the object controlled by this collision model is simulated. If false, it implies that the object's motion might be driven by other means than physics simulation (e.g., animation)."
},
{
"name": "bSelfCollision",
"description": "A boolean flag indicating if the object can collide with itself or not."
},
{
"name": "d_contactDistance",
"description": "The distance to the actual (visual) surface, used for collision detection purposes. This can be thought of as a padding around the collision geometry."
},
{
"name": "contactStiffness",
"description": "A default contact stiffness value that defines how stiff the response should be when collisions occur between objects."
},
{
"name": "contactFriction",
"description": "The friction (damping) coefficient for contacts. This affects how much tangential force is applied to prevent sliding along collision surfaces."
},
{
"name": "contactRestitution",
"description": "The coefficient of restitution that defines the elasticity of collisions. A value of 0 indicates perfectly inelastic collisions, while a value close to 1 represents highly elastic collisions."
},
{
"name": "contactResponse",
"description": "Indicates which contact response algorithm should be used for this collision model. This is indicative and might not always be honored if the colliding models specify different algorithms."
},
{
"name": "color",
"description": "A color value that can be used to visually represent the collision geometry during simulations or debugging sessions."
},
{
"name": "group",
"description": "A set of group IDs. No collisions will occur between models included in a common group (i.e., sharing a common ID)."
},
{
"name": "size",
"description": "The number of collision elements in this model, such as triangles or lines."
},
{
"name": "d_numberOfContacts",
"description": "A data field representing the number of contacts attached to the collision model."
},
{
"name": "previous",
"description": "A link to the previous (coarser / upper / parent level) CollisionModel in a hierarchy, if any."
},
{
"name": "next",
"description": "A link to the next (finer / lower / child level) CollisionModel in a hierarchy, if any."
},
{
"name": "enum_type",
"description": "An integer value corresponding to the type of collision model. Useful for optimizations involving static_casts or identifying specific types of collision models at runtime."
}
],
"methods": [
{
"name": "canCollideWith",
"parameters": [
"CollisionModel* model"
],
"returns": "bool",
"description": "Tests whether this CollisionModel can collide with another provided CollisionModel. This is based on the self-collision flag and group IDs, among other factors."
},
{
"name": "createPrevious",
"parameters": [
""
],
"returns": "DerivedModel*",
"description": "A template method used to create or get a previous model in the hierarchy of collision models."
}
]
},
"maths": {
"maths": "The CollisionModel class in SOFA is an abstract base class designed to represent collision geometry for objects within the simulation environment. This class serves as a blueprint for more specific collision models, such as TriangleSetTopologyContainer and LineSetTopologyContainer, each tailored to particular types of geometric primitives (e.g., triangles or lines). The primary role of CollisionModel is to manage collision detection between different entities in a physics-based simulation.\n\n1. **Collision Detection**:\n - **Proximity Handling**: The class provides attributes such as `d_contactDistance` and `proximity`, which define the distance threshold for collision detection. This is mathematically represented as a function that measures the minimum distance between geometric primitives (e.g., vertices, edges) of different models.\n - **Contact Response Parameters**: Additional parameters include `contactStiffness`, `contactFriction`, and `contactRestitution`. These are mathematical coefficients used in force calculations when collisions occur. The contact stiffness (\\(k\text{ or } \\eta\text{-stiffness}\text{)}) models the elastic response, while friction and restitution control the dissipation of energy during collisions.\n\n2. **Hierarchy Management**:\n - `previous` and `next`: These links manage a hierarchy of CollisionModels, enabling multi-level collision detection structures. For example, in hierarchical BVH (Bounding Volume Hierarchy) trees, these pointers link to coarser or finer levels of the tree, allowing efficient traversal for proximity checks.\n\n3. **Topology Association**:\n - `getCollisionTopology()`: This method links CollisionModel with a topology object (`BaseMeshTopology`). The association is crucial as it maps collision geometry to mesh structures, enabling detailed spatial queries (e.g., vertex-to-face tests).\n\n4. **Visualization and Debugging**:\n - Color and Drawing: The `draw` methods allow for visualization of the collision model, which can be useful for debugging or visualizing the simulation setup.\n\n5. **Self-Collision Handling**:\n - Attributes like `bSelfCollision` control whether a given object should perform self-collisions (i.e., parts of an object colliding with itself). This is crucial in simulations involving deformable objects, where internal collisions are necessary to maintain structural integrity.\n\n6. **Group Management and Collision Pruning**:\n - `group`: The set of group IDs associated with the collision model can be used for collision pruning by avoiding unnecessary pairwise tests between models within the same group.\n\n7. **User Data Handling**:\n - `SetUserData` and `GetUserData`: These methods allow users to attach custom data to a CollisionModel, enabling additional flexibility in application-specific scenarios.\n\n8. **Contact Response Configuration**:\n - The `contactResponse` attribute allows the user to specify which contact response algorithm should be used for this model, providing control over how collisions are resolved physically."
},
"summary": {
"abstract": "The CollisionModel abstract class in SOFA manages collision geometry for physics simulations, handling proximity detection, contact response parameters, and hierarchical bounding volume structures.",
"sheet": "# CollisionModel\n\n## Overview\nThe CollisionModel is an abstract base class that represents collision geometry within the SOFA simulation framework. It handles various aspects of collision detection and response, including proximity thresholds, contact stiffness, friction, and restitution coefficients. The component supports a hierarchy of models through pointers to previous (coarser) and next (finer) levels in bounding volume hierarchies.\n\n## Parameters and Data\nThe CollisionModel exposes several significant data fields that control its behavior:\n- `bActive`: A boolean flag indicating if this collision model is active and should be included in default collision detections.\n- `bMoving`: A boolean flag indicating if the object's position changes between iterations.\n- `bSimulated`: A boolean flag indicating if the object is controlled by a simulation.\n- `bSelfCollision`: A boolean flag indicating if the object can self-collide.\n- `proximity`: The proximity threshold for collision detection.\n- `d_contactDistance`: Additional distance along the normal of the collision element to apply 'skinning' effect for collision.\n- `contactStiffness`: Contact stiffness coefficient (\\(k\\)).\n- `contactFriction`: Contact friction coefficient (dry or viscous).\n- `contactRestitution`: Coefficient of restitution for contact response.\n- `color`: RGBA color used to display the collision model if requested.\n\n## Dependencies and Connections\nThe CollisionModel typically requires connections with other SOFA components such as:\n- **Previous**: A pointer to the previous (coarser / upper / parent level) CollisionModel in the hierarchy.\n- **Next**: A pointer to the next (finer / lower / child level) CollisionModel in the hierarchy.\n- **CollisionElementActiver**: A component that activates or deactivates collision elements during execution.\n\n## Practical Notes\n- Ensure proper setting of `bActive`, `bMoving`, and `bSimulated` flags to control simulation behavior accurately.\n- Adjust proximity thresholds (`proximity`) and contact response parameters (stiffness, friction, restitution) based on the physical properties of the objects being simulated.\n- For efficient collision detection, manage the hierarchy levels appropriately using `previous` and `next` pointers."
}
}