Mathematical and Physical Description of MechanicalPickParticlesWithTagsVisitor

Methods

{
  "name": "MechanicalPickParticlesWithTagsVisitor",
  "namespace": "sofa::simulation::mechanicalvisitor",
  "module": "Sofa.framework.Simulation.Core",
  "include": "sofa/simulation/mechanicalvisitor/MechanicalPickParticlesWithTagsVisitor.h",
  "doc": "Find mechanical particles hit by the given ray on dof containing one tag or all provided by a tag list\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": "unsigned int &"
        },
        {
          "name": "point",
          "type": "type::Vec3 &"
        },
        {
          "name": "rayLength",
          "type": "SReal &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `MechanicalPickParticlesWithTagsVisitor` is part of the SOFA framework's Simulation.Core module and inherits from `BaseMechanicalVisitor`. It is designed to find mechanical particles (2D or 3D positions or rigid DOFs) that are hit by a given ray, specifically those associated with degrees-of-freedom (DOFs) containing one or all tags provided in a list. The component facilitates the selection of specific particles based on their tags and interaction with rays for picking operations.\n\n### Interactions with Other Components:\n- **`BaseMechanicalState`:** The visitor interacts with `BaseMechanicalState` components to gather and process mechanical state information. It checks if each `BaseMechanicalState` component should be included in the pick operation based on its tags.\n- **`BaseMapping`:** This component handles mechanical mappings, which are used to link different mechanical states (e.g., free DOFs to constrained ones).\n\n### Practical Usage:\nThis visitor is typically used within a simulation scenario where specific particles need to be selected or interacted with based on their tags and proximity to a ray. It supports picking operations in scenarios such as surgical simulations, haptics, and interactive simulations where precise particle selection is necessary.\n\n#### Data Fields:\n- `rayOrigin` (type::Vec3d): The origin of the ray used for particle picking.\n- `rayDirection` (type::Vec3d): The direction vector of the ray used for particle picking.\n- `radius0` (double): Initial radius used in particle selection.\n- `dRadius` (double): Incremental radius used in particle selection.\n- `tags` (std::list<sofa::core::objectmodel::Tag>): List of tags to filter the mechanical particles.\n- `mustContainAllTags` (bool): Flag indicating whether all provided tags must be present for a particle to be included.",
  "maths": "<maths_md_description>\n# Mathematical and Physical Description of `MechanicalPickParticlesWithTagsVisitor`\n\n## Overview\nThe `MechanicalPickParticlesWithTagsVisitor` is a visitor component in the SOFA framework designed to identify mechanical particles that are intersected by a given ray. These particles can be associated with degrees-of-freedom (DOFs) containing specific tags, which allows for selective particle picking based on predefined criteria.\n\n## Governing Equations and Operators\nThe `MechanicalPickParticlesWithTagsVisitor` does not directly contribute to the governing equations or operators typically found in a Finite Element Method (FEM) simulation pipeline. It is primarily a utility component that facilitates the selection of specific mechanical particles for interaction, such as picking operations.\n\n## Constitutive and Kinematic Laws\nThe `MechanicalPickParticlesWithTagsVisitor` does not involve constitutive laws, strain measures, or stress tensors. Its primary function is to identify particles based on their position relative to a given ray and the presence of specific tags. The component checks if each mechanical state contains one or all of the provided tags before performing particle picking.\n\n## Role in FEM Pipeline\nThe `MechanicalPickParticlesWithTagsVisitor` operates outside the core FEM pipeline, which typically includes stages such as spatial discretization, time integration, nonlinear solution, and linear resolution. Instead, it serves a role in post-processing or interactive operations:\n- **Assembly**: It does not contribute to the assembly of global matrices (e.g., mass matrix $M$, stiffness matrix $K$).\n- **Time Integration**: It is not involved in time integration schemes.\n- **Nonlinear Resolution**: It does not participate in nonlinear solution procedures.\n- **Linear Resolution**: It is not part of linear solve operations.\n\n## Numerical Methods and Discretization Choices\nThe `MechanicalPickParticlesWithTagsVisitor` utilizes a simple ray-picking algorithm to identify particles that lie along the given ray. The algorithm checks if each mechanical state contains one or all provided tags, then performs picking based on the particle's proximity to the ray.\n- **Ray-Picking**: The component uses the origin (`rayOrigin`) and direction (`rayDirection`) of a ray to determine which particles intersect with it.\n\n## Variational / Lagrangian Mechanics Framework\nThe `MechanicalPickParticlesWithTagsVisitor` does not directly contribute to variational or Lagrangian mechanics frameworks. Its role is purely computational, aimed at selecting specific mechanical particles for interactive operations such as picking.\n\n### Summary of Mathematical Content\n- The component does not involve governing equations related to FEM simulation (e.g., mass matrix $M$, stiffness matrix $K$, internal force $f_{int}$).\n- It operates on the basis of simple geometric checks and tag-based filtering for particle selection.\n</maths_md_description>",
  "abstract": "Identifies mechanical particles hit by a given ray based on specified tags, facilitating selective particle picking operations.",
  "sheet": "# MechanicalPickParticlesWithTagsVisitor\n\n## Overview\nThe `MechanicalPickParticlesWithTagsVisitor` is a utility component in the SOFA framework designed to identify mechanical particles that are intersected by a given ray. These particles can be associated with degrees-of-freedom (DOFs) containing specific tags, which allows for selective particle picking based on predefined criteria.\n\n## Parameters and Data\n- `rayOrigin` (type::Vec3d): The origin of the ray used for particle picking.\n- `rayDirection` (type::Vec3d): The direction vector of the ray used for particle picking.\n- `radius0` (double): Initial radius used in particle selection.\n- `dRadius` (double): Incremental radius used in particle selection.\n- `tags` (std::list<sofa::core::objectmodel::Tag>): List of tags to filter the mechanical particles.\n- `mustContainAllTags` (bool): Flag indicating whether all provided tags must be present for a particle to be included."
}