Methods

{
  "name": "TransformationVisitor",
  "namespace": "sofa::simulation",
  "module": "Sofa.framework.Simulation.Common",
  "include": "sofa/simulation/common/TransformationVisitor.h",
  "doc": "",
  "inherits": [
    "Visitor"
  ],
  "templates": [],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "setTranslation",
      "return_type": "void",
      "params": [
        {
          "name": "dx",
          "type": "SReal"
        },
        {
          "name": "dy",
          "type": "SReal"
        },
        {
          "name": "dz",
          "type": "SReal"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setRotation",
      "return_type": "void",
      "params": [
        {
          "name": "rx",
          "type": "SReal"
        },
        {
          "name": "ry",
          "type": "SReal"
        },
        {
          "name": "rz",
          "type": "SReal"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setScale",
      "return_type": "void",
      "params": [
        {
          "name": "sx",
          "type": "SReal"
        },
        {
          "name": "sy",
          "type": "SReal"
        },
        {
          "name": "sz",
          "type": "SReal"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "processVisualModel",
      "return_type": "void",
      "params": [
        {
          "name": "node",
          "type": "simulation::Node *"
        },
        {
          "name": "v",
          "type": "core::visual::VisualModel *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "processMechanicalState",
      "return_type": "void",
      "params": [
        {
          "name": "node",
          "type": "simulation::Node *"
        },
        {
          "name": "m",
          "type": "core::behavior::BaseMechanicalState *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "processNodeTopDown",
      "return_type": "Result",
      "params": [
        {
          "name": "node",
          "type": "simulation::Node *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "isThreadSafe",
      "return_type": "bool",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getCategoryName",
      "return_type": "const char *",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `TransformationVisitor` is a component in the SOFA framework that inherits from the `Visitor` class and is part of the Sofa.framework.Simulation.Common module. Its primary role is to apply transformations (translation, rotation, and scaling) to both visual models and mechanical states within the simulation scene graph.\n\n### Role and Purpose:\nThe `TransformationVisitor` enables users to systematically apply geometric transformations across all relevant nodes in a SOFA simulation, affecting both visual representations and underlying physical models. It facilitates operations such as adjusting the position, orientation, or scale of objects within the simulation environment.\n\n### Interactions with Other Components:\n- **setTranslation(dx, dy, dz):** Sets the translation vector for transformation.\n- **setRotation(rx, ry, rz):** Sets the rotation angles (in radians) around each axis.\n- **setScale(sx, sy, sz):** Sets the scaling factors along each axis.\n- **processVisualModel(node, v):** Applies the set transformations to a visual model (`core::visual::VisualModel`).\n- **processMechanicalState(node, m):** Applies the set transformations to a mechanical state (`core::behavior::BaseMechanicalState`).\n- **processNodeTopDown(node):** Traverses nodes top-down and applies transformation methods to their visual models and mechanical states.\n\n### Practical Usage Guidance:\nThe `TransformationVisitor` can be used during simulation setup or runtime to adjust the geometry of objects in a consistent manner. The transformations are applied to both the visual appearance (`VisualModel`) and physical behavior (`BaseMechanicalState`).\n\n#### Data Fields:\n- **translation:** A 3D vector representing translation.\n- **rotation:** A 3D vector representing rotation angles around each axis.\n- **scale:** A 3D vector representing scaling factors along each axis.",
  "maths": "<p>The <code>TransformationVisitor</code> in the SOFA framework is designed to apply geometric transformations (translation, rotation, and scaling) to both visual models and mechanical states within the simulation scene graph. It primarily facilitates operations that adjust the position, orientation, or scale of objects within a simulation environment.</p>\n\n<ul>\n<li><strong>Governing Equations:</strong> The <code>TransformationVisitor</code> itself does not directly contribute to any governing equations such as mass matrix $M$, stiffness matrix $K$, internal force $f_{int}$, or residual $R$. However, it modifies the state of mechanical objects in a way that can indirectly affect these quantities by altering positions and orientations used in their computation.</li>\n<li><strong>Constitutive Laws:</strong> The component does not directly implement any constitutive laws such as strain measures, stress tensors, hyperelastic potentials, or damping models. It is primarily concerned with applying geometric transformations rather than defining material behavior.</li>\n<li><strong>Kinematic Laws:</strong> The <code>TransformationVisitor</code> applies kinematic operations to modify the position, orientation, and scale of objects within the simulation:\n<ul>\n<li><strong>Translation:</strong> A rigid body translation is represented as a 3D vector $\\mathbf{t} = (dx, dy, dz)$.</li>\n<li><strong>Rotation:</strong> Rotation around each axis is defined by angles $(rx, ry, rz)$. The rotation can be expressed using a rotation matrix or quaternion depending on the implementation context. For example, the rotation matrix $R$ for rotations about the x, y, and z axes (in that order) can be written as:\n\\[\nR = R_z(rz) \\cdot R_y(ry) \\cdot R_x(rx)\n\\]\nwhere\n\\[\nR_x(rx) = \\begin{pmatrix}\n1 & 0 & 0 \\\\ \n0 & \\cos(rx) & -\\sin(rx) \\\\ \n0 & \\sin(rx) & \\cos(rx)\n\\end{pmatrix},\nR_y(ry) = \\begin{pmatrix}\n\\cos(ry) & 0 & \\sin(ry) \\\\ \n0 & 1 & 0 \\\\ \n-\\sin(ry) & 0 & \\cos(ry)\n\\end{pmatrix},\nR_z(rz) = \\begin{pmatrix}\n\\cos(rz) & -\\sin(rz) & 0 \\\\ \n\\sin(rz) & \\cos(rz) & 0 \\\\ \n0 & 0 & 1\n\\end{pmatrix}.\n\\]</li>\n<li><strong>Scaling:</strong> Scaling factors along each axis are represented as $\\mathbf{s} = (sx, sy, sz)$ and applied to the coordinates of points.</li>\n</ul></li>\n<li><strong>Role in FEM Pipeline:</strong>\n<ul>\n<li>The <code>TransformationVisitor</code> does not directly participate in assembly, time integration, nonlinear solve, or linear solve stages. It is more concerned with modifying the scene graph and updating object states.</li>\n<li>It operates during state updates to apply geometric transformations to both visual models (for rendering purposes) and mechanical states (affecting physical behavior).</li>\n</ul></li>\n<li><strong>Numerical Methods:</strong> The component encodes straightforward numerical operations for applying translation, rotation, and scaling. These are basic linear algebraic operations that do not involve complex discretization choices.</li>\n<li><strong>Variational / Lagrangian Mechanics Framework:</strong>\n<ul>\n<li>The transformations applied by the <code>TransformationVisitor</code> can influence the overall simulation by modifying object positions, orientations, and scales. However, it does not directly contribute to variational or Lagrangian formulations.</li>\n<li>Indirectly, these transformations may affect how forces are computed in subsequent steps (e.g., through altered contact conditions or modified deformation states).</li>\n</ul></li>\n</ul>",
  "abstract": "The `TransformationVisitor` applies geometric transformations (translation, rotation, scaling) to visual models and mechanical states within the SOFA simulation scene graph.",
  "sheet": "# TransformationVisitor\n\n## Overview\nThe `TransformationVisitor` is a component in the Sofa.framework.Simulation.Common module that inherits from the `Visitor` class. It facilitates applying geometric transformations (translation, rotation, and scaling) to both visual models (`core::visual::VisualModel`) and mechanical states (`core::behavior::BaseMechanicalState`).\n\n## Mathematical Model\nThe `TransformationVisitor` applies kinematic operations to modify the position, orientation, and scale of objects within the simulation:\n- **Translation:** A rigid body translation is represented as a 3D vector \\(\\mathbf{t} = (dx, dy, dz)\\).\n- **Rotation:** Rotation around each axis is defined by angles \\((rx, ry, rz)\\). The rotation can be expressed using a rotation matrix or quaternion depending on the implementation context. For example, the rotation matrix \\(R\\) for rotations about the x, y, and z axes (in that order) can be written as:\n\\[\nR = R_z(rz) \\cdot R_y(ry) \\cdot R_x(rx)\n\\]\nwhere\n\\[\nR_x(rx) = \n\\begin{pmatrix}\n1 & 0 & 0 \\\\ \n0 & \\cos(rx) & -\\sin(rx) \\\\ \n0 & \\sin(rx) & \\cos(rx)\n\\end{pmatrix},\nR_y(ry) = \n\\begin{pmatrix}\n\\cos(ry) & 0 & \\sin(ry) \\\\ \n0 & 1 & 0 \\\\ \n-\\sin(ry) & 0 & \\cos(ry)\n\\end{pmatrix},\nR_z(rz) = \n\\begin{pmatrix}\n\\cos(rz) & -\\sin(rz) & 0 \\\\ \n\\sin(rz) & \\cos(rz) & 0 \\\\ \n0 & 0 & 1\n\\end{pmatrix}.\n\\]\n- **Scaling:** Scaling factors along each axis are represented as \\(\\mathbf{s} = (sx, sy, sz)\\) and applied to the coordinates of points.\n\n## Parameters and Data\nThe significant parameters exposed by the `TransformationVisitor` include:\n- **Translation:** A 3D vector representing translation. Set using `setTranslation(dx, dy, dz)`.\n- **Rotation:** A 3D vector representing rotation angles around each axis. Set using `setRotation(rx, ry, rz)`.\n- **Scale:** A 3D vector representing scaling factors along each axis. Set using `setScale(sx, sy, sz)`.\n\n## Dependencies and Connections\nThe `TransformationVisitor` typically requires nodes with visual models (`core::visual::VisualModel`) and mechanical states (`core::behavior::BaseMechanicalState`). It fits into the scene graph by traversing nodes top-down and applying transformations to their respective components."
}