{
  "name": "ContactListener",
  "main": {
    "name": "ContactListener",
    "namespace": "sofa::component::collision::response::contact",
    "module": "Sofa.Component.Collision.Response.Contact",
    "include": "sofa/component/collision/response/contact/ContactListener.h",
    "doc": "Utility component to retrieve information about contacts.",
    "inherits": [
      "BaseObject"
    ],
    "templates": [],
    "data_fields": [],
    "links": [],
    "methods": [
      {
        "name": "init",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "handleEvent",
        "return_type": "void",
        "params": [
          {
            "name": "event",
            "type": "core::objectmodel::Event *"
          }
        ],
        "is_virtual": true,
        "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": "getDistances",
        "return_type": "int",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getContactsVector",
        "return_type": "int",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "canCreate",
        "return_type": "bool",
        "params": [
          {
            "name": "obj",
            "type": "T *&"
          },
          {
            "name": "context",
            "type": "core::objectmodel::BaseContext *"
          },
          {
            "name": "arg",
            "type": "core::objectmodel::BaseObjectDescription *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": true,
        "access": "public"
      }
    ]
  },
  "desc": {
    "description": "<p>The `ContactListener` is an utility component in the SOFA framework, designed to retrieve and store information about contacts between collision models.</p>\n\n<p>It inherits from `BaseObject`, which allows it to participate in the scene graph hierarchy of SOFA. The primary role of `ContactListener` is to handle events related to collisions and extract contact details such as number of contacts, distances, points, and elements involved.</p>\n\n<h4>Interactions with Other Components</h4>\n<ul>\n  <li><strong>NarrowPhaseDetection:</strong> It uses the detection outputs from `NarrowPhaseDetection` to gather information about collisions.</li>\n  <li><strong>CollisionModel:</strong> It monitors contact between two collision models (or a single model), which are provided during initialization.</li>\n</ul>\n\n<h4>Data Fields and Methods</h4>\n<ul>\n  <li><strong>getNumberOfContacts:</strong> Returns the number of stored contacts.</li>\n  <li><strong>getDistances:</strong> Retrieves distances between contact points as a vector.</li>\n  <li><strong>getContactPoints:</strong> Provides contact points, represented as tuples with collision model IDs and positions.</li>\n  <li><strong>getContactElements:</strong> Supplies contact elements in the form of tuples with collision model IDs and element indices.</li>\n</ul>\n\n<h4>Practical Usage Guidance</h4>\n<ul>\n  <li>The `ContactListener` is typically used to monitor and log detailed contact information between specified collision models during a simulation.</li>\n  <li>To use it, specify the collision models by their paths through attributes in the SOFA XML configuration.</li>\n</ul>"
  },
  "maths": {
    "maths": "<p>The `ContactListener` is an utility component designed to retrieve information about contacts between collision models within the SOFA framework. It operates based on principles from computational geometry and contact mechanics, ensuring accurate detection and logging of contact details.</p>\n\n<h4>Mathematical Model</h4>\n<ul>\n<li><strong>Contact Points:</strong> The points of contact are identified as intersections between geometric objects (such as spheres, planes, or more complex shapes) representing the collision models. If two objects intersect, the intersection point is a contact point.</li>\n\n<p>For example, if we have two spheres with centers at \\(\\mathbf{c}_1\\) and \\(\\mathbf{c}_2\\), and radii \\(r_1\\) and \\(r_2\\), the distance between their centers is:</p>\n\n\\[\nd = ||\\mathbf{c}_1 - \\mathbf{c}_2||\n\\]\n\n<p>A contact occurs if \\(d < r_1 + r_2\\).</p>\n\n<li><strong>Contact Distances:</strong> The distances between contact points are simply the Euclidean distance between pairs of contact points.</li>\n\n<p>If \\(\\mathbf{p}_i\\) and \\(\\mathbf{p}_j\\) are two contact points, then their distance is given by:</p>\n\n\\[\nd_{ij} = ||\\mathbf{p}_i - \\mathbf{p}_j||\n\\]\n\n<li><strong>Contact Elements:</strong> In the context of mesh-based collision models, each contact point belongs to a specific element (e.g., triangle or tetrahedron) in the underlying topology. These elements can be indexed and identified using their vertices' coordinates.</li>\n</ul>\n\n<h4>Physical Principles</h4>\n<ul>\n<li><strong>Collision Detection:</strong> The `ContactListener` relies on the `NarrowPhaseDetection` component to determine when two objects are in contact. This is often done through algorithms such as GJK (Gilbert–Johnson–Keerthi) or EPA (Expanding Polytope Algorithm).</li>\n\n<li><strong>Contact Information Storage:</strong> Once a collision is detected, the `ContactListener` stores detailed information about each contact point, including its position and the elements it belongs to. This data can be used for further analysis or visualization.</li>\n</ul>"
  },
  "summary": {
    "abstract": "The ContactListener retrieves and stores information about contacts between collision models, handling events related to collisions and extracting details such as contact points, distances, and elements involved.",
    "sheet": "\n# ContactListener\n\n## Overview\n\nThe `ContactListener` is a utility component in the SOFA framework that retrieves and stores information about contacts between collision models. It inherits from `BaseObject`, allowing it to participate in the scene graph hierarchy of SOFA. The primary role of this component is to handle events related to collisions and extract contact details such as the number of contacts, distances, points, and elements involved.\n\n## Practical Notes\n\nThe `ContactListener` is typically used to monitor and log detailed contact information between specified collision models during a simulation. To use it effectively, specify the collision models by their paths through attributes in the SOFA XML configuration."
  }
}