Data Fields

Methods

{
  "name": "Vertex2Frame",
  "namespace": "sofa::component::engine::transform",
  "module": "Sofa.Component.Engine.Transform",
  "include": "sofa/component/engine/transform/Vertex2Frame.h",
  "doc": "Return a rigid position from the vertices, texCoords, normals and facets of any mesh.\n\nThis class gets as inputs the vertices, texCoords, normals and d_facets of any mesh and returns as output a rigid position",
  "inherits": [
    "DataEngine"
  ],
  "templates": [
    "sofa::defaulttype::Rigid3Types"
  ],
  "data_fields": [
    {
      "name": "d_frames",
      "type": "VecCoord",
      "xmlname": "frames",
      "help": "Frames at output"
    },
    {
      "name": "d_useNormals",
      "type": "bool",
      "xmlname": "useNormals",
      "help": "Use normals to compute the orientations; if disabled the direction of the x axisof a vertice is the one from this vertice to the next one"
    },
    {
      "name": "d_invertNormals",
      "type": "bool",
      "xmlname": "invertNormals",
      "help": "Swap normals"
    },
    {
      "name": "d_rotation",
      "type": "int",
      "xmlname": "rotation",
      "help": "Apply a local rotation on the frames. If 0 a x-axis rotation is applied. If 1 a y-axis rotation is applied, If 2 a z-axis rotation is applied."
    },
    {
      "name": "d_rotationAngle",
      "type": "double",
      "xmlname": "rotationAngle",
      "help": "Angle rotation"
    }
  ],
  "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": "computeOrientation",
      "return_type": "type::Quat<SReal>",
      "params": [
        {
          "name": "xAxis",
          "type": "const CPos &"
        },
        {
          "name": "yAxis",
          "type": "const CPos &"
        },
        {
          "name": "zAxis",
          "type": "const CPos &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `Vertex2Frame` component in the SOFA framework transforms vertices, texture coordinates (texCoords), normals, and facets from any mesh into rigid positions. This class inherits from `DataEngine` and is part of the Sofa.Component.Engine.Transform module. Its primary role is to compute a rigid position based on the provided geometric data of the mesh.\n\n### Interactions with Other Components\n- **Inputs**: The component takes vertices, texCoords, normals, and d_facets as input. These inputs can come from various other components that generate or provide mesh data.\n- **Outputs**: It outputs frames (rigid positions) that can be used by other components for further processing, such as visualization, collision detection, or transformation operations.\n\n### Practical Usage Guidance\n- The component provides several configuration options through its data fields:\n  - `d_frames`: Stores the output rigid positions.\n  - `d_useNormals`: A boolean to specify whether normals should be used to compute orientations (default is true).\n  - `d_invertNormals`: Inverts the direction of the normals if set to true.\n  - `d_rotation` and `d_rotationAngle`: Allow specifying local rotations around specified axes by angle.\n- The initialization (`init`) and reinitialization (`reinit`) methods ensure that the component is properly configured and updated based on input data changes.\n\n### Data Fields\n- **d_frames**: Stores the output rigid positions (frames).\n- **d_useNormals**: Boolean to enable or disable the use of normals for orientation computation.\n- **d_invertNormals**: Boolean to invert the direction of normals.\n- **d_rotation**: Specifies the axis around which local rotations are applied (x-axis: 0, y-axis: 1, z-axis: 2).\n- **d_rotationAngle**: Angle by which the frames are rotated locally.",
  "maths": "The `Vertex2Frame` component in the SOFA framework transforms vertices, texture coordinates (texCoords), normals, and facets from any mesh into rigid positions. Its primary role is to compute a rigid position based on the provided geometric data of the mesh.\n\n### Governing Equations or Operators Implemented:\n- **Output Frames:** The `Vertex2Frame` component generates frames (rigid positions) that consist of both translation vectors and rotation quaternions for each vertex in the input mesh. Each frame is represented as a rigid body position $\\mathbf{F}_i = (\\mathbf{p}_i, \\mathbf{q}_i)$ where $\\mathbf{p}_i$ is the translational component (position vector) and $\\mathbf{q}_i$ is the rotational component (unit quaternion).\n\n### Constitutive or Kinematic Laws Involved:\n- **Orientation Computation:** The orientation of each frame is computed based on either the normals or vertex positions.\n  - If `d_useNormals` is true, the normal vectors at each vertex are used to define the $z$-axis ($\\mathbf{z}_i$), and the cross product between a predefined $y$-axis (typically $(0,1,0)$) and $\\mathbf{z}_i$ yields the $x$-axis ($\\mathbf{x}_i$). The orientation quaternion is then derived from these axes.\n  - If `d_useNormals` is false, the direction from one vertex to its subsequent neighbor defines the $x$-axis ($\\mathbf{x}_i$), and a predefined $y$-axis (typically $(0,1,0)$) is used to define the $z$-axis via cross products.\n\n### Role in the Global FEM Pipeline:\n- **Transformation Mapping:** This component acts as a transformation mapping in the SOFA framework. It converts geometric data into rigid positions which can be utilized for various purposes such as visualization, collision detection, or further mechanical state updates.\n- **Initialization and Update:** The `init` method ensures that the component is properly initialized, while the `reinit` and `doUpdate` methods update the frames based on changes in input data. This update process fits into the broader simulation loop where geometric transformations are applied before physical simulations proceed.\n\n### Numerical Methods or Discretization Choices:\n- **Local Rotation:** The component supports local rotations around specified axes by a given angle (d_rotationAngle). These rotations are encoded as quaternions and applied to each frame. Specifically, the rotation quaternion $\\mathbf{q}_r$ is defined using an axis-angle representation where the axis of rotation can be either the $x$, $y$, or $z$-axis depending on `d_rotation` (0 for x-axis, 1 for y-axis, and 2 for z-axis).\n\n### Broad Variational/Lagrangian Mechanics Framework:\n- **Geometric Data to Rigid Positions:** The process of converting geometric data into rigid positions is a mapping operation. This mapping does not directly contribute to the variational formulation or Lagrangian mechanics equations but provides a basis for further mechanical simulations.\n  - For example, if the frames generated by `Vertex2Frame` are used in collision detection or contact modeling, these operations will be incorporated within the broader framework of variational mechanics and Lagrange multipliers as constraints.\n\nIn summary, `Vertex2Frame` facilitates the transformation of geometric mesh data into rigid positions, which can then be utilized for various purposes in a FEM simulation pipeline.",
  "abstract": "The `Vertex2Frame` component computes rigid positions from vertices, texture coordinates, normals, and facets of a mesh by generating frames with specified orientations based on input data.",
  "sheet": "# Vertex2Frame\n\n## Overview\n\nThe `Vertex2Frame` component is part of the Sofa.Component.Engine.Transform module. It inherits from `DataEngine`, indicating its role in processing geometric data to produce rigid positions (frames) for further use in simulations, such as visualization or collision detection.\n\n## Parameters and Data\n\n- **d_frames**: Stores the output rigid positions (frames).\n- **d_useNormals** (`bool`): Enables or disables the use of normals for orientation computation. Default is true.\n- **d_invertNormals** (`bool`): Inverts the direction of normals if set to true.\n- **d_rotation** (`int`): Specifies the axis around which local rotations are applied (0: x-axis, 1: y-axis, 2: z-axis).\n- **d_rotationAngle** (`double`): Angle by which frames are rotated locally.\n\n## Practical Notes\n\nThe `Vertex2Frame` component computes orientations based on either normals or vertex directions. If `d_useNormals` is true, the normal vectors define the $z$-axis ($\\mathbf{z}_i$), and the cross product between a predefined $y$-axis (typically $(0,1,0)$) and $\\mathbf{z}_i$ yields the $x$-axis ($\\mathbf{x}_i$). The orientation quaternion is then derived from these axes. If `d_useNormals` is false, the direction from one vertex to its subsequent neighbor defines the $x$-axis ($\\mathbf{x}_i$), and a predefined $y$-axis (typically $(0,1,0)$) is used to define the $z$-axis via cross products. Local rotations can be applied around specified axes by a given angle."
}