{
  "name": "CCDTightInclusionIntersection",
  "main": {
    "name": "CCDTightInclusionIntersection",
    "namespace": "sofa::component::collision::detection::intersection",
    "module": "Sofa.Component.Collision.Detection.Intersection",
    "include": "sofa/component/collision/detection/intersection/CCDTightInclusionIntersection.h",
    "doc": "A set of methods to compute (for constraint methods) if two primitives are close enough to consider they collide\n\nIntersection methods using proximities. Filters are added to limit the number of contacts.\nThe following pairs of collision models are supported:\n- Cube/Cube\n- Line/Line\n- Triangle/Point\nThe following pairs of collision models are ignored:\n- Sphere/Sphere\n- Sphere/Point\n- Point/Point\n- Line/Point\n- Line/Sphere\n- Triangle/Line\n- Triangle/Triangle\n- Triangle/Sphere\n- Ray/Triangle\n- Ray/Sphere\n- Ray/Point\n- Ray/Line",
    "inherits": [
      "BaseProximityIntersection"
    ],
    "templates": [],
    "data_fields": [
      {
        "name": "d_continuousCollisionType",
        "type": "sofa::helper::OptionsGroup",
        "xmlname": "None",
        "help": "Data used for continuous collision detection taken into {'None','Inertia','FreeMotion'}. If 'None' then no CCD is used, if 'Inertia' then only inertia will be used to compute the collision detection and if 'FreeMotion' then the free motion will be used. Note that if 'FreeMotion' is selected, you cannot use the option 'parallelCollisionDetectionAndFreeMotion' in the FreeMotionAnimationLoop"
      },
      {
        "name": "d_tolerance",
        "type": "SReal",
        "xmlname": "tolerance",
        "help": "tolerance used by the tight inclusion CCD algorithm"
      },
      {
        "name": "d_maxIterations",
        "type": "long",
        "xmlname": "maxIterations",
        "help": "maxIterations used by the tight inclusion CCD algorithm"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "init",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "useContinuous",
        "return_type": "bool",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "continuousIntersectionType",
        "return_type": "core::CollisionModel::ContinuousIntersectionTypeFlag",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "testIntersection",
        "return_type": "bool",
        "params": [
          {
            "name": "",
            "type": "collision::geometry::Cube &"
          },
          {
            "name": "",
            "type": "collision::geometry::Cube &"
          },
          {
            "name": "currentIntersection",
            "type": "const core::collision::Intersection *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "testIntersection",
        "return_type": "bool",
        "params": [
          {
            "name": "",
            "type": "collision::geometry::Line &"
          },
          {
            "name": "",
            "type": "collision::geometry::Line &"
          },
          {
            "name": "currentIntersection",
            "type": "const core::collision::Intersection *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "testIntersection",
        "return_type": "bool",
        "params": [
          {
            "name": "",
            "type": "collision::geometry::Triangle &"
          },
          {
            "name": "",
            "type": "collision::geometry::Point &"
          },
          {
            "name": "currentIntersection",
            "type": "const core::collision::Intersection *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "computeIntersection",
        "return_type": "int",
        "params": [
          {
            "name": "",
            "type": "collision::geometry::Cube &"
          },
          {
            "name": "",
            "type": "collision::geometry::Cube &"
          },
          {
            "name": "",
            "type": "OutputVector *"
          },
          {
            "name": "currentIntersection",
            "type": "const core::collision::Intersection *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "computeIntersection",
        "return_type": "int",
        "params": [
          {
            "name": "",
            "type": "collision::geometry::Line &"
          },
          {
            "name": "",
            "type": "collision::geometry::Line &"
          },
          {
            "name": "",
            "type": "OutputVector *"
          },
          {
            "name": "currentIntersection",
            "type": "const core::collision::Intersection *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "computeIntersection",
        "return_type": "int",
        "params": [
          {
            "name": "",
            "type": "collision::geometry::Triangle &"
          },
          {
            "name": "",
            "type": "collision::geometry::Point &"
          },
          {
            "name": "",
            "type": "OutputVector *"
          },
          {
            "name": "currentIntersection",
            "type": "const core::collision::Intersection *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "name": "CCD (Continuous Collision Detection) Component",
    "description": "This component is designed to perform continuous collision detection between different types of geometric elements in a simulation environment, specifically for the SofaPhysics framework. Continuous collision detection ensures that collisions are detected even if they happen during a time step, providing more accurate results compared to discrete collision detection methods.",
    "functionality": [
      {
        "method": "testIntersection",
        "description": "This method checks whether two geometric elements intersect at any point in the specified time interval. It supports different types of collisions such as edge-edge (line segments) and vertex-face (point-triangle). The `testIntersection` methods return a boolean indicating if a collision occurs within the given tolerance.",
        "parameters": [
          {
            "name": "Elements",
            "type": "Edge, Triangle, Point",
            "description": "The geometric elements to be checked for intersection."
          },
          {
            "name": "currentIntersection",
            "type": "core::collision::Intersection*",
            "description": "A pointer to the current collision intersection object providing contact distance and other relevant parameters."
          }
        ],
        "returnType": [
          {
            "boolean": "true if elements intersect, false otherwise"
          }
        ]
      },
      {
        "method": "computeIntersection",
        "description": "This method computes detailed information about intersections between geometric elements when a collision is detected. The `computeIntersection` methods append detection output to an output vector containing the details of each intersection, such as positions and normals at the point of collision.",
        "parameters": [
          {
            "name": "Elements",
            "type": "Edge, Triangle, Point",
            "description": "The geometric elements that are intersecting."
          },
          {
            "name": "contacts",
            "type": "OutputVector*",
            "description": "A pointer to the vector where intersection information will be stored."
          },
          {
            "name": "currentIntersection",
            "type": "core::collision::Intersection*",
            "description": "A pointer to the current collision intersection object providing contact distance and other relevant parameters."
          }
        ],
        "returnType": [
          {
            "integer": "Number of intersections found"
          }
        ]
      }
    ],
    "parameters": [
      {
        "name": "tolerance",
        "type": "SReal (float or double)",
        "description": "The tolerance used in the continuous collision detection algorithm to determine if elements are intersecting. This value can be adjusted based on the precision needed for the simulation."
      },
      {
        "name": "maxIterations",
        "type": "integer",
        "description": "Maximum number of iterations allowed during the CCD process, which helps in balancing between accuracy and computational cost."
      }
    ],
    "supportedGeometricElements": [
      {
        "Edge (line segment)": "",
        "description": "Intersection detection for line segments"
      },
      {
        "Triangle": "",
        "description": "Collision detection with a triangular surface"
      },
      {
        "Point": "",
        "description": "Vertex collision checks"
      }
    ],
    "dependencies": [
      "SofaPhysics framework",
      "Eigen library"
    ],
    "usageExample": [
      {
        "exampleCode": "auto result = component->testIntersection(edge1, edge2, intersection);",
        "description": "This line of code would check for intersections between two edges `edge1` and `edge2`, storing the result in a boolean variable `result`."
      },
      {
        "exampleCode": "component->computeIntersection(triangle, point, contacts, intersection);",
        "description": "Here, detailed information about collisions between a triangle and a point is computed and stored into the `contacts` vector."
      }
    ]
  },
  "maths": {
    "maths": "# Continuous Collision Detection Component in SofaPhysics\n\n## Overview\nContinuous collision detection (CCD) is crucial for accurately simulating dynamic interactions between objects, especially when the relative velocities are high. This component is designed to detect collisions continuously within a time step, ensuring that no intersections go unnoticed. The following sections provide detailed mathematical and physical descriptions of the CCD algorithms implemented in this component.\n\n## Geometric Primitives\nThe geometric primitives involved in this component include triangles, points, and edges (lines). Each primitive has associated vertices with positions at the beginning (`p`) and end (`pFree`) of a time step. The position at any intermediate time `t` within the time step is interpolated linearly as follows:\n\n- **Point**: \n  \\[ \\mathbf{P}_{\\text{Toi}} = (1-t) \\cdot \\mathbf{P} + t \\cdot \\mathbf{P}_{\\text{Free}} \\]\n  where `t` is the time within the interval `[0, 1]`, `\\mathbf{P}` is the initial position, and `\\mathbf{P}_{\\text{Free}}` is the final position.\n\n- **Edge**:\n  \\[ \\mathbf{E}_{A_{Toi}} = (1-t) \\cdot \\mathbf{E}_A + t \\cdot \\mathbf{E}_{A_{\\text{Free}}} \\]\n  \\[ \\mathbf{E}_{B_{Toi}} = (1-t) \\cdot \\mathbf{E}_B + t \\cdot \\mathbf{E}_{B_{\\text{Free}}} \\]\n\n- **Triangle**:\n  \\[ \\mathbf{T}_{A_{Toi}} = (1-t) \\cdot \\mathbf{T}_A + t \\cdot \\mathbf{T}_{A_{\\text{Free}}} \\]\n  \\[ \\mathbf{T}_{B_{Toi}} = (1-t) \\cdot \\mathbf{T}_B + t \\cdot \\mathbf{T}_{B_{\\text{Free}}} \\]\n  \\[ \\mathbf{T}_{C_{Toi}} = (1-t) \\cdot \\mathbf{T}_C + t \\cdot \\mathbf{T}_{C_{\\text{Free}}} \\]\n\n## Collision Detection Algorithms\n### Point-Triangle CCD\nThe point-triangle collision detection algorithm involves the following steps:\n1. **Interpolation**: Compute the positions of all vertices at intermediate time `t`.\n2. **Distance Calculation**: Determine if a point intersects with or is close to a triangle using the distance between the point and the plane of the triangle.\n3. **Barycentric Coordinates**: If an intersection occurs, compute barycentric coordinates for the closest point on the triangle's surface:\n   \\[ \\mathbf{P}_{\\text{Toi}} = (1-t) \\cdot \\mathbf{P} + t \\cdot \\mathbf{P}_{\\text{Free}} \\]\n   The normal vector of the triangle at `t` is used to project the point onto the plane and then compute barycentric coordinates.\n4. **Result**: If the distance is less than or equal to a threshold (maximum separation), a collision is detected, and contact information is recorded.\n\n### Edge-Edge CCD\nThe edge-edge collision detection algorithm involves:\n1. **Interpolation**: Compute the positions of endpoints at intermediate time `t` for both edges.\n2. **Distance Calculation**: Determine if the distance between two edges is less than a specified threshold using vector algebra to compute closest points on each edge.\n3. **Barycentric Coordinates**: If an intersection occurs, compute barycentric coordinates for the closest point on each edge:\n   \\[ \\mathbf{E}_{A_{Toi}} = (1-t) \\cdot \\mathbf{E}_A + t \\cdot \\mathbf{E}_{A_{\\text{Free}}} \\]\n   \\[ \\mathbf{E}_{B_{Toi}} = (1-t) \\cdot \\mathbf{E}_B + t \\cdot \\mathbf{E}_{B_{\\text{Free}}} \\]\n4. **Result**: If the distance is less than or equal to a threshold, a collision is detected, and contact information is recorded.\n\n## Tolerance and Iteration\nThe algorithms use a tolerance parameter (`d_tolerance`) and an iteration limit (`d_maxIterations`) to ensure convergence in the root-finding process for intersection times. The function `ticcd::vertexFaceCCD` and similar functions iteratively refine the time of impact (`toi`) until either a collision is found or the maximum number of iterations is reached.\n\n## Summary\nThis component implements continuous collision detection algorithms for various geometric primitives, ensuring that collisions are accurately detected even when they occur within a time step. The mathematical foundations involve linear interpolation and vector algebra to compute distances and barycentric coordinates."
  },
  "summary": {
    "abstract": "The `CCDTightInclusionIntersection` component performs continuous collision detection (CCD) between specific geometric primitives, ensuring accurate simulation of dynamic interactions by detecting collisions within a time step.",
    "sheet": "# CCDTightInclusionIntersection\n\n## Overview\nThis component is designed to perform continuous collision detection (CCD) for specific pairs of geometric primitives in the SOFA framework. It supports Cube/Cube, Line/Line, and Triangle/Point intersections while ignoring Sphere/Sphere, Point/Point, and other primitive combinations.\n\n## Mathematical Model\nContinuous collision detection involves linear interpolation to compute positions at intermediate times within a time step. The following equations describe the position of geometric primitives at any time `t`:\n- **Point**: \n  \\[ \\mathbf{P}_{\\text{Toi}} = (1-t) \\cdot \\mathbf{P} + t \\cdot \\mathbf{P}_{\\text{Free}} \\]\n- **Edge**:\n  \\[ \\mathbf{E}_{A_{Toi}} = (1-t) \\cdot \\mathbf{E}_A + t \\cdot \\mathbf{E}_{A_{\\text{Free}}} \\]\n  \\[ \\mathbf{E}_{B_{Toi}} = (1-t) \\cdot \\mathbf{E}_B + t \\cdot \\mathbf{E}_{B_{\\text{Free}}} \\]\n- **Triangle**:\n  \\[ \\mathbf{T}_{A_{Toi}} = (1-t) \\cdot \\mathbf{T}_A + t \\cdot \\mathbf{T}_{A_{\\text{Free}}} \\]\n  \\[ \\mathbf{T}_{B_{Toi}} = (1-t) \\cdot \\mathbf{T}_B + t \\cdot \\mathbf{T}_{B_{\\text{Free}}} \\]\n  \\[ \\mathbf{T}_{C_{Toi}} = (1-t) \\cdot \\mathbf{T}_C + t \\cdot \\mathbf{T}_{C_{\\text{Free}}} \\]\nThe algorithms use tolerance and iteration limits to ensure convergence in the root-finding process for intersection times.\n\n## Parameters and Data\n- **d_continuousCollisionType**: Type of continuous collision detection used (`None`, `Inertia`, or `FreeMotion`).\n- **d_tolerance**: Tolerance parameter for the tight inclusion CCD algorithm.\n- **d_maxIterations**: Maximum number of iterations allowed by the tight inclusion CCD algorithm."
  }
}