{
  "name": "JoinPoints",
  "main": {
    "name": "JoinPoints",
    "namespace": "sofa::component::engine::generate",
    "module": "Sofa.Component.Engine.Generate",
    "include": "sofa/component/engine/generate/JoinPoints.h",
    "doc": "Merge points from a set of points within a given distance.",
    "inherits": [
      "DataEngine"
    ],
    "templates": [
      "sofa::defaulttype::Vec3Types"
    ],
    "data_fields": [
      {
        "name": "f_points",
        "type": "VecCoord",
        "xmlname": "points",
        "help": "Points"
      },
      {
        "name": "f_distance",
        "type": "Real",
        "xmlname": "distance",
        "help": "Distance to merge points"
      },
      {
        "name": "f_mergedPoints",
        "type": "VecCoord",
        "xmlname": "mergedPoints",
        "help": "Merged Points"
      }
    ],
    "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"
      }
    ]
  },
  "desc": {
    "description": "The `JoinPoints` component in SOFA is designed to merge points from a set of input points if they are within a specified distance, effectively reducing the number of points while maintaining their average position. This component inherits from the `DataEngine`, which indicates it processes data and provides output based on that processing.\n\n**Role and Purpose:**\n- The primary role of `JoinPoints` is to reduce point cloud density by merging nearby points into a single representative point, calculated as an average of the merged points. This can be useful in scenarios where high-resolution point clouds are simplified for efficiency or visualization purposes.\n\n**Interactions with Other Components:*\n- `JoinPoints` interacts with other components through its data fields and methods inherited from `DataEngine`. Specifically, it uses input points (`f_points`) and a distance threshold (`f_distance`). The output of this component is the set of merged points (`f_mergedPoints`).\n\n**Practical Usage Guidance:**\n- Users should provide an array of points (`f_points`) and define a merge distance (`f_distance`). When `doUpdate` is called, it processes these inputs to produce a new array of merged points (`f_mergedPoints`). This component is typically used in the preprocessing stage or within pipelines where point cloud reduction is required.\n\n**Data Fields:**\n- **points (VecCoord):** Input set of points to be processed.\n- **distance (Real):** Distance threshold for merging points.\n- **mergedPoints (VecCoord):** Output set of merged points."
  },
  "maths": {
    "maths": "The `JoinPoints` component in the SOFA framework is designed to merge points from an input set if they are within a specified distance, effectively reducing the density of the point cloud while preserving their average position. This operation can be seen as a form of clustering or simplification in computational geometry and has applications in various contexts such as efficient processing or visualization of high-resolution data.\n\n### Mathematical Description\n\n#### Input Data\n- **Points** (\textbf{f_points}): A set of points \textbf{P} = \\{p_1, p_2, ..., p_n\\}, where each point $p_i$ is a coordinate vector in 3D space.\n- **Distance** (\textbf{f_distance}): A scalar distance threshold $d_{\text{merge}}$ used to determine if two points should be merged.\n\n#### Output Data\n- **Merged Points** (\textbf{f_mergedPoints}): A set of merged points \textbf{P'} = \\{p'_1, p'_2, ..., p'_m\\} where each $p'_j$ is the average position of a cluster of original points within $d_{\text{merge}}$.\n\n#### Merging Process\nThe `JoinPoints` component performs the following steps to merge points:\n\n1. **Initialization**:\n   - Initialize an empty list \textbf{mergedPoints} to store the resulting merged points.\n   - Create a copy of the input point set, denoted as $\textbf{copyPoints}$, and initialize a corresponding list of coefficients (weights) for each point in this set. Initially, all weights are set to 1.\n\n2. **Point Merging**:\n   - For each point $p_i$ in \textbf{copyPoints}, determine if there exists another point $p_j$ within the distance threshold $d_{\text{merge}}$. Specifically, calculate the Euclidean distance between pairs of points and check if it is less than $d_{\text{merge}}$.\n   - If a nearby point $p_j$ is found, merge them into a single new point $p'$ by computing the weighted average:\n     \n     \\[\n     p' = \\frac{w_i p_i + w_j p_j}{w_i + w_j}\n     \\]\n\n   - The weights are then updated: $w_i \rightarrow w_i + w_j$.\n   - Remove the merged point $p_j$ from both \textbf{copyPoints} and its corresponding weight list.\n\n3. **Final Output**:\n   - After processing all points, convert the remaining set of merged points in \textbf{copyPoints} to a vector and store it as the output \textbf{f_mergedPoints}.\n\n### Role in FEM Pipeline\nThe `JoinPoints` component does not directly contribute to the governing equations or operators typically found in finite element analysis, such as mass matrix $M$, stiffness matrix $K$, internal forces $\textbf{f}_{\text{int}}$, residual vector $R$, etc. It is primarily a preprocessing tool used before mesh generation and spatial discretization, where it can help reduce the number of points to make subsequent computational tasks more efficient.\n\n### Numerical Methods and Discretization Choices\n- **Point Merging**: The merging process uses simple Euclidean distance checks followed by weighted averaging to form new representative points. This is a straightforward geometric operation that does not involve complex discretization or numerical integration schemes.\n\n### Variational / Lagrangian Mechanics Framework Fit\nThe `JoinPoints` component operates outside the core variational mechanics framework of FEM simulation. Its role is preparatory, helping to optimize data before it enters into more rigorous mechanical and physical modeling stages. The reduction in point cloud density can indirectly improve computational efficiency for subsequent operations such as meshing, solving linear systems, or applying constraints."
  }
}