{
  "name": "BarycentricStickContact",
  "main": {
    "name": "BarycentricStickContact",
    "namespace": "sofa::component::collision::response::contact",
    "module": "Sofa.Component.Collision.Response.Contact",
    "include": "sofa/component/collision/response/contact/BarycentricStickContact.h",
    "doc": "",
    "inherits": [
      "Contact"
    ],
    "templates": [
      "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>, SphereCollisionModel<sofa::sofa::defaulttype::Vec3Types>",
      "PointCollisionModel<sofa::sofa::defaulttype::Vec3Types>, PointCollisionModel<sofa::sofa::defaulttype::Vec3Types>",
      "SphereCollisionModel<sofa::sofa::defaulttype::Vec3Types>, PointCollisionModel<sofa::sofa::defaulttype::Vec3Types>",
      "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>, SphereCollisionModel<sofa::sofa::defaulttype::Vec3Types>",
      "TriangleCollisionModel<sofa::sofa::defaulttype::Vec3Types>, TriangleCollisionModel<sofa::sofa::defaulttype::Vec3Types>"
    ],
    "data_fields": [
      {
        "name": "d_keepAlive",
        "type": "bool",
        "xmlname": "keepAlive",
        "help": "set to true to keep this contact alive even after collisions are no longer detected"
      }
    ],
    "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": "keepAlive",
        "return_type": "bool",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setKeepAlive",
        "return_type": "void",
        "params": [
          {
            "name": "val",
            "type": "bool"
          }
        ],
        "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": {
    "name": "BarycentricStickContact",
    "description": "The BarycentricStickContact class is a contact handler in the SOFA (Simulation Open-Framework Architecture) framework designed to manage and apply forces between colliding objects using stick-like spring elements.",
    "parameters": [
      {
        "name": "CollisionModel1",
        "type": "template parameter",
        "description": "The type of the first collision model involved in the contact handling."
      },
      {
        "name": "CollisionModel2",
        "type": "template parameter",
        "description": "The type of the second collision model involved in the contact handling."
      },
      {
        "name": "ResponseDataTypes",
        "type": "template parameter",
        "default": "sofa::defaulttype::Vec3Types",
        "description": "Specifies the data types used for response calculations, defaulting to Vec3 (vector of 3 dimensions)."
      }
    ],
    "methods": [
      {
        "name": "BarycentricStickContact",
        "parameters": [
          "CollisionModel1* model1",
          "CollisionModel2* model2",
          "Intersection* intersectionMethod"
        ],
        "description": "Constructor which initializes the BarycentricStickContact object with two collision models and an intersection method."
      },
      {
        "name": "~BarycentricStickContact",
        "parameters": [],
        "description": "Destructor for cleaning up resources used by the contact handler."
      },
      {
        "name": "setDetectionOutputs",
        "parameters": [
          "OutputVector* outputs"
        ],
        "description": "Method to set detection outputs from collision detection, updating the internal state of stick contacts."
      },
      {
        "name": "createResponse",
        "parameters": [
          "core::objectmodel::BaseContext* group"
        ],
        "description": "Creates response (spring-like forces) within a specified base context group."
      },
      {
        "name": "removeResponse",
        "parameters": [],
        "description": "Removes the contact responses previously set by createResponse method."
      },
      {
        "name": "keepAlive",
        "parameters": [],
        "returns": "bool",
        "description": "Returns whether this contact handler should be kept alive even if there's no ongoing collision between objects."
      },
      {
        "name": "setKeepAlive",
        "parameters": [
          "bool val"
        ],
        "description": "Sets the keep-alive flag for the contact handler, enabling or disabling its persistence outside of active collisions."
      }
    ],
    "attributes": [
      {
        "name": "d_keepAlive",
        "type": "Data<bool>",
        "default": "false",
        "description": "A data attribute to control whether this contact handler should remain active even when no collision is detected between objects. If set to true, the contact force field will be kept alive."
      }
    ],
    "dependencies": [
      {
        "name": "CollisionModel1",
        "type": "class",
        "description": "The first collision model type used for defining geometry and behavior in collisions."
      },
      {
        "name": "CollisionModel2",
        "type": "class",
        "description": "The second collision model type used for defining geometry and behavior in collisions."
      }
    ],
    "example_usage": "This component can be instantiated with various types of collision models (e.g., Sphere, Point, Line, Triangle) to apply spring-like forces between intersecting elements. The setDetectionOutputs method is used after a detection phase to define the contact points, while createResponse and removeResponse methods control the lifecycle of these contacts in the simulation framework."
  },
  "maths": {
    "maths": "The BarycentricStickContact class in the SOFA framework is designed to handle contact between two colliding objects by simulating the interaction through a system of barycentric stick-like spring elements. These springs are used to maintain or enforce certain physical properties, such as distance and orientation, between points on the surfaces of the colliding bodies. The mathematical formulation behind this class involves several key concepts from physics and computational mechanics.\n\n### 1. Contact Detection:\nThe process begins with identifying contact points between two objects through collision detection methods. In SOFA, this is facilitated by the `Intersection` method, which identifies intersections or proximities between the geometric representations of the colliding bodies (e.g., spheres, triangles).\n\n### 2. Barycentric Coordinates and Contact Mappings:\nThe `mapper::ContactMapper` class maps contact points to barycentric coordinates within elements such as lines, triangles, or spheres. This mapping allows for more precise localization and force distribution within the colliding objects.\n\n- **Barycentric Coordinates:** For a triangle (a common element in mesh-based representations), if P is a point inside a triangle defined by vertices A, B, and C, then P can be represented as a linear combination of these vertices using barycentric coordinates:\n  \\[P = uA + vB + wC\\]\n  where \\(u + v + w = 1\\) and \\(0 \\\\leq u,v,w \\\\leq 1\\).\n\n### 3. Spring Force Field Application:\nThe `sofa::component::solidmechanics::spring::VectorSpringForceField` class is used to apply forces between the contact points using spring-like elements. The force generated by these springs depends on their stiffness and damping parameters, as well as the distance between the contact points.\n\n- **Hooke's Law:** For a linear elastic spring, the restoring force \\(\\mathbf{F}\\) is given by Hooke’s law:\n  \\[\\mathbf{F} = -k (l - l_0) \\hat{n}\\]\n  where \\(k\\) is the spring stiffness, \\(l\\) is the current length of the spring, and \\(l_0\\) is its rest length. The term \\(\\hat{n}\\) represents a unit vector in the direction along which the force acts.\n\n### 4. Force Distribution:\nThe forces applied by these springs are distributed back to the objects via the `ContactMapper`, ensuring that the overall motion of both objects is consistent with physical principles such as conservation of momentum and energy.\n\n- **Damping:** Damping can also be introduced into the system, which reduces oscillations and brings the system towards equilibrium more quickly. The damping force \\(\\mathbf{F_d}\\) might be modeled as proportional to the relative velocity between contact points:\n  \\[\\mathbf{F_d} = -c (v_1 - v_2)\\]\n  where \\(c\\) is the damping coefficient, and \\(v_1\\), \\(v_2\\) are the velocities of the two objects at the contact point.\n\n### 5. Time Evolution:\nThe entire system evolves over time through integration methods (e.g., Euler's method or Runge-Kutta methods). Forces generated by these springs contribute to the accelerations and subsequent positions and velocities of the colliding bodies, ensuring that they respond realistically to collisions.\n\n### 6. Persistence Mechanism (`keepAlive`):\nThe `d_keepAlive` flag can be set to true, allowing the contact handler to persist even after objects are no longer in direct collision. This feature helps maintain continuity in simulations where objects may have brief but frequent contacts.\n\nIn summary, BarycentricStickContact uses a combination of geometric mappings and spring-based force fields to model interactions between colliding bodies, ensuring realistic physical behavior through the principles of elasticity and damping."
  },
  "summary": {
    "abstract": "The BarycentricStickContact component manages forces between colliding objects using stick-like spring elements, ensuring realistic physical behavior through elasticity and damping.",
    "sheet": "# BarycentricStickContact\n\n## Overview\nBarycentricStickContact is a contact handler in the SOFA framework designed to manage forces between colliding objects by simulating interactions with barycentric stick-like spring elements. It handles collision detection, force distribution through springs, and persistence of contacts.\n\n## Mathematical Model\nThe BarycentricStickContact component uses Hooke's law for linear elastic springs to apply restoring forces between contact points:\n\\[ \\mathbf{F} = -k (l - l_0) \\hat{n} \\]\nwhere \\( k \\) is the spring stiffness, \\( l \\) is the current length of the spring, and \\( l_0 \\) is its rest length. The term \\( \\hat{n} \\) represents a unit vector in the direction along which the force acts.\n\nDamping can also be introduced to reduce oscillations:\n\\[ \\mathbf{F_d} = -c (v_1 - v_2) \\]\nwhere \\( c \\) is the damping coefficient, and \\( v_1 \\), \\( v_2 \\) are the velocities of the two objects at the contact point.\n\n## Parameters and Data\n- **keepAlive**: A boolean parameter that allows the contact handler to persist even after objects are no longer in direct collision. Default value is `false`."
  }
}