{
  "name": "BarycentricMapperHexahedronSetTopology",
  "main": {
    "name": "BarycentricMapperHexahedronSetTopology",
    "namespace": "sofa::component::mapping::linear",
    "module": "Sofa.Component.Mapping.Linear",
    "include": "sofa/component/mapping/linear/BarycentricMappers/BarycentricMapperHexahedronSetTopology.h",
    "doc": "Class allowing barycentric mapping computation on a HexahedronSetTopology",
    "inherits": [
      "BarycentricMapperTopologyContainer"
    ],
    "templates": [
      "sofa::sofa::defaulttype::Vec3Types, sofa::sofa::defaulttype::Vec3Types"
    ],
    "data_fields": [],
    "links": [],
    "methods": [
      {
        "name": "getElements",
        "return_type": "int",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getBarycentricCoefficients",
        "return_type": "int",
        "params": [
          {
            "name": "barycentricCoordinates",
            "type": "const int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "computeBase",
        "return_type": "void",
        "params": [
          {
            "name": "base",
            "type": "Mat3x3 &"
          },
          {
            "name": "in",
            "type": "const typename In::VecCoord &"
          },
          {
            "name": "element",
            "type": "const Hexahedron &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "computeCenter",
        "return_type": "void",
        "params": [
          {
            "name": "center",
            "type": "Vec3 &"
          },
          {
            "name": "in",
            "type": "const typename In::VecCoord &"
          },
          {
            "name": "element",
            "type": "const Hexahedron &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "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": "public"
      },
      {
        "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": "public"
      },
      {
        "name": "addPointInCube",
        "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": "setPointInCube",
        "return_type": "int",
        "params": [
          {
            "name": "pointIndex",
            "type": "const int"
          },
          {
            "name": "cubeIndex",
            "type": "const int"
          },
          {
            "name": "baryCoords",
            "type": "const SReal *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "applyOnePoint",
        "return_type": "void",
        "params": [
          {
            "name": "hexaId",
            "type": "const int &"
          },
          {
            "name": "out",
            "type": "typename Out::VecCoord &"
          },
          {
            "name": "in",
            "type": "const typename In::VecCoord &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "handleTopologyChange",
        "return_type": "void",
        "params": [
          {
            "name": "t",
            "type": "core::topology::Topology *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setTopology",
        "return_type": "void",
        "params": [
          {
            "name": "topology",
            "type": "sofa::core::topology::TopologyContainer *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      }
    ]
  },
  "desc": {
    "name": "BarycentricMapperHexahedronSetTopology",
    "description": "The BarycentricMapperHexahedronSetTopology is a specialized component used in simulation frameworks like Sofa to map points from one topology (the 'from' topology) to another (the 'to' topology). Specifically, it uses barycentric coordinates within hexahedral elements (cubes or rectangular prisms) for the mapping. This mapper allows for precise and smooth deformation of geometries by associating each point in the target topology with a specific location within a source hexahedron, defined through its barycentric coordinates.",
    "parameters": [
      {
        "name": "applyOnRestPosition",
        "description": "If set to '1', the mapper will use rest positions for computing mappings. Useful when dealing with deformed meshes where the initial position is more stable than current deformation state.",
        "type": "bool",
        "default_value": "0"
      },
      {
        "name": "from",
        "description": "The name of the topology container that serves as the source for mapping points from hexahedral elements.",
        "type": "string",
        "required": true
      },
      {
        "name": "to",
        "description": "The name of the topology container that receives the mapped points. If not specified, the component works within a single topology context.",
        "type": "string"
      }
    ],
    "details": "This mapper is particularly useful in scenarios where detailed deformation and transformation of 3D geometries are required, such as in biomechanical simulations or any simulation needing precise control over how one geometry deforms to match another. It ensures that the mapping process accounts for the local structure within hexahedra, leading to more natural-looking deformations compared to simpler point-to-point mappings.",
    "example_use_case": "In a biomechanical simulation of an organ deformation where the organ's surface needs to be mapped onto a simplified mesh (the 'to' topology) from a detailed hexahedral mesh (the 'from' topology), this mapper ensures that each vertex on the simplified mesh is correctly positioned based on its barycentric coordinates within corresponding hexahedra of the detailed mesh, leading to smooth and accurate deformation patterns."
  },
  "maths": {
    "response": "The BarycentricMapperHexahedronSetTopology is a specialized mapper that uses barycentric coordinates to map points from one topology (the 'from' or source topology) to another ('to' or target topology). It's specifically designed for hexahedral elements, which are six-faced polyhedra often resembling cubes or rectangular prisms. The key idea behind this component is to associate each point in the target topology with a precise location within a hexahedron from the source topology based on barycentric coordinates. Below is a detailed mathematical and physical description of how this mapper operates and its underlying principles.\n\n### Mathematical Description:\n\n#### Barycentric Coordinates:\nBarycentric coordinates are a form of coordinate system where any point within an n-dimensional simplex (such as a triangle in 2D or a tetrahedron in 3D) can be expressed as a linear combination of the vertices of that simplex. For hexahedral elements, each vertex is one of the eight corners of the cube. The barycentric coordinates \\\\( (w_0, w_1, ..., w_7) \\\\) for a point within the hexahedron satisfy:\n\n\\[\n\begin{align*}\n    &0 \\leq w_i \\leq 1 \\quad \\text{for all } i = 0, 1, ..., 7 \\\\\n    &w_0 + w_1 + ... + w_7 = 1.\n\\end{align*}\n\\]\n\n#### Mapping Using Barycentric Coordinates:\nThe mapping of a point within the hexahedron is computed as follows. Given the barycentric coordinates \\\\( (f_x, f_y, f_z) \\), which range from 0 to 1 and correspond to the distance along each axis relative to the cube's edges, the position \\\\( P_{target} \\\\) of a point in the target topology can be calculated as:\n\n\\[\n\begin{align*}\n    &P_{target} = \\sum_{i=0}^{7} w_i P_{source,i},\n\\end{align*}\n\\]\nwhere \\\\( P_{source,i} \\\\) are the positions of the eight vertices of the hexahedron in the source topology. For a hexahedron with vertices labeled as 0 through 7, this expands to:\n\n\\[\n\begin{align*}\n    &P_{target} = P_0 (1-f_x)(1-f_y)(1-f_z) + P_1 f_x(1-f_y)(1-f_z) \\\\\n    &+ P_2 f_xf_y(1-f_z) + P_3 (1-f_x)f_y(1-f_z) \\\\\n    &+ P_4 (1-f_x)(1-f_y)f_z + P_5 f_x(1-f_y)f_z \\\\\n    &+ P_6 f_xf_yf_z + P_7 (1-f_x)f_yf_z.\n\\end{align*}\n\\]\n\n### Physical Description:\n\n#### Deformation and Smooth Mapping:\nThe primary physical application of the BarycentricMapperHexahedronSetTopology is in simulating deformable objects. When a hexahedral element deforms, each vertex moves to a new position. The mapper ensures that points within these elements are smoothly interpolated based on their barycentric coordinates, allowing for realistic deformation.\n\n#### Handling Hexahedra:\nThe hexahedron (cube or rectangular prism) is divided into eight vertices. Each vertex has its own coordinate in space. Given a point inside the hexahedron defined by its barycentric coordinates \\\\( f_x \\), \\\\( f_y \\), and \\\\( f_z \\), the mapper calculates the new position of that point based on the movement of all eight vertices.\n\n#### Updating Mappings During Simulation:\nDuring a simulation, the source hexahedra can deform or even be removed. The BarycentricMapperHexahedronSetTopology updates its mappings accordingly by re-computing barycentric coordinates if necessary and ensuring that points are correctly mapped to valid hexahedral elements.\n\n### Implementation Summary:\n- **Initialization:** Points in the target topology are associated with hexahedra in the source topology, using barycentric coordinates.\n- **Simulation Steps:** For each point, its position is interpolated based on the current positions of the vertices of the hexahedron and the stored barycentric coordinates.\n- **Handling Topology Changes:** If a hexahedron is removed or renumbered, the mapper updates its internal state to ensure consistent mappings.\n\n### Conclusion:\nThe BarycentricMapperHexahedronSetTopology provides a robust and efficient method for interpolating points within deforming hexahedral elements. By leveraging barycentric coordinates, it ensures smooth and physically accurate deformation of objects in simulations."
  },
  "summary": {
    "abstract": "The BarycentricMapperHexahedronSetTopology maps points using barycentric coordinates within hexahedral elements for precise deformation in simulations.",
    "sheet": "# BarycentricMapperHexahedronSetTopology\n\n## Overview\nThe BarycentricMapperHexahedronSetTopology is a specialized component that handles the mapping of points from one topology to another using barycentric coordinates within hexahedral elements. It inherits from `BarycentricMapperTopologyContainer` and operates on hexahedral sets, enabling precise deformation by associating each point in the target topology with a specific location defined through its barycentric coordinates.\n\n## Mathematical Model\nThe component computes mappings using barycentric coordinates within hexahedra. For a given hexahedron with vertices \\\\( \\mathbf{v}_0, \\mathbf{v}_1, \\ldots, \\mathbf{v}_7 \\\\), the position of an internal point \\\\( \\mathbf{x} \\\\) can be expressed as:\n\n\\[\n  \\mathbf{x} = \\sum_{i=0}^{7} b_i \\mathbf{v}_i,\n\\]\nwhere \\\\( b_i \\\\) are the barycentric coordinates satisfying \\\\( \\sum_{i=0}^{7} b_i = 1 \\\\). The component computes these coordinates and uses them to map points accurately within hexahedral elements.\n\n## Dependencies and Connections\nThis component typically requires a `TopologyContainer` for managing the topology of the hexahedra. It fits into the scene graph by handling the mapping between different topologies, ensuring that deformations are smooth and precise."
  }
}