Data Fields

Methods

{
  "name": "NormalsFromPoints",
  "namespace": "sofa::component::engine::generate",
  "module": "Sofa.Component.Engine.Generate",
  "include": "sofa/component/engine/generate/NormalsFromPoints.h",
  "doc": "Compute vertex normals by averaging face normals.\n\nThis class compute vertex normals by averaging face normals",
  "inherits": [
    "DataEngine"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "position",
      "type": "VecCoord",
      "xmlname": "position",
      "help": "Vertices of the mesh"
    },
    {
      "name": "normals",
      "type": "VecCoord",
      "xmlname": "normals",
      "help": "Computed vertex normals of the mesh"
    },
    {
      "name": "invertNormals",
      "type": "bool",
      "xmlname": "invertNormals",
      "help": "Swap normals"
    },
    {
      "name": "useAngles",
      "type": "bool",
      "xmlname": "useAngles",
      "help": "Use incident angles to weight faces normal contributions at each vertex"
    }
  ],
  "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 `NormalsFromPoints` component in the SOFA framework is part of the engine module and computes vertex normals by averaging face normals for both triangular and quadrilateral mesh elements. This class inherits from `DataEngine`, indicating that it processes data to generate new output data fields.\n\n**Role and Purpose:**\n- The primary role of this component is to calculate vertex normals based on the geometry (triangles and quads) provided by the mesh. It supports customization options for normal inversion and weighting with incident angles.\n\n**Interactions with Other Components:**\n- `NormalsFromPoints` interacts with other components through its data fields (`position`, `triangles`, `quads`, `normals`). The input positions, triangles, and quads are required to compute the vertex normals, which are then stored in the `normals` field.\n\n**Usage Guidance:**\n- **Data Fields:*\n  - *position*: Vertices of the mesh used for normal computation.\n  - *triangles* and *quads*: Faces of the mesh (3-element arrays for triangles, 4-element arrays for quads).\n  - *normals*: Computed vertex normals output.\n  - *invertNormals*: Boolean flag to swap the direction of computed normals.\n  - *useAngles*: Boolean flag to weight face normal contributions based on incident angles at each vertex.\n\n- **Methods:**\n  - `init()`: Initializes internal state variables, typically called during component setup.\n  - `reinit()`: Reinitializes and calls the update method, useful for resetting computations.\n  - `doUpdate()`: Core logic to compute normals by averaging face normals for both triangles and quads.",
  "maths": "The `NormalsFromPoints` component in the SOFA framework computes vertex normals by averaging face normals for both triangular and quadrilateral mesh elements. This process is essential for rendering, shading, and other geometric computations. The mathematical details are as follows:\n\n### Governing Equations and Operators\n- **Face Normals:** For each triangle with vertices \\(\\mathbf{v}_1\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\", \"\nv_2, \\mathbf{v}_3\\), the face normal \\\\mathbf{n}\\\\) is computed as:\n\n\begin{align*}\n    \\mathbf{n} = (\\mathbf{v}_2 - \\mathbf{v}_1) \\times (\\mathbf{v}_3 - \\mathbf{v}_1)\n\tag{1}\n\text{Similarly, for each quadrilateral with vertices \\\\mathbf{v}_1, \\mathbf{v}_2, \\mathbf{v}_3, \\mathbf{v}_4\\), face normals are computed using cross products of edges.}\n\n- **Vertex Normals:** Vertex normals are obtained by averaging the normalized face normals of adjacent faces. If the option `useAngles` is enabled, the contribution of each face normal \\\\mathbf{n}_i\\) to a vertex normal \\\\mathbf{N}\\) is weighted by the angle between edges at that vertex. For a triangle with vertices \\\\mathbf{v}_1, \\mathbf{v}_2, \\mathbf{v}_3\\), the contribution of face normal \\\\mathbf{n}\\) to vertex normals \\\\mathbf{N}_j\\) is:\n\n\begin{align*}\n    \\mathbf{N}_{\\mathbf{v}_1} &+= \\mathbf{n} \\times \\frac{\\arccos( -(\\mathbf{e}_{31} \\cdot \\mathbf{e}_{12}) / (|\\mathbf{e}_{31}| |\\mathbf{e}_{12}|) )}{|\\mathbf{n}|}, \\\\\n    \\mathbf{N}_{\\mathbf{v}_2} &+= \\mathbf{n} \\times \\frac{\\arccos( -(\\mathbf{e}_{12} \\cdot \\mathbf{e}_{23}) / (|\\mathbf{e}_{12}| |\\mathbf{e}_{23}|) )}{|\\mathbf{n}|}, \\\\\n    \\mathbf{N}_{\\mathbf{v}_3} &+= \\mathbf{n} \\times \\frac{\\arccos( -(\\mathbf{e}_{23} \\cdot \\mathbf{e}_{31}) / (|\\mathbf{e}_{23}| |\\mathbf{e}_{31}|) )}{|\\mathbf{n}|},\n\tag{2}\n\text{where \\\\mathbf{e}_{ij}\\) denotes the edge vector from vertex \\\\mathbf{v}_i\\) to \\\\mathbf{v}_j\\. If `useAngles` is disabled, each face normal is simply normalized and added to the vertex normals.}\n\n### Constitutive or Kinematic Laws Involved\n- **Normal Calculation:** The calculation of face normals relies on the cross product of edge vectors. This adheres to geometric principles rather than mechanical laws.\n\n### Role in the Global FEM Pipeline\nThe `NormalsFromPoints` component is not directly involved in the core numerical steps of FEM, such as assembly, time integration, nonlinear solve, linear solve, or constraint handling. Instead, it plays a supporting role by providing vertex normals for mesh geometry, which can be useful for rendering and other visualization tasks.\n\n### Numerical Methods and Discretization Choices\n- **Discretization:** The component operates on discrete geometric elements (triangles and quads) to compute normals. There is no direct connection to the FEM discretization scheme but rather a purely geometric operation.\n\n### Broader Variational/Lagrangian Mechanics Framework\nThe `NormalsFromPoints` does not directly fit into the variational or Lagrangian mechanics framework as it pertains more to geometric and rendering aspects rather than mechanical simulation. However, accurate vertex normals are important for visualizing deformable models in simulations.\n",
  "abstract": "Computes vertex normals by averaging face normals for triangular and quadrilateral mesh elements, with options to invert normals and weight contributions based on incident angles.",
  "sheet": "# NormalsFromPoints\n\n## Overview\nThe `NormalsFromPoints` component computes vertex normals by averaging the face normals of triangles and quads in a mesh. It inherits from `DataEngine`, indicating its role as a data processor that generates new output fields such as computed vertex normals.\n\n## Mathematical Model\n### Face Normals\nFor each triangle with vertices \\(\\mathbf{v}_1, \\mathbf{v}_2, \\mathbf{v}_3\\), the face normal \\(\\mathbf{n}\\) is computed as:\n\\[ \n    \\mathbf{n} = (\\mathbf{v}_2 - \\mathbf{v}_1) \\times (\\mathbf{v}_3 - \\mathbf{v}_1)\n\\]\nSimilarly, for each quadrilateral with vertices \\(\\mathbf{v}_1, \\mathbf{v}_2, \\mathbf{v}_3, \\mathbf{v}_4\\), face normals are computed using cross products of edges.\n\n### Vertex Normals\nVertex normals are obtained by averaging the normalized face normals of adjacent faces. If `useAngles` is enabled, each face normal contribution to a vertex normal is weighted by the angle between edges at that vertex. For a triangle with vertices \\(\\mathbf{v}_1, \\mathbf{v}_2, \\mathbf{v}_3\\), the contributions are:\n\\[ \n    \\mathbf{N}_{\\mathbf{v}_1} += \\mathbf{n} \\times \\frac{\\arccos( -(\\mathbf{e}_{31} \\cdot \\mathbf{e}_{12}) / (|\\mathbf{e}_{31}| |\\mathbf{e}_{12}|) )}{|\\mathbf{n}|}, \n    \\quad\n    \\mathbf{N}_{\\mathbf{v}_2} += \\mathbf{n} \\times \\frac{\\arccos( -(\\mathbf{e}_{12} \\cdot \\mathbf{e}_{23}) / (|\\mathbf{e}_{12}| |\\mathbf{e}_{23}|) )}{|\\mathbf{n}|}, \n    \\quad\n    \\mathbf{N}_{\\mathbf{v}_3} += \\mathbf{n} \\times \\frac{\\arccos( -(\\mathbf{e}_{23} \\cdot \\mathbf{e}_{31}) / (|\\mathbf{e}_{23}| |\\mathbf{e}_{31}|) )}{|\\mathbf{n}|}\n\\]\nwhere \\(\\mathbf{e}_{ij}\\) denotes the edge vector from vertex \\(\\mathbf{v}_i\\) to \\(\\mathbf{v}_j\\). If `useAngles` is disabled, each face normal is simply normalized and added to the vertex normals.\n\n## Parameters and Data\n- **position**: Vertices of the mesh used for normal computation (type: VecCoord).\n- **normals**: Computed vertex normals output (type: VecCoord).\n- **invertNormals**: Boolean flag to swap the direction of computed normals (default: false).\n- **useAngles**: Boolean flag to weight face normal contributions based on incident angles at each vertex (default: false)."
}