Methods

{
  "name": "NarrowPhaseDetection",
  "namespace": "sofa::core::collision",
  "module": "Sofa.framework.Core",
  "include": "sofa/core/collision/NarrowPhaseDetection.h",
  "doc": "Given a set of potentially colliding pairs of models, compute set of contact points",
  "inherits": [],
  "templates": [],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "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": "beginNarrowPhase",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addCollisionPair",
      "return_type": "void",
      "params": [
        {
          "name": "cmPair",
          "type": "const std::pair<core::CollisionModel *, core::CollisionModel *> &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addCollisionPairs",
      "return_type": "void",
      "params": [
        {
          "name": "v",
          "type": "const int &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "endNarrowPhase",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getPrimitiveTestCount",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getDetectionOutputs",
      "return_type": "const DetectionOutputMap &",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getDetectionOutputs",
      "return_type": "DetectionOutputVector *&",
      "params": [
        {
          "name": "cm1",
          "type": "CollisionModel *"
        },
        {
          "name": "cm2",
          "type": "CollisionModel *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "zeroCollision",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "changeInstanceNP",
      "return_type": "void",
      "params": [
        {
          "name": "inst",
          "type": "Instance"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `NarrowPhaseDetection` class in the SOFA framework is designed to compute contact points between potentially colliding pairs of models during simulations, facilitating accurate collision detection and response. It inherits from the `Detection` base class and is part of the collision handling subsystem.\n\n**Role and Purpose:**\nThe primary role of `NarrowPhaseDetection` is to process and refine potential collisions detected by broader collision detection algorithms (broad phase). This component computes detailed contact information, such as contact points and penetration depths, which are essential for realistic simulation of interactions between models.\n\n**Interactions with Other Components:**\n- **Collision Models**: `NarrowPhaseDetection` interacts directly with `core::CollisionModel` objects to determine if they collide. It receives pairs of collision models from the broad phase detector and processes them using methods like `addCollisionPair()` and `addCollisionPairs()`. The results are stored in a `DetectionOutputMap`, which associates each pair of collision models with their corresponding contact information.\n- **Visual Parameters**: The component can visualize detection outputs through the `draw()` method, leveraging the `core::visual::VisualParams` to draw lines and points representing contacts.\n\n**Practical Usage Guidance:**\nThe key methods for practical usage include:\n- `beginNarrowPhase()`: Initializes the narrow phase collision detection process, clearing previous results.\n- `addCollisionPair()` and `addCollisionPairs()`: Adds pairs of potentially colliding models to be processed.\n- `endNarrowPhase()`: Finalizes the processing and returns any detected contacts for further handling by contact response processes. The `getDetectionOutputs()` method can retrieve detailed outputs.\n\n**Data Fields:**\nThe internal state includes mappings (`m_outputsMap`) that store collision detection results, counters (`_zeroCollision`, `m_primitiveTestCount`), and support structures for multi-instance simulation management (`m_storedOutputsMap`).",
  "maths": "The `NarrowPhaseDetection` class in the SOFA framework is designed to refine and compute detailed contact information between potentially colliding pairs of models, thereby facilitating accurate collision detection and response. This component operates within the broader context of collision handling, where it plays a critical role in the narrow phase of collision detection algorithms.\n\n### Governing Equations or Operators\n- **Contact Points**: The `NarrowPhaseDetection` does not directly implement equations governing contact forces or constraints but instead computes the set of contact points between pairs of models. These contact points are essential for subsequent computations involving contact forces and constraint resolution.\n\n### Constitutive or Kinematic Laws Involved\n- **Collision Detection Outputs**: The component primarily deals with collision detection outputs, which include information such as contact positions, penetration depths, and other relevant metrics derived from the geometry and relative positions of colliding models. These outputs are used to formulate constraints in subsequent stages of the simulation pipeline.\n\n### Role in the Global FEM Pipeline\n- **Assembly Phase**: During the assembly phase, `NarrowPhaseDetection` processes potential collision pairs detected by broader collision detection algorithms (broad phase) and computes detailed contact information.\n- **Time Integration**: The computed contact points are not directly used for time integration but are essential inputs for subsequent stages such as constraint handling.\n\n### Numerical Methods or Discretization Choices\n- **Data Structures**: `NarrowPhaseDetection` utilizes data structures like `DetectionOutputMap`, which maps pairs of collision models to their corresponding detection outputs. The use of stable sorted associative containers ensures reproducible contact response and deterministic simulation behavior.\n- **Clearing and Management**: The component includes methods such as `beginNarrowPhase()` and `endNarrowPhase()` for managing the state between simulation steps, ensuring that previous results are cleared before new detections begin.\n\n### Integration into Variational / Lagrangian Mechanics Framework\nThe `NarrowPhaseDetection` fits into the broader variational or Lagrangian mechanics framework by providing detailed contact information necessary for enforcing constraints and computing forces. While it does not directly contribute to the governing equations of motion, its outputs are critical inputs for subsequent stages that enforce physical consistency and numerical stability in deformable body simulations.\n\n### Summary\n- **Mathematical Content**: The component is primarily concerned with collision detection rather than direct contributions to governing mechanical equations.\n- **Role**: It refines potential collisions into detailed contact information, essential for enforcing constraints and computing forces in the simulation pipeline.",
  "abstract": "The `NarrowPhaseDetection` computes detailed contact information between potentially colliding pairs of models, facilitating accurate collision detection and response.",
  "sheet": "\n# NarrowPhaseDetection\n\n## Overview\n\nThe `NarrowPhaseDetection` component refines potential collisions detected by broader algorithms into detailed contact information such as contact points and penetration depths. It interacts with `core::CollisionModel` objects to process pairs of potentially colliding models, storing the results in a `DetectionOutputMap`. This component is essential for accurate collision detection and response within SOFA simulations.\n\n## Parameters and Data\n\nThe internal state includes mappings (`m_outputsMap`) that store collision detection results, counters (`_zeroCollision`, `m_primitiveTestCount`), and support structures for multi-instance simulation management (`m_storedOutputsMap`).\n\n## Dependencies and Connections\n\n- **Collision Models**: Interacts directly with `core::CollisionModel` objects to determine if they collide. It receives pairs of collision models from the broad phase detector and processes them using methods like `addCollisionPair()` and `addCollisionPairs()`. The results are stored in a `DetectionOutputMap`, which associates each pair of collision models with their corresponding contact information.\n- **Visual Parameters**: Can visualize detection outputs through the `draw()` method, leveraging the `core::visual::VisualParams` to draw lines and points representing contacts.\n\n## Practical Notes\n\nKey methods for practical usage include:\n- `beginNarrowPhase()`: Initializes the narrow phase collision detection process, clearing previous results.\n- `addCollisionPair()` and `addCollisionPairs()`: Adds pairs of potentially colliding models to be processed.\n- `endNarrowPhase()`: Finalizes the processing and returns any detected contacts for further handling by contact response processes. The `getDetectionOutputs()` method can retrieve detailed outputs."
}