Data Fields

Links

Methods

{
  "name": "VolumeFromTriangles",
  "namespace": "sofa::component::engine::generate",
  "module": "Sofa.Component.Engine.Generate",
  "include": "sofa/component/engine/generate/VolumeFromTriangles.h",
  "doc": "This component computes the volume of a given closed surfacic mesh.\n\nThis class computes the volume of a given closed surfacic mesh.\nBased on the divergence theorem with F(x,y,z)=<x,0,0> so that div(F)=1: https://en.wikipedia.org/wiki/Divergence_theorem",
  "inherits": [
    "DataEngine"
  ],
  "templates": [
    "sofa::defaulttype::Rigid3Types",
    "sofa::sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_positions",
      "type": "VecCoord",
      "xmlname": "position",
      "help": "If not set by user, find the context mechanical."
    },
    {
      "name": "d_triangles",
      "type": "VecTriangles",
      "xmlname": "triangles",
      "help": "If not set by user, find the context topology."
    },
    {
      "name": "d_quads",
      "type": "VecQuads",
      "xmlname": "quads",
      "help": "If not set by user, find the context topology."
    },
    {
      "name": "d_volume",
      "type": "Real",
      "xmlname": "volume",
      "help": "The volume is only relevant if the surface is closed."
    },
    {
      "name": "d_doUpdate",
      "type": "bool",
      "xmlname": "update",
      "help": "If true, will update the volume at each time step of the simulation."
    }
  ],
  "links": [
    {
      "name": "l_topology",
      "target": "BaseMeshTopology",
      "kind": "single",
      "xmlname": "topology",
      "help": "link to the topology"
    },
    {
      "name": "l_state",
      "target": "MechanicalState",
      "kind": "single",
      "xmlname": "mechanical",
      "help": "link to the mechanical"
    }
  ],
  "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": "parse",
      "return_type": "void",
      "params": [
        {
          "name": "arg",
          "type": "core::objectmodel::BaseObjectDescription *"
        }
      ],
      "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": "getVolume",
      "return_type": "SReal",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "updateVolume",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `VolumeFromTriangles` component in the SOFA framework is designed to compute the volume of a closed surfacic mesh. This engine-based component relies on the divergence theorem with F(x,y,z) = <x,0,0> such that div(F)=1 to calculate the volume. It takes as input positions and either triangles or quads defining the surface mesh topology.\n\nThe component interacts with other SOFA components through its API by inheriting from `sofa::core::DataEngine`. It links to mechanical states (`MechanicalState`) and topology containers (`BaseMeshTopology`) to retrieve the necessary data for computations. It updates the computed volume based on the provided mesh topology, ensuring that the surface is closed and valid.\n\nPractical usage of this component involves setting up positions and either triangles or quads as inputs to define the surfacic mesh. The `d_doUpdate` field controls whether the volume should be updated at each time step during simulation. The computed volume can then be accessed via the `getVolume()` method, which returns a real number representing the calculated volume.\n\nThe component ensures that all necessary data fields and links are properly initialized and validated to prevent errors during computation.",
  "maths": "The `VolumeFromTriangles` component in the SOFA framework computes the volume of a closed surfacic mesh using the divergence theorem. Specifically, it employs the vector field \\( F(x,y,z) = (x,0,0) \\), which satisfies \\( \nabla \bullet F = 1 \\). The volume \\( V \\) is computed as follows:\n\n\begin{equation}\nV = \\iint_{S} F \bullet dA\n\\end{equation}\nwhere \\( S \\) represents the surface of the mesh and \\( dA \\) denotes an infinitesimal area element on that surface.\n\n### Governing Equations / Operators:\n- **Volume Calculation:** The volume is computed by integrating over the triangular or quad faces of the surface mesh. For each triangle with vertices \\( p_0, p_1, p_2 \\), the contribution to the volume is given by:\n\begin{equation}\nV_{\\text{triangle}} = \\frac{(p_1[1] - p_0[1])(p_2[2] - p_0[2]) - (p_2[1] - p_0[1])(p_1[2] - p_0[2])}{6} \times (p_0[0] + p_1[0] + p_2[0])\n\\end{equation}\n- For each quad, it is decomposed into two triangles and the volume contributions from both are summed.\n\n### Constitutive / Kinematic Laws Involved:\n- **Divergence Theorem Application:** \\( \nabla \bullet F = 1 \\) for the vector field \\( F(x,y,z) = (x,0,0) \\).\n- **Triangle Volume Contribution Calculation:** This is based on a projection of the triangle onto the x-axis and integration over that projection.\n\n### Role in the Global FEM Pipeline:\nThis component operates outside the primary FEM pipeline, which focuses on solving nonlinear dynamical systems. The `VolumeFromTriangles` component computes geometric properties (volume) from surface mesh data. It does not directly contribute to mass matrix \\( M \\), stiffness matrix \\( K \\), internal force \\( f_{\text{int}} \\), or the residual \\( R \\). Instead, it serves as a post-processing tool for analysis and visualization.\n\n### Numerical Methods / Discretization Choices:\n- The volume computation relies on numerical integration over discrete surface elements (triangles and quads).\n- Triangular/quadrilateral faces are used to discretize the surface mesh.\n\n### Fit into Broader Variational / Lagrangian Mechanics Framework:\nThe `VolumeFromTriangles` component is not directly involved in variational mechanics or Lagrangian dynamics. However, it can be considered an auxiliary tool that provides information useful for validation and analysis of simulation results. It does not contribute to the dynamic equations but helps in ensuring that the surface mesh remains closed and valid throughout a simulation.\n",
  "abstract": "The `VolumeFromTriangles` component computes the volume of a closed surfacic mesh using the divergence theorem with the vector field F(x,y,z) = (x,0,0). It interacts with mechanical states and topology containers to retrieve necessary data for computations.",
  "sheet": "# VolumeFromTriangles\n\n## Overview\nThe `VolumeFromTriangles` component computes the volume of a closed surfacic mesh using the divergence theorem. This engine-based component retrieves positions and either triangles or quads defining the surface mesh topology from linked mechanical states (`MechanicalState`) and topology containers (`BaseMeshTopology`).\n\n## Mathematical Model\nThe volume is computed by integrating over the triangular or quad faces of the surface mesh. For each triangle with vertices \\( p_0, p_1, p_2 \\), the contribution to the volume is given by:\n\\[ V_{\\text{triangle}} = \\frac{(p_1[1] - p_0[1])(p_2[2] - p_0[2]) - (p_2[1] - p_0[1])(p_1[2] - p_0[2])}{6} \\times (p_0[0] + p_1[0] + p_2[0]) \\]\nFor each quad, it is decomposed into two triangles and the volume contributions from both are summed.\n\n## Parameters and Data\n- **d_positions**: `VecCoord` - Positions of mesh vertices. If not set by user, finds context mechanical state.\n- **d_triangles**: `VecTriangles` - Triangular faces defining the surface topology. If not set by user, finds context topology.\n- **d_quads**: `VecQuads` - Quadrilateral faces defining the surface topology. If not set by user, finds context topology.\n- **d_volume**: `Real` - The computed volume of the closed surfacic mesh.\n- **d_doUpdate**: `bool` - Controls whether to update the volume at each time step during simulation (default: false).\n\n## Dependencies and Connections\nThe component links to:\n- **l_topology**: `BaseMeshTopology` - Topology container for retrieving surface topology data.\n- **l_state**: `MechanicalState` - Mechanical state for retrieving positions of mesh vertices."
}