{
  "name": "BarycentricMapperTetrahedronSetTopology",
  "main": {
    "name": "BarycentricMapperTetrahedronSetTopology",
    "namespace": "sofa::component::mapping::linear",
    "module": "Sofa.Component.Mapping.Linear",
    "include": "sofa/component/mapping/linear/BarycentricMappers/BarycentricMapperTetrahedronSetTopology.h",
    "doc": "Class allowing barycentric mapping computation on a TetrahedronSetTopology",
    "inherits": [
      "BarycentricMapperTopologyContainer"
    ],
    "templates": [
      "sofa::defaulttype::Vec3Types, sofa::defaulttype::Vec3Types"
    ],
    "data_fields": [],
    "links": [],
    "methods": [
      {
        "name": "addPointInTetra",
        "return_type": "int",
        "params": [
          {
            "name": "index",
            "type": "const int"
          },
          {
            "name": "baryCoords",
            "type": "const SReal *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getElements",
        "return_type": "int",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "getBarycentricCoefficients",
        "return_type": "int",
        "params": [
          {
            "name": "barycentricCoordinates",
            "type": "const int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "computeBase",
        "return_type": "void",
        "params": [
          {
            "name": "base",
            "type": "Mat3x3d &"
          },
          {
            "name": "in",
            "type": "const typename In::VecCoord &"
          },
          {
            "name": "element",
            "type": "const Tetrahedron &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "computeCenter",
        "return_type": "void",
        "params": [
          {
            "name": "center",
            "type": "Vec3 &"
          },
          {
            "name": "in",
            "type": "const typename In::VecCoord &"
          },
          {
            "name": "element",
            "type": "const Tetrahedron &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "computeDistance",
        "return_type": "void",
        "params": [
          {
            "name": "d",
            "type": "SReal &"
          },
          {
            "name": "v",
            "type": "const Vec3 &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "addPointInElement",
        "return_type": "void",
        "params": [
          {
            "name": "elementIndex",
            "type": "const int"
          },
          {
            "name": "baryCoords",
            "type": "const SReal *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "processTopologicalChanges",
        "return_type": "void",
        "params": [
          {
            "name": "out",
            "type": "const typename Out::VecCoord &"
          },
          {
            "name": "in",
            "type": "const typename In::VecCoord &"
          },
          {
            "name": "t",
            "type": "core::topology::Topology *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "processAddPoint",
        "return_type": "void",
        "params": [
          {
            "name": "pos",
            "type": "const sofa::type::Vec3d &"
          },
          {
            "name": "in",
            "type": "const typename In::VecCoord &"
          },
          {
            "name": "vectorData",
            "type": "MappingData &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      }
    ]
  },
  "desc": {
    "title": "Barycentric Mapper Tetrahedron Set Topology",
    "description": "The BarycentricMapperTetrahedronSetTopology class is a specialized mapping mechanism in the SOFA (Simulation Open-Framework Architecture) framework designed for use with tetrahedral meshes. This component allows for barycentric interpolation of points within the topological structure defined by a TetrahedronSetTopology container.",
    "parameters": [
      {
        "name": "fromTopology",
        "type": "sofa::core::topology::TopologyContainer*",
        "description": "The source topology container that defines the tetrahedral mesh."
      },
      {
        "name": "toTopology",
        "type": "sofa::core::topology::BaseMeshTopology*",
        "description": "The target topology to which mapping is applied. This should be a BaseMeshTopology object representing the destination geometry."
      }
    ],
    "methods": [
      {
        "name": "addPointInTetra",
        "parameters": [
          {
            "type": "const Index&",
            "name": "index"
          },
          {
            "type": "const SReal*",
            "name": "baryCoords"
          }
        ],
        "return_type": "Index",
        "description": "Adds a point to a specific tetrahedron using barycentric coordinates provided in baryCoords."
      },
      {
        "name": "getElements",
        "parameters": [],
        "return_type": "type::vector<Tetrahedron>",
        "description": "Retrieves the list of tetrahedra that compose the mesh."
      },
      {
        "name": "getBarycentricCoefficients",
        "parameters": [
          {
            "type": "const std::array<Real, MappingData::NumberOfCoordinates>&",
            "name": "barycentricCoordinates"
          }
        ],
        "return_type": "std::array<Real, Tetrahedron::NumberOfNodes>",
        "description": "Converts the barycentric coordinates to coefficients that correspond to the nodes of a tetrahedron."
      },
      {
        "name": "computeBase",
        "parameters": [
          {
            "type": "Mat3x3d&",
            "name": "base"
          },
          {
            "type": "const typename In::VecCoord&",
            "name": "in"
          },
          {
            "type": "const Tetrahedron&",
            "name": "element"
          }
        ],
        "return_type": "void",
        "description": "Computes the base matrix for a given tetrahedral element using the input coordinates."
      },
      {
        "name": "computeCenter",
        "parameters": [
          {
            "type": "Vec3&",
            "name": "center"
          },
          {
            "type": "const typename In::VecCoord&",
            "name": "in"
          },
          {
            "type": "const Tetrahedron&",
            "name": "element"
          }
        ],
        "return_type": "void",
        "description": "Calculates the center of mass for a given tetrahedral element."
      },
      {
        "name": "computeDistance",
        "parameters": [
          {
            "type": "SReal&",
            "name": "d"
          },
          {
            "type": "const Vec3&",
            "name": "v"
          }
        ],
        "return_type": "void",
        "description": "Computes the distance from a given point to its nearest tetrahedron using barycentric coordinates."
      },
      {
        "name": "addPointInElement",
        "parameters": [
          {
            "type": "const Index&",
            "name": "elementIndex"
          },
          {
            "type": "const SReal*",
            "name": "baryCoords"
          }
        ],
        "return_type": "void",
        "description": "Adds a point to the specified tetrahedral element using barycentric coordinates."
      },
      {
        "name": "processTopologicalChanges",
        "parameters": [
          {
            "type": "const typename Out::VecCoord&",
            "name": "out"
          },
          {
            "type": "const typename In::VecCoord&",
            "name": "in"
          },
          {
            "type": "core::topology::Topology*",
            "name": "t"
          }
        ],
        "return_type": "void",
        "description": "Handles topology changes such as addition, removal or renumbering of points within the tetrahedral mesh."
      },
      {
        "name": "processAddPoint",
        "parameters": [
          {
            "type": "const type::Vec3d&",
            "name": "pos"
          },
          {
            "type": "const typename In::VecCoord&",
            "name": "in"
          },
          {
            "type": "MappingData&",
            "name": "vectorData"
          }
        ],
        "return_type": "void",
        "description": "Processes the addition of a point within the tetrahedral mesh, determining its closest tetrahedron and storing barycentric coordinates."
      }
    ]
  },
  "maths": {
    "maths": "The **BarycentricMapperTetrahedronSetTopology** component in the SOFA framework is designed to perform barycentric interpolation within a tetrahedral mesh. This mapping is crucial for transferring properties or deformations from one set of nodes (master) to another (slave), such as when simulating embedded meshes or multi-resolution coupling scenarios.\n\n### Governing Equations and Operators\n\n1. **Barycentric Coordinates**:\n   Given a tetrahedron with vertices \\( \textbf{v}_0, \textbf{v}_1, \textbf{v}_2, \textbf{v}_3 \\), any point \\(\textbf{p}\\) within this tetrahedron can be expressed as:\n   \n   \\\\[ \\textbf{p} = w_0 \\textbf{v}_0 + w_1 \\textbf{v}_1 + w_2 \\textbf{v}_2 + w_3 \\textbf{v}_3 \\\\]\n\n   where \\(w_i\\) are the barycentric coordinates satisfying:\n   \\\\[ w_0 + w_1 + w_2 + w_3 = 1 \\\\]\n\n2. **Barycentric Interpolation**:\n   If a point is added to the tetrahedral mesh at position \\(\textbf{p}\\), its barycentric coordinates are computed and used for interpolation of properties (e.g., displacement, velocity) from the vertices of the containing tetrahedron. The interpolation weights can be derived using geometric transformations as implemented in methods like `computeBase` and `computeCenter`. \n\n### Constitutive or Kinematic Laws Involved\n\n- **Strain Measures**: Not directly involved; this component is concerned with topological mappings rather than strain measures.\n\n- **Stress Tensors, Hyperelastic Potentials, Damping Models**: Not directly involved. This component focuses on the geometric and positional mapping of points within a tetrahedral mesh structure.\n\n### Role in FEM Pipeline\n\n1. **Topology Handling**:\n   - **`addPointInTetra`:** Adds a point to a specified tetrahedron with given barycentric coordinates, updating internal data structures accordingly.\n   - **`computeBase`, `computeCenter`, `computeDistance`:** Compute geometric transformations and distances needed for mapping points accurately within the tetrahedral elements.\n\n2. **Topological Changes Processing**:\n   - **`processTopologicalChanges`:** Handles changes to the mesh topology, including adding, removing, or renumbering points, ensuring that barycentric coordinates are correctly updated when such changes occur.\n\n3. **Constraint Handling and Mapping**:\n   - This component facilitates constraint handling by enabling precise mapping of slave nodes based on their position within tetrahedral elements of the master mesh. It ensures consistency in virtual work between the mapped points and the deformed geometry.\n\n### Numerical Methods or Discretization Choices\n\n- **Discretization**: The tetrahedron set topology represents a discretized domain where each point's position is interpolated based on its barycentric coordinates within a tetrahedral element. No explicit finite element matrices (like mass or stiffness) are directly involved, but the geometric interpolation ensures consistency with the underlying FEM spatial discretization.\n\n### Integration into Variational/Lagrangian Mechanics Framework\n\nThe BarycentricMapperTetrahedronSetTopology component supports consistent mapping between different resolutions or levels of detail within a simulation. By ensuring that slave nodes are correctly mapped using barycentric interpolation, it preserves the physical invariants and consistency required for variational mechanics formulations. Specifically, this ensures that forces computed at slave nodes can be accurately back-projected to master nodes for use in the nonlinear solution phase.\n\n### Summary\nThe BarycentricMapperTetrahedronSetTopology component plays a critical role in maintaining geometric consistency within a tetrahedral mesh during simulation by performing barycentric interpolation. This ensures that any mapped properties or deformations are accurately and physically consistent with the underlying mechanical model."
  },
  "summary": {
    "abstract": "The BarycentricMapperTetrahedronSetTopology performs barycentric interpolation for points within tetrahedral meshes, ensuring geometric consistency during simulation.",
    "sheet": "# BarycentricMapperTetrahedronSetTopology\n\n## Overview\nThe BarycentricMapperTetrahedronSetTopology is a specialized mapping component in the SOFA framework designed to handle barycentric interpolation within tetrahedral meshes. It ensures geometric consistency by accurately mapping points based on their barycentric coordinates, which is crucial for maintaining physical invariants and consistency in simulations involving embedded or multi-resolution models.\n\n## Mathematical Model\nGiven a tetrahedron with vertices \\(\\textbf{v}_0, \\textbf{v}_1, \\textbf{v}_2, \\textbf{v}_3\\), any point \\(\\textbf{p}\\) within this tetrahedron can be expressed as:\n\n\\[ \n\\textbf{p} = w_0 \\textbf{v}_0 + w_1 \\textbf{v}_1 + w_2 \\textbf{v}_2 + w_3 \\textbf{v}_3 \n\\]\nwhere \\(w_i\\) are the barycentric coordinates satisfying:\n\n\\[ \nw_0 + w_1 + w_2 + w_3 = 1 \n\\]\n\nThe interpolation weights are computed using geometric transformations as implemented in methods like `computeBase` and `computeCenter`. This ensures that properties (e.g., displacement, velocity) are accurately interpolated from the vertices of the containing tetrahedron.\n\n## Dependencies and Connections\nThis component typically requires a TetrahedronSetTopology container to define the mesh structure. It exchanges data with other components such as force fields or solvers to ensure consistent mapping during simulation.\n"
  }
}