Data Fields

Methods

{
  "name": "ProjectiveTransformEngine",
  "namespace": "sofa::component::engine::transform",
  "module": "Sofa.Component.Engine.Transform",
  "include": "sofa/component/engine/transform/ProjectiveTransformEngine.h",
  "doc": "Project the position of 3d points onto a plane according to a projection matrix.\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::Vec3Types"
  ],
  "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 projected 3d points"
    },
    {
      "name": "proj_mat",
      "type": "ProjMat",
      "xmlname": "proj_mat",
      "help": "projection matrix"
    },
    {
      "name": "focal_distance",
      "type": "Real",
      "xmlname": "focal_distance",
      "help": "focal distance "
    }
  ],
  "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"
    }
  ],
  "description": "The `ProjectiveTransformEngine` is an engine component in the SOFA framework designed to project positions of 3D points onto a plane using a specified projection matrix. This transformation can include various operations such as translation, rotation, and scaling. The component takes an input array of 3D points (`input_position`) and applies the provided `projection_matrix` along with the focal distance to generate the projected output positions (`output_position`).\n\nThe component inherits from `DataEngine`, indicating that it processes data inputs and outputs within a SOFA simulation pipeline. It has four primary fields: `f_inputX`, `f_outputX`, `proj_mat`, and `focal_distance`. The input and output arrays are represented by the `VecCoord` type, while the projection matrix is of type `ProjMat`, and the focal distance is a single real number.\n\nThe component interacts with other SOFA components through its API, where it can receive 3D point data and transformation parameters to produce transformed positions. The methods `init()`, `reinit()`, and `doUpdate()` manage initialization, reinitialization, and the update process for applying transformations, respectively.",
  "maths": "The `ProjectiveTransformEngine` is designed to project positions of 3D points onto a plane using a specified projection matrix. This transformation can include various operations such as translation, rotation, and scaling. The mathematical details are as follows:\n\n1. **Input Data**:\n   - \\(\\mathbf{X}_{in} = [x_1, x_2, ..., x_n]^T\\) where each \\(x_i\\) is a 3D vector representing the input position.\n   - Projection matrix: \\(P\\), which can be used to represent translation, rotation, and scaling transformations.\n   - Focal distance: \\(f\\).\n\n2. **Transformation Process**:\n   Each input point \\(\begin{pmatrix} x_i \\\\ y_i \\\\ z_i \\end{pmatrix}\\) is extended with a homogeneous coordinate to form a 4D vector \\(X_{i,4} = \\begin{pmatrix} x_i \\\\ y_i \\\\ z_i \\\\ 1 \\end{pmatrix}\\).\n   The transformed point in the new frame is obtained by applying the projection matrix:\n   \\[\n   X'_{i,4} = P \\cdot X_{i,4}\n   \\]\n   Let \\(X'_i = (x'_i, y'_i, z'_i)\\), then the final projected position is computed using the focal distance and normalization:\n   \\[\n   x''_i = f \\frac{x'_i}{z'_i}, \\quad y''_i = f \\frac{y'_i}{z'_i}\n   \\]\n\n3. **Mathematical Formulation**:\n   - Homogeneous transformation: The 4D vector is transformed by the projection matrix.\n     \\[\n     X'_{i,4} = P \begin{pmatrix} x_i \\\\ y_i \\\\ z_i \\\\ 1 \\end{pmatrix}\n     \\]\n   - Normalization and scaling:\n     \\[\n     X''_i = f \\frac{X'_i}{z'_i} = f \\begin{pmatrix} \\frac{x'_i}{z'_i} \\\\ \\frac{y'_i}{z'_i} \\\\ 1 \\\\ 0 \\end{pmatrix}\n     \\]\n   - Output position:\n     \\[\n     X_{out} = [x''_1, x''_2, ..., x''_n]^T\n     \\]\n\n4. **Role in the Global FEM Pipeline**:\n   This component primarily operates on the geometric transformation of points and is used for projection or view transformations rather than directly contributing to core mechanics like mass matrix, stiffness matrix, internal forces, etc.\n\n5. **Numerical Methods / Discretization Choices**:\n   - The projection operation uses a standard 4x4 homogeneous coordinate system for affine transformations (including translation, rotation, scaling).\n   - No specific numerical methods or discretization schemes are used beyond the basic matrix multiplication and normalization.\n\n6. **Fit into Variational/Lagrangian Mechanics Framework**:\n   This component operates at the level of geometric transformation and does not directly involve variational principles or Lagrangian mechanics. It is more relevant for visualization or coordinate transformations in the context of a broader simulation pipeline.",
  "abstract": "The `ProjectiveTransformEngine` projects positions of 3D points onto a plane using a specified projection matrix, extending from `DataEngine` for data processing in SOFA simulations.",
  "sheet": "# ProjectiveTransformEngine\n\n## Overview\n\nThe `ProjectiveTransformEngine` is an engine component that extends the functionality of `DataEngine`. It projects positions of 3D points onto a plane using a specified projection matrix, enabling transformations such as translation, rotation, and scaling. This component processes input data fields to generate transformed output positions.\n\n## Mathematical Model\n\nEach input point \\\\( \\mathbf{x}_i = (x_i, y_i, z_i) \\\\) is extended with a homogeneous coordinate to form a 4D vector \\\\( X_{i,4} = \\begin{pmatrix} x_i \\\\ y_i \\\\ z_i \\\\ 1 \\end{pmatrix} \\\\). The transformed point in the new frame is obtained by applying the projection matrix \\\\( P \\\\):\n\n\begin{equation}\nX'_{i,4} = P X_{i,4}\n\tag{1}\n\text{Let } X'_i = (x'_i, y'_i, z'_i), \\text{ then the final projected position is computed using the focal distance and normalization:}\n\\end{equation}\n\n\begin{align*}\nx''_i &= f \\frac{x'_i}{z'_i}, \\\\\ny''_i &= f \\frac{y'_i}{z'_i}.\n\tag{2}\n\text{Output position:}\n\\end{align*}\n\n\begin{equation}\nX_{out} = [x''_1, x''_2, ..., x''_n]^T.\n\tag{3}\n\text{Homogeneous transformation: The 4D vector is transformed by the projection matrix.}\n\\end{equation}\n\n## Parameters and Data\n\n- **f_inputX**: Input array of 3D points (`VecCoord` type).\n- **f_outputX**: Output array of projected 3D points (`VecCoord` type).\n- **proj_mat**: Projection matrix (`ProjMat` type) used for transformation.\n- **focal_distance**: Focal distance (`Real` type)."
}