Data Fields

Methods

{
  "name": "ProximityROI",
  "namespace": "sofa::component::engine::select",
  "module": "Sofa.Component.Engine.Select",
  "include": "sofa/component/engine/select/ProximityROI.h",
  "doc": "Find the N closest primitives from a given position.\n\nThis class find the point at a given distance from a set of points",
  "inherits": [
    "DataEngine"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "f_num",
      "type": "unsigned int",
      "xmlname": "N",
      "help": "Maximum number of points to select"
    },
    {
      "name": "f_X0",
      "type": "VecCoord",
      "xmlname": "position",
      "help": "Rest position coordinates of the degrees of freedom"
    },
    {
      "name": "f_indices",
      "type": "SetIndex",
      "xmlname": "indices",
      "help": "Indices of the points contained in the ROI"
    },
    {
      "name": "f_pointsInROI",
      "type": "VecCoord",
      "xmlname": "pointsInROI",
      "help": "Points contained in the ROI"
    },
    {
      "name": "f_indicesOut",
      "type": "SetIndex",
      "xmlname": "indicesOut",
      "help": "Indices of the points not contained in the ROI"
    },
    {
      "name": "p_drawSphere",
      "type": "bool",
      "xmlname": "drawSphere",
      "help": "Draw sphere(s)"
    },
    {
      "name": "p_drawPoints",
      "type": "bool",
      "xmlname": "drawPoints",
      "help": "Draw Points"
    },
    {
      "name": "_drawSize",
      "type": "double",
      "xmlname": "drawSize",
      "help": "rendering size for box and topological elements"
    }
  ],
  "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": "canCreate",
      "return_type": "bool",
      "params": [
        {
          "name": "obj",
          "type": "T *&"
        },
        {
          "name": "context",
          "type": "core::objectmodel::BaseContext *"
        },
        {
          "name": "arg",
          "type": "core::objectmodel::BaseObjectDescription *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "public"
    }
  ],
  "description": "The **ProximityROI** is an engine component in the SofaPhysics simulation framework that identifies points within a specified proximity to given reference positions (centers). It can be used for various applications, such as point cloud analysis or selecting specific elements based on their distance from predefined locations.",
  "details": {
    "functionality": [
      "The **ProximityROI** component determines the N closest primitives (points) from one or more specified center positions within a given radius.",
      "It supports visualization of both the selected points and spheres representing the defined proximity regions if enabled through parameters."
    ],
    "parameters": {
      "centers": "A vector of 3D coordinates defining the centers of spherical regions where points are to be identified.",
      "radii": "A vector specifying the radii for each center, defining the size of the spherical region around each center.",
      "f_num": "The maximum number of closest points to select from all the defined proximity regions.",
      "p_drawSphere": "Boolean parameter to control whether spheres representing the defined proximity regions are drawn during visualization.",
      "p_drawPoints": "Boolean parameter to enable or disable drawing of identified points within the specified proximity."
    },
    "inputs": {
      "f_X0": "Input data representing the rest positions (coordinates) of all degrees of freedom that need to be checked against the defined proximity regions."
    },
    "outputs": [
      "f_indices: Indices of the points contained in the region of interest.",
      "f_pointsInROI: Coordinates of identified points within the defined proximity regions.",
      "f_distanceInROI: Distances between each selected point and its closest center.",
      "f_indicesOut: Indices of points not included in any defined proximity region."
    ],
    "methods": {
      "init": "Initialization method that sets up internal parameters and performs initial configurations.",
      "reinit": "Reinitialization method called whenever the component's configuration changes, ensuring consistency across simulations.",
      "doUpdate": "Core update method which evaluates the distances from specified centers to all input points and selects those within defined proximity regions.",
      "draw": "Method for rendering spheres representing the proximity regions and selected points if visualization is enabled."
    },
    "template_support": [
      "The component can be instantiated with different data types, allowing flexibility in handling various coordinate formats depending on simulation requirements."
    ],
    "usage_example": [
      "This engine can be particularly useful in scenarios requiring identification or selection of specific elements based on their proximity to one or more reference positions. Examples include selecting particles within a certain distance from key anatomical landmarks in biomechanics simulations, or identifying atoms close to particular sites in molecular dynamics."
    ]
  },
  "maths": "The **ProximityROI** component in the SOFA framework is designed to find points within a specified proximity (distance) from given reference positions, known as centers. This component operates on the rest position coordinates of degrees of freedom and selects points based on their distance from predefined centers. It provides indices of points that lie within specified distances (radii) and can output these points and their respective distances to the closest center.\n\n### Governing Equations\nThe ProximityROI does not directly contribute to any governing equations in terms of mass matrix \\(M\\), stiffness matrix \\(K\\), internal forces \\(f_{int}\\), or residuals \\(R\\). Instead, it serves as an engine that processes and selects points based on geometric criteria. The primary operation involves determining the distance between a point and each center:\n\n\begin{equation}\n    \text{dist}(i,j) = ||\boldsymbol{x}_0^i - \boldsymbol{c}^j||\n\tag{1}\n\raisetag{-2em}\n\text{where }\boldsymbol{x}_0^i \text{ is the position of point } i, \\text{ and }\\boldsymbol{c}^j \text{ is the center of sphere } j.\n\raisetag{-3em}\n\tag{2}\n\raisetag{-1em}\n\raisetag{-1em}\n\raisetag{-1em}\n\raisetag{-1em}\n\raisetag{-1em}\n\raisetag{-1em}\n\raisetag{-1em}\n\raisetag{-1em}\n\n### Constitutive or Kinematic Laws Involved\n- **Distance Calculation**: The Euclidean distance is used to determine if a point lies within the specified radius of any center.\n- **Sorting and Selection**: Points are sorted based on their distances from centers, and the top \\(N\\) points (where \\(N\\) is user-defined) are selected. If multiple spheres are defined, the minimum distance between each point and all centers is used for selection.\n\n### Role in FEM Pipeline\nThe ProximityROI operates outside of the core mechanical simulation pipeline; it does not directly contribute to assembling or solving equations. Its role includes:\n- **Preprocessing**: Identifying and selecting points based on their spatial proximity.\n- **Postprocessing**: Providing indices, coordinates, and distances for further analysis or visualization.\n\n### Numerical Methods and Discretization Choices\nThe component uses simple geometric distance calculations to determine if a point lies within the specified radius of any center. The primary numerical method involves sorting points based on their minimum distance from centers using a heap sort algorithm, ensuring efficient selection of up to \\(N\\) closest points.\n\n### Integration into Variational / Lagrangian Mechanics Framework\nThe ProximityROI does not directly integrate into the variational or Lagrangian mechanics framework. Instead, it serves as an auxiliary tool for preprocessing and postprocessing within the simulation pipeline, enabling users to analyze and manipulate point cloud data based on geometric criteria.",
  "abstract": "Identifies points within specified distances from given centers, providing indices of selected points and their coordinates.",
  "sheet": "# ProximityROI\n\n**Overview:**\nThe `ProximityROI` component identifies the N closest primitives (points) to a set of reference positions. It operates on rest position coordinates and provides indices and coordinates of points within specified distances from predefined centers.\n\n**Parameters and Data:*\n- **N (`f_num`, unsigned int):** Maximum number of points to select.\n- **position (`f_X0`, VecCoord):** Rest position coordinates of the degrees of freedom.\n- **indices (`f_indices`, SetIndex):** Indices of the points contained in the ROI.\n- **pointsInROI (`f_pointsInROI`, VecCoord):** Points contained in the ROI.\n- **indicesOut (`f_indicesOut`, SetIndex):** Indices of the points not contained in the ROI.\n- **drawSphere (`p_drawSphere`, bool):** Draw sphere(s).\n- **drawPoints (`p_drawPoints`, bool):** Draw points.\n- **drawSize (`_drawSize`, double):** Rendering size for box and topological elements.\n\n**Dependencies and Connections:**\nThe `ProximityROI` component is typically used in conjunction with other components that provide rest position coordinates (e.g., `MechanicalObject`). It can be connected to visualization or further processing components based on the selected points.\n\n**Practical Notes:**\n- Ensure that the number of points (`N`) is set appropriately for efficient selection and analysis.\n- The component uses geometric distance calculations, which are straightforward but may require careful tuning depending on the application."
}