The BarycentricPenalityContact component handles contact interactions between different collision models in SOFA using a penalty method that computes repulsive forces based on penetration depth.
sheet
# BarycentricPenalityContact
**Overview**: The `BarycentricPenalityContact` component manages contact interactions between various collision models within the SOFA framework. It uses a penalty method to compute repulsive forces at contact points, ensuring realistic and computationally feasible responses.
**Mathematical Model**:
The BarycentricPenalityContact computes repulsive forces based on the penetration depth using the following equation:
\[ \mathbf{F}_i = -k_p d_i \mathbf{n}_i \]
where,
- \(\mathbf{F}_i\) is the repulsive force at contact point \(i\).
- \(k_p\) is a penalty stiffness coefficient.
- \(d_i\) is the penetration depth at contact point \(i\).
- \(\mathbf{n}_i\) is the unit normal vector at contact point \(i\).
**Dependencies and Connections**: This component typically requires collision models such as `CylinderCollisionModel`, `LineCollisionModel`, `PointCollisionModel`, `RigidSphereModel`, `SphereCollisionModel`, and `TriangleCollisionModel`. It fits into the scene graph by handling interactions between these models, ensuring realistic contact responses.
Component Name
BarycentricPenalityContact
Namespace
sofa::component::collision::response::contact
Description
The BarycentricPenalityContact is a contact response handler in the SOFA (Simulation Open-Framework Architecture) framework. This component manages how two collision models interact when they come into contact with each other, applying forces to prevent interpenetration or enforce collision constraints based on the barycentric coordinates of the points involved.
Purpose
It is designed to handle various types of collision geometries such as spheres, rigid spheres, points, lines, triangles and cylinders. The component uses a penalty-based approach where forces are computed based on how much two objects penetrate each other, aiming to push them apart or enforce specific constraints.
The BarycentricPenalityContact class is a template that can be instantiated with different types of collision models (TCollisionModel1 and TCollisionModel2) as well as response data types. This allows for flexibility in handling various physical scenarios.
Key Components
{'Component': 'mapper::ContactMapper', 'Description': 'This class is used to map contact points from the collision models to their corresponding mechanical states, allowing forces and constraints to be applied correctly based on the barycentric coordinates of these points.'}
{'Component': 'PenalityContactForceField', 'Description': 'A force field that applies penalty-based forces in response to collisions. This is a critical part of the BarycentricPenalityContact mechanism for enforcing physical constraints and preventing interpenetration between objects.'}
Methods
{'Method': 'cleanup()', 'Description': 'This method cleans up any resources or data associated with the contact response. It ensures that memory is released properly when the component is no longer needed.'}
{'Method': 'setDetectionOutputs(OutputVector* outputs)', 'Description': 'This method sets the detection outputs for collision detection, allowing the BarycentricPenalityContact to manage and respond to specific detected contact points between objects. It uses a map (contactIndex) to track active contacts over time.'}
{'Method': 'createResponse(core::objectmodel::BaseContext* group)', 'Description': 'This method creates or updates the response force field based on the current state of collision detection and contact management, allowing for dynamic adjustments in the physical simulation as needed.'}
{'Method': 'removeResponse()', 'Description': 'This method removes any created responses, cleaning up after a simulation or interaction has ended to ensure no lingering forces affect subsequent simulations.'}
Usage
The BarycentricPenalityContact component is typically used in physical simulations where detailed contact interactions need to be managed between different geometrical objects. By defining specific collision models and response data types, it can be tailored for a variety of simulation scenarios including rigid body dynamics, deformable object interactions, or complex multi-body systems.
Dependencies
{'Dependency': 'SOFA Framework', 'Description': "The component relies heavily on the SOFA framework's core components and libraries for collision detection and response management. It is part of a larger ecosystem designed to handle physics-based simulations efficiently."}
maths
## Mathematical and Physical Description of the BarycentricPenalityContact Component in SOFA
The **BarycentricPenalityContact** component is used to handle contact interactions between different collision models in the Simulation Open-Framework Architecture (SOFA). This component computes forces at contact points based on a penalty method, which introduces a repulsive force proportional to the penetration depth when two bodies overlap. The key aspects of this approach are summarized below.
### Contact Detection and Mapping
1. **Contact Detection**: Contacts between objects are detected by an intersection detection algorithm (`Intersection` in SOFA). This provides the contact points (or vertices) where collision occurs.
2. **Mapping**: The `BarycentricPenalityContact` component uses a barycentric mapping technique to map these contacts from the collision models to the mechanical state of the bodies involved. For instance, if one body is represented by triangle meshes and another by spheres, this mapping translates contact points on triangles into forces applied at corresponding vertices.
### Force Calculation Using Penalty Method
The penalty method calculates repulsive forces based on the penetration depth at each contact point:
\[ \mathbf{F}_i = -k_p d_i \mathbf{n}_i \]
where,
- \(\mathbf{F}_i\) is the repulsive force applied at contact point \(i\).
- \(k_p\) is a penalty stiffness coefficient, defining how strongly the system resists penetration.
- \(d_i\) is the depth of penetration at contact point \(i\), measured as the distance by which two bodies overlap along the normal direction to their surfaces.
- \(\mathbf{n}_i\) is the unit normal vector at contact point \(i\).
### Contact Index Mapping
A mapping (`ContactIndexMap`) keeps track of active contacts, ensuring that duplicate or overlapping contacts are managed effectively. This helps in maintaining consistency over time for each individual contact point.
### Implementation Details
The component is templated to allow flexibility with different collision models (e.g., spheres, lines, triangles) and data types (usually vectors). It uses the `PenalityContactForceField` class to apply forces calculated based on the penalty method. The mapping of contacts from collision models to mechanical states employs specialized contact mappers such as `BarycentricContactMapper`, which handle specific geometries like triangles.
### Integration with SOFA Framework
In the SOFA framework, this component integrates seamlessly within the broader simulation pipeline:
1. **Initialization**: It is initialized with the collision models and intersection method.
2. **Detection Outputs Handling**: When contact detection outputs are provided, it sets up forces based on these contacts (`setDetectionOutputs`).
3. **Force Field Creation**: A force field representing these repulsive forces is created within a specified context (`createResponse`).
4. **Cleanup and Removal**: Proper cleanup ensures no dangling references or memory leaks occur when the component is removed from the simulation.
### Example Scenarios
1. **Sphere-Sphere Contact**:
When two spheres overlap, each contact point on the surface of one sphere that penetrates into the other will have a repulsive force applied based on its penetration depth and the chosen penalty stiffness.
2. **Triangle-Triangle Contact**:
In the case of triangle collision models, the barycentric coordinates are used to map the forces from the contact points (which may be inside or on edges/faces) back to the vertices of the triangles.
### Summary
The BarycentricPenalityContact component provides a robust and flexible approach for handling contact interactions in SOFA simulations. It leverages the penalty method combined with efficient mapping techniques to ensure realistic and computationally feasible contact responses across various geometric models.
{
"name": "BarycentricPenalityContact",
"main": {
"name": "BarycentricPenalityContact",
"namespace": "sofa::component::collision::response::contact",
"module": "Sofa.Component.Collision.Response.Contact",
"include": "sofa/component/collision/response/contact/BarycentricPenalityContact.h",
"doc": "",
"inherits": [
"Contact"
],
"templates": [
"CylinderCollisionModel<sofa::sofa::defaulttype::Rigid3Types>, CylinderCollisionModel<sofa::sofa::defaulttype::Rigid3Types>",
"CylinderCollisionModel<sofa::sofa::defaulttype::Rigid3Types>, RigidSphereModel",
"CylinderCollisionModel<sofa::sofa::defaulttype::Rigid3Types>, SphereCollisionModel<sofa::sofa::defaulttype::Vec3Types>",
"CylinderCollisionModel<sofa::sofa::defaulttype::Rigid3Types>, TriangleCollisionModel<sofa::sofa::defaulttype::Vec3Types>",
"LineCollisionModel<sofa::sofa::defaulttype::Vec3Types>, LineCollisionModel<sofa::sofa::defaulttype::Vec3Types>",
"LineCollisionModel<sofa::sofa::defaulttype::Vec3Types>, PointCollisionModel<sofa::sofa::defaulttype::Vec3Types>",
"LineCollisionModel<sofa::sofa::defaulttype::Vec3Types>, RigidSphereModel",
"LineCollisionModel<sofa::sofa::defaulttype::Vec3Types>, SphereCollisionModel<sofa::sofa::defaulttype::Vec3Types>",
"PointCollisionModel<sofa::sofa::defaulttype::Vec3Types>, PointCollisionModel<sofa::sofa::defaulttype::Vec3Types>",
"RigidSphereModel, PointCollisionModel<sofa::sofa::defaulttype::Vec3Types>",
"RigidSphereModel, RigidSphereModel",
"SphereCollisionModel<sofa::sofa::defaulttype::Vec3Types>, PointCollisionModel<sofa::sofa::defaulttype::Vec3Types>",
"SphereCollisionModel<sofa::sofa::defaulttype::Vec3Types>, RigidSphereModel",
"SphereCollisionModel<sofa::sofa::defaulttype::Vec3Types>, SphereCollisionModel<sofa::sofa::defaulttype::Vec3Types>",
"TriangleCollisionModel<sofa::sofa::defaulttype::Vec3Types>, LineCollisionModel<sofa::sofa::defaulttype::Vec3Types>",
"TriangleCollisionModel<sofa::sofa::defaulttype::Vec3Types>, PointCollisionModel<sofa::sofa::defaulttype::Vec3Types>",
"TriangleCollisionModel<sofa::sofa::defaulttype::Vec3Types>, RigidSphereModel",
"TriangleCollisionModel<sofa::sofa::defaulttype::Vec3Types>, SphereCollisionModel<sofa::sofa::defaulttype::Vec3Types>",
"TriangleCollisionModel<sofa::sofa::defaulttype::Vec3Types>, TriangleCollisionModel<sofa::sofa::defaulttype::Vec3Types>"
],
"data_fields": [],
"links": [],
"methods": [
{
"name": "setInteractionTags",
"return_type": "void",
"params": [
{
"name": "mstate1",
"type": "MechanicalState1 *"
},
{
"name": "mstate2",
"type": "MechanicalState2 *"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "protected"
},
{
"name": "cleanup",
"return_type": "void",
"params": [],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getCollisionModels",
"return_type": "std::pair<core::CollisionModel *, core::CollisionModel *>",
"params": [],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "setDetectionOutputs",
"return_type": "void",
"params": [
{
"name": "outputs",
"type": "OutputVector *"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "createResponse",
"return_type": "void",
"params": [
{
"name": "group",
"type": "core::objectmodel::BaseContext *"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "removeResponse",
"return_type": "void",
"params": [],
"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"
}
]
},
"desc": {
"Component Name": "BarycentricPenalityContact",
"Namespace": "sofa::component::collision::response::contact",
"Description": "The BarycentricPenalityContact is a contact response handler in the SOFA (Simulation Open-Framework Architecture) framework. This component manages how two collision models interact when they come into contact with each other, applying forces to prevent interpenetration or enforce collision constraints based on the barycentric coordinates of the points involved.",
"Purpose": [
"It is designed to handle various types of collision geometries such as spheres, rigid spheres, points, lines, triangles and cylinders. The component uses a penalty-based approach where forces are computed based on how much two objects penetrate each other, aiming to push them apart or enforce specific constraints.",
"The BarycentricPenalityContact class is a template that can be instantiated with different types of collision models (TCollisionModel1 and TCollisionModel2) as well as response data types. This allows for flexibility in handling various physical scenarios."
],
"Key Components": [
{
"Component": "mapper::ContactMapper",
"Description": "This class is used to map contact points from the collision models to their corresponding mechanical states, allowing forces and constraints to be applied correctly based on the barycentric coordinates of these points."
},
{
"Component": "PenalityContactForceField",
"Description": "A force field that applies penalty-based forces in response to collisions. This is a critical part of the BarycentricPenalityContact mechanism for enforcing physical constraints and preventing interpenetration between objects."
}
],
"Methods": [
{
"Method": "cleanup()",
"Description": "This method cleans up any resources or data associated with the contact response. It ensures that memory is released properly when the component is no longer needed."
},
{
"Method": "setDetectionOutputs(OutputVector* outputs)",
"Description": "This method sets the detection outputs for collision detection, allowing the BarycentricPenalityContact to manage and respond to specific detected contact points between objects. It uses a map (contactIndex) to track active contacts over time."
},
{
"Method": "createResponse(core::objectmodel::BaseContext* group)",
"Description": "This method creates or updates the response force field based on the current state of collision detection and contact management, allowing for dynamic adjustments in the physical simulation as needed."
},
{
"Method": "removeResponse()",
"Description": "This method removes any created responses, cleaning up after a simulation or interaction has ended to ensure no lingering forces affect subsequent simulations."
}
],
"Usage": [
"The BarycentricPenalityContact component is typically used in physical simulations where detailed contact interactions need to be managed between different geometrical objects. By defining specific collision models and response data types, it can be tailored for a variety of simulation scenarios including rigid body dynamics, deformable object interactions, or complex multi-body systems."
],
"Dependencies": [
{
"Dependency": "SOFA Framework",
"Description": "The component relies heavily on the SOFA framework's core components and libraries for collision detection and response management. It is part of a larger ecosystem designed to handle physics-based simulations efficiently."
}
]
},
"maths": {
"maths": "## Mathematical and Physical Description of the BarycentricPenalityContact Component in SOFA\n\nThe **BarycentricPenalityContact** component is used to handle contact interactions between different collision models in the Simulation Open-Framework Architecture (SOFA). This component computes forces at contact points based on a penalty method, which introduces a repulsive force proportional to the penetration depth when two bodies overlap. The key aspects of this approach are summarized below.\n\n### Contact Detection and Mapping\n\n1. **Contact Detection**: Contacts between objects are detected by an intersection detection algorithm (`Intersection` in SOFA). This provides the contact points (or vertices) where collision occurs. \n2. **Mapping**: The `BarycentricPenalityContact` component uses a barycentric mapping technique to map these contacts from the collision models to the mechanical state of the bodies involved. For instance, if one body is represented by triangle meshes and another by spheres, this mapping translates contact points on triangles into forces applied at corresponding vertices.\n\n### Force Calculation Using Penalty Method\n\nThe penalty method calculates repulsive forces based on the penetration depth at each contact point:\n\\[ \\mathbf{F}_i = -k_p d_i \\mathbf{n}_i \\]\nwhere,\n- \\(\\mathbf{F}_i\\) is the repulsive force applied at contact point \\(i\\).\n- \\(k_p\\) is a penalty stiffness coefficient, defining how strongly the system resists penetration.\n- \\(d_i\\) is the depth of penetration at contact point \\(i\\), measured as the distance by which two bodies overlap along the normal direction to their surfaces.\n- \\(\\mathbf{n}_i\\) is the unit normal vector at contact point \\(i\\).\n\n### Contact Index Mapping\n\nA mapping (`ContactIndexMap`) keeps track of active contacts, ensuring that duplicate or overlapping contacts are managed effectively. This helps in maintaining consistency over time for each individual contact point.\n\n### Implementation Details\n\nThe component is templated to allow flexibility with different collision models (e.g., spheres, lines, triangles) and data types (usually vectors). It uses the `PenalityContactForceField` class to apply forces calculated based on the penalty method. The mapping of contacts from collision models to mechanical states employs specialized contact mappers such as `BarycentricContactMapper`, which handle specific geometries like triangles.\n\n### Integration with SOFA Framework\n\nIn the SOFA framework, this component integrates seamlessly within the broader simulation pipeline:\n1. **Initialization**: It is initialized with the collision models and intersection method.\n2. **Detection Outputs Handling**: When contact detection outputs are provided, it sets up forces based on these contacts (`setDetectionOutputs`).\n3. **Force Field Creation**: A force field representing these repulsive forces is created within a specified context (`createResponse`).\n4. **Cleanup and Removal**: Proper cleanup ensures no dangling references or memory leaks occur when the component is removed from the simulation.\n\n### Example Scenarios\n\n1. **Sphere-Sphere Contact**:\n When two spheres overlap, each contact point on the surface of one sphere that penetrates into the other will have a repulsive force applied based on its penetration depth and the chosen penalty stiffness.\n2. **Triangle-Triangle Contact**:\n In the case of triangle collision models, the barycentric coordinates are used to map the forces from the contact points (which may be inside or on edges/faces) back to the vertices of the triangles.\n\n### Summary\nThe BarycentricPenalityContact component provides a robust and flexible approach for handling contact interactions in SOFA simulations. It leverages the penalty method combined with efficient mapping techniques to ensure realistic and computationally feasible contact responses across various geometric models."
},
"summary": {
"abstract": "The BarycentricPenalityContact component handles contact interactions between different collision models in SOFA using a penalty method that computes repulsive forces based on penetration depth.",
"sheet": "# BarycentricPenalityContact\n\n**Overview**: The `BarycentricPenalityContact` component manages contact interactions between various collision models within the SOFA framework. It uses a penalty method to compute repulsive forces at contact points, ensuring realistic and computationally feasible responses.\n\n**Mathematical Model**: \nThe BarycentricPenalityContact computes repulsive forces based on the penetration depth using the following equation:\n\\[ \\mathbf{F}_i = -k_p d_i \\mathbf{n}_i \\]\nwhere,\n- \\(\\mathbf{F}_i\\) is the repulsive force at contact point \\(i\\).\n- \\(k_p\\) is a penalty stiffness coefficient.\n- \\(d_i\\) is the penetration depth at contact point \\(i\\).\n- \\(\\mathbf{n}_i\\) is the unit normal vector at contact point \\(i\\).\n\n**Dependencies and Connections**: This component typically requires collision models such as `CylinderCollisionModel`, `LineCollisionModel`, `PointCollisionModel`, `RigidSphereModel`, `SphereCollisionModel`, and `TriangleCollisionModel`. It fits into the scene graph by handling interactions between these models, ensuring realistic contact responses."
}
}