RayCollisionModel

sofa::component::collision::geometry::RayCollisionModel

CollisionModel

Doc (from source)

Collision model representing a ray in space, e.g. a mouse click

Abstract (AI generated)

The `RayCollisionModel` represents one or more rays in the simulation space for collision detection purposes, managing their geometric properties and interactions with other components.

Metadata

module

Sofa.Component.Collision.Geometry

namespace

sofa::component::collision::geometry

include

sofa/component/collision/geometry/RayCollisionModel.h

inherits

CollisionModel

description

The RayCollisionModel component in the SOFA framework is designed to represent one or more rays within the simulation space for collision detection purposes. This component does not directly contribute to the governing equations of FEM, such as mass matrix ($ M $), stiffness matrix ($ K $), internal force vector ($ f_{int} $), residual ($ R $), etc., which are typically associated with structural mechanics and material behavior. Instead, it is primarily concerned with defining and managing the geometric properties of rays for collision detection.

Geometric Representation

Each ray in this model is defined by three key parameters:
- Origin: The starting point of the ray ($ \mathbf{o} $).
- Direction: The normalized direction vector ($ \hat{d} $) indicating the orientation of the ray.
- Length: The scalar length ($ l $) along this direction from the origin.

Thus, a ray can be mathematically described as:

$$ \mathbf{r}(t) = \mathbf{o} + t \hat{d}, \quad 0 \\leq t \\leq l $$

Role in FEM Pipeline

Assembly: The RayCollisionModel does not participate directly in the assembly of global stiffness or mass matrices.
Time Integration: It is not involved in time integration schemes for dynamic simulations as it represents static geometric entities used for collision detection.
Nonlinear Solve and Linear Solve: It does not contribute to the nonlinear solve process or linear solver operations, which are central to FEM analysis.
Constraint Handling and Mapping: While RayCollisionModel may be involved in detecting contact interactions, it itself does not impose mechanical constraints on the system.
Rendering: The component provides methods for visualizing rays within the simulation environment using OpenGL rendering tools.

Numerical Methods and Discretization Choices

The discretization choices are primarily related to managing the set of rays efficiently:
- Bounding Tree Calculation: A bounding tree is computed to optimize collision detection. This involves determining a minimum bounding box for each ray, given by its origin ($ \mathbf{o} $), direction ($ \hat{d} $), and length ($ l $).

For each ray, the bounding box can be defined as:

$$ \\text{min}_{\\mathbf{e}} = \\begin{cases} o_e + d_e l & \\text{if } d_e < 0 \\\n o_e & \\text{otherwise} \\\n \end{cases},\quad \\text{max}_{\\mathbf{e}} = \\begin{cases} o_e & \\text{if } d_e < 0 \\\n o_e + d_e l & \\text{otherwise} \\\n \end{cases},\quad e \\in \{x, y, z\}$$

Translation: The applyTranslation method translates all rays by a given vector ($ \mathbf{d} = (dx, dy, dz) $), updating their origins as follows:
$$ \mathbf{o}'_i = \mathbf{o}_i + \mathbf{d}, \quad \\forall i \\in [0, N-1] $$

Broader Framework Integration

The RayCollisionModel fits into the broader variational and Lagrangian mechanics framework as a tool for collision detection. It ensures that rays can be accurately represented within the simulation space to detect intersections with other geometric models (e.g., meshes, solids). While not directly contributing to the structural or material response of deformable systems, it plays an important role in interactive applications where user inputs (like mouse clicks) need to be mapped into the simulation environment for real-time interaction.

Conclusion

In summary, RayCollisionModel is a specialized component that handles collision detection using rays. It does not contribute directly to the FEM formulation but integrates seamlessly with other components in SOFA to enable interactive and realistic simulations involving user inputs or laser pointers.

Data Fields

Name	Type	Default	Help
`d_defaultLength`	SReal		The default length for all rays in this collision model

Methods

void init () virtual

void resize (int size)

void computeBoundingTree (int maxDepth) virtual

void draw (const core::visual::VisualParams * , int index)

core::behavior::MechanicalState<defaulttype::Vec3Types> * getMechanicalState ()

int addRay (const type::Vec3 & origin, const type::Vec3 & direction, SReal length)

Ray getRay (int index)

int getNbRay ()

void setNbRay (int n)

void applyTranslation (const double dx, const double dy, const double dz)

void addContact (response::contact::BaseRayContact * contact) virtual

void removeContact (response::contact::BaseRayContact * contact) virtual

const int & getContacts ()

{
  "name": "RayCollisionModel",
  "namespace": "sofa::component::collision::geometry",
  "module": "Sofa.Component.Collision.Geometry",
  "include": "sofa/component/collision/geometry/RayCollisionModel.h",
  "doc": "Collision model representing a ray in space, e.g. a mouse click",
  "inherits": [
    "CollisionModel"
  ],
  "templates": [],
  "data_fields": [
    {
      "name": "d_defaultLength",
      "type": "SReal",
      "xmlname": "defaultLength",
      "help": "The default length for all rays in this collision model"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "resize",
      "return_type": "void",
      "params": [
        {
          "name": "size",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "computeBoundingTree",
      "return_type": "void",
      "params": [
        {
          "name": "maxDepth",
          "type": "int"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "draw",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const core::visual::VisualParams *"
        },
        {
          "name": "index",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getMechanicalState",
      "return_type": "core::behavior::MechanicalState<defaulttype::Vec3Types> *",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addRay",
      "return_type": "int",
      "params": [
        {
          "name": "origin",
          "type": "const type::Vec3 &"
        },
        {
          "name": "direction",
          "type": "const type::Vec3 &"
        },
        {
          "name": "length",
          "type": "SReal"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getRay",
      "return_type": "Ray",
      "params": [
        {
          "name": "index",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getNbRay",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setNbRay",
      "return_type": "void",
      "params": [
        {
          "name": "n",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyTranslation",
      "return_type": "void",
      "params": [
        {
          "name": "dx",
          "type": "const double"
        },
        {
          "name": "dy",
          "type": "const double"
        },
        {
          "name": "dz",
          "type": "const double"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addContact",
      "return_type": "void",
      "params": [
        {
          "name": "contact",
          "type": "response::contact::BaseRayContact *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "removeContact",
      "return_type": "void",
      "params": [
        {
          "name": "contact",
          "type": "response::contact::BaseRayContact *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getContacts",
      "return_type": "const int &",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `RayCollisionModel` component in the SOFA framework represents collision models for rays, such as those used to simulate mouse clicks or laser pointers. It inherits from the general `CollisionModel` class and is part of the `sofa::component::collision::geometry` namespace. This component manages a set of rays defined by an origin, direction, and length.\n\n### Role in SOFA Ecosystem:\n- **Ray Representation**: The primary role of `RayCollisionModel` is to represent one or more rays within the simulation space for collision detection purposes.\n- **Interaction**: It interacts with other components such as `MechanicalState`, `VisualParams`, and contact response classes like `BaseRayContact` for handling collisions.\n\n### Interactions with Other Components:\n- The component initializes and resizes its internal data structures to manage rays.\n- It computes bounding trees (necessary for efficient collision detection) using methods inherited from the parent class.\n- It handles rendering through a `draw` method that visualizes each ray in OpenGL.\n- Contacts are managed via `addContact`, `removeContact`, and `getContacts` methods, which interact with the contact response system.\n\n### Practical Usage Guidance:\n- **Data Fields**: The component contains a data field `d_defaultLength` to set the default length for all rays within this collision model.\n- **Methods**: \n  - `addRay`, `getRay`, and related methods manage individual ray data such as origin, direction, and length.\n  - `resize` adjusts the number of rays in the model.\n  - The `applyTranslation` method translates all rays by a given vector.\n- **Initialization**: The component requires a mechanical state (Vec3 type) to be present in its context for proper functioning.",
  "maths": "The `RayCollisionModel` component in the SOFA framework is designed to represent one or more rays within the simulation space for collision detection purposes. This component does not directly contribute to the governing equations of FEM, such as mass matrix (\\( M \\)), stiffness matrix (\\( K \\)), internal force vector (\\( f_{int} \\)), residual (\\( R \\)), etc., which are typically associated with structural mechanics and material behavior. Instead, it is primarily concerned with defining and managing the geometric properties of rays for collision detection.\n\n### Geometric Representation\n\nEach ray in this model is defined by three key parameters:\n- **Origin**: The starting point of the ray (\\( \\mathbf{o} \\)).\n- **Direction**: The normalized direction vector (\\( \\hat{d} \\)) indicating the orientation of the ray.\n- **Length**: The scalar length (\\( l \\)) along this direction from the origin.\n\nThus, a ray can be mathematically described as:\n\n\\[ \\mathbf{r}(t) = \\mathbf{o} + t \\hat{d}, \\quad 0 \\\\leq t \\\\leq l \\]\n\n### Role in FEM Pipeline\n\n1. **Assembly**: The `RayCollisionModel` does not participate directly in the assembly of global stiffness or mass matrices.\n2. **Time Integration**: It is not involved in time integration schemes for dynamic simulations as it represents static geometric entities used for collision detection.\n3. **Nonlinear Solve and Linear Solve**: It does not contribute to the nonlinear solve process or linear solver operations, which are central to FEM analysis.\n4. **Constraint Handling and Mapping**: While `RayCollisionModel` may be involved in detecting contact interactions, it itself does not impose mechanical constraints on the system.\n5. **Rendering**: The component provides methods for visualizing rays within the simulation environment using OpenGL rendering tools.\n\n### Numerical Methods and Discretization Choices\n\nThe discretization choices are primarily related to managing the set of rays efficiently:\n- **Bounding Tree Calculation**: A bounding tree is computed to optimize collision detection. This involves determining a minimum bounding box for each ray, given by its origin (\\( \\mathbf{o} \\)), direction (\\( \\hat{d} \\)), and length (\\( l \\)).\n\nFor each ray, the bounding box can be defined as:\n\n\\[ \\\\text{min}_{\\\\mathbf{e}} = \\\\begin{cases}\n    o_e + d_e l & \\\\text{if } d_e < 0 \\\\\\n    o_e & \\\\text{otherwise} \\\\\\n    \\end{cases},\\quad\n    \\\\text{max}_{\\\\mathbf{e}} = \\\\begin{cases}\n        o_e & \\\\text{if } d_e < 0 \\\\\\n        o_e + d_e l & \\\\text{otherwise} \\\\\\n    \\end{cases},\\quad e \\\\in \\{x, y, z\\}\\]\n\n- **Translation**: The `applyTranslation` method translates all rays by a given vector (\\( \\mathbf{d} = (dx, dy, dz) \\)), updating their origins as follows:\n    \\[ \\mathbf{o}'_i = \\mathbf{o}_i + \\mathbf{d}, \\quad \\\\forall i \\\\in [0, N-1] \\]\n\n### Broader Framework Integration\n\nThe `RayCollisionModel` fits into the broader variational and Lagrangian mechanics framework as a tool for collision detection. It ensures that rays can be accurately represented within the simulation space to detect intersections with other geometric models (e.g., meshes, solids). While not directly contributing to the structural or material response of deformable systems, it plays an important role in interactive applications where user inputs (like mouse clicks) need to be mapped into the simulation environment for real-time interaction.\n\n### Conclusion\n\nIn summary, `RayCollisionModel` is a specialized component that handles collision detection using rays. It does not contribute directly to the FEM formulation but integrates seamlessly with other components in SOFA to enable interactive and realistic simulations involving user inputs or laser pointers.",
  "abstract": "The `RayCollisionModel` represents one or more rays in the simulation space for collision detection purposes, managing their geometric properties and interactions with other components.",
  "sheet": "# RayCollisionModel\n\n**Overview**\n\nThe `RayCollisionModel` component is designed to represent and manage one or more rays within the SOFA simulation environment. It handles ray data such as origin, direction, and length, and provides methods for adding, removing, and visualizing rays. This component interacts with other components like MechanicalState and contact response classes to enable efficient collision detection.\n\n**Parameters and Data**\n\n- **defaultLength**: The default length for all rays in this collision model (`SReal` type).\n\n**Dependencies and Connections**\n\nThe `RayCollisionModel` typically requires a mechanical state (Vec3 type) to be present in its context. It interacts with other components such as MechanicalState, VisualParams, and contact response classes like BaseRayContact for handling collisions.\n\n**Practical Notes**\n\n- The component manages ray data efficiently using methods like `addRay`, `getRay`, and `resize`.\n- Bounding tree calculations are performed to optimize collision detection.\n- The `applyTranslation` method translates all rays by a given vector."
}