Data Fields

Links

Methods

{
  "name": "SphereCollisionModel",
  "namespace": "sofa::component::collision::geometry",
  "module": "Sofa.Component.Collision.Geometry",
  "include": "sofa/component/collision/geometry/SphereCollisionModel.h",
  "doc": "Collision model which represents a set of Spheres.",
  "inherits": [
    "CollisionModel"
  ],
  "templates": [
    "sofa::defaulttype::Rigid3Types",
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_radius",
      "type": "VecReal",
      "xmlname": "listRadius",
      "help": "Radius of each sphere"
    },
    {
      "name": "d_defaultRadius",
      "type": "SReal",
      "xmlname": "radius",
      "help": "Default radius"
    },
    {
      "name": "d_showImpostors",
      "type": "bool",
      "xmlname": "showImpostors",
      "help": "Draw spheres as impostors instead of \\\"real\\\" spheres"
    }
  ],
  "links": [
    {
      "name": "l_topology",
      "target": "BaseMeshTopology",
      "kind": "single"
    }
  ],
  "methods": [
    {
      "name": "init",
      "description": "Initializes the collision model."
    },
    {
      "name": "resize",
      "parameters": [
        "size"
      ],
      "description": "Resizes the collision model to a given size (number of spheres)."
    },
    {
      "name": "computeBoundingTree",
      "parameters": [
        "maxDepth"
      ],
      "description": "Computes the bounding tree for efficient collision detection."
    },
    {
      "name": "drawCollisionModel",
      "parameters": [
        "vparams"
      ],
      "description": "Draws the collision model visualization."
    }
  ],
  "description": "The `SphereCollisionModel` is a collision model in the SOFA (Simulation Open Framework Architecture) framework that represents objects as spheres for collision detection purposes.",
  "parameters": [
    {
      "name": "defaultRadius",
      "description": "Default radius used when no specific radius is defined for an individual sphere.",
      "type": "SReal",
      "required": false
    },
    {
      "name": "radius",
      "description": "List of radii for each individual sphere in the model.",
      "type": "VecReal",
      "required": false
    },
    {
      "name": "showImpostors",
      "description": "Boolean flag to enable drawing spheres as impostors (2D images) instead of actual 3D spheres.",
      "type": "bool",
      "required": false
    }
  ],
  "functionality": "This component allows simulating objects as spheres, which simplifies collision calculations. It supports defining custom radii for individual spheres or using a default radius. The collision model can be visualized in the simulation scene and is used by various collision detection algorithms within SOFA.",
  "usage": "The `SphereCollisionModel` is typically attached to a mechanical object (like a mesh) that has a defined mechanical state. It uses the positions from this mechanical state as the centers of the spheres. The component is useful for quickly setting up simple collision models, especially when precise shape details are not critical.",
  "dependencies": [
    "core::behavior::MechanicalState",
    "core::CollisionModel"
  ],
  "specializations": "The class template can be specialized for different data types (e.g., Vec3Types, Rigid3Types) to handle various representations of positions and orientations.",
  "maths": "<p>The <code>SphereCollisionModel</code> is primarily concerned with representing objects as spheres for collision detection purposes within the context of a simulation framework. The following provides a rigorous mathematical and physical description:</p>\n\n<h3 id=\"governing-equations-or-operators-contributed\">Governing Equations or Operators Contributed</h3>\n<p>The <code>SphereCollisionModel</code> does not contribute to the governing equations such as mass matrix \\(M\\), stiffness matrix \\(K\\), internal force \\(f_{int}\\), residual \\(R\\), etc., which are central to FEM. It is primarily a geometric representation component designed for collision detection and visualization.</p>\n\n<h3 id=\"constitutive-or-kinematic-laws-involved\">Constitutive or Kinematic Laws Involved</h3>\n<p>Since the <code>SphereCollisionModel</code> is focused on geometry, it does not involve constitutive laws (such as stress-strain relationships) or hyperelastic potentials. It merely defines and handles spherical collision elements through their geometric properties.</p>\n\n<h4 id=\"geometric-properties\">Geometric Properties:</h4>\n<ul>\n<li><strong>Center</strong>: The position vector \\(\\mathbf{c} \\in \\mathbb{R}^3\\) of the center of each sphere. For a given sphere with index \\(i\\),\n  \\[\\mathbf{c}_i = \\texttt{center}(i).\\]</li>\n<li><strong>Radius</strong>: The radius scalar \\(r_i\\) for each sphere indexed by \\(i\\):\n  \\[r_i = \\texttt{getRadius}(i),\\]\nwhere \\(r_i\\) can be specified individually or defaulted.</li>\n</ul>\n\n<h3 id=\"role-in-the-global-fem-pipeline\">Role in the Global FEM Pipeline</h3>\n<p>The <code>SphereCollisionModel</code> plays a role primarily in:</p>\n<ul>\n<li><strong>Visualization</strong>: Drawing spheres for visual inspection.</li>\n<li><strong>Collision Detection and Bounding Box Computation</strong>: For each sphere, it computes the bounding box which is used to determine if collisions are possible between different objects or parts of a model. The bounding box \\(\\texttt{bbox}\\) includes all points within the sphere:</li>\n</ul>\n<p>For a given sphere with center \\(\\mathbf{c}_i\\) and radius \\(r_i\\),\n  \\[\\texttt{bbox} = [\\mathbf{c}_i - (r_i, r_i, r_i), \\mathbf{c}_i + (r_i, r_i, r_i)].\\]</p>\n\n<h3 id=\"numerical-methods-or-discretization-choices-encoded\">Numerical Methods or Discretization Choices Encoded</h3>\n<p>The <code>SphereCollisionModel</code> does not encode any numerical methods related to FEM discretization. However, it implements:</p>\n<ul>\n<li><strong>Bounding Tree Construction</strong>: Used for efficient collision detection between sets of spheres. This involves computing bounding boxes and building a hierarchy (tree) of these bounds.</li>\n</ul>\n\n<h3 id=\"fit-into-the-broader-variational--lagrangian-mechanics-framework\">Fit into the Broader Variational / Lagrangian Mechanics Framework</h3>\n<p>The <code>SphereCollisionModel</code> is a geometric model and does not directly contribute to variational principles or Lagrangian mechanics. It serves as an input for collision detection algorithms which, in turn, can influence dynamics through constraint forces. However, it operates at the level of geometry rather than energetics.</p>\n\n<p>To summarize:</p>\n<ul>\n<li>The <code>SphereCollisionModel</code> is a geometric representation component.</li>\n<li>It contributes to visualization and collision detection mechanisms but does not participate in solving the FEM equations directly.</li>\n<li>Its primary role involves defining spheres, computing their bounding boxes, and enabling efficient collision detection through hierarchical data structures.</li>\n</ul>",
  "abstract": "The `SphereCollisionModel` represents objects as spheres for collision detection purposes, providing geometric properties such as centers and radii, and enabling efficient visualization and bounding box computation.",
  "sheet": "# SphereCollisionModel\n\n## Overview\nThe `SphereCollisionModel` is a component in the SOFA framework that represents objects as spheres for collision detection. It handles the geometric aspects of these spheres, including their centers and radii, and supports efficient collision detection through bounding boxes and hierarchical structures.\n\n## Parameters and Data\n- **listRadius (`d_radius`, `VecReal`)**: Radius of each sphere.\n- **radius (`d_defaultRadius`, `SReal`)**: Default radius for all spheres if not specified individually.\n- **showImpostors (`d_showImpostors`, `bool`)**: Flag to draw spheres as impostors instead of real spheres, which can improve rendering performance.\n\n## Dependencies and Connections\nThe component requires a `BaseMeshTopology` link to define the topology of the model. It is typically used in conjunction with other collision detection components and visualization modules within the SOFA scene graph.\n\n## Practical Notes\n- Ensure that the radii are set appropriately for accurate collision detection.\n- Using impostors can improve rendering performance but may reduce visual fidelity."
}