{
  "name": "BroadPhaseDetection",
  "main": {
    "name": "BroadPhaseDetection",
    "namespace": "sofa::core::collision",
    "module": "Sofa.framework.Core",
    "include": "sofa/core/collision/BroadPhaseDetection.h",
    "doc": "given a set of root collision models, computes potentially colliding pairs.",
    "inherits": [],
    "templates": [],
    "data_fields": [],
    "links": [],
    "methods": [
      {
        "name": "beginBroadPhase",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addCollisionModel",
        "return_type": "void",
        "params": [
          {
            "name": "cm",
            "type": "core::CollisionModel *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addCollisionModels",
        "return_type": "void",
        "params": [
          {
            "name": "v",
            "type": "const int &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "endBroadPhase",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getCollisionModelPairs",
        "return_type": "int &",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "changeInstanceBP",
        "return_type": "void",
        "params": [
          {
            "name": "inst",
            "type": "Instance"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      }
    ]
  },
  "desc": {
    "description": "The `BroadPhaseDetection` component in SOFA is designed to compute potentially colliding pairs from a set of root collision models. This class manages the broad-phase detection, which aims at reducing the number of potential collisions by identifying candidate pairs that might collide. It inherits from the abstract base class `Detection`. The key methods include:\n\n- `beginBroadPhase()`: Clears all previously detected potentially colliding pairs.\n- `addCollisionModel(core::CollisionModel *cm)`: Adds a new collision model to the set of root models managed by this component.\n- `addCollisionModels(const sofa::type::vector<core::CollisionModel*>& v)`: Adds multiple collision models at once to the set of root models.\n- `endBroadPhase()`: Performs actions when broad phase detection is complete (default implementation does nothing).\n- `getCollisionModelPairs()`: Retrieves the list of potentially colliding pairs detected by this component.\n\n`BroadPhaseDetection` interacts with other SOFA components through its API, primarily by adding collision models and retrieving potential collisions. It supports multi-instance management via protected method `changeInstanceBP`, which helps to maintain state across different simulation instances."
  },
  "maths": {
    "maths": "The `BroadPhaseDetection` component in SOFA is primarily focused on collision detection, specifically the broad phase. The broad phase aims to reduce the number of potential collision pairs that need further detailed examination (narrow phase) by identifying candidate pairs that might collide based on some initial criteria, such as bounding volume overlap.\n\n### Key Methods and Functionality:\n\n- **`beginBroadPhase()`**: This method clears all previously detected potentially colliding pairs. It is typically called at the start of each simulation step to reset the state for new collision detection.\n    - Mathematically, this can be represented as resetting a set of potential collisions: \n        \\[ P_{coll}^{(t)} = \\emptyset \\]\n        where \\(P_{coll}^{(t)}\\) is the set of potentially colliding pairs at time step \\(t\\).\n\n- **`addCollisionModel(core::CollisionModel *cm)`**: This method adds a new collision model to the set of root models managed by this component. It identifies candidate collision pairs involving `cm`.\n    - In terms of mathematical representation, adding a collision model can be seen as augmenting the set of potential collisions based on initial overlap criteria (e.g., bounding box overlaps): \n        \\[ P_{coll}^{(t)} = P_{coll}^{(t)} \\cup C_{pairs}(cm) \\]\n        where \\(C_{pairs}(cm)\\) is the set of collision pairs involving `cm`.\n\n- **`addCollisionModels(const sofa::type::vector<core::CollisionModel*>& v)`**: This method adds multiple collision models at once to the set of root models. It iterates over each model and calls `addCollisionModel()` for each one.\n    - Mathematically, this can be represented as: \n        \\[ P_{coll}^{(t)} = P_{coll}^{(t)} \\cup \\left\\{ C_{pairs}(cm) | cm \\in v \\right\\} \\]\n\n- **`endBroadPhase()`**: This method performs actions when broad phase detection is complete. The default implementation does nothing, but derived classes can override this to perform additional tasks.\n    - In a mathematical context, it signifies the end of the broad phase and the potential pairs are ready for further analysis in the narrow phase: \n        \\[ P_{coll}^{(t)} = \\text{final set of potentially colliding pairs at time step } t \\]\n\n- **`getCollisionModelPairs()`**: This method retrieves the list of potentially colliding pairs detected by this component. It returns a vector of collision model pairs.\n    - Mathematically, this can be represented as returning the final set of potential collisions: \n        \\[ P_{coll}^{(t)} = \\left\\{ (cm_i, cm_j) | i, j \\in I \\right\\} \\]\n\n### Interactions and State Management:\n\n- **Multi-instance management**: The method `changeInstanceBP` helps to maintain state across different simulation instances. It swaps the current set of potentially colliding pairs with a stored set for a given instance.\n    - Mathematically, this can be represented as: \n        \\[ P_{coll}^{(t)} = \\text{storedCmPairs}[inst] \\]\n\n### Summary:\n\nThe `BroadPhaseDetection` component serves to identify candidate collision pairs efficiently by performing initial checks (e.g., bounding volume overlap). This phase significantly reduces the computational cost of detailed collision analysis in subsequent narrow phases. The mathematical operations involve set union and resetting operations, ensuring that only potentially colliding pairs are processed further."
  },
  "summary": {
    "abstract": "The `BroadPhaseDetection` component identifies potentially colliding pairs from a set of root collision models, reducing the number of detailed collision checks required in subsequent narrow phases.",
    "sheet": "# BroadPhaseDetection\n\n**Overview**\n\nThe `BroadPhaseDetection` component is responsible for identifying candidate collision pairs efficiently by performing initial checks (e.g., bounding volume overlap) on a set of root collision models. This phase significantly reduces the computational cost of detailed collision analysis in subsequent narrow phases.\n\n**Parameters and Data**\n\n- **beginBroadPhase()**: Clears all previously detected potentially colliding pairs, resetting the state for new collision detection at each simulation step.\n- **addCollisionModel(core::CollisionModel *cm)**: Adds a single collision model to the set of root models managed by this component. Identifies candidate collision pairs involving `cm` based on initial overlap criteria (e.g., bounding box overlaps).\n- **addCollisionModels(const sofa::type::vector<core::CollisionModel*>& v)**: Adds multiple collision models at once, iterating over each model and calling `addCollisionModel()` for each one.\n- **endBroadPhase()**: Performs actions when broad phase detection is complete. The default implementation does nothing but can be overridden by derived classes to perform additional tasks.\n- **getCollisionModelPairs()**: Retrieves the list of potentially colliding pairs detected by this component, returning a vector of collision model pairs.\n\n**Dependencies and Connections**\n\nThe `BroadPhaseDetection` component typically requires or exchanges data with other components such as `CollisionModel`, which provides the root models for broad phase detection. It fits into the scene graph by managing the set of potentially colliding pairs, which are then processed further in narrow phases.\n\n**Practical Notes**\n\n- Ensure that collision models added to `BroadPhaseDetection` have appropriate bounding volumes defined for efficient initial overlap checks.\n- The performance of broad phase detection can be significantly improved by optimizing the initial overlap criteria and ensuring that only relevant pairs are identified."
  }
}