Data Fields

Methods

{
  "name": "TransformEngine",
  "namespace": "sofa::component::engine::transform",
  "module": "Sofa.Component.Engine.Transform",
  "include": "sofa/component/engine/transform/TransformEngine.h",
  "doc": "Engine applying a transformation on 3d points (translation / rotation).\n\nThis class transforms the positions of one DataFields into new positions after applying a transformation\nThis transformation can be either translation, rotation, scale",
  "inherits": [
    "DataEngine"
  ],
  "templates": [
    "sofa::defaulttype::Rigid2Types",
    "sofa::defaulttype::Rigid3Types",
    "sofa::defaulttype::Vec1Types"
  ],
  "data_fields": [
    {
      "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"
    },
    {
      "name": "translation",
      "type": "type::Vec3",
      "xmlname": "translation",
      "help": "translation vector (x,y,z)"
    },
    {
      "name": "rotation",
      "type": "type::Vec3",
      "xmlname": "rotation",
      "help": "rotation vector (x,y,z)"
    },
    {
      "name": "quaternion",
      "type": "type::Quat<SReal>",
      "xmlname": "quaternion",
      "help": "rotation quaternion (qx,qy,qz,qw)"
    },
    {
      "name": "scale",
      "type": "type::Vec3",
      "xmlname": "scale",
      "help": "scale factor"
    },
    {
      "name": "inverse",
      "type": "bool",
      "xmlname": "inverse",
      "help": "true to apply inverse transformation"
    }
  ],
  "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": "protected"
    }
  ],
  "description": "The `TransformEngine` is a component in the SOFA framework that applies transformations (such as translation, rotation, and scaling) on arrays of 3D points. It inherits from `DataEngine`, which enables it to process input data fields and produce output based on specified operations.\n\n### Role and Purpose\nThis engine transforms the positions of one set of coordinates (`input_position`) into a new set of transformed positions (`output_position`). The transformations can be defined through translation, rotation (both as Euler angles or quaternions), and scaling. It supports both forward and inverse transformations based on the `inverse` flag.\n\n### Interactions with Other Components\nThe `TransformEngine` interacts with other SOFA components via its API, specifically through data fields:\n- **input_position**: The input array of 3D points to be transformed.\n- **output_position**: The output array containing transformed positions after applying the specified operations.\n- **translation**: A vector defining translation in (x,y,z) coordinates.\n- **rotation**: A vector representing rotation angles around (x,y,z) axes.\n- **quaternion**: A quaternion for specifying rotations, providing an alternative to Euler angles.\n- **scale**: A scaling factor applied uniformly across (x,y,z).\n\n### Practical Usage Guidance and Data Fields\nTo use `TransformEngine`, configure the following data fields:\n- Set the input position array (`input_position`) with 3D points.\n- Define transformation parameters: translation, rotation (either as Euler angles or quaternion), and scale factor.\n- Specify whether to apply an inverse transformation using the `inverse` flag.\n\nThis component is useful for modifying positions in simulation scenarios requiring geometric transformations on point clouds or object representations.",
  "maths": "The `TransformEngine` in the SOFA framework is designed to apply geometric transformations, including translation, rotation, and scaling, on arrays of 3D points. It does not contribute directly to the governing equations or operators typical of FEM simulations such as mass matrix $M$, stiffness matrix $K$, internal force $\bm{f}_{int}$, or residual $R$. Instead, it serves a role in modifying positions for various simulation and visualization purposes. Below is a detailed mathematical and physical description of its functionality.\n\n### Transformations Applied\nThe `TransformEngine` supports three types of transformations:\n1. **Translation**: Given an input position vector $\bm{p} = (x,y,z)$, translation by vector $\bm{t} = (t_x,t_y,t_z)$ is applied as follows:\n   \n   \\[\\bm{p}_{\text{translated}} = \\begin{pmatrix}\nx + t_x \\\\ y + t_y \\\\ z + t_z\n\\end{pmatrix}\\]\n2. **Rotation**: Rotation can be specified either through Euler angles $\bm{\theta} = (\theta_x, \theta_y, \theta_z)$ or a quaternion $q$. When using Euler angles, the rotation is performed around each axis in sequence (z-y-x convention), and the corresponding rotation matrix $R$ is computed. For quaternion-based rotations:\n   \\[\\bm{p}_{\text{rotated}} = q(\bm{p})q^{-1}\\]\n3. **Scaling**: Scaling by a factor $\bm{s} = (s_x, s_y, s_z)$ modifies each component of the position vector proportionally:\n   \\[\\bm{p}_{\text{scaled}} = \\begin{pmatrix}\nx \times s_x \\\\ y \times s_y \\\\ z \times s_z\n\\end{pmatrix}\\]\n\n### Transformation Pipeline\nThe `TransformEngine` processes an input array of 3D points and applies the specified transformations in sequence. The operations can be configured to apply either forward or inverse transformations based on a flag (`inverse`).\n\n1. **Input Array**: Denoted as $\bm{P} = \begin{bmatrix}\bm{p}_1 & \bm{p}_2 & ... & \bm{p}_N\text{ }\text{ } \\end{bmatrix}$ where each $\bm{p}_i$ is a 3D point.\n\n2. **Transformation Application**: The transformations (translation, rotation, scaling) are applied to each input point $\bm{p}_i$. These operations can be composed into a single transformation matrix $T_{\text{total}}$, which encapsulates all individual transformations:\n   \n   \\[\\bm{P}_{\text{output}} = T_{\text{total}} \times \bm{P}\\]\n\n3. **Inverse Transformation**: If `inverse` is set to true, the inverse transformation matrix $T^{-1}$ is applied instead of $T_{\text{total}}$.\n\n### Role in Global FEM Pipeline\nAlthough the `TransformEngine` does not directly contribute to the variational or Lagrangian formulations that underpin FEM simulations, it can play a supportive role by modifying positions and orientations of objects within the simulation. This is particularly useful for setting up initial configurations, applying boundary conditions, or implementing mappings between different parts of the simulation.\n\n### Numerical Methods and Discretization Choices\nThe transformations are applied directly to the input points without numerical integration or spatial discretization steps typical in FEM simulations. The transformations are executed as a sequence of operations on each point individually, and no iterative solvers are involved since these transformations do not require solving nonlinear equations.\n\n### Broader Variational / Lagrangian Mechanics Framework\nWhile `TransformEngine` does not derive from the variational principles that underlie FEM formulations, it can be seen as a tool for manipulating configurations within such simulations. Transformations like translation and rotation are fundamental operations in both classical mechanics and geometric modeling, which make this component valuable for setting up initial conditions or applying external forces indirectly through position updates.",
  "abstract": "The `TransformEngine` applies translation, rotation, and scaling transformations to input 3D point arrays, producing transformed output positions.",
  "sheet": "# TransformEngine\n\n## Overview\n\nThe `TransformEngine` is a SOFA engine that processes an array of 3D points (`input_position`) by applying specified geometric transformations (translation, rotation, scaling) and outputs the transformed coordinates (`output_position`). It inherits from `DataEngine`, enabling it to handle input data fields and produce output based on defined operations.\n\n## Parameters and Data\n\nThe significant parameters exposed by this component are:\n\n- **input_position**: The array of 3D points to be transformed (type: VecCoord).\n- **output_position**: The resulting array of transformed positions after applying the specified transformations (type: VecCoord).\n- **translation**: Translation vector in (x, y, z) coordinates (type: type::Vec3).\n- **rotation**: Rotation angles around (x, y, z) axes (type: type::Vec3).\n- **quaternion**: Quaternion for specifying rotations as an alternative to Euler angles (type: type::Quat<SReal>).\n- **scale**: Scaling factor applied uniformly across (x, y, z) coordinates (type: type::Vec3).\n- **inverse**: Boolean flag indicating whether to apply the inverse transformation (type: bool)."
}