{
  "name": "CollisionResponse",
  "main": {
    "name": "CollisionResponse",
    "namespace": "sofa::component::collision::response::contact",
    "module": "Sofa.Component.Collision.Response.Contact",
    "include": "sofa/component/collision/response/contact/CollisionResponse.h",
    "doc": "Default class to create reactions to the collisions.",
    "inherits": [],
    "templates": [],
    "data_fields": [
      {
        "name": "d_response",
        "type": "sofa::helper::OptionsGroup",
        "xmlname": "response",
        "help": "contact response class"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "createContacts",
        "return_type": "void",
        "params": [
          {
            "name": "outputs",
            "type": "const DetectionOutputMap &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "init",
        "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"
      },
      {
        "name": "reset",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "cleanup",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getContactResponse",
        "return_type": "int",
        "params": [
          {
            "name": "model1",
            "type": "core::CollisionModel *"
          },
          {
            "name": "model2",
            "type": "core::CollisionModel *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "removeContacts",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "const ContactVector &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setDefaultResponseType",
        "return_type": "void",
        "params": [
          {
            "name": "responseT",
            "type": "const int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getDefaultResponseType",
        "return_type": "int",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setContactTags",
        "return_type": "void",
        "params": [
          {
            "name": "model1",
            "type": "core::CollisionModel *"
          },
          {
            "name": "model2",
            "type": "core::CollisionModel *"
          },
          {
            "name": "contact",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": true,
        "access": "protected"
      },
      {
        "name": "changeInstance",
        "return_type": "void",
        "params": [
          {
            "name": "inst",
            "type": "Instance"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "initializeResponseOptions",
        "return_type": "sofa::helper::OptionsGroup",
        "params": [
          {
            "name": "pipeline",
            "type": "sofa::core::objectmodel::BaseContext *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": true,
        "access": "protected"
      },
      {
        "name": "contactCreationError",
        "return_type": "void",
        "params": [
          {
            "name": "errorStream",
            "type": "int &"
          },
          {
            "name": "model1",
            "type": "const core::CollisionModel *"
          },
          {
            "name": "model2",
            "type": "const core::CollisionModel *"
          },
          {
            "name": "responseUsed",
            "type": "int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "createNewContacts",
        "return_type": "void",
        "params": [
          {
            "name": "outputsMap",
            "type": "const DetectionOutputMap &"
          },
          {
            "name": "nbContact",
            "type": "int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "removeInactiveContacts",
        "return_type": "void",
        "params": [
          {
            "name": "outputsMap",
            "type": "const DetectionOutputMap &"
          },
          {
            "name": "nbContact",
            "type": "int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "setNumberOfContacts",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      }
    ]
  },
  "desc": {
    "name": "CollisionResponse",
    "namespace": "sofa::component::collision::response::contact",
    "description": "The CollisionResponse class manages the response to collisions between collision models in SOFA (Simulation Open-Framework Architecture). It inherits from core::collision::ContactManager and is responsible for creating, initializing, drawing, resetting, cleaning up, and removing contacts based on a contact detection algorithm. This component facilitates handling various types of contact responses and parameters.",
    "public_methods": [
      {
        "name": "createContacts",
        "description": "Creates contacts between collision models according to the provided DetectionOutputMap."
      },
      {
        "name": "init",
        "description": "Initializes the CollisionResponse object, setting up necessary configurations for managing collisions based on the context."
      },
      {
        "name": "draw",
        "description": "Draws contacts in a specified visual parameter context (vparams) if they exist and are not null."
      },
      {
        "name": "reset",
        "description": "Resets the state of all managed contacts, typically used to restore initial conditions or clear previous interactions."
      },
      {
        "name": "cleanup",
        "description": "Cleans up resources used by the collision response management system, including contact objects that were created during the simulation process."
      },
      {
        "name": "getContactResponse",
        "description": "Returns the type of contact response to be applied between two given CollisionModels based on their individual preferences and default settings."
      },
      {
        "name": "removeContacts",
        "description": "Removes specified contacts from both active and stored (keeping alive) lists, including cleaning up and removing their responses from the system."
      },
      {
        "name": "setDefaultResponseType",
        "description": "Sets a default contact response type for managing collisions when no specific response is provided or selected in configuration files."
      }
    ],
    "protected_methods": [
      {
        "name": "contactCreationError",
        "description": "Handles errors during contact creation by logging failure messages into a stringstream. It includes detailed information about the models involved and supported model types for the contact response type."
      },
      {
        "name": "createNewContacts",
        "description": "Creates new contacts if they haven't been created before, based on detection output maps provided by collision detection algorithms."
      },
      {
        "name": "removeInactiveContacts",
        "description": "Removes inactive contacts that are no longer in collision from the active list to maintain an updated state of ongoing collisions."
      },
      {
        "name": "setNumberOfContacts",
        "description": "Computes and sets the number of current contacts attached to each collision model. This helps in tracking how many other models a particular model is currently colliding with, aiding in physics calculations or visual feedback."
      }
    ],
    "data_fields": [
      {
        "name": "d_response",
        "type": "Data<sofa::helper::OptionsGroup>",
        "description": "Stores the contact response class options group which contains different types of responses that can be applied when a collision is detected."
      },
      {
        "name": "d_responseParams",
        "type": "Data<std::string>",
        "description": "Holds additional parameters for configuring specific behaviors of the chosen contact response type, formatted as name-value pairs (e.g., 'param1=value1&param2=value2')."
      }
    ]
  },
  "maths": {
    "maths": "# Mathematical and Physical Description of the CollisionResponse Component\n\n## Overview\nThe CollisionResponse component in the SOFA framework is responsible for managing responses to collisions between different physical entities (models) within a simulation. It handles various types of contact detection algorithms and allows customization of response behaviors through parameters and settings.\n\n## Key Components and Processes\n### Contact Management\n- **Contact Creation:** The class manages the creation of contacts based on collision detection outputs. If two collision models are in contact, a new contact instance is created to handle interactions between these models.\n- **Initialization:** During initialization (`init()` method), it ensures that the response types for contacts are valid and properly set up, including setting default parameters if necessary.\n\n### Contact Response Customization\n- **Contact Responses:** The `getContactResponse` function decides which type of contact response to use between two collision models. This decision can be influenced by specific attributes of each model (e.g., material properties).\n- **Parameters and Settings:** Custom parameters for the contact responses are handled through the `d_responseParams` Data field, allowing fine-tuning of the interactions.\n\n### Visualization (`draw()` Method)\n- The `draw()` method facilitates visualization of contacts by invoking the draw function on each contact instance. This is crucial for debugging and understanding the simulation state visually.\n\n## Mathematical Models and Interactions\n### Contact Detection\nThe core functionality revolves around detecting when two collision models intersect or come into contact. Mathematically, this can be described through:\n- **Geometric Intersection:** The intersection of two geometric shapes representing collision models (e.g., spheres, boxes). This involves solving for points where the boundaries of these shapes overlap.\n\n### Force and Energy Models\nOnce a contact is detected, various force or energy-based models can be applied to simulate the response. Commonly used models include:\n- **Spring-Damper Model:** A simple model that applies forces proportional to the displacement (Hooke's Law) and velocity difference between two contacting surfaces.\n    - Force: \\(F = k(x_2 - x_1 - d_{0})\\), where \\(k\\) is the spring constant, \\(x_1\\), \\(x_2\\) are positions of contact points on each model, and \\(d_0\\) is the rest distance.\n    - Damping: \\(F_d = c(v_2 - v_1)\\), where \\(c\\) is the damping coefficient, and \\(v_1\\), \\(v_2\\) are velocities at contact points.\n- **Friction Models:** Models that account for frictional forces (both static and kinetic). These can be modeled using Coulomb's law of friction:\n    - Static Friction: Prevents sliding if the applied force is below a certain threshold.\n    - Kinetic Friction: Acts when surfaces are in motion relative to each other.\n\n### Contact Response Lifecycle\n- **Initialization:** Ensuring all contact parameters and settings are valid before simulation begins.\n- **Contact Creation:** Dynamic creation of contacts based on collision detection outputs.\n- **Contact Removal:** Properly cleaning up and removing contacts that are no longer needed, maintaining the integrity of the simulation pipeline.\n\n## Conclusion\nThe CollisionResponse component in SOFA provides a robust framework for handling contact detection and response mechanisms. It leverages various mathematical models to simulate realistic interactions between physical entities within simulations."
  },
  "summary": {
    "abstract": "The CollisionResponse component manages responses to collisions between physical entities in SOFA simulations by creating, initializing, visualizing, resetting, cleaning up, and removing contacts based on collision detection outputs.",
    "sheet": "# CollisionResponse\n\n## Overview\nThe CollisionResponse component is responsible for managing the response to collisions between different physical entities within a simulation. It handles contact creation, initialization, visualization, resetting, cleaning up, and removing contacts based on collision detection outputs.\n\n## Mathematical Model\n### Force Models\n- **Spring-Damper Model:** A simple model that applies forces proportional to displacement (Hooke's Law) and velocity difference between two contacting surfaces:\n  - Force: \\(F = k(x_2 - x_1 - d_{0})\\), where \\(k\\) is the spring constant, \\(x_1\\), \\(x_2\\) are positions of contact points on each model, and \\(d_0\\) is the rest distance.\n  - Damping: \\(F_d = c(v_2 - v_1)\\), where \\(c\\) is the damping coefficient, and \\(v_1\\), \\(v_2\\) are velocities at contact points.\n\n### Friction Models\n- **Coulomb's Law of Friction:** Accounts for frictional forces (both static and kinetic).\n  - Static Friction: Prevents sliding if the applied force is below a certain threshold.\n  - Kinetic Friction: Acts when surfaces are in motion relative to each other.\n\n## Parameters and Data\n- **d_response**: An `sofa::helper::OptionsGroup` that defines the contact response class. This parameter controls which type of contact response is used between two collision models.\n\n## Dependencies and Connections\nThe CollisionResponse component typically requires or exchanges data with components responsible for collision detection, such as `CollisionDetection`. It fits into the scene graph by handling the interactions between detected collisions."
  }
}