Methods

{
  "name": "MechanicalPickParticlesVisitor",
  "namespace": "sofa::simulation::mechanicalvisitor",
  "module": "Sofa.framework.Simulation.Core",
  "include": "sofa/simulation/mechanicalvisitor/MechanicalPickParticlesVisitor.h",
  "doc": "Find mechanical particles hit by the given ray.\n A mechanical particle is defined as a 2D or 3D, position or rigid DOF\n which is linked to the free mechanical DOFs by mechanical mappings",
  "inherits": [
    "BaseMechanicalVisitor"
  ],
  "templates": [],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "fwdMechanicalState",
      "return_type": "Result",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "mm",
          "type": "sofa::core::behavior::BaseMechanicalState *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "fwdMechanicalMapping",
      "return_type": "Result",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "map",
          "type": "sofa::core::BaseMapping *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "fwdMappedMechanicalState",
      "return_type": "Result",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "mm",
          "type": "sofa::core::behavior::BaseMechanicalState *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getClosestParticle",
      "return_type": "void",
      "params": [
        {
          "name": "mstate",
          "type": "sofa::core::behavior::BaseMechanicalState *&"
        },
        {
          "name": "indexCollisionElement",
          "type": "int &"
        },
        {
          "name": "point",
          "type": "type::Vec3 &"
        },
        {
          "name": "rayLength",
          "type": "SReal &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `MechanicalPickParticlesVisitor` is a visitor component in the SOFA framework designed to find mechanical particles that are hit by a given ray. It operates within the simulation's scene graph, interacting with various mechanical states and mappings to identify pickable particles based on their positions relative to the specified ray.\n\nThis component inherits from `BaseMechanicalVisitor`, which provides a foundational structure for traversing the mechanical elements of a SOFA simulation. Its primary methods include:\n- `fwdMechanicalState`: Handles the forward traversal of mechanical states, checking if picking is enabled and whether the model is static or simulated.\n- `fwdMappedMechanicalState`: Similar to `fwdMechanicalState`, but specifically deals with mapped mechanical states.\n- `fwdMechanicalMapping`: Manages the traversal through mappings between mechanical states.\n- `getClosestParticle`: Returns the closest pickable particle along the ray, sorting particles by their distance from the ray and selecting the nearest one.\n\n`MechanicalPickParticlesVisitor` relies on its internal state to store information about the ray (origin and direction) and the radius of the picking area. It also maintains a list of identified particles in `particles`, which is used to determine the closest particle hit by the ray.",
  "maths": "The `MechanicalPickParticlesVisitor` is a visitor component in the SOFA framework designed to identify mechanical particles that are hit by a given ray. It operates within the simulation's scene graph, interacting with various mechanical states and mappings to determine which particles intersect with the specified ray.\n\n### Governing Equations or Operators:\n- **Mechanical State Interaction:** The visitor interacts with `BaseMechanicalState` objects to obtain particle positions. For a given set of mechanical particles, their positions are denoted by vectors \\(\\mathbf{p}_i = (x_i, y_i, z_i)\\), where \\(i\\) indexes the particles.\n- **Ray Definition:** The ray is defined by its origin \\(\boldsymbol{o} = (o_x, o_y, o_z)\\) and direction vector \\(\boldsymbol{d} = (d_x, d_y, d_z)\\). Any point on the ray can be parameterized as:\n  \n  \n  \\[ \\mathbf{r}(t) = \\boldsymbol{o} + t \\cdot \\boldsymbol{d}, \\quad t \\in [0, \\infty) \\]\n\n### Constitutive or Kinematic Laws Involved:\n- **Distance Calculation:** The distance from a particle position \\(\boldsymbol{p}_i\\) to the ray is computed using the formula for the perpendicular distance between a point and a line in 3D. This involves finding the minimum distance along the direction vector of the ray.\n\n### Role in the Global FEM Pipeline:\n- **Traversal:** The visitor traverses the mechanical states and mappings within the SOFA scene graph to identify pickable particles. It checks if picking is enabled for each `BaseMechanicalState` and ensures that static objects (not simulated) are excluded from consideration.\n- **Identification:** Once the mechanical state interactions have been processed, the visitor identifies all particles that lie along or near the ray based on their positions relative to the specified ray origin and direction. These particles are stored in an internal list sorted by distance to the ray.\n\n### Numerical Methods or Discretization Choices:\n- **Picking Area Radius:** The visitor uses a picking area radius \\(r_0\\) and a tolerance value \\(\text{dRadius}\\). Particles within this tolerance range from the closest point on the ray are considered for selection. The threshold distance is defined as:\n  \n  \\[ d_{max} = d + r_0 \\times 10^{-10}, \\]\n  where \\(d\\) is the shortest distance to the ray.\n- **Sorting and Selection:** Particles are sorted by their distances from the ray, and the closest one within the tolerance range is selected as the final pickable particle. The distance along the ray direction for each candidate point is computed as:\n  \n  \\[ t = (\\mathbf{p}_i - \\boldsymbol{o}) \\cdot \\boldsymbol{d}, \\]\n  where \\(t\\) represents the parametric position of the intersection along the ray.\n\n### Integration into Variational / Lagrangian Mechanics Framework:\n- **Mechanical State Context:** The visitor operates on mechanical states, which are part of the broader variational mechanics framework. Each `BaseMechanicalState` contains information about particle positions and may be linked through mappings to other mechanical states representing different levels of detail or constraints.\n\n### Summary:\nThe `MechanicalPickParticlesVisitor` is primarily concerned with identifying particles that intersect a given ray within the SOFA simulation environment. It does not directly contribute to governing equations like mass matrices, stiffness matrices, internal forces, or residuals but plays an important role in user interaction and visualization by providing a method for selecting mechanical elements based on their spatial relationships.",
  "abstract": "Identifies mechanical particles intersecting a specified ray in SOFA simulations, facilitating user interaction and visualization.",
  "sheet": "# MechanicalPickParticlesVisitor\n\n**Overview:**\nMechanicalPickParticlesVisitor is a visitor component that identifies mechanical particles hit by a given ray. It operates within the simulation's scene graph to determine which particles are closest to the ray based on their positions relative to the specified ray origin and direction.\n\nThe component interacts with `BaseMechanicalState` objects to obtain particle positions and uses methods such as `fwdMechanicalState`, `fwdMappedMechanicalState`, and `fwdMechanicalMapping` for traversal. It also includes a method, `getClosestParticle`, which returns the closest pickable particle along the ray.\n\n**Dependencies and Connections:**\nThe component typically requires interaction with mechanical states (`BaseMechanicalState`) and mappings (`BaseMapping`). It fits into the scene graph by traversing these components to identify particles that intersect with a given ray.\n\n**Practical Notes:**\nPicking operations are sensitive to numerical precision, particularly in determining the closest particle. The picking area radius and tolerance values must be carefully configured to ensure accurate selection of particles."
}