Data Fields

Methods

{
  "name": "MergePoints",
  "namespace": "sofa::component::engine::generate",
  "module": "Sofa.Component.Engine.Generate",
  "include": "sofa/component/engine/generate/MergePoints.h",
  "doc": "Merge 2 coordinate vectors.\n\nThis class merge 2 coordinate vectors.",
  "inherits": [
    "DataEngine"
  ],
  "templates": [
    "sofa::defaulttype::Rigid2Types",
    "sofa::defaulttype::Rigid3Types",
    "sofa::defaulttype::Vec1Types"
  ],
  "data_fields": [
    {
      "name": "f_X1",
      "type": "VecCoord",
      "xmlname": "position1",
      "help": "position coordinates of the degrees of freedom of the first object"
    },
    {
      "name": "f_X2",
      "type": "VecCoord",
      "xmlname": "position2",
      "help": "Rest position coordinates of the degrees of freedom of the second object"
    },
    {
      "name": "f_X2_mapping",
      "type": "SetIndex",
      "xmlname": "mappingX2",
      "help": "Mapping of indices to inject position2 inside position1 vertex buffer"
    },
    {
      "name": "f_indices1",
      "type": "SetIndex",
      "xmlname": "indices1",
      "help": "Indices of the points of the first object"
    },
    {
      "name": "f_indices2",
      "type": "SetIndex",
      "xmlname": "indices2",
      "help": "Indices of the points of the second object"
    },
    {
      "name": "f_points",
      "type": "VecCoord",
      "xmlname": "points",
      "help": "position coordinates resulting from the merge"
    },
    {
      "name": "f_noUpdate",
      "type": "bool",
      "xmlname": "noUpdate",
      "help": "do not update the output at each time step (false)"
    }
  ],
  "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"
    }
  ],
  "description": "The **MergePoints** component in the SOFA framework is designed to merge two coordinate vectors, typically representing positions from two different objects or parts of an object. This merging operation can be used for combining multiple mesh components into a single set of points, which is useful in various simulation scenarios involving composite structures.\n\n### Role and Purpose:\nThe `MergePoints` component inherits from the `DataEngine`, indicating that it operates as part of the data processing pipeline within SOFA simulations. It merges two coordinate vectors (`f_X1` and `f_X2`) into a single output vector (`f_points`). The merging can be done in either an injection mode or addition mode, depending on whether a mapping is provided (`f_X2_mapping`).\n\n### Interactions with Other Components:\nThe component interacts primarily through its data fields with other SOFA components. It takes as input the position coordinates of two objects and produces merged indices for each object's points along with the combined set of coordinates. This output can be used by subsequent components in the pipeline, such as visualizers or further processing engines.\n\n### Practical Usage Guidance:\nThe `MergePoints` component requires the following data fields to be provided or configured:\n- **f_X1**: Position coordinates of the degrees of freedom of the first object (`VecCoord`).\n- **f_X2**: Rest position coordinates of the second object (`VecCoord`).\n- **f_X2_mapping** (optional): A mapping that specifies where points from `f_X2` should be inserted into `f_X1` if in injection mode.\n\nThe component also outputs:\n- **f_indices1**: Indices of the points corresponding to the first object (`SetIndex`).\n- **f_indices2**: Indices of the points corresponding to the second object (`SetIndex`).\n- **f_points**: Combined position coordinates from both objects (`VecCoord`).\n\nThe `f_noUpdate` flag can be set to prevent the component from updating its output at each simulation step if it is not required.\n\n### Usage Example:\nThe component can be used in scenarios where two separate parts of a structure need to be merged into a single mesh for visualization or further processing. For example, combining different body segments in a biomechanical simulation.",
  "maths": "The **MergePoints** component in the SOFA framework is designed to merge two coordinate vectors, typically representing positions from two different objects or parts of an object. This merging operation can be used for combining multiple mesh components into a single set of points, which is useful in various simulation scenarios involving composite structures.\n\n### Governing Equations and Operators:\nThe MergePoints component does not implement any governing equations related to the physics or constitutive laws of materials directly. Instead, it operates at the level of data management and merging coordinates from two different sources.\n\nGiven two coordinate vectors \\( \textbf{x}_1 \\) and \\( \textbf{x}_2 \\):\n- **f_X1** (position coordinates of the first object)\n- **f_X2** (rest position coordinates of the second object)\n\nThe component merges these vectors into a single output vector \\( \textbf{p} \\) based on two modes:\n\n#### Addition Mode\nIn this mode, if no mapping is provided (`f_X2_mapping`), the component simply concatenates the two coordinate vectors:\n\\[\n\textbf{p} = [\textbf{x}_1; \textbf{x}_2]\n\\]\nwhere \\( [\textbf{x}_1; \textbf{x}_2] \\) denotes vector concatenation.\n\n#### Injection Mode\nIn this mode, if a mapping is provided (`f_X2_mapping`), the component injects points from \\( \textbf{x}_2 \\) into specified positions in \\( \textbf{x}_1 \\). The mapping provides indices where each point of \\( \textbf{x}_2 \\) should be inserted into \\( \textbf{x}_1 \\).\n\nThe resulting vector is updated based on the provided mapping:\n\\[\n\textbf{p}[posX] = \textbf{x}_2[i]\n\\]\nwhere \\( posX \\) is the position index in \\( \textbf{p} \\) determined by the mapping.\n\n### Constitutive and Kinematic Laws Involved:\nThe MergePoints component does not involve any constitutive or kinematic laws. It purely operates on coordinate vectors, which are typically inputs from other components such as mesh generators, deformable object models, or external data sources.\n\n### Role in the Global FEM Pipeline:\nThe role of MergePoints is to manage and merge data rather than contribute directly to the physics simulation pipeline. Specifically:\n- **Assembly**: It does not contribute to assembling mass matrices, stiffness matrices, internal forces, residuals, or Jacobians.\n- **Time Integration**: It does not participate in time integration schemes like implicit Euler or Newmark methods.\n- **Nonlinear Solve**: It is not involved in the nonlinear solve process.\n- **Linear Solve**: It does not contribute to linear solver operations.\n- **Constraint Handling and Mapping**: It can be used as a preprocessing step before applying constraints or mappings, but it does not handle these directly.\n\n### Numerical Methods or Discretization Choices:\nThe MergePoints component uses straightforward data manipulation techniques without any specific numerical discretization choices. The only decision-making involves whether to use addition mode or injection mode based on the presence of a mapping vector.\n\n### Integration into Variational / Lagrangian Mechanics Framework:\nThe MergePoints component does not integrate directly into the variational or Lagrangian mechanics framework, as it is purely a data management tool. It can be used in conjunction with components that handle these frameworks by providing combined coordinate sets for further processing.\n\nIn summary, while MergePoints is an essential tool for combining different parts of a structure within SOFA simulations, its mathematical content is limited to basic vector operations without any direct involvement in the underlying physics or mechanics equations.",
  "abstract": "The MergePoints component merges two coordinate vectors into one, facilitating the combination of multiple mesh components or object parts in SOFA simulations.",
  "sheet": "# MergePoints\n\n## Overview\n\nMergePoints inherits from `DataEngine` and is designed to merge two coordinate vectors (`f_X1` and `f_X2`) into a single output vector (`f_points`). This component can be used for combining different mesh components or object parts in SOFA simulations.\n\n## Parameters and Data\n\n- **f_X1**: Position coordinates of the degrees of freedom of the first object (`VecCoord`).\n- **f_X2**: Rest position coordinates of the second object (`VecCoord`).\n- **f_X2_mapping** (optional): A mapping that specifies where points from `f_X2` should be inserted into `f_X1` if in injection mode (`SetIndex`).\n- **f_indices1**: Indices of the points corresponding to the first object (`SetIndex`).\n- **f_indices2**: Indices of the points corresponding to the second object (`SetIndex`).\n- **f_points**: Combined position coordinates from both objects (`VecCoord`).\n- **f_noUpdate**: A boolean flag that prevents the component from updating its output at each simulation step if set to `true` (default is `false`)."
}