{
  "name": "GenerateRigidMass",
  "main": {
    "name": "GenerateRigidMass",
    "namespace": "sofa::component::engine::generate",
    "module": "Sofa.Component.Engine.Generate",
    "include": "sofa/component/engine/generate/GenerateRigidMass.h",
    "doc": "Engine computing the RigidMass of a mesh: mass, volume and inertia matrix.",
    "inherits": [
      "DataEngine"
    ],
    "templates": [
      "sofa::defaulttype::Rigid3Types, Rigid3Mass"
    ],
    "data_fields": [
      {
        "name": "m_density",
        "type": "Real",
        "xmlname": "density",
        "help": "input: Density of the object"
      },
      {
        "name": "rigidMass",
        "type": "MassType",
        "xmlname": "rigidMass",
        "help": "output: rigid mass computed"
      },
      {
        "name": "mass",
        "type": "Real",
        "xmlname": "mass",
        "help": "output: mass of the mesh"
      },
      {
        "name": "volume",
        "type": "Real",
        "xmlname": "volume",
        "help": "output: volume of the mesh"
      },
      {
        "name": "inertiaMatrix",
        "type": "Mat3x3",
        "xmlname": "inertiaMatrix",
        "help": "output: the inertia matrix of the mesh"
      },
      {
        "name": "massCenter",
        "type": "Vec3",
        "xmlname": "massCenter",
        "help": "output: the gravity center of the mesh"
      },
      {
        "name": "centerToOrigin",
        "type": "type::Vec3",
        "xmlname": "centerToOrigin",
        "help": "output: vector going from the mass center to the space origin"
      }
    ],
    "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": "integrateMesh",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "integrateTriangle",
        "return_type": "void",
        "params": [
          {
            "name": "kV0",
            "type": "type::Vec3"
          },
          {
            "name": "kV1",
            "type": "type::Vec3"
          },
          {
            "name": "kV2",
            "type": "type::Vec3"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "generateRigid",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "GetCustomTemplateName",
        "return_type": "int",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": true,
        "access": "public"
      }
    ]
  },
  "desc": {
    "description": "The `GenerateRigidMass` is an engine component in the SOFA framework, designed to compute the Rigid Mass properties (mass, volume, and inertia matrix) of a given mesh. It inherits from `DataEngine`, allowing it to process input data and generate output values based on the provided mesh geometry.\n\n**Role and Purpose:**\nThe primary role of `GenerateRigidMass` is to calculate the physical properties required for rigid-body dynamics simulations within SOFA. These calculations are essential for ensuring accurate simulation results, particularly in scenarios involving collision detection and response.\n\n**Interactions with Other Components:**\n`GenerateRigidMass` interacts with other components through its input data fields (`m_density`, `m_positions`, `m_triangles`, `m_quads`, and `m_polygons`). It processes this geometry information to compute the rigid mass properties, which are then available for use by other simulation components. This output includes the overall mass, volume, inertia matrix, gravity center (massCenter), and a vector from the mass center to the space origin.\n\n**Practical Usage Guidance:**\nThe `GenerateRigidMass` component requires input data fields such as vertex positions (`m_positions`) and mesh topology (triangles, quads, polygons). The user must provide these inputs to enable the engine to perform its computations. Additionally, a density value (`m_density`) can be specified to adjust the mass calculations according to material properties.\n\nThe computed outputs include `mass`, `volume`, `inertiaMatrix`, `massCenter`, and `centerToOrigin`. These values are used by other components in the simulation pipeline to ensure accurate physical behavior of the rigid body. The component also provides methods like `init()`, `reinit()`, and `doUpdate()` for managing its initialization and update cycles."
  },
  "maths": {
    "maths": "# Mathematical and Physical Description of GenerateRigidMass Component\n\n## Overview\nThe `GenerateRigidMass` component in the SOFA framework is designed to calculate physical properties (mass, volume, and inertia tensor) for a given mesh. These properties are crucial for performing accurate rigid-body dynamics simulations. The mathematical model involves several key steps: calculating the volume of the mesh, determining its mass based on density, and computing the inertia tensor.\n\n## Input Data\nThe component takes in the following inputs:\n- **Density (\\(\\rho\\))**: Mass per unit volume of the material, given in kg/m³.\n- **Vertex Positions (\\(\boldsymbol{V}\\))**: A set of vertices \\(\boldsymbol{V} = \\\\{\boldsymbol{v}_1, \\ldots, \\boldsymbol{v}_N\\\\}\\), where each \\(\\boldsymbol{v}_i\\) is a 3D vector representing the position of vertex i.\n- **Mesh Topology (\\(\boldsymbol{T}, \\boldsymbol{Q}, \\boldsymbol{P}\\\\))**: The mesh topology, which consists of triangles \\(\boldsymbol{T}\\), quads \\(\boldsymbol{Q}\\), and polygons \\(\boldsymbol{P}\\). These are defined as sets of indices into the vertex array \\(\boldsymbol{V}\\).\n\n## Volume Calculation\nThe volume of the mesh is calculated by integrating over its surface. For a triangular mesh, this involves summing up contributions from each tetrahedron formed between triangles and an arbitrary origin point \\(\\boldsymbol{o} = (0, 0, 0)\\):\n\n$$\nV = \\sum_{j=1}^{N_t} V_j,\n$$\nwhere \n\n$$\nV_j = \\frac{1}{6} |\\boldsymbol{o}, \\boldsymbol{v}_{T_j(1)}, \\boldsymbol{v}_{T_j(2)}, \\boldsymbol{v}_{T_j(3)}|,\n$$\nand the determinant (volume of the tetrahedron) is given by:\n\n$$\n|\\boldsymbol{o}, \\boldsymbol{v}_{T_j(1)}, \\boldsymbol{v}_{T_j(2)}, \\boldsymbol{v}_{T_j(3)}| = \\det\n\\begin{bmatrix}\n    0 & x_1 & y_1 & z_1 \\\\\n    0 & x_2 & y_2 & z_2 \\\\\n    0 & x_3 & y_3 & z_3 \\\\\n    0 & x_o & y_o & z_o\n\\end{bmatrix},\n$$\nwhere \\(\\boldsymbol{o} = (x_o, y_o, z_o)\\), and \\((x_i, y_i, z_i)\\) are the coordinates of vertex i.\n\n## Mass Calculation\nThe mass of the mesh is calculated as:\n\n$$\nm = V \\cdot \\rho,\n$$\nwhere \\(V\\) is the volume and \\(\\rho\\) is the density provided by the user.\n\n## Inertia Tensor Calculation\nThe inertia tensor (or moment of inertia tensor) describes how mass is distributed around the center of mass. It is a 3x3 matrix given by:\n\n$$\nI = \\begin{bmatrix}\n    I_{xx} & -I_{xy} & -I_{xz} \\\\\n   -I_{yx} & I_{yy} & -I_{yz} \\\\\n   -I_{zx} & -I_{zy} & I_{zz}\n\\end{bmatrix},\n$$\nwhere the components are calculated as follows:\n\n- \\(I_{xx}\\) = \\(m (y^2 + z^2) - \\sum_j m_j y_j^2 - \\sum_k m_k z_k^2\\)\n- \\(I_{yy}\\) = \\(m (x^2 + z^2) - \\sum_j m_j x_j^2 - \\sum_k m_k z_k^2\\)\n- \\(I_{zz}\\) = \\(m (x^2 + y^2) - \\sum_j m_j x_j^2 - \\sum_k m_k y_k^2\\)\n- \\(I_{xy} = I_{yx} = -m x y + \\sum_j m_j x_j y_j\\)\n- \\(I_{xz} = I_{zx} = -m x z + \\sum_j m_j x_j z_j\\)\n- \\(I_{yz} = I_{zy} = -m y z + \\sum_k m_k y_k z_k\\)\n\nHere, the center of mass (massCenter) is given by:\n\n$$\n\\boldsymbol{c} = \\frac{1}{V} \\int_V \\boldsymbol{r} dV,\n$$\nwhere \\(\\boldsymbol{r}\\) represents the position vector.\n\n## Center to Origin Vector Calculation\nThe vector from the center of mass (massCenter) to the space origin is simply:\n\n$$\n\\boldsymbol{o} - \\boldsymbol{c},\n$$\nwhere \\(\\boldsymbol{o}\\) is the origin point and \\(\\boldsymbol{c}\\) is the computed center of mass.\n\n## Summary\nThe `GenerateRigidMass` component effectively calculates key rigid-body properties (mass, volume, inertia tensor, center of mass, and origin-to-center vector) from input mesh data using integral calculus and physical principles. This information is critical for simulating realistic rigid-body dynamics in the SOFA framework."
  },
  "summary": {
    "abstract": "The `GenerateRigidMass` component computes rigid-body properties (mass, volume, inertia matrix) of a given mesh using its input data fields.",
    "sheet": "# GenerateRigidMass\n\n## Overview\nThe `GenerateRigidMass` is an engine component in the SOFA framework that calculates physical properties such as mass, volume, and inertia tensor for a given mesh. It inherits from `DataEngine`, processing input geometry to generate these rigid-body properties.\n\n## Mathematical Model\n### Volume Calculation\nThe volume of the mesh is calculated by summing contributions from each tetrahedron formed between triangles and an arbitrary origin point \\(\\boldsymbol{o} = (0, 0, 0)\\):\n\n\begin{align*}\nV &= \\sum_{j=1}^{N_t} V_j, \\\\\nV_j &= \\frac{1}{6} |\\boldsymbol{o}, \\boldsymbol{v}_{T_j(1)}, \\boldsymbol{v}_{T_j(2)}, \\boldsymbol{v}_{T_j(3)}|,\n\\end{align*}\n\nwhere the determinant (volume of the tetrahedron) is given by:\n\n\begin{equation*}\n|\\boldsymbol{o}, \\boldsymbol{v}_{T_j(1)}, \\boldsymbol{v}_{T_j(2)}, \\boldsymbol{v}_{T_j(3)}| = \n\\det\n\\begin{bmatrix}\n    0 & x_1 & y_1 & z_1 \\\\\n    0 & x_2 & y_2 & z_2 \\\\\n    0 & x_3 & y_3 & z_3 \\\\\n    0 & x_o & y_o & z_o\n\\end{bmatrix}.\n\\end{equation*}\n\n### Mass Calculation\nThe mass of the mesh is calculated as:\n\n\begin{equation*}\nm = V \\cdot \\rho,\n\\end{equation*}\n\nwhere \\(V\\) is the volume and \\(\rho\\) is the density provided by the user.\n\n### Inertia Tensor Calculation\nThe inertia tensor (or moment of inertia tensor) describes how mass is distributed around the center of mass. It is a 3x3 matrix given by:\n\n\begin{equation*}\nI = \\begin{bmatrix}\n    I_{xx} & -I_{xy} & -I_{xz} \\\\\n   -I_{yx} & I_{yy} & -I_{yz} \\\\\n   -I_{zx} & -I_{zy} & I_{zz}\n\\end{bmatrix},\n\\end{equation*}\n\nwhere the components are calculated as follows:\n\n- \\(I_{xx}\\) = \\(m (y^2 + z^2) - \\sum_j m_j y_j^2 - \\sum_k m_k z_k^2\\)\n- \\(I_{yy}\\) = \\(m (x^2 + z^2) - \\sum_j m_j x_j^2 - \\sum_k m_k z_k^2\\)\n- \\(I_{zz}\\) = \\(m (x^2 + y^2) - \\sum_j m_j x_j^2 - \\sum_k m_k y_k^2\\)\n- \\(I_{xy} = I_{yx} = -m x y + \\sum_j m_j x_j y_j\\)\n- \\(I_{xz} = I_{zx} = -m x z + \\sum_j m_j x_j z_j\\)\n- \\(I_{yz} = I_{zy} = -m y z + \\sum_k m_k y_k z_k\\)\n\nHere, the center of mass (massCenter) is given by:\n\n\begin{equation*}\n\\boldsymbol{c} = \\frac{1}{V} \\int_V \\boldsymbol{r} dV,\n\\end{equation*}\n\nwhere \\(\\boldsymbol{r}\\) represents the position vector.\n\n### Center to Origin Vector Calculation\nThe vector from the center of mass (massCenter) to the space origin is simply:\n\n\begin{equation*}\n\\boldsymbol{o} - \\boldsymbol{c},\n\\end{equation*}\n\nwhere \\(\\boldsymbol{o}\\) is the origin point and \\(\\boldsymbol{c}\\) is the computed center of mass.\n\n## Parameters and Data\n- **Density (m_density)**: Input parameter specifying the density of the object, type `Real`.\n- **Rigid Mass (rigidMass)**: Output rigid mass computed by the component, type `MassType`.\n- **Mass (mass)**: Output total mass of the mesh, type `Real`.\n- **Volume (volume)**: Output volume of the mesh, type `Real`.\n- **Inertia Matrix (inertiaMatrix)**: Output inertia matrix of the mesh, type `Mat3x3`.\n- **Mass Center (massCenter)**: Output gravity center of the mesh, type `Vec3`.\n- **Center to Origin (centerToOrigin)**: Output vector from the mass center to the space origin, type `type::Vec3`."
  }
}