Data Fields

Methods

{
  "name": "NearestPointROI",
  "namespace": "sofa::component::engine::select",
  "module": "Sofa.Component.Engine.Select",
  "include": "sofa/component/engine/select/NearestPointROI.h",
  "doc": "Attach given pair of particles, projecting the positions of the second particles to the first ones.\n\nGiven two mechanical states, find correspondence between degrees of freedom, based on the minimal distance.\nProject all the points from the second mechanical state on the first one. This done by finding the point in the\nfirst mechanical state closest to each point in the second mechanical state. If the distance is less than a provided\ndistance (named radius), the indices of the degrees of freedom in their respective mechanical states is added to\nan output list.",
  "inherits": [
    "DataEngine"
  ],
  "templates": [
    "sofa::sofa::defaulttype::Rigid2Types",
    "sofa::sofa::defaulttype::Rigid3Types",
    "sofa::sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "f_radius",
      "type": "Real",
      "xmlname": "radius",
      "help": "Radius to search corresponding fixed point"
    },
    {
      "name": "d_useRestPosition",
      "type": "bool",
      "xmlname": "useRestPosition",
      "help": "If true will use restPosition only at init"
    },
    {
      "name": "d_drawPairs",
      "type": "bool",
      "xmlname": "drawPairs",
      "help": "Option to draw the positions pairs computed"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "reinit",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "doUpdate",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "draw",
      "return_type": "void",
      "params": [
        {
          "name": "vparams",
          "type": "const core::visual::VisualParams *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "computeNearestPointMaps",
      "return_type": "void",
      "params": [
        {
          "name": "x1",
          "type": "const VecCoord &"
        },
        {
          "name": "x2",
          "type": "const VecCoord &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `NearestPointROI` component is part of the SOFA framework's engine module, specifically designed for selecting and processing pairs of particles based on their proximity within two mechanical states. This component inherits from `DataEngine`, indicating it processes data to generate new outputs. It facilitates the projection of positions from one set of particles onto another by identifying nearest points within a specified radius (`f_radius`).\n\nThe component accepts two sets of indices (`d_inputIndices1` and `d_inputIndices2`) that define which points in each mechanical state should be considered for pairing. The output includes the indices of paired degrees of freedom from both states, edge lists connecting pairs, index pairs, and distances between them.\n\nThe component can use rest positions or current positions based on the `d_useRestPosition` flag. Additionally, it offers an option to visualize these pairings (`d_drawPairs`). The process involves initializing connections (`init()`), reinitializing parameters (`reinit()`), computing nearest point maps (`computeNearestPointMaps()`), and drawing visual representations of pairs (`draw()`).\n\nThis component interacts with mechanical states through `core::behavior::MechanicalState` interfaces, enabling it to work seamlessly within the SOFA simulation environment for tasks requiring proximity-based particle interactions.",
  "maths": "The `NearestPointROI` component in the SOFA framework is designed to project positions from one set of particles onto another based on their proximity. The primary role of this component is to establish a mapping between two mechanical states, identifying pairs of points that are closest within a specified radius (`f_radius`). This component does not directly contribute to governing equations or operators such as the mass matrix $M$, stiffness matrix $K$, internal force $f_{int}$, or residual $R$. Instead, it focuses on providing data-driven mappings and constraints between degrees of freedom (DOFs) in two mechanical states. The role in the FEM pipeline is mainly related to mapping and constraint projection, rather than directly contributing to the nonlinear solve, linear solve, or assembly phases.\n\n### Mathematical Description:\n- **Nearest Point Projection:** Given two sets of points $x_1 \text{ and } x_2$, each representing positions in one mechanical state, the component identifies for each point in $x_2$ the nearest point in $x_1$. The distance between these pairs is calculated using a Euclidean norm:\n  \\[ d(x_{2,i}, x_{1,j}) = \norm{x_{2,i} - x_{1,j}}^2 \\]\n- **Distance Threshold:** Only pairs where this distance is less than the specified radius (`f_radius`) are retained. This filtering ensures that only proximate points influence each other.\n  \\[ d(x_{2,i}, x_{1,j}) < f_{radius}^2 \\]\n\n### Physical Description:\n- **Proximity-Based Mapping:** The component's primary function is to establish a proximity-based mapping between two sets of particles. This can be useful in scenarios where one mechanical state acts as an attachment or constraint for another, such as simulating surgical instruments interacting with soft tissues.\n  - For each point $x_{2,i}$ in the second mechanical state, the nearest point $x_{1,j}$ in the first mechanical state is identified if it lies within the specified radius.\n- **Indices and Distances:** The output includes lists of indices (`f_indices1` and `f_indices2`) corresponding to the paired points, a list of edges connecting these pairs (`d_edges`), a list of index pairs (`d_indexPairs`), and a list of distances between them (`d_distances`).\n- **Visualization Option:** An optional flag (`d_drawPairs`) allows for visualizing these pairings during simulation.\n\n### Numerical Methods:\n- The component uses a straightforward nearest neighbor search algorithm, where the distance is computed using the Euclidean norm. The computational complexity of this process depends on the number of points in each mechanical state and can be optimized through data structures such as kd-trees or spatial hashing for large datasets.\n\n### Role in FEM Pipeline:\n- **Mapping:** This component primarily serves to establish mappings between DOFs, which can be used for constraint projection, multi-resolution coupling, or attachment mechanisms within the broader simulation framework. These mappings do not directly influence the governing equations but provide the necessary data for enforcing constraints or applying forces in a physics-based manner.\n\n### Variational / Lagrangian Mechanics Framework:\n- The `NearestPointROI` component does not explicitly contribute to variational formulations or Lagrangian mechanics. Instead, it provides a preprocessing step that enables more complex interactions within the simulation environment, such as enforcing constraints or defining attachments between different mechanical states.",
  "abstract": "The `NearestPointROI` component projects positions from one set of particles onto another based on their proximity within a specified radius, establishing mappings between degrees of freedom in two mechanical states.",
  "sheet": "# NearestPointROI\n\n## Overview\nThe `NearestPointROI` component is part of the SOFA framework's engine module. It processes data to project positions from one set of particles onto another based on their proximity within a specified radius (`f_radius`). This component establishes mappings between degrees of freedom in two mechanical states, facilitating tasks requiring proximity-based particle interactions.\n\n## Parameters and Data\n- **`f_radius`:** Radius to search for corresponding fixed points. Type: `Real`, Default: Not specified.\n- **`d_useRestPosition`:** If true, uses rest positions only at initialization. Type: `bool`, Default: Not specified.\n- **`d_drawPairs`:** Option to draw the computed position pairs. Type: `bool`, Default: Not specified.\n\n## Dependencies and Connections\nThe component typically requires two mechanical states as inputs and exchanges data with components that manage these states, such as those handling degrees of freedom or positions. It fits into the scene graph by providing mappings between DOFs in different mechanical states."
}