{
  "name": "Hexa2QuadTopologicalMapping",
  "main": {
    "name": "Hexa2QuadTopologicalMapping",
    "namespace": "sofa::component::topology::mapping",
    "module": "Sofa.Component.Topology.Mapping",
    "include": "sofa/component/topology/mapping/Hexa2QuadTopologicalMapping.h",
    "doc": "Topological mapping where HexahedronSetTopology is converted to QuadSetTopology\n\nThis class, called Hexa2QuadTopologicalMapping, is a specific implementation of the interface TopologicalMapping where :\nINPUT TOPOLOGY = HexahedronSetTopology\nOUTPUT TOPOLOGY = QuadSetTopology, as the boundary of the INPUT TOPOLOGY\nHexa2QuadTopologicalMapping class is templated by the pair (INPUT TOPOLOGY, OUTPUT TOPOLOGY)",
    "inherits": [
      "TopologicalMapping"
    ],
    "templates": [],
    "data_fields": [
      {
        "name": "d_flipNormals",
        "type": "bool",
        "xmlname": "flipNormals",
        "help": "Flip Normal ? (Inverse point order when creating triangle)"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "init",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "updateTopologicalMappingTopDown",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getFromIndex",
        "return_type": "int",
        "params": [
          {
            "name": "ind",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "description": "The `Hexa2QuadTopologicalMapping` is a specific implementation within the SOFA framework that handles topological mappings between two types of mesh topology: **HexahedronSetTopology** (input) and **QuadSetTopology** (output). This class facilitates the conversion of hexahedral elements into quad elements, effectively mapping the boundary of the input hexahedral topology to a set of quads. It is part of the `sofa::component::topology::mapping` namespace within the `Sofa.Component.Topology.Mapping` module.\n\n### Role and Purpose\nThe primary role of this component is to enable the transformation between different topological representations, which is crucial for simulations that require multi-resolution or reduced models. By converting hexahedra to quads, it supports various applications in computational biomechanics, surgical simulation, haptics, soft robotics, and multiphysics problems.\n\n### Interactions with Other Components\nThis component interacts with other SOFA components through the `TopologicalMapping` interface and inherits from this base class. It requires a **HexahedronSetTopology** as input and produces a **QuadSetTopology** as output. The process involves initializing the target topology (`init()`), updating topological mappings (`updateTopologicalMappingTopDown()`), and providing methods to translate indices between the source and target topologies (`getFromIndex()`).\n\n### Practical Usage Guidance and Data Fields\n- **flipNormals**: A boolean data field that allows flipping normals when creating quads, which can be toggled via the `flipNormals` parameter.\n\nUsage typically involves setting up the appropriate input and output topologies within a SOFA scene graph. The component ensures proper initialization of the target topology from the source and handles updates to reflect changes in the source topology on the target."
  },
  "maths": {
    "maths": "# Mathematical and Physical Description of Hexa2QuadTopologicalMapping Component\n\n## Introduction\nThe `Hexa2QuadTopologicalMapping` is a specialized topological mapping component in the SOFA (Simulation Open Framework Architecture) framework. It handles the conversion from hexahedral elements (3D cubes, represented as **HexahedronSetTopology**) to quad elements (2D faces, represented as **QuadSetTopology**). The primary purpose of this component is to map the boundary surfaces of a hexahedral mesh onto a set of quadrilateral faces. This mapping facilitates various applications in computational biomechanics and engineering simulations where reduced models or multi-resolution representations are needed.\n\n## Mathematical Description\n### Topological Mapping\nThe conversion from hexahedra to quads involves breaking down each hexahedron into its constituent faces. Each hexahedron (a 3D cube) has six quadrilateral faces, and the mapping process essentially extracts these faces and represents them as individual quad elements.\n\n#### Hexahedron Representation\nA hexahedron can be represented by its eight vertices and twelve edges. The vertices are indexed in a specific order to form six quadrilateral faces. For example:\n- **Vertices**: $V_0, V_1, V_2, V_3, V_4, V_5, V_6, V_7$\n- **Faces** (Quads):\n  - Face 0: $(V_0, V_3, V_2, V_1)$\n  - Face 1: $(V_4, V_5, V_6, V_7)$\n  - Face 2: $(V_0, V_1, V_5, V_4)$\n  - Face 3: $(V_1, V_2, V_6, V_5)$\n  - Face 4: $(V_2, V_3, V_7, V_6)$\n  - Face 5: $(V_3, V_0, V_4, V_7)$\n\n### Conversion Process\nDuring the conversion process, each hexahedron is decomposed into its six faces. These faces are then represented as individual quadrilateral elements in the target topology.\n\n#### Visibility Check\nThe component also checks for visibility of each quad face after a hexahedron removal or modification. This ensures that only relevant faces (those not occluded by other hexahedra) remain visible and part of the output quad topology.\n\n### Index Mapping\nTo facilitate efficient indexing, the `Hexa2QuadTopologicalMapping` maintains mappings between indices in the source (hexahedral) and target (quad) topologies. The `getFromIndex()` method provides a way to retrieve these mappings.\n\n## Physical Description\n### Applications\nThe primary physical application of this component is to enable simulations that require reduced models or multi-resolution representations. For example:\n- **Biomechanics**: Simulating tissue behavior at different resolutions, where detailed hexahedral models are simplified into quad-based surfaces for faster computation and visualization.\n- **Engineering**: Multi-physics problems where complex 3D structures need to be represented in a simpler 2D form, such as stress analysis on the surface of a solid object.\n\n### Normal Flipping Mechanism\nThe `flipNormals` parameter allows users to flip normals when creating quads. This is important for ensuring consistent surface orientation and correct normal direction, which can affect lighting, shading, and other physical properties in simulations and visualizations.\n\n#### Normal Calculation\nFor each quad face $(V_i, V_j, V_k)$:\n- Calculate the vectors: $\\vec{AB} = V_j - V_i$ and $\\vec{AC} = V_k - V_i$\n- Compute the normal vector using the cross product: $\\vec{N} = \\vec{AB} \\times \\vec{AC}$\n\nWhen `flipNormals` is enabled, this normal vector is negated to reverse its direction.\n\n## Conclusion\nThe `Hexa2QuadTopologicalMapping` component in SOFA provides a robust mechanism for converting hexahedral topologies into quad-based representations. This facilitates various applications by enabling reduced models and multi-resolution simulations, while also allowing control over surface properties such as normal orientation."
  },
  "summary": {
    "abstract": "The `Hexa2QuadTopologicalMapping` converts hexahedral elements to quad elements, mapping the boundary surfaces of a hexahedral mesh onto individual quad faces.",
    "sheet": "# Hexa2QuadTopologicalMapping\n\n## Overview\nThe `Hexa2QuadTopologicalMapping` is a specialized topological mapping component that handles the conversion from **HexahedronSetTopology** (input) to **QuadSetTopology** (output). This class facilitates the transformation of hexahedral elements into quad elements, effectively representing the boundary surfaces of the input topology as individual quadrilateral faces. It inherits from the `TopologicalMapping` interface and supports various applications in computational biomechanics and engineering simulations.\n\n## Mathematical Model\nThe conversion process involves breaking down each hexahedron into its six constituent quadrilateral faces. Each hexahedron (a 3D cube) is represented by eight vertices, and the mapping extracts these vertices to form individual quad elements:\n- **Vertices**: $V_0, V_1, V_2, V_3, V_4, V_5, V_6, V_7$\n- **Faces** (Quads):\n  - Face 0: $(V_0, V_3, V_2, V_1)$\n  - Face 1: $(V_4, V_5, V_6, V_7)$\n  - Face 2: $(V_0, V_1, V_5, V_4)$\n  - Face 3: $(V_1, V_2, V_6, V_5)$\n  - Face 4: $(V_2, V_3, V_7, V_6)$\n  - Face 5: $(V_3, V_0, V_4, V_7)$\n\n## Parameters and Data\n- **flipNormals**: A boolean parameter that allows flipping normals when creating quads. Default value is `false`.\n\n## Practical Notes\nThe component ensures proper initialization of the target topology from the source and handles updates to reflect changes in the source topology on the target. The `flipNormals` parameter can be toggled to control normal orientation, which affects surface properties such as lighting and shading."
  }
}