{
  "name": "ClusteringEngine",
  "main": {
    "name": "ClusteringEngine",
    "namespace": "sofa::component::engine::analyze",
    "module": "Sofa.Component.Engine.Analyze",
    "include": "sofa/component/engine/analyze/ClusteringEngine.h",
    "doc": "Group points into overlapping clusters according to a user defined number of clusters and radius.\n\nThis class groups points into overlapping clusters according to a user defined number of clusters and radius\nIt takes input positions (and optionally a meshtopology if geodesic distances are preferred)\noutput clusters can then be fed to\n    - shape matching engine\n    - blendSkinningMapping",
    "inherits": [
      "DataEngine"
    ],
    "templates": [
      "sofa::defaulttype::Vec3Types"
    ],
    "data_fields": [
      {
        "name": "d_useTopo",
        "type": "bool",
        "xmlname": "useTopo",
        "help": "Use available topology to compute neighborhood."
      },
      {
        "name": "d_radius",
        "type": "Real",
        "xmlname": "radius",
        "help": "Neighborhood range."
      },
      {
        "name": "d_fixedRadius",
        "type": "Real",
        "xmlname": "fixedRadius",
        "help": "Neighborhood range (for non mechanical particles)."
      },
      {
        "name": "d_nbClusters",
        "type": "int",
        "xmlname": "number",
        "help": "Number of clusters (-1 means that all input points are selected)."
      },
      {
        "name": "d_fixedPosition",
        "type": "VecCoord",
        "xmlname": "fixedPosition",
        "help": "Input positions of fixed (non mechanical) particles."
      },
      {
        "name": "d_position",
        "type": "VecCoord",
        "xmlname": "position",
        "help": "Input rest positions."
      },
      {
        "name": "d_cluster",
        "type": "VVI",
        "xmlname": "cluster",
        "help": "Computed clusters."
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "init",
        "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"
      }
    ]
  },
  "desc": {
    "description": "The `ClusteringEngine` is part of the `sofa::component::engine::analyze` namespace in the SOFA framework and is designed to group points into overlapping clusters based on user-defined parameters such as the number of clusters and radius. It operates by taking input positions (and optionally topology) and computes clusters that can be used for further analysis or mapping, like shape matching engines or blendSkinningMapping.\n\nThe component inherits from `DataEngine` and supports various data fields including:\n- `d_useTopo`: Boolean to use available topology in neighborhood computation.\n- `d_radius`: Radius defining the neighborhood range for mechanical particles.\n- `d_fixedRadius`: Radius for non-mechanical particles.\n- `d_nbClusters`: Number of clusters to create (-1 means all input points are selected).\n- `d_fixedPosition`: Input positions of fixed (non-mechanical) particles.\n- `d_position`: Rest positions of the points.\n- `d_cluster`: Computed clusters, stored as a vector of vectors containing indices.\n\nThe component interacts with other SOFA components through its API by providing input and output data. The primary methods include:\n- `init()`: Initializes the ClusteringEngine.\n- `doUpdate()`: Performs the clustering operation based on user-defined parameters.\n- `draw(const core::visual::VisualParams*)`: Draws visual representation of clusters if visualization is enabled.\n\nThe component supports importing precomputed clusters and exporting computed clusters to files for further analysis."
  },
  "maths": {
    "maths": "# Mathematical and Physical Description of the Clustering Engine Component\n\n## Introduction\nThe ClusteringEngine component in the SOFA framework is designed to group points into overlapping clusters based on user-defined parameters such as the number of clusters and radius. This tool leverages both geometric and topological information to create meaningful groupings, which can be used for further analysis or mapping tasks.\n\n## Core Concepts\n### Input Data Fields\n1. **Rest Positions (`d_position`)**: The initial positions of points that need to be clustered.\n2. **Fixed Positions (`d_fixedPosition`)**: Positions of fixed (non-mechanical) particles, which are typically excluded from dynamic computations but can influence the clustering process.\n3. **Number of Clusters (`d_nbClusters`)**: Specifies the desired number of clusters to form; setting this parameter to -1 indicates that all input points should be used for clustering without predefining cluster count.\n4. **Radius Parameters (`d_radius`, `d_fixedRadius`)**: Defines the neighborhood range for mechanical and non-mechanical particles, respectively.\n\n### Topological Considerations\nThe ClusteringEngine can optionally use topological information to compute neighborhoods more accurately:\n- If `d_useTopo` is true, it leverages connectivity information from topology data (e.g., edges in a mesh).\n\n## Clustering Algorithm\nThe component employs an algorithm that iterates over the input points and groups them into clusters based on their proximity within predefined radii. The main steps are as follows:\n\n1. **Initialization**\n   - Read the rest positions (`d_position`), fixed positions (`d_fixedPosition`), number of clusters (`d_nbClusters`), radius parameters (`d_radius`, `d_fixedRadius`).\n   - Initialize the output cluster vector (`d_cluster`).\n   \n2. **Voronoi or Topological Neighborhood Computation**\n   - Depending on whether topological information is available and to be used, compute the neighborhood for each point.\n   - If using Voronoi computation:\n     \\[ d[i] = \\min_{j} ||\\text{position}[i] - \\text{position}[j]|| \\]\n     Where `d` represents distances between points.\n   - If using topological information, the algorithm iterates over connected edges to determine neighborhoods more accurately.\n\n3. **Clustering Process**\n   - For each point, if it is not already part of a cluster and within the specified radius (`d_radius`), assign it to an existing or new cluster based on proximity.\n   - For fixed points (if `d_fixedRadius` is defined), apply similar logic but with the different radius value.\n\n4. **Output Computation**\n   - Store each cluster as a set of indices representing which points belong to that cluster.\n   \n### Visualization and Data Export\n- The component provides methods for drawing clusters visually, allowing researchers or users to inspect clustering results interactively.\n- Additionally, the component supports exporting computed clusters to files for further analysis or validation.\n\n## Mathematical Formulation\nThe core mathematical operation of ClusteringEngine involves proximity-based grouping. For each point `i`, we compute its distance to all other points and group it with those that are within a specified radius:\n\\[ \\text{Cluster}[k] = \\left\\{ i : ||\\text{position}[i] - \\text{position}[j]|| < d_{\\text{radius}} \\right\\} \\]\nWhere `d_radius` can be either the mechanical (`d_radius`) or fixed radius (`d_fixedRadius`).\n\n### Visualization\nThe component visualizes clusters by drawing lines between points that belong to the same cluster. This is done through a method that takes current positions and draws lines based on indices stored in each cluster.\n\\[ \\text{Visualize}[i, j] = \\left\\{\n  \\begin{array}{ll}\n    \\text{Draw Line}(\\text{currentPositions}[i], \\text{currentPositions}[j]) & \\text{if } i \\neq j \\\\\n    \\text{No Operation} & \\text{otherwise}\n  \\end{array}\n\\right. \\]\n\n## Summary\nThe ClusteringEngine is a powerful tool for grouping points into clusters based on proximity and user-defined parameters, providing both topological and geometric flexibility in clustering algorithms."
  },
  "summary": {
    "abstract": "The ClusteringEngine groups points into overlapping clusters based on user-defined parameters such as the number of clusters and radius, optionally using topological information for neighborhood computation.",
    "sheet": "# ClusteringEngine\n\n## Overview\nThe ClusteringEngine is part of the `sofa::component::engine::analyze` namespace in the SOFA framework. It groups points into overlapping clusters based on user-defined parameters such as the number of clusters and radius, optionally using topological information for neighborhood computation.\n\n## Parameters and Data\n- **d_useTopo**: Boolean to use available topology in neighborhood computation (default: false).\n- **d_radius**: Radius defining the neighborhood range for mechanical particles (type: Real).\n- **d_fixedRadius**: Radius for non-mechanical particles (type: Real).\n- **d_nbClusters**: Number of clusters to create (-1 means all input points are selected, type: int).\n- **d_fixedPosition**: Input positions of fixed (non-mechanical) particles (type: VecCoord).\n- **d_position**: Rest positions of the points (type: VecCoord).\n- **d_cluster**: Computed clusters, stored as a vector of vectors containing indices (type: VVI).\n\n## Practical Notes\nThe ClusteringEngine can optionally use topological information to compute neighborhoods more accurately. Ensure that the radius parameters are set appropriately for meaningful clustering results."
  }
}