Data Fields

Methods

{
  "name": "CollisionPipeline",
  "namespace": "sofa::component::collision::detection::algorithm",
  "module": "Sofa.Component.Collision.Detection.Algorithm",
  "include": "sofa/component/collision/detection/algorithm/CollisionPipeline.h",
  "doc": "The default collision detection and modeling pipeline.",
  "inherits": [
    "PipelineImpl"
  ],
  "templates": [],
  "data_fields": [
    {
      "name": "d_doPrintInfoMessage",
      "type": "bool",
      "xmlname": "verbose",
      "help": "Display extra information at each computation step. (default=false)"
    },
    {
      "name": "d_doDebugDraw",
      "type": "bool",
      "xmlname": "draw",
      "help": "Draw the detected collisions. (default=false)"
    },
    {
      "name": "d_depth",
      "type": "int",
      "xmlname": "depth",
      "help": ", min=?, max=?)"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getResponseList",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "doCollisionReset",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "doCollisionDetection",
      "return_type": "void",
      "params": [
        {
          "name": "collisionModels",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "doCollisionResponse",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "checkDataValues",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": {
    "summary": "The CollisionPipeline class is responsible for managing the collision detection and response pipeline in SOFA, a simulation framework.",
    "details": {
      "responsibilities": [
        "Manages the initialization, collision detection, and response stages of collision handling.",
        "Provides methods to detect collisions using bounding volume hierarchies (BVH) and broad/narrow phase algorithms.",
        "Generates and manages contact responses based on detected collisions."
      ],
      "methods": {
        "init()": "Initializes the pipeline and checks data values.",
        "doCollisionReset()": "Removes collision response from the previous simulation step.",
        "doCollisionDetection(const sofa::type::vector<core::CollisionModel*>& collisionModels)": "Detects new collisions using bounding volume hierarchies, broad phase, and narrow phase algorithms.",
        "doCollisionResponse()": "Creates contact responses based on detected collisions.",
        "getResponseList() const": "Returns a set of available response types for the current pipeline."
      },
      "data_members": {
        "d_doPrintInfoMessage": "A boolean flag to control whether to print information messages during collision detection and response stages.",
        "d_doDebugDraw": "A boolean flag to enable or disable debugging visualization.",
        "d_depth": "An integer value representing the depth of bounding volume hierarchies used in collision detection."
      },
      "interaction_with_components": {
        "BroadPhaseDetection": "Used for early rejection of non-colliding objects using bounding volumes.",
        "NarrowPhaseDetection": "Performs detailed intersection tests between potential colliders.",
        "ContactManager": "Responsible for creating and managing contacts resulting from collisions.",
        "IntersectionMethod": "Determines the type of intersection method used in collision detection."
      },
      "usage_examples": [
        {
          "example_1": "In a simulation, CollisionPipeline is initialized to set up the necessary data structures. During each simulation step, doCollisionDetection() is called to detect collisions among collision models, followed by doCollisionResponse() to handle the detected collisions."
        }
      ]
    },
    "dependencies": [
      "sofa::simulation::PipelineImpl",
      "core::collision::BroadPhaseDetection",
      "core::collision::NarrowPhaseDetection",
      "core::collision::ContactManager",
      "core::collision::IntersectionMethod"
    ],
    "notes": "The CollisionPipeline class integrates various components to handle the collision detection and response process effectively, ensuring that all necessary stages are performed in sequence."
  },
  "maths": "The CollisionPipeline class in the SOFA simulation framework is responsible for managing collision detection and response. The mathematical and physical principles underlying its operations are detailed below.\n\n### Mathematical Principles:\n\n#### Bounding Volume Hierarchies (BVH)\nThe pipeline uses bounding volume hierarchies to efficiently detect potential collisions. A BVH is a tree structure where each node represents a region in space enclosing one or more objects. Mathematically, the process involves constructing such trees and performing spatial queries.\n- **Bounding Box Construction:** Each object can be enclosed within an axis-aligned bounding box (AABB), which can be described by its minimum and maximum coordinates along each dimension:\n  \\[ \text{AABB}(o) = [x_{\text{min}}, x_{\text{max}}] \times [y_{\text{min}}, y_{\text{max}}] \times [z_{\text{min}}, z_{\text{max}}] \\]\n- **Bounding Volume Tree Construction:** A BVH tree can be constructed using a recursive partitioning scheme, such as splitting along the longest dimension or surface area heuristics. Each internal node represents a bounding volume that encloses its children.\n\n#### Broad Phase Detection:\nThe broad phase is responsible for quickly eliminating pairs of objects that are far apart and cannot possibly collide. This is achieved by comparing the bounding volumes of objects in the BVH.\n- **Intersection Test:** The AABBs of two objects can be checked for overlap using simple coordinate comparisons:\n  \\[ \text{AABB}_1 = [x_{1\text{min}}, x_{1\text{max}}] \times [y_{1\text{min}}, y_{1\text{max}}] \times [z_{1\text{min}}, z_{1\text{max}}], \\quad \text{AABB}_2 = [x_{2\text{min}}, x_{2\text{max}}] \times [y_{2\text{min}}, y_{2\text{max}}] \times [z_{2\text{min}}, z_{2\text{max}}] \\]\n  The two AABBs intersect if and only if:\n  \\[ x_{1\text{min}} \\leq x_{2\text{max}} \\quad \\text{and} \\quad x_{2\text{min}} \\leq x_{1\text{max}} \\]\n  (similar conditions for y and z)\n\n#### Narrow Phase Detection:\nThe narrow phase involves performing detailed intersection tests on pairs of objects that pass the broad phase. The pipeline supports various types of geometric primitives, such as spheres, boxes, or polygons.\n- **Sphere-Sphere Intersection:** Two spheres with centers \\( C_1 = (x_{1}, y_{1}, z_{1}) \\) and \\( C_2 = (x_{2}, y_{2}, z_{2}) \\), and radii \\( r_1 \\) and \\( r_2 \\), intersect if the distance between their centers is less than or equal to the sum of their radii:\n  \\[ \text{Distance}(C_1, C_2) = \\sqrt{(x_{1}-x_{2})^2 + (y_{1}-y_{2})^2 + (z_{1}-z_{2})^2} \\leq r_1 + r_2 \\]\n- **Polygon Intersection:** More complex shapes like polygons can be tested for intersection using techniques such as separating axis theorem, which checks if there exists a plane that separates the two objects.\n\n#### Contact Response Generation:\nThe collision detection phase results in contact points and penetration depths. The response generation involves applying forces or constraints to resolve these contacts. \n- **Contact Forces:** For each contact pair \\((p_1, p_2)\\), a contact force \\( F_c \\) is computed based on the restitution coefficient \\( e \\) (coefficient of restitution), penetration depth \\( d \\), and normal vector \\( n \\):\n  \\[ F_c = k_n \times d + c_d \times v_n \\]\n  where \\( k_n \\) is a stiffness term, and \\( c_d \\) accounts for damping. The force is applied along the contact normal:\n  \\[ F_{\\text{contact}} = -F_c \times n \\]\n\n### Physical Principles:\nThe physical principles underlying collision detection and response are rooted in Newtonian mechanics and conservation laws.\n- **Conservation of Momentum:** In an elastic collision, momentum is conserved. The total momentum before the collision must equal the total momentum after the collision:\n  \\[ m_1 \times v_{1\text{initial}} + m_2 \times v_{2\text{initial}} = m_1 \times v_{1\text{final}} + m_2 \times v_{2\text{final}} \\]\n- **Restitution:** The coefficient of restitution (\\( e \\)) describes the elasticity of a collision. It ranges from 0 to 1, where 0 represents a completely inelastic collision and 1 represents an elastic collision:\n  \\[ v_{r1} - v_{r2} = -e \times (v_{i1} - v_{i2}) \\]\n  where \\( v_r \\) is the relative velocity after the collision, and \\( v_i \\) is the initial relative velocity.\n\n### Algorithmic Steps:\nThe CollisionPipeline follows a series of steps to manage the collision detection and response pipeline.\n1. **Initialization:** The pipeline initializes its data structures and checks input values using `init()`.\n2. **Collision Reset:** In each simulation step, old contact responses are removed using `doCollisionReset()`.\n3. **Broad Phase Detection:** Potential colliders are identified using bounding volumes through the method `doCollisionDetection()`, which involves recursive BVH traversal.\n4. **Narrow Phase Detection:** Detailed intersection tests are performed on pairs of objects that pass the broad phase, leading to contact detection.\n5. **Response Generation:** Contact forces and constraints are applied based on detected contacts using `doCollisionResponse()`.\n\nBy following these principles, CollisionPipeline ensures efficient and accurate collision handling in simulations.",
  "abstract": "CollisionPipeline manages the collision detection and response pipeline in SOFA, handling broad phase and narrow phase detection, as well as contact response generation.",
  "sheet": "# CollisionPipeline\n\n## Overview\nCollisionPipeline is responsible for managing the collision detection and response pipeline in SOFA. It handles broad phase and narrow phase detection using bounding volume hierarchies (BVH) and detailed intersection tests, followed by generating contact responses based on detected collisions.\n\n## Mathematical Model\n### Bounding Volume Hierarchies (BVH)\nThe pipeline uses BVH to efficiently detect potential collisions. A BVH is a tree structure where each node represents a region in space enclosing one or more objects. Mathematically, the process involves constructing such trees and performing spatial queries.\n- **Bounding Box Construction:** Each object can be enclosed within an axis-aligned bounding box (AABB), which can be described by its minimum and maximum coordinates along each dimension:\n  \\[ \text{AABB}(o) = [x_{\text{min}}, x_{\text{max}}] \times [y_{\text{min}}, y_{\text{max}}] \times [z_{\text{min}}, z_{\text{max}}] \\]\n- **Bounding Volume Tree Construction:** A BVH tree can be constructed using a recursive partitioning scheme, such as splitting along the longest dimension or surface area heuristics. Each internal node represents a bounding volume that encloses its children.\n\n### Broad Phase Detection:\nThe broad phase is responsible for quickly eliminating pairs of objects that are far apart and cannot possibly collide. This is achieved by comparing the bounding volumes of objects in the BVH.\n- **Intersection Test:** The AABBs of two objects can be checked for overlap using simple coordinate comparisons:\n  \\[ \text{AABB}_1 = [x_{1\text{min}}, x_{1\text{max}}] \times [y_{1\text{min}}, y_{1\text{max}}] \times [z_{1\text{min}}, z_{1\text{max}}], \\quad \text{AABB}_2 = [x_{2\text{min}}, x_{2\text{max}}] \times [y_{2\text{min}}, y_{2\text{max}}] \times [z_{2\text{min}}, z_{2\text{max}}] \\]\n  The two AABBs intersect if and only if:\n  \\[ x_{1\text{min}} \\\nleq x_{2\text{max}} \\quad \\text{and} \\quad x_{2\text{min}} \\\nleq x_{1\text{max}} \\]\n  (similar conditions for y and z)\n\n### Narrow Phase Detection:\nThe narrow phase involves performing detailed intersection tests on pairs of objects that pass the broad phase. The pipeline supports various types of geometric primitives, such as spheres, boxes, or polygons.\n- **Sphere-Sphere Intersection:** Two spheres with centers \\( C_1 = (x_{1}, y_{1}, z_{1}) \\) and \\( C_2 = (x_{2}, y_{2}, z_{2}) \\), and radii \\( r_1 \\) and \\( r_2 \\), intersect if the distance between their centers is less than or equal to the sum of their radii:\n  \\[ \text{Distance}(C_1, C_2) = \\\nsqrt{(x_{1}-x_{2})^2 + (y_{1}-y_{2})^2 + (z_{1}-z_{2})^2} \\\nleq r_1 + r_2 \\]\n- **Polygon Intersection:** More complex shapes like polygons can be tested for intersection using techniques such as separating axis theorem, which checks if there exists a plane that separates the two objects.\n\n### Contact Response Generation:\nThe collision detection phase results in contact points and penetration depths. The response generation involves applying forces or constraints to resolve these contacts. \n- **Contact Forces:** For each contact pair \\((p_1, p_2)\\), a contact force \\( F_c \\) is computed based on the restitution coefficient \\( e \\) (coefficient of restitution), penetration depth \\( d \\), and normal vector \\( n \\):\n  \\[ F_c = k_n \\\ntimes d + c_d \\\ntimes v_n \\]\n  where \\( k_n \\) is a stiffness term, and \\( c_d \\) accounts for damping. The force is applied along the contact normal:\n  \\[ F_{\text{contact}} = -F_c \\\ntimes n \\]\n\n## Parameters and Data\n- **verbose (bool):** Display extra information at each computation step. Default: `false`.\n- **draw (bool):** Draw the detected collisions. Default: `false`.\n- **depth (int):** Depth of bounding volume hierarchies used in collision detection."
}