Data Fields

Links

Methods

{
  "name": "VolumeFromTetrahedrons",
  "namespace": "sofa::component::engine::generate",
  "module": "Sofa.Component.Engine.Generate",
  "include": "sofa/component/engine/generate/VolumeFromTetrahedrons.h",
  "doc": "This component computes the volume of a given volumetric mesh.\n\nThis class returns the volumes of a given volumic mesh.",
  "inherits": [
    "DataEngine"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_positions",
      "type": "VecCoord",
      "xmlname": "position",
      "help": "If not set by user, find the context mechanical."
    },
    {
      "name": "d_tetras",
      "type": "VecTetras",
      "xmlname": "tetras",
      "help": "If not set by user, find the context topology."
    },
    {
      "name": "d_hexas",
      "type": "VecHexas",
      "xmlname": "hexas",
      "help": "If not set by user, find the context topology."
    },
    {
      "name": "d_volume",
      "type": "Real",
      "xmlname": "volume",
      "help": "The computed volume."
    },
    {
      "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 `VolumeFromTetrahedrons` component computes the volume of a given volumetric mesh in the SOFA framework. It is part of the `Sofa.Component.Engine.Generate` module and inherits from the `DataEngine` class, which is responsible for processing data within the simulation pipeline.\n\nThis component interacts with other components through several key API elements:\n- **Mechanical State**: The mechanical state provides the positions of vertices in the mesh. This linkage ensures that position data can be retrieved if not explicitly set by the user.\n- **Topology**: It accesses topology information (tetrahedrons and hexahedrons) either directly from input fields or through a linked topology container, ensuring the component has all necessary geometry information to compute volumes.\n\nFor practical usage:\n- The `d_positions` field holds vertex positions. If not set by the user, it is automatically fetched from the mechanical state in context.\n- The `d_tetras` and `d_hexas` fields store tetrahedron and hexahedron indices respectively. These can be set manually or derived from a linked topology container if unset.\n- The `d_volume` field returns the computed volume, which is read-only once calculated.\n- The `d_doUpdate` flag controls whether the component updates its output at each simulation time step.\n\nThe initialization and reinitialization methods ensure that required data fields are correctly set up and validated. The `updateVolume` method computes the volume based on tetrahedron and hexahedron definitions, summing individual volumes to produce a total mesh volume.",
  "maths": "The `VolumeFromTetrahedrons` component in the SOFA framework is designed to compute the volume of a given volumetric mesh, which is composed of tetrahedra and hexahedra. It interacts with other components through several key API elements: mechanical state for vertex positions and topology information (tetrahedra and hexahedra) either directly or via a linked topology container.\n\n### Mathematical Description:\n\n#### 1. Volume Calculation\nThe component calculates the volume by summing up the individual volumes of tetrahedra and hexahedra that compose the volumetric mesh. For each tetrahedron and hexahedron, it uses their respective geometric formulas to compute their volumes.\n\n- **Tetrahedron Volume**:\nThe volume $V_T$ of a single tetrahedron with vertices $\textbf{p}_1, \textbf{p}_2, \textbf{p}_3, \textbf{p}_4$ is given by:\n\begin{equation}\n    V_T = \\frac{1}{6} \\left| \\det(\\mathbf{T}) \\right|\n\tag{1}\\label{eq:tet_vol}\n\\end{equation}\nwhere $\\mathbf{T}$ is the matrix formed by placing the vectors from $\textbf{p}_1$ to $\textbf{p}_2$, $\textbf{p}_3$, and $\textbf{p}_4$ as columns.\n\n- **Hexahedron Volume**:\nThe volume $V_H$ of a single hexahedron with vertices $\textbf{q}_0, \textbf{q}_1, ..., \textbf{q}_7$ is computed using the formula for an arbitrary hexahedron, which can be derived from its determinant form or decomposed into simpler shapes (e.g., prisms or tetrahedra).\n\nThe total volume $V_{\text{total}}$ of the mesh is then given by summing the individual volumes:\n\begin{equation}\n    V_{\\text{total}} = \\sum_{i=1}^{N_T} V_T^{(i)} + \\sum_{j=1}^{N_H} V_H^{(j)}\n\tag{2}\\label{eq:total_vol}\n\\end{equation}\nwhere $N_T$ is the number of tetrahedra and $N_H$ is the number of hexahedra in the mesh.\n\n#### 2. Data Fields\n- **d_positions**: The vertex positions $\textbf{p}_i$, where each $\textbf{p}_i \notin \textbf{R}^3$. If not explicitly set by the user, these are retrieved from the mechanical state context.\n- **d_tetras**: Indices of vertices forming tetrahedra in the mesh. Each tetrahedron is defined by four indices corresponding to its vertices.\n- **d_hexas**: Indices of vertices forming hexahedra in the mesh. Each hexahedron is defined by eight indices corresponding to its vertices.\n- **d_volume**: The computed volume $V_{\text{total}}$. This field is read-only once calculated.\n- **d_doUpdate**: A flag that controls whether the component updates its output at each simulation time step.\n\n#### 3. Numerical Methods and Discretization Choices\nThe `VolumeFromTetrahedrons` component does not contribute to solving any governing equations such as those for elasticity or dynamics. Instead, it focuses on geometric computation:\n- The volume calculation is straightforwardly based on the positions of vertices and the indices that define tetrahedra and hexahedra.\n\n#### 4. Role in the Global FEM Pipeline\nThis component plays a role in the pre-processing phase where mesh properties are computed or verified before the simulation begins. It can also update its volume computation at each time step if `d_doUpdate` is set to true, which could be useful for monitoring changes in the volume of deformable objects during simulations.\n\n#### 5. Fit into Variational / Lagrangian Mechanics Framework\nThis component does not directly fit into a variational or Lagrangian mechanics framework as it primarily deals with geometric properties (volumes) rather than dynamical or energetic quantities. However, accurate volume computation is essential for ensuring the correctness of physical simulations, particularly in cases where material incompressibility constraints are applied.\n\n### Summary\nThe `VolumeFromTetrahedrons` component computes the total volume of a volumetric mesh composed of tetrahedra and hexahedra by summing up individual volumes. It retrieves necessary data from mechanical state and topology information, contributing to geometric verification or monitoring in simulations.",
  "abstract": "The `VolumeFromTetrahedrons` component computes the total volume of a volumetric mesh composed of tetrahedra and hexahedra, retrieving necessary data from mechanical state and topology information.",
  "sheet": "# VolumeFromTetrahedrons\n\n## Overview\nThe `VolumeFromTetrahedrons` component is an engine that calculates the total volume of a given volumetric mesh. It retrieves vertex positions from the mechanical state and tetrahedron/hexahedron indices from the topology information.\n\n## Mathematical Model\nThe component computes the volume by summing up individual volumes of tetrahedra and hexahedra in the mesh.\n\n- **Tetrahedron Volume**: The volume $V_T$ of a single tetrahedron with vertices $\\mathbf{p}_1, \\mathbf{p}_2, \\mathbf{p}_3, \\mathbf{p}_4$ is given by:\n  \n  \\[ V_T = \\frac{1}{6} \\left| \\det(\\mathbf{T}) \\right| \\]\n\n  where $\\mathbf{T}$ is the matrix formed by placing the vectors from $\\mathbf{p}_1$ to $\\mathbf{p}_2$, $\\mathbf{p}_3$, and $\\mathbf{p}_4$ as columns.\n\n- **Hexahedron Volume**: The volume $V_H$ of a single hexahedron with vertices $\\mathbf{q}_0, \\mathbf{q}_1, ..., \\mathbf{q}_7$ is computed using the formula for an arbitrary hexahedron.\n\nThe total volume $V_{\\text{total}}$ of the mesh is then given by:\n\n\\[ V_{\\text{total}} = \\sum_{i=1}^{N_T} V_T^{(i)} + \\sum_{j=1}^{N_H} V_H^{(j)} \\]\n\nwhere $N_T$ is the number of tetrahedra and $N_H$ is the number of hexahedra in the mesh.\n\n## Parameters and Data\n- **d_positions**: The vertex positions $\\mathbf{p}_i$, where each $\\mathbf{p}_i \\in \\mathbb{R}^3$. If not explicitly set by the user, these are retrieved from the mechanical state context.\n- **d_tetras**: Indices of vertices forming tetrahedra in the mesh. Each tetrahedron is defined by four indices corresponding to its vertices.\n- **d_hexas**: Indices of vertices forming hexahedra in the mesh. Each hexahedron is defined by eight indices corresponding to its vertices.\n- **d_volume**: The computed volume $V_{\\text{total}}$. This field is read-only once calculated.\n- **d_doUpdate**: A flag that controls whether the component updates its output at each simulation time step.\n\n## Dependencies and Connections\nThe `VolumeFromTetrahedrons` component requires mechanical state and topology information to retrieve vertex positions and tetrahedron/hexahedron indices, respectively. It fits into the SOFA scene graph by linking with these components."
}