Data Fields

Methods

{
  "name": "ShapeMatching",
  "namespace": "sofa::component::engine::analyze",
  "module": "Sofa.Component.Engine.Analyze",
  "include": "sofa/component/engine/analyze/ShapeMatching.h",
  "doc": "Compute target positions using shape matching deformation method by Mueller et al.\n\nThis class computes target positions using shape matching deformation [Muller05][Muller11]",
  "inherits": [
    "DataEngine",
    "SingleStateAccessor"
  ],
  "templates": [
    "sofa::defaulttype::Rigid3Types",
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_iterations",
      "type": "unsigned int",
      "xmlname": "iterations",
      "help": "Number of iterations."
    },
    {
      "name": "d_affineRatio",
      "type": "Real",
      "xmlname": "affineRatio",
      "help": "Blending between affine and rigid."
    },
    {
      "name": "d_fixedweight",
      "type": "Real",
      "xmlname": "fixedweight",
      "help": "weight of fixed particles."
    },
    {
      "name": "d_fixedPosition0",
      "type": "VecCoord",
      "xmlname": "fixedPosition0",
      "help": "rest positions of non mechanical particles."
    },
    {
      "name": "d_fixedPosition",
      "type": "VecCoord",
      "xmlname": "fixedPosition",
      "help": "current (fixed) positions of non mechanical particles."
    },
    {
      "name": "d_position",
      "type": "VecCoord",
      "xmlname": "position",
      "help": "Input positions."
    },
    {
      "name": "d_cluster",
      "type": "VVI",
      "xmlname": "cluster",
      "help": "Input clusters."
    },
    {
      "name": "d_targetPosition",
      "type": "VecCoord",
      "xmlname": "targetPosition",
      "help": "Computed target positions."
    }
  ],
  "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"
    }
  ],
  "summary": "The ShapeMatching component is a data engine that computes target positions using the shape matching deformation method described in [Muller05] and [Muller11]. This technique allows for the efficient computation of transformations between clusters of points, enabling realistic deformations in simulations.",
  "description": "The **ShapeMatching** class is part of the SOFA (Simulation Open-Framework Architecture) framework and implements a deformation model based on shape matching. It computes target positions by transforming rest configurations to current configurations through an iterative process that blends rigid and affine transformations.\n\n### Key Features:\n- **Input Data:**\n  - `d_position`: Current positions of the points.\n  - `d_fixedPosition0`: Rest positions of non-mechanical particles (fixed points).\n  - `d_cluster`: Clusters of points that are transformed together.\n- **Parameters:*\n  - `d_iterations`: Number of iterations to refine the transformations.\n  - `d_affineRatio`: Blending factor between rigid and affine transformations.\n  - `d_fixedweight`: Weight applied to fixed particles during computations.\n- **Output Data:**\n  - `d_targetPosition`: Computed target positions for each point based on shape matching.\n\n### Algorithm:\nThe core algorithm computes the transformation matrix (`T`) for each cluster by minimizing the difference between rest and current configurations. It performs this minimization iteratively to refine the transformations, blending rigid and affine components using the polar decomposition method. The result is a set of target positions that represent how points should move to match the desired deformation.\n\n### Usage:\nThe `doUpdate` function computes the transformation matrices for each cluster in parallel (if enabled) and updates the target positions accordingly. It handles both generic point data (`Vec3Types`) and rigid body data (`Rigid3Types`).\n\n### Visualization:\nThe `draw` method is overridden but currently does not perform any specific drawing operations, leaving it as a placeholder for potential visualization enhancements.\n\nThis component is particularly useful in simulations where realistic deformations need to be applied to complex shapes or objects based on predefined cluster configurations.",
  "parameters": [
    {
      "name": "d_iterations",
      "description": "Number of iterations used to refine the transformation matrices.",
      "type": "unsigned int"
    },
    {
      "name": "d_affineRatio",
      "description": "Blending factor between rigid and affine transformations (0.0 for purely rigid, 1.0 for purely affine).",
      "type": "Real"
    },
    {
      "name": "d_fixedweight",
      "description": "Weight applied to fixed particles during the computation.",
      "type": "Real"
    }
  ],
  "inputs": [
    {
      "name": "d_position",
      "description": "Current positions of all points in the simulation."
    },
    {
      "name": "d_fixedPosition0",
      "description": "Rest positions of non-mechanical (fixed) particles."
    },
    {
      "name": "d_cluster",
      "description": "Clusters that define groups of points to be transformed together."
    }
  ],
  "outputs": [
    {
      "name": "d_targetPosition",
      "description": "Calculated target positions for each point after applying the shape matching deformation."
    }
  ],
  "maths": "<maths_md_description>\n\n### Governing Equations and Operators\n\nThe **ShapeMatching** class computes target positions based on a shape matching deformation method as described in \\[Muller05\\] and \\[Muller11\\]. This method aims to transform rest configurations of clusters of points into current configurations by blending rigid and affine transformations. The governing equations involve the following key components:\n\n#### Position Variables\n- **Rest Positions**: $p_0^i$ (for mechanical particles) and $q_0^j$ (for fixed particles).\n- **Current Positions**: $p_i$ (for mechanical particles) and $q_j$ (for fixed particles).\n- **Target Positions**: $t_i$, the positions to be computed.\n\n#### Weighting Factors\n- **Blending Factor**: $\\alpha \\in [0,1]$, where $\\alpha = 1$ corresponds to an affine transformation and $\\alpha = 0$ corresponds to a rigid transformation.\n- **Fixed Particle Weight**: $w_f$, the weight applied to fixed particles during computations.\n\n#### Center of Mass Calculation\nFor each cluster $i$, we compute the center of mass ($X_{cm0}^i$) in rest configuration and the current center of mass ($X_{cm}^i$):\n\n\begin{align*}\n  X_{cm0}^i &= \\frac{1}{W_i} \\\n               &\\sum_{j \\in C(i)} w_j p_0^j, \\\\\n  X_{cm}^i   &= \\frac{1}{W_i} \\\n               &\\sum_{j \\in C(i)} w_j p_j,\n\tag{1}\n\tag{2}\n\tag{3}\n\tag{4}\n\tag{5}\n\n\\end{align*}\n\nwhere $w_j = 1$ for mechanical particles and $w_j = w_f$ for fixed particles, and $W_i$ is the total weight of all points in cluster $i$:\n\n$$W_i = \\sum_{j \\in C(i)} w_j.$$\n\n#### Transformation Matrix Calculation\nThe transformation matrix $T^i$ for each cluster $i$ is computed iteratively to minimize the difference between rest and current configurations. The matrix $Q_x^{-1}$ is defined as:\n\n$$Q_x = W_i - \\sum_{j \\in C(i)} w_j (p_0^j - X_{cm0}^i) (p_0^j - X_{cm0}^i)^T.$$\n\nThe transformation matrix $T^i$ is then computed using the polar decomposition method for blending rigid and affine transformations:\n\n$$T^i = T^i Q_x^{-1} \\alpha + R^i (1 - \\alpha),$$\n\nwhere $R^i$ is the rotation component obtained from the polar decomposition of $T^i$.\n\n#### Target Position Calculation\nThe target positions are computed iteratively as follows:\n\n$$t_i = X_{cm}^k + T^k (p_0^i - X_{cm0}^k),$$\n\nwhere $k$ is the cluster to which point $i$ belongs.\n\n### Constitutive or Kinematic Laws Involved\n- **Strain Measures**: The shape matching method inherently involves strain measures based on the difference between rest and current configurations, but it does not explicitly define a strain measure in the traditional sense of continuum mechanics. Instead, it focuses on transforming positions to match desired deformations.\n- **Stress Tensors**: No explicit stress tensors are involved as this method is focused on positional transformations rather than force-based deformation.\n\n### Role in the Global FEM Pipeline\nThe **ShapeMatching** component plays a role in the mapping phase of the simulation pipeline, where it computes target positions based on specified clusters and transformation parameters. This computed data can be used for further processing or as input to other components (e.g., constraint projections or deformation models).\n\n### Numerical Methods or Discretization Choices\n- **Iterative Process**: The method iteratively refines the transformation matrices, allowing for convergence towards a target configuration.\n- **Parallel Computation**: The computations can be performed in parallel using OpenMP, which speeds up processing time for large clusters.\n\n### Integration into Variational / Lagrangian Mechanics Framework\nWhile shape matching is not directly derived from variational principles or Lagrangian mechanics, it can be seen as a form of geometrically consistent deformation modeling. The method focuses on maintaining the relative configuration within clusters and blending rigid and affine transformations to achieve smooth deformations.\n\n### Summary\nThe **ShapeMatching** component in SOFA implements an iterative process for computing target positions based on shape matching deformation methods, which blend rigid and affine transformations. It computes center of mass, transformation matrices, and target positions iteratively, ensuring that the computed deformations are consistent with specified clusters and input parameters.\n",
  "abstract": "The ShapeMatching component computes target positions by blending rigid and affine transformations iteratively based on shape matching deformation methods.",
  "sheet": "# ShapeMatching\n\n## Overview\nShapeMatching is an engine that computes target positions using the shape matching deformation method, blending rigid and affine transformations iteratively. It handles both generic point data (`Vec3Types`) and rigid body data (`Rigid3Types`).\n\n## Mathematical Model\nThe **ShapeMatching** class computes target positions based on a shape matching deformation method as described in [Muller05] and [Muller11]. This method aims to transform rest configurations of clusters of points into current configurations by blending rigid and affine transformations. The governing equations involve the following key components:\n\n#### Position Variables\n- **Rest Positions**: $p_0^i$ (for mechanical particles) and $q_0^j$ (for fixed particles).\n- **Current Positions**: $p_i$ (for mechanical particles) and $q_j$ (for fixed particles).\n- **Target Positions**: $t_i$, the positions to be computed.\n\n#### Weighting Factors\n- **Blending Factor**: $\\alpha \\in [0,1]$, where $\\alpha = 1$ corresponds to an affine transformation and $\\alpha = 0$ corresponds to a rigid transformation.\n- **Fixed Particle Weight**: $w_f$, the weight applied to fixed particles during computations.\n\n#### Center of Mass Calculation\nFor each cluster $i$, we compute the center of mass ($X_{cm0}^i$) in rest configuration and the current center of mass ($X_{cm}^i$):\n\\begin{align*}\n  X_{cm0}^i &= \\frac{1}{W_i} \\\n               &\\sum_{j \\in C(i)} w_j p_0^j, \\\\\n  X_{cm}^i   &= \\frac{1}{W_i} \\\n               &\\sum_{j \\in C(i)} w_j p_j,\n\\end{align*}\nwhere $w_j = 1$ for mechanical particles and $w_j = w_f$ for fixed particles, and $W_i$ is the total weight of all points in cluster $i$:\n$$W_i = \\sum_{j \\in C(i)} w_j.$$\n\n#### Transformation Matrix Calculation\nThe transformation matrix $T^i$ for each cluster $i$ is computed iteratively to minimize the difference between rest and current configurations. The matrix $Q_x^{-1}$ is defined as:\n$$Q_x = W_i - \\sum_{j \\in C(i)} w_j (p_0^j - X_{cm0}^i) (p_0^j - X_{cm0}^i)^T.$$\nThe transformation matrix $T^i$ is then computed using the polar decomposition method for blending rigid and affine transformations:\n$$T^i = T^i Q_x^{-1} \\alpha + R^i (1 - \\alpha),$$\nwhere $R^i$ is the rotation component obtained from the polar decomposition of $T^i$.\n\n#### Target Position Calculation\nThe target positions are computed iteratively as follows:\n$$t_i = X_{cm}^k + T^k (p_0^i - X_{cm0}^k),$$\nwhere $k$ is the cluster to which point $i$ belongs.\n\n## Parameters and Data\n- **iterations**: Number of iterations (`unsigned int`)\n- **affineRatio**: Blending between affine and rigid transformations (`Real`, default: 1.0)\n- **fixedweight**: Weight of fixed particles (`Real`, default: 1.0)\n- **fixedPosition0**: Rest positions of non-mechanical particles (`VecCoord`)\n- **fixedPosition**: Current (fixed) positions of non-mechanical particles (`VecCoord`)\n- **position**: Input positions (`VecCoord`)\n- **cluster**: Input clusters (`VVI`)\n- **targetPosition**: Computed target positions (`VecCoord`)"
}