Data Fields

Methods

{
  "name": "TransformPosition",
  "namespace": "sofa::component::engine::transform",
  "module": "Sofa.Component.Engine.Transform",
  "include": "sofa/component/engine/transform/TransformPosition.h",
  "doc": "Transform position of 3d points.\n\nThis class transforms the positions of one DataFields into new positions after applying a transformation\nThis transformation can be either : projection on a plane (plane defined by an origin and a normal vector),\ntranslation, rotation, scale and some combinations of translation, rotation and scale, affine or read from a\ntransformation file",
  "inherits": [
    "DataEngine"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "f_origin",
      "type": "Coord",
      "xmlname": "origin",
      "help": "A 3d point on the plane/Center of the scale"
    },
    {
      "name": "f_inputX",
      "type": "VecCoord",
      "xmlname": "input_position",
      "help": "input array of 3d points"
    },
    {
      "name": "f_outputX",
      "type": "VecCoord",
      "xmlname": "output_position",
      "help": "output array of 3d points projected on a plane"
    },
    {
      "name": "f_normal",
      "type": "Coord",
      "xmlname": "normal",
      "help": "plane normal"
    },
    {
      "name": "f_translation",
      "type": "Coord",
      "xmlname": "translation",
      "help": "translation vector "
    },
    {
      "name": "f_rotation",
      "type": "Coord",
      "xmlname": "rotation",
      "help": "rotation vector "
    },
    {
      "name": "f_scale",
      "type": "Coord",
      "xmlname": "scale",
      "help": "scale factor"
    },
    {
      "name": "f_affineMatrix",
      "type": "Mat4x4",
      "xmlname": "matrix",
      "help": "4x4 affine matrix"
    },
    {
      "name": "f_method",
      "type": "sofa::helper::OptionsGroup",
      "xmlname": "method",
      "help": "transformation method either translation or scale or rotation or random or projectOnPlane"
    },
    {
      "name": "f_seed",
      "type": "long",
      "xmlname": "seedValue",
      "help": "the seed value for the random generator"
    },
    {
      "name": "f_maxRandomDisplacement",
      "type": "Real",
      "xmlname": "maxRandomDisplacement",
      "help": "the maximum displacement around initial position for the random transformation"
    },
    {
      "name": "f_fixedIndices",
      "type": "SetIndex",
      "xmlname": "fixedIndices",
      "help": "Indices of the entries that are not transformed"
    },
    {
      "name": "f_drawInput",
      "type": "bool",
      "xmlname": "drawInput",
      "help": "Draw input points"
    },
    {
      "name": "f_drawOutput",
      "type": "bool",
      "xmlname": "drawOutput",
      "help": "Draw output points"
    },
    {
      "name": "f_pointSize",
      "type": "Real",
      "xmlname": "pointSize",
      "help": "Point size"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "getTransfoFromTxt",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "getTransfoFromTrm",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "getTransfoFromTfm",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "selectTransformationMethod",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "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"
    }
  ],
  "description": "The `TransformPosition` component in the SOFA framework is designed to transform the positions of 3D points based on various transformation methods such as projection, translation, rotation, scaling, and affine transformations. It inherits from the `DataEngine` class and operates on `Vec3Types`, which are typically vectors representing 3-dimensional coordinates.\n\n### Role in SOFA Ecosystem\nThis component is part of the Engine module within the SOFA framework and allows for the manipulation of point positions through a variety of methods, including reading transformations from files. It is particularly useful for creating complex geometric transformations on sets of points, which can be applied to different simulation scenarios.\n\n### Interactions with Other Components\n- **Data Fields**: The component interacts with input (`input_position`) and output (`output_position`) DataFields that store the positions of 3D points before and after transformation. It also handles additional fields such as `normal`, `translation`, `rotation`, `scale`, and `affineMatrix` for defining transformations.\n- **Transformation Methods**: The component supports several methods for transforming input data, including projection onto a plane, translation, rotation, scaling, and affine transformations read from files (`.trm`, `.tfm`, `.txt`, or `.xfm`).\n\n### Practical Usage Guidance\n- **Input Data Fields**:\n  - `input_position`: Input array of 3D points.\n  - `origin`: A point on the plane or center for scaling operations.\n  - `normal`: Normal vector defining a projection plane.\n  - `translation`, `rotation`, and `scale`: Vectors or factors used in respective transformations.\n- **Output Data Field**:\n  - `output_position`: Output array of transformed points.\n- **Transformation Methods**: Configured via the `method` field, which accepts options like translation, rotation, scale, affine transformation from a file, and random displacement. The `seedValue` and `maxRandomDisplacement` fields are used for generating random transformations.\n\n### Additional Configuration Fields\n- `fixedIndices`: Indices of points that should not be transformed.\n- `drawInput`, `drawOutput`: Boolean values to enable drawing the input or output points, respectively.\n- `pointSize`: Size of the points when drawn.",
  "maths": "<h2>Governing Equations and Operators</h2>\n\n<p>The <code>TransformPosition</code> component in the SOFA framework is designed to transform the positions of 3D points based on various transformation methods. The primary mathematical operations include:</p>\n<ul>\n<li><strong>Projection onto a Plane:</strong></li>\n</ul>\n\\[\n    \\text{For each point } p_i, \n    p_i' = p_i + (o - p_i) \\cdot n \\cdot n\n\\]\n<p>where $p_i$ is the original position of the point, $o$ is a point on the plane, and $n$ is the normal vector to the plane.</p>\n<ul>\n<li><strong>Translation:</strong></li>\n</ul>\n\\[\n    \\text{For each point } p_i,\n    p_i' = p_i + t\n\\]\n<p>where $t$ is a translation vector.</p>\n<ul>\n<li><strong>Rotation:</strong></li>\n</ul>\n\\[\n    \\text{For each point } p_i, \n    p_i' = q(p_i)\n\\]\n<p>where $q$ represents the rotation quaternion derived from Euler angles defined by a rotation vector.</p>\n<ul>\n<li><strong>Scaling:</strong></li>\n</ul>\n\\[\n    \\text{For each point } p_i, \n    p_i' = o + (p_i - o) \\cdot s\n\\]\n<p>where $o$ is the center of scaling and $s$ is a scale factor.</p>\n<ul>\n<li><strong>Affine Transformation:</strong></li>\n</ul>\n\\[\n    \\text{For each point } p_i, \n    p_i' = M(p_i)\n\\]\n<p>where $M$ is a 4x4 affine transformation matrix.</p>\n<ul>\n<li><strong>Random Displacement:</strong></li>\n</ul>\n\\[\n    \\text{For each point } p_i, \n    p_i' = p_i + r\n\\]\n<p>where $r$ is a random vector with a maximum displacement specified by the user.</p>\n\n<h2>Constitutive and Kinematic Laws</h2>\n<ul>\n<li><strong>Projection onto Plane:</strong></li>\n</ul>\n<p>The projection operation involves aligning points to a plane defined by its normal $n$ and an origin point $o$. The transformed position $p_i'$ is computed such that the vector from $o$ to $p_i'$ is orthogonal to the plane.</p>\n<ul>\n<li><strong>Translation:</strong></li>\n</ul>\n<p>A simple translation operation shifts each point by a specified vector $t$.</p>\n<ul>\n<li><strong>Rotation:</strong></li>\n</ul>\n\\[\n    q = \\text{createQuaterFromEuler}(\\theta_x, \\theta_y, \\theta_z)\n\\]\n<p>The rotation is defined by Euler angles converted to a quaternion $q$, which then rotates each point.</p>\n<ul>\n<li><strong>Scaling:</strong></li>\n</ul>\n<p>The scaling operation scales the distance of points from an origin point $o$ by a scale factor $s$. This can be expressed as a linear transformation around the center $o$.</p>\n<ul>\n<li><strong>Affine Transformation:</strong></li>\n</ul>\n\\[\n    M = \\begin{bmatrix} \n        m_{11} & m_{12} & m_{13} & t_x \\\\ \n        m_{21} & m_{22} & m_{23} & t_y \\\\ \n        m_{31} & m_{32} & m_{33} & t_z \\\\ \n        0      & 0      & 0      & 1    \n    \\end{bmatrix}\n\\]\n<p>The affine transformation matrix $M$ combines rotation, scaling, and translation. It can be read from a file with the appropriate format.</p>\n<ul>\n<li><strong>Random Displacement:</strong></li>\n</ul>\n\\[\n    r = \\text{randomVector}(-d_{max}, d_{max})\n\\]\n<p>The random displacement vector $r$ is generated within a specified range, where $d_{max}$ is the maximum allowed displacement.</p>\n\n<h2>Role in the FEM Pipeline</h2>\n<p><code>TransformPosition</code> is not directly involved in core aspects of the finite element method such as stiffness or mass matrix assembly. Instead, it provides pre-processing capabilities for manipulating point positions before they are used in further simulation steps.</p>\n\n<h3>Assembly Phase:</h3>\n<p>The component does not participate in global matrix assembly but can be used to prepare input data (e.g., initial configurations) for other components that perform FEM operations.</p>\n\n<h3>Time Integration and Nonlinear Resolution:</h3>\n<p><code>TransformPosition</code> is typically applied before the simulation begins or during initialization steps. It does not contribute directly to time integration schemes, linear solvers, or nonlinear solution methods used in the FEM pipeline.</p>\n\n<h2>Numerical Methods and Discretization Choices:</h2>\n<p>The component supports a variety of numerical methods for transforming point positions. These include direct mathematical operations (projection, translation, scaling) and more complex transformations involving rotations and affine matrices. The specific choice depends on the method selected via input parameters.</p>\n\n<h2>Integration into Variational / Lagrangian Mechanics Framework:</h2>\n<p><code>TransformPosition</code> is an auxiliary component that prepares or modifies point positions before they are used in a broader simulation context. It does not directly contribute to variational formulations, but the transformed points can be used as input for other components that do.</p>",
  "abstract": "The `TransformPosition` component transforms the positions of 3D points using methods such as projection, translation, rotation, scaling, affine transformations, and random displacements.",
  "sheet": "# TransformPosition\n\n## Overview\n\nThe `TransformPosition` component is an engine that manipulates the positions of 3D points based on various transformation methods. It inherits from the `DataEngine` class and operates on `Vec3Types`. The component supports projection onto a plane, translation, rotation, scaling, affine transformations read from files, and random displacements.\n\n## Mathematical Model\n\nThe primary mathematical operations include:\n\n- **Projection onto a Plane**:\n  \n  For each point $p_i$,\n  \\[ p_i' = p_i + (o - p_i) \\cdot n \\cdot n \\]\n  where $p_i$ is the original position of the point, $o$ is a point on the plane, and $n$ is the normal vector to the plane.\n\n- **Translation**:\n  \n  For each point $p_i$,\n  \\[ p_i' = p_i + t \\]\n  where $t$ is a translation vector.\n\n- **Rotation**:\n  \n  For each point $p_i$,\n  \\[ p_i' = q(p_i) \\]\n  where $q$ represents the rotation quaternion derived from Euler angles defined by a rotation vector.\n\n- **Scaling**:\n  \n  For each point $p_i$,\n  \\[ p_i' = o + (p_i - o) \\cdot s \\]\n  where $o$ is the center of scaling and $s$ is a scale factor.\n\n- **Affine Transformation**:\n  \n  For each point $p_i$,\n  \\[ p_i' = M(p_i) \\]\n  where $M$ is a 4x4 affine transformation matrix.\n\n- **Random Displacement**:\n  \n  For each point $p_i$,\n  \\[ p_i' = p_i + r \\]\n  where $r$ is a random vector with a maximum displacement specified by the user.\n\n## Parameters and Data\n\nThe significant Data fields exposed by the component include:\n\n- **f_origin**: A point on the plane or center for scaling operations (`Coord` type).\n- **f_inputX**: Input array of 3D points (`VecCoord` type).\n- **f_outputX**: Output array of transformed points (`VecCoord` type).\n- **f_normal**: Normal vector defining a projection plane (`Coord` type).\n- **f_translation**: Translation vector (`Coord` type).\n- **f_rotation**: Rotation vector (`Coord` type).\n- **f_scale**: Scale factor (`Coord` type).\n- **f_affineMatrix**: 4x4 affine transformation matrix (`Mat4x4` type).\n- **f_method**: Transformation method (options include translation, rotation, scale, affine from file, and random displacement) (`sofa::helper::OptionsGroup` type).\n- **f_seed**: Seed value for the random generator (`long` type).\n- **f_maxRandomDisplacement**: Maximum displacement around initial position for random transformation (`Real` type).\n- **f_fixedIndices**: Indices of points that should not be transformed (`SetIndex` type).\n- **f_drawInput**: Boolean to enable drawing input points (`bool` type).\n- **f_drawOutput**: Boolean to enable drawing output points (`bool` type).\n- **f_pointSize**: Size of the points when drawn (`Real` type)."
}